mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-11-14 10:39:32 +01:00
2598 lines
106 KiB
TypeScript
2598 lines
106 KiB
TypeScript
/**
|
||
* @fileoverview Zod validation schemas for API routes
|
||
*
|
||
* This module contains Zod schemas for validating API request bodies.
|
||
* Schemas are used in src/web/server.ts route handlers.
|
||
*
|
||
* @module web/schemas
|
||
*/
|
||
|
||
import { z } from 'zod';
|
||
import { SAFE_PATH_PATTERN, isSafePushEndpoint } from '../utils/index.js';
|
||
import { isValidWebviewUrl } from './webview-proxy.js';
|
||
import { isBlockedWebviewUrl } from './webview-egress-policy.js';
|
||
import {
|
||
MAX_TERMINAL_BUFFER_BYTES,
|
||
MAX_TERMINAL_SCROLLBACK_LINES,
|
||
MIN_TERMINAL_BUFFER_BYTES,
|
||
MIN_TERMINAL_SCROLLBACK_LINES,
|
||
} from '../config/terminal-history.js';
|
||
import { MAX_EDITABLE_BYTES } from '../config/file-editing.js';
|
||
import { CODEX_REASONING_EFFORTS } from '../types/session.js';
|
||
import { WEBHOOK_KINDS, WEBHOOK_SCOPES } from '../types/push.js';
|
||
import { DISCORD_ON_DELETE, DISCORD_PING_MODES, DISCORD_THREAD_CREATION } from '../types/discord.js';
|
||
import { MIN_MATCH_LENGTH, MAX_MATCH_LENGTH } from '../config/agent-wait.js';
|
||
import { MAX_WAKE_MACS } from '../config/remote-wake-limits.js';
|
||
import { MAX_INPUT_LENGTH } from '../config/terminal-limits.js';
|
||
import { MAX_MESSAGE_BYTES } from './agent-inbox.js';
|
||
import { enabledCliIds, enabledClis } from '../config/cli-registry/registry.js';
|
||
import type { SessionMode } from '../types.js';
|
||
import { isAdvisorModel } from '../types/session.js';
|
||
|
||
// ========== Path Validation ==========
|
||
|
||
/** Validate a path string: no shell metacharacters, no traversal, must be absolute */
|
||
export function isValidWorkingDir(p: string): boolean {
|
||
if (!p || !p.startsWith('/')) return false;
|
||
if (
|
||
p.includes(';') ||
|
||
p.includes('&') ||
|
||
p.includes('|') ||
|
||
p.includes('$') ||
|
||
p.includes('`') ||
|
||
p.includes('(') ||
|
||
p.includes(')') ||
|
||
p.includes('{') ||
|
||
p.includes('}') ||
|
||
p.includes('<') ||
|
||
p.includes('>') ||
|
||
p.includes("'") ||
|
||
p.includes('"') ||
|
||
p.includes('\n') ||
|
||
p.includes('\r')
|
||
) {
|
||
return false;
|
||
}
|
||
if (p.includes('..')) return false;
|
||
return SAFE_PATH_PATTERN.test(p);
|
||
}
|
||
|
||
/** Zod refinement for safe absolute path */
|
||
const safePathSchema = z.string().max(1000).refine(isValidWorkingDir, {
|
||
message: 'Invalid path: must be absolute, no shell metacharacters or traversal',
|
||
});
|
||
|
||
/**
|
||
* Filesystem picker paths are never interpolated into a shell command, so legal
|
||
* filename characters such as spaces, quotes, and parentheses are accepted.
|
||
* Containment and symlink resolution are enforced by the route after parsing.
|
||
*/
|
||
const filesystemPickerPathSchema = z
|
||
.string()
|
||
.max(4096)
|
||
.refine((p) => p.startsWith('/') && !p.includes('\0') && !p.includes('\n') && !p.includes('\r'), {
|
||
message: 'Path must be an absolute filesystem path',
|
||
})
|
||
.refine((p) => !p.split('/').includes('..'), { message: 'Path traversal is not allowed' });
|
||
|
||
/**
|
||
* Opt-in flag for listing dot-prefixed entries in the path picker. Absent means
|
||
* off, so an old client keeps the previous behavior. It is a string rather than
|
||
* a boolean because it arrives as a query parameter; `'false'` is accepted (and
|
||
* means off) so a client can send the flag unconditionally.
|
||
*/
|
||
const showHiddenQuerySchema = z.enum(['true', 'false']).optional();
|
||
|
||
/**
|
||
* Body for the path picker's "New folder": one folder name created directly inside `path`. The name is held
|
||
* to the character set `safePathSchema` accepts (letters, digits, `_ - . ~` and space, no `..`), so every
|
||
* name it accepts is one Link Existing and a session working directory accept (the parent's own path is
|
||
* judged there separately), and never a control character. It is also one path segment, not dot-prefixed (the picker hides those by default) and not tilde-prefixed (a folder named `~` is an `rm -rf ~` accident), and at
|
||
* most 255 BYTES, the usual filesystem limit.
|
||
*/
|
||
export const FilesystemMkdirSchema = z.object({
|
||
path: filesystemPickerPathSchema,
|
||
name: z
|
||
.string()
|
||
.trim()
|
||
.min(1, 'Folder name is required')
|
||
.refine((n) => Buffer.byteLength(n) <= 255, { message: 'Folder name is too long' })
|
||
.refine((n) => /^[\p{L}\p{N}_\-. ~]+$/u.test(n), {
|
||
message: 'Folder name can only use letters, numbers, spaces and _ - . ~',
|
||
})
|
||
.refine((n) => !n.includes('..') && !n.startsWith('.') && !n.startsWith('~'), {
|
||
message: 'Folder name cannot contain "..", or start with a dot or a tilde',
|
||
}),
|
||
sessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid session id')
|
||
.optional(),
|
||
/** Same opt-in flag as browse: lets the picker create inside a hidden folder it is showing. */
|
||
showHidden: showHiddenQuerySchema,
|
||
});
|
||
|
||
/** Query validation for the lazy, allowlisted filesystem path picker. */
|
||
export const FilesystemBrowseQuerySchema = z.object({
|
||
path: filesystemPickerPathSchema.optional(),
|
||
sessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid session id')
|
||
.optional(),
|
||
showHidden: showHiddenQuerySchema,
|
||
});
|
||
|
||
/** Query validation for a single allowlisted path-picker file preview. */
|
||
export const FilesystemPreviewQuerySchema = z.object({
|
||
path: filesystemPickerPathSchema,
|
||
sessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid session id')
|
||
.optional(),
|
||
showHidden: showHiddenQuerySchema,
|
||
});
|
||
|
||
/**
|
||
* Body validation for `PUT /api/sessions/:id/file-content` (File Viewer edit
|
||
* mode). `content.max()` counts UTF-16 code units, which for UTF-8 output is
|
||
* always <= the byte length, so it is a coarse pre-filter that never rejects
|
||
* valid content; the handler enforces the exact MAX_EDITABLE_BYTES byte cap.
|
||
* Workspace containment and symlink resolution are enforced by the route via
|
||
* validateSessionFilePath after parsing.
|
||
*/
|
||
export const FileWriteSchema = z
|
||
.object({
|
||
path: z
|
||
.string()
|
||
.min(1)
|
||
.max(4096)
|
||
.refine((p) => !p.includes('\0') && !p.includes('\n') && !p.includes('\r'), {
|
||
message: 'Invalid path',
|
||
}),
|
||
content: z.string().max(MAX_EDITABLE_BYTES),
|
||
baseHash: z.string().regex(/^[a-f0-9]{64}$/, 'baseHash must be a sha256 hex digest'),
|
||
eol: z.enum(['lf', 'crlf']).optional(),
|
||
force: z.boolean().optional(),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* Body validation for `POST /api/sessions/:id/html-view` (render a local HTML file
|
||
* as a sandboxed page). `path` is absolute or relative to the session workspace;
|
||
* the extension, containment, guard and broad-root checks are the route's
|
||
* (html-view-routes.ts), after parsing.
|
||
*/
|
||
export const HtmlViewOpenSchema = z
|
||
.object({
|
||
path: z
|
||
.string({ error: 'Missing path parameter' })
|
||
.min(1, 'Missing path parameter')
|
||
.max(4096)
|
||
.refine((p) => !p.includes('\0') && !p.includes('\n') && !p.includes('\r'), {
|
||
message: 'Invalid path',
|
||
}),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* The run-mode ids the API currently accepts: every ENABLED registry entry.
|
||
*
|
||
* Exported so anything needing the authoritative list derives it from here rather than
|
||
* restating the nine names (which is how the old literal enum drifted from the run menu).
|
||
*/
|
||
export function sessionModeIds(): string[] {
|
||
return enabledCliIds();
|
||
}
|
||
|
||
/**
|
||
* Validation for a run mode, resolved AT PARSE TIME.
|
||
*
|
||
* ⚠️ Deliberately not a `z.enum([...])`. An enum has to be handed its members when the
|
||
* SCHEMA OBJECT is built, which happens once at module import — so a CLI enabled while the
|
||
* server was running kept failing validation with INVALID_INPUT until a restart, even
|
||
* though the run menu already offered it. Checking membership inside the refinement moves
|
||
* the question to when the request is actually validated.
|
||
*
|
||
* The cast is because callers type this field as `SessionMode`; the runtime check above is
|
||
* what actually constrains it.
|
||
*/
|
||
function sessionModeSchema(): z.ZodType<SessionMode> {
|
||
return (
|
||
z
|
||
.string()
|
||
// Bounded BEFORE the membership check, and before the failure message quotes the value
|
||
// back. `.max(24)` matches the `cliId` pattern in cli-registry/schema.ts — no id longer
|
||
// than that can ever be registered, so nothing legitimate is rejected — and it means a
|
||
// rejected mode cannot echo a body-limit-sized string into an error string and a log
|
||
// line. Without it the only bound on either was the HTTP body limit.
|
||
.max(24)
|
||
.superRefine((value, ctx) => {
|
||
const allowed = sessionModeIds();
|
||
if (!allowed.includes(value)) {
|
||
ctx.addIssue({
|
||
code: 'custom',
|
||
message: `Invalid run mode ${JSON.stringify(value)}. Enabled modes: ${allowed.join(', ')}`,
|
||
});
|
||
}
|
||
}) as unknown as z.ZodType<SessionMode>
|
||
);
|
||
}
|
||
|
||
// ========== Env Var Allowlist ==========
|
||
|
||
/**
|
||
* Allowlisted env var key prefixes, contributed by the ENABLED CLIs in the registry
|
||
* (`env.allowedPrefixes`) — `CLAUDE_CODE_`, `OPENCODE_`, `CODEX_`, `GEMINI_`, `GOOGLE_`,
|
||
* `ANTIGRAVITY_`, `PI_`, `GROK_`, `XAI_`, `DSH_`, `DEEPSEEK_`, `OMP_`, `COPILOT_` as shipped.
|
||
*
|
||
* ⚠️ Resolved AT PARSE TIME, not at module load. This used to be a frozen array computed
|
||
* once when the module was imported, which meant a CLI enabled while the server was running
|
||
* had its env prefix rejected until a restart — validation and the run menu disagreeing
|
||
* about which CLIs exist. Reading the registry per call costs a memoized array lookup.
|
||
*
|
||
* ⚠️ This is ONE GLOBAL LIST applied with no mode context, so admitting a prefix for one CLI
|
||
* widens it for every mode at once. That is why an entry only ever contributes its own
|
||
* VENDOR namespace: pi's ~34 provider keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, HF_TOKEN, …)
|
||
* share no prefix and stay out, and a dsh `settings.yaml` can nominate ANY env var as a
|
||
* provider credential — same problem, same answer. Those CLIs authenticate via their own
|
||
* `/login` or the server process's own environment.
|
||
*/
|
||
function allowedEnvPrefixes(): string[] {
|
||
return enabledClis().flatMap((entry) => entry.env.allowedPrefixes);
|
||
}
|
||
|
||
/**
|
||
* Allowlisted exact env var keys (checked alongside the prefixes), likewise contributed by
|
||
* enabled registry entries via `env.allowedKeys`.
|
||
*
|
||
* As shipped this is claude's CLAUDE_CONFIG_DIR, which relocates the Claude CLI's user
|
||
* config (credentials, settings, stats) so a case can run on a separate Claude subscription
|
||
* (#255). Exact match only — CLAUDE_CONFIG_DIR_EXTRA etc. stay rejected.
|
||
*/
|
||
function allowedEnvKeys(): Set<string> {
|
||
return new Set(enabledClis().flatMap((entry) => entry.env.allowedKeys));
|
||
}
|
||
|
||
/** Env var keys that are always blocked (security-sensitive) */
|
||
const BLOCKED_ENV_KEYS = new Set([
|
||
'PATH',
|
||
'LD_PRELOAD',
|
||
'LD_LIBRARY_PATH',
|
||
'NODE_OPTIONS',
|
||
'CODEMAN_MUX_NAME',
|
||
'CODEMAN_TMUX',
|
||
'OPENCODE_SERVER_PASSWORD', // Security-sensitive: server auth password
|
||
]);
|
||
|
||
/**
|
||
* Validate that an env var key is allowed.
|
||
*
|
||
* ⚠️ `BLOCKED_ENV_KEYS` is checked FIRST and is deliberately NOT registry-driven. It is a
|
||
* hard floor: a rogue or fat-fingered `allowedPrefixes` entry (say `''`, which prefixes
|
||
* everything) still cannot unblock PATH or LD_PRELOAD.
|
||
*/
|
||
function isAllowedEnvKey(key: string): boolean {
|
||
if (BLOCKED_ENV_KEYS.has(key)) return false;
|
||
if (allowedEnvKeys().has(key)) return true;
|
||
return allowedEnvPrefixes().some((prefix) => key.startsWith(prefix));
|
||
}
|
||
|
||
/** Zod schema for env overrides with allowlist enforcement */
|
||
const safeEnvOverridesSchema = z
|
||
.record(z.string(), z.string())
|
||
.optional()
|
||
.refine(
|
||
(val) => {
|
||
if (!val) return true;
|
||
return Object.keys(val).every(isAllowedEnvKey);
|
||
},
|
||
{
|
||
message:
|
||
'envOverrides contains blocked or disallowed env var keys. Only CLAUDE_CODE_*, OPENCODE_*, CODEX_*, GEMINI_*, GOOGLE_*, ANTIGRAVITY_*, PI_*, GROK_*, XAI_*, DSH_*, DEEPSEEK_*, OMP_*, COPILOT_* keys and CLAUDE_CONFIG_DIR are allowed.',
|
||
}
|
||
);
|
||
|
||
// ========== Effort Level ==========
|
||
|
||
/**
|
||
* Claude CLI effort level for new sessions. Injected as a `--settings` soft default
|
||
* (NOT the CLAUDE_CODE_EFFORT_LEVEL env var, which would hard-lock the session and
|
||
* block in-session `/effort` switching). `ultracode` enables dynamic workflow orchestration.
|
||
*/
|
||
const effortLevelSchema = z.enum(['low', 'medium', 'high', 'xhigh', 'max', 'ultracode']).optional();
|
||
|
||
/**
|
||
* Claude advisor model for new sessions: `fable`/`opus`/`sonnet` or a full model id in one of
|
||
* those families (isAdvisorModel). Merged into the launch `--settings` JSON as `advisorModel`,
|
||
* a soft default that /advisor still switches in-session. The allowlist is also the injection
|
||
* guard for the single-quoted `--settings` argument.
|
||
*/
|
||
const advisorModelSchema = z
|
||
.string()
|
||
.max(64)
|
||
.refine((value) => isAdvisorModel(value), {
|
||
message: 'advisorModel must be fable, opus, sonnet or a full claude-fable/opus/sonnet model id',
|
||
})
|
||
.optional();
|
||
|
||
// ========== Session Routes ==========
|
||
|
||
/**
|
||
* Schema for POST /api/sessions
|
||
* Creates a new session with optional working directory, mode, and name.
|
||
*/
|
||
/** Schema for OpenCode-specific configuration */
|
||
const OpenCodeConfigSchema = z
|
||
.object({
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/]+$/)
|
||
.optional(),
|
||
autoAllowTools: z.boolean().optional(),
|
||
continueSession: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9_-]+$/)
|
||
.optional(),
|
||
forkSession: z.boolean().optional(),
|
||
configContent: z
|
||
.string()
|
||
.max(10000)
|
||
.refine(
|
||
(val) => {
|
||
try {
|
||
JSON.parse(val);
|
||
return true;
|
||
} catch {
|
||
return false;
|
||
}
|
||
},
|
||
{ message: 'configContent must be valid JSON' }
|
||
)
|
||
.optional(),
|
||
})
|
||
.optional();
|
||
|
||
/** Schema for Codex (OpenAI CLI)-specific configuration */
|
||
const CodexConfigSchema = z
|
||
.object({
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/]+$/)
|
||
.optional(),
|
||
reasoningEffort: z.enum(CODEX_REASONING_EFFORTS).optional(),
|
||
resumeSessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9_-]+$/)
|
||
.optional(),
|
||
dangerouslyBypassApprovals: z.boolean().optional(),
|
||
networkAccess: z.boolean().optional(),
|
||
animations: z.boolean().optional(),
|
||
renderMode: z
|
||
.enum(['scrollback', 'hybrid'])
|
||
.optional()
|
||
.transform(() => 'hybrid' as const),
|
||
})
|
||
.optional();
|
||
|
||
/** Schema for Gemini CLI-specific configuration */
|
||
const GeminiConfigSchema = z
|
||
.object({
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/]+$/)
|
||
.optional(),
|
||
approvalMode: z.enum(['default', 'auto_edit', 'yolo', 'plan']).optional(),
|
||
resumeSession: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._-]+$/)
|
||
.optional(),
|
||
})
|
||
.optional();
|
||
|
||
/** Schema for Antigravity CLI (agy)-specific configuration */
|
||
const AntigravityConfigSchema = z
|
||
.object({
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/]+$/)
|
||
.optional(),
|
||
dangerouslySkipPermissions: z.boolean().optional(),
|
||
resumeConversationId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._-]+$/)
|
||
.optional(),
|
||
})
|
||
.optional();
|
||
|
||
/**
|
||
* Schema for Pi CLI (pi.dev)-specific configuration.
|
||
*
|
||
* No bypass field exists on purpose: pi has no permission prompts. The one
|
||
* privilege-shaped knob is the TRI-STATE `approveProjectTrust` (see PiConfig),
|
||
* which the multi-user clamp MATERIALIZES to `false` for non-granted owners.
|
||
*/
|
||
const PiConfigSchema = z
|
||
.object({
|
||
// `:` for a thinking suffix (`sonnet:high`), `/` for `provider/id`.
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/:]+$/)
|
||
.optional(),
|
||
provider: z
|
||
.string()
|
||
.max(50)
|
||
.regex(/^[a-z0-9-]+$/)
|
||
.optional(),
|
||
thinking: z.enum(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']).optional(),
|
||
continueSession: z.boolean().optional(),
|
||
resumeSessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._-]+$/)
|
||
.optional(),
|
||
approveProjectTrust: z.boolean().optional(),
|
||
})
|
||
.optional();
|
||
|
||
/**
|
||
* Schema for Grok Build CLI (xAI `grok`)-specific configuration.
|
||
*
|
||
* `alwaysApprove` maps to `--always-approve` (grok's bypassPermissions mode).
|
||
* An ABSENT config spawns bare `grok` = grok's own ask-mode default, so the
|
||
* multi-user clamp only needs the only-if-sent branch (like codex/antigravity).
|
||
*/
|
||
const GrokConfigSchema = z
|
||
.object({
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/]+$/)
|
||
.optional(),
|
||
alwaysApprove: z.boolean().optional(),
|
||
continueSession: z.boolean().optional(),
|
||
// Ids only: grok's --resume also matches session TITLES (arbitrary user
|
||
// strings), which this regex deliberately cannot express.
|
||
resumeSessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._-]+$/)
|
||
.optional(),
|
||
})
|
||
.optional();
|
||
|
||
const CopilotConfigSchema = z
|
||
.object({
|
||
// A leading alphanumeric, like resumeSessionId below: a value like `--yolo` would otherwise be read
|
||
// as its own flag after `--model` (bypassing the allowAll clamp). `/` stays for provider/id.
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._\-/]*$/)
|
||
.optional(),
|
||
allowAll: z.boolean().optional(),
|
||
continueSession: z.boolean().optional(),
|
||
// A single plain word with a leading alphanumeric: --resume also matches session NAMES, so
|
||
// `my-feature` is accepted, but a value like `--yolo` must not be, because --resume's value is
|
||
// optional and the next token would be read as its own flag (bypassing the allowAll clamp).
|
||
resumeSessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/)
|
||
.optional(),
|
||
})
|
||
.optional();
|
||
|
||
/**
|
||
* Schema for OMP CLI-specific configuration.
|
||
*/
|
||
const OmpConfigSchema = z
|
||
.object({
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/]+$/)
|
||
.optional(),
|
||
resumeSessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._-]+$/)
|
||
.optional(),
|
||
continueSession: z.boolean().optional(),
|
||
})
|
||
.optional();
|
||
|
||
/**
|
||
* Schema for DeepSeek Harness (`dsh`)-specific configuration.
|
||
*
|
||
* `permissionMode` maps to the `DSH_PERMISSION_MODE` env export, NOT to a flag —
|
||
* the harness has no command-line permission switch. An ABSENT config spawns the
|
||
* profile under the harness's own `workspace-write` default, which still asks
|
||
* for approval, so the multi-user clamp only needs the only-if-sent branch (like
|
||
* codex/antigravity/grok).
|
||
*
|
||
* `profile` is a directory name under `$DSH_HOME/profiles`, so it is constrained
|
||
* to a single path SEGMENT: no separators, no dots-only names. It is interpolated
|
||
* into the `bash -c "…"` spawn line and joined into a filesystem path, and this
|
||
* regex is what keeps both safe.
|
||
*/
|
||
const DeepSeekConfigSchema = z
|
||
.object({
|
||
profile: z
|
||
.string()
|
||
.min(1)
|
||
.max(64)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/)
|
||
.optional(),
|
||
permissionMode: z.enum(['read-only', 'workspace-write', 'danger-full-access']).optional(),
|
||
resumeSession: z.boolean().optional(),
|
||
resumeSessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._-]+$/)
|
||
.optional(),
|
||
statusReporting: z.boolean().optional(),
|
||
})
|
||
.optional();
|
||
|
||
/**
|
||
* Body of POST /api/deepseek/install-profile.
|
||
*
|
||
* `package` is a package SPECIFIER handed to `dsh plugin … add`, which runs a
|
||
* real package-manager install, so it is the security-relevant field. Two things
|
||
* contain it: this regex (an npm name, optionally scoped, optionally with an
|
||
* `@version` tail, and NOTHING else — no path, no URL, no git spec, no leading
|
||
* dash that could be read as a flag), and the route, which spawns an argv ARRAY
|
||
* with no shell. The route additionally requires the privileged grant in
|
||
* multi-user mode: installing a plugin is arbitrary code execution on the host,
|
||
* the same bar as a `shell` session.
|
||
*/
|
||
export const DeepSeekInstallProfileSchema = z
|
||
.object({
|
||
profile: z
|
||
.string()
|
||
.min(1)
|
||
.max(64)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/)
|
||
.optional(),
|
||
package: z
|
||
.string()
|
||
.min(1)
|
||
.max(214)
|
||
.regex(/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[a-zA-Z0-9][a-zA-Z0-9._-]*)?$/)
|
||
.optional(),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* POST /api/deepseek/web: start the background `dsh web` for one browser authority.
|
||
*
|
||
* `authority` becomes `--trusted-host`, which is what dsh fences its own `/api`
|
||
* behind, so it must be the origin the browser will actually load the tab from
|
||
* (`location.host`). It reaches a spawn as one element of an argv ARRAY, never a
|
||
* shell string, so this regex is defence in depth rather than the only guard: it
|
||
* admits host:port in the shapes a browser authority can take (dotted names,
|
||
* IPv4, bracketed IPv6) and nothing that could be read as a second argument.
|
||
*/
|
||
export const DeepSeekWebStartSchema = z
|
||
.object({
|
||
authority: z
|
||
.string()
|
||
.min(1)
|
||
.max(255)
|
||
.regex(/^(?:\[[0-9a-fA-F:]+\]|[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?)(?::\d{1,5})?$/),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* The session that spawned the one being created — pure UI decoration, drawn as a
|
||
* lineage line between the two tabs. Accepted here and, equivalently, as the
|
||
* `X-Codeman-Parent-Session` header (the agent skill sets that once on its shared
|
||
* curl invocation so every spawn recipe carries it); the body wins when both are
|
||
* present. `resolveParentSessionId()` in route-helpers.ts re-checks it against live
|
||
* sessions and DROPS anything it cannot resolve — a bad value must never fail a
|
||
* spawn, and this is never an ownership or permission signal.
|
||
*/
|
||
const parentSessionIdSchema = z.string().max(100).optional();
|
||
|
||
/**
|
||
* Tab group the new session should be placed in (the group's "New session"
|
||
* action). Advisory like parentSessionId: the layout service looks the id up in
|
||
* the creating owner's own layout and ignores one it cannot find, so a stale or
|
||
* foreign id never fails a spawn. A malformed value (null, empty, over-long) is
|
||
* still a 400, because only the browser sends it.
|
||
*/
|
||
const tabGroupIdSchema = z.string().min(1).max(100).optional();
|
||
|
||
export const CreateSessionSchema = z.object({
|
||
workingDir: safePathSchema.optional(),
|
||
mode: sessionModeSchema().optional(),
|
||
name: z.string().max(100).optional(),
|
||
/** Session that spawned this one — see parentSessionIdSchema. */
|
||
parentSessionId: parentSessionIdSchema,
|
||
/** Tab group to place the new session in: see tabGroupIdSchema. */
|
||
tabGroupId: tabGroupIdSchema,
|
||
envOverrides: safeEnvOverridesSchema,
|
||
/** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
|
||
effort: effortLevelSchema,
|
||
/** Claude advisor model (soft default via --settings, switchable in-session via /advisor) */
|
||
advisorModel: advisorModelSchema,
|
||
/** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
|
||
modelOverride: z.string().max(50).optional(),
|
||
/**
|
||
* Claude model for THIS session only, passed as `claude --model <id>`; nothing is written to
|
||
* disk. Wins over the app-wide default model. A subset of the registry's `model-claude`
|
||
* pattern, so a value accepted here is never rejected at launch. The first character must be
|
||
* a letter or digit: the value lands in argv, and no model id opens with `-`, so a
|
||
* flag-shaped value is refused here rather than left to the launch quoting. An empty string
|
||
* means no per-session model, as it does for `modelOverride`. Claude only: the route refuses
|
||
* it for any other CLI and on a remote attach.
|
||
*/
|
||
model: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._\-[\]]*$/)
|
||
.or(z.literal(''))
|
||
.optional(),
|
||
openCodeConfig: OpenCodeConfigSchema,
|
||
codexConfig: CodexConfigSchema,
|
||
geminiConfig: GeminiConfigSchema,
|
||
antigravityConfig: AntigravityConfigSchema,
|
||
piConfig: PiConfigSchema,
|
||
grokConfig: GrokConfigSchema,
|
||
copilotConfig: CopilotConfigSchema,
|
||
deepSeekConfig: DeepSeekConfigSchema,
|
||
ompConfig: OmpConfigSchema,
|
||
/** Resume a previous Claude conversation by its session ID (used for reboot recovery) */
|
||
resumeSessionId: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-f0-9-]+$/, 'resumeSessionId must be a valid UUID')
|
||
.optional(),
|
||
/**
|
||
* COD-105 — attach to an EXISTING remote tmux session discovered via
|
||
* `GET /api/remote-hosts/:hostId/sessions` (one this Codeman didn't create).
|
||
* The resulting session is NON-owned (closing it detaches, never kills the
|
||
* remote). `remoteSessionName` is a discovered `codeman-*` tmux session name.
|
||
*/
|
||
attachRemoteSession: z
|
||
.object({
|
||
hostId: z.string().min(1).max(200),
|
||
remoteSessionName: z
|
||
.string()
|
||
.min(1)
|
||
.max(200)
|
||
.regex(/^codeman-[a-zA-Z0-9._-]+$/, 'remoteSessionName must be a codeman-* tmux session name'),
|
||
})
|
||
.optional(),
|
||
});
|
||
|
||
/**
|
||
* Schema for POST /api/sessions/:id/run
|
||
* Runs a prompt in a session.
|
||
*/
|
||
export const RunPromptSchema = z.object({
|
||
prompt: z.string().min(1).max(100000),
|
||
});
|
||
|
||
/**
|
||
* Schema for POST /api/sessions/:id/resize
|
||
* Resizes a session's terminal.
|
||
*/
|
||
export const ResizeSchema = z.object({
|
||
cols: z.number().int().min(1).max(500),
|
||
rows: z.number().int().min(1).max(200),
|
||
viewportType: z.enum(['mobile', 'tablet', 'desktop']).optional(),
|
||
force: z.boolean().optional(),
|
||
});
|
||
|
||
/**
|
||
* Schema for POST /api/status-telemetry
|
||
* Claude Code statusline payload forwarded by the Codeman-managed statusLine
|
||
* exporter (see hooks-config.generateStatusLineCommand). Validates only the
|
||
* subset Codeman displays; unknown keys (session_id, transcript_path, cwd, …)
|
||
* are stripped by z.object. Auth-exempt like /api/hook-event.
|
||
*/
|
||
// NOTE: every modeled field is `.nullish()` (not `.optional()`) on purpose.
|
||
// Claude's statusline blob is officially shipped but undocumented in exact
|
||
// shape, and `z.optional()` REJECTS an explicit `null` (accepts only
|
||
// `undefined`) — a single stray `null` (e.g. `cost:{total_cost_usd:null}`)
|
||
// would 400 the ENTIRE POST before the deliberately-tolerant parser
|
||
// (usage-telemetry.ts, which only acts on `typeof === 'number'/'string'`) ever
|
||
// runs, silently killing the chip's data feed. `.nullish()` keeps the schema
|
||
// gate as forgiving as the parser it guards.
|
||
const RateLimitWindowSchema = z
|
||
.object({
|
||
used_percentage: z.number().nullish(),
|
||
resets_at: z.number().nullish(),
|
||
})
|
||
.nullish();
|
||
|
||
export const StatusTelemetrySchema = z.object({
|
||
sessionId: z.string().min(1).max(100),
|
||
data: z
|
||
.object({
|
||
rate_limits: z
|
||
.object({
|
||
five_hour: RateLimitWindowSchema,
|
||
seven_day: RateLimitWindowSchema,
|
||
})
|
||
.nullish(),
|
||
context_window: z
|
||
.object({
|
||
used_percentage: z.number().nullish(),
|
||
total_input_tokens: z.number().nullish(),
|
||
total_output_tokens: z.number().nullish(),
|
||
})
|
||
.nullish(),
|
||
cost: z.object({ total_cost_usd: z.number().nullish() }).nullish(),
|
||
model: z.object({ display_name: z.string().max(100).nullish() }).nullish(),
|
||
// Main-conversation prompt-cache statistics (Claude Code v2.1.251+). Every documented
|
||
// scalar field is listed nullish: `expires_at`/`hit_ratio`/`last_miss_at`/
|
||
// `recache_tokens_if_cold` are all documented as possibly null, and the object gains
|
||
// fields over CLI versions, so a stricter shape would 400 the whole post and blank the
|
||
// footer (the recurring .optional()/null trap). Causes stay `unknown` (the parser keeps
|
||
// the strings); `last_miss_cause`'s extra numeric keys and the `miss_causes` record are
|
||
// stripped by Zod unread, which keeps the stored object bounded — a hostile localhost
|
||
// payload cannot bloat state, since only the normalized subset below is ever stored.
|
||
prompt_cache: z
|
||
.object({
|
||
warm: z.boolean().nullish(),
|
||
caching_observed: z.boolean().nullish(),
|
||
// No length cap: a future TTL longer than today's `5m`/`1h` must not 400 the whole
|
||
// post and blank the footer. parsePromptCache discards any TTL it does not know, so
|
||
// the stored value stays bounded to those two regardless.
|
||
ttl: z.string().nullish(),
|
||
expires_at: z.number().nullish(),
|
||
requests: z.number().nullish(),
|
||
misses: z.number().nullish(),
|
||
expected_rebuilds: z.number().nullish(),
|
||
hit_ratio: z.number().nullish(),
|
||
cache_write_tokens: z.number().nullish(),
|
||
miss_recache_tokens: z.number().nullish(),
|
||
last_miss_at: z.number().nullish(),
|
||
recache_tokens_if_cold: z.number().nullish(),
|
||
// Keep the first 20 causes instead of 400-ing the whole post (which also drops the
|
||
// footer, the plan chip and the model report it carries) when Claude Code reports more. The
|
||
// preprocess slices BEFORE the array validates, so an over-long array costs one bounded
|
||
// slice, never per-element validation across every entry (parsePromptCache then keeps
|
||
// the string ones among those 20).
|
||
last_miss_cause: z
|
||
.object({
|
||
causes: z.preprocess((v) => (Array.isArray(v) ? v.slice(0, 20) : v), z.array(z.unknown()).nullish()),
|
||
})
|
||
.nullish(),
|
||
})
|
||
.nullish(),
|
||
})
|
||
.nullish(),
|
||
});
|
||
|
||
// ========== Case Routes ==========
|
||
|
||
/**
|
||
* Schema for POST /api/cases
|
||
* Creates a new case folder.
|
||
*/
|
||
export const CreateCaseSchema = z.object({
|
||
name: z
|
||
.string()
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format. Use only letters, numbers, hyphens, underscores.'),
|
||
description: z.string().max(1000).optional(),
|
||
/**
|
||
* Create the case in this folder instead of under the cases directory. Absolute, or starting with
|
||
* `~`. Only length-bounded here: what makes it acceptable (shape, blocked trees, symlinks, an
|
||
* existing folder with contents) is judged by `prepareNewCasePath()` in web/case-path.ts, which
|
||
* also produces the user-facing reason.
|
||
*/
|
||
path: z.string().min(1).max(1000).optional(),
|
||
});
|
||
|
||
/**
|
||
* Schema for POST /api/cases/clone — issue #236.
|
||
*
|
||
* `repository` is only length-bounded here on purpose: what makes an operand safe
|
||
* is the transport/shape analysis in `parseGitRepositoryUrl` (which also produces
|
||
* the user-facing rejection reason), and duplicating a weaker version of that as a
|
||
* regex would be the copy that drifts. The route parses before touching git.
|
||
*/
|
||
export const CloneCaseSchema = z.object({
|
||
name: z
|
||
.string()
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format. Use only letters, numbers, hyphens, underscores.'),
|
||
repository: z.string().min(1).max(2048),
|
||
/** Branch or tag → `--branch <ref> --single-branch`. */
|
||
ref: z.string().min(1).max(200).optional(),
|
||
/** `--depth 1`. */
|
||
shallow: z.boolean().optional(),
|
||
description: z.string().max(1000).optional(),
|
||
/**
|
||
* Clone into this exact folder (the folder itself, no case-name subfolder is added) instead of under the cases directory, and
|
||
* register it as a linked case. Absolute or starting with `~`; only length-bounded here, since
|
||
* `prepareNewCasePath()` (web/case-path.ts) judges it and produces the user-facing reason.
|
||
*/
|
||
path: z.string().min(1).max(1000).optional(),
|
||
});
|
||
|
||
/** Schema for POST /api/cases/clone-preflight — ask the remote what it has, clone nothing. */
|
||
export const ClonePreflightSchema = z.object({
|
||
repository: z.string().min(1).max(2048),
|
||
});
|
||
|
||
// ========== Git worktrees of a case (src/git-worktrees.ts) ==========
|
||
|
||
/**
|
||
* A worktree name: one segment of letters, digits, `.`, `_`, `-`, starting with a letter or
|
||
* digit, at most 64 characters (Claude Code's own `--worktree` limit). The finer rules (no `..`,
|
||
* no trailing `.lock`) are `worktreeNameError()`, which every route applies after this.
|
||
*/
|
||
const worktreeNameSchema = z
|
||
.string()
|
||
.min(1)
|
||
.max(64)
|
||
.regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'Invalid worktree name. Use letters, digits, ".", "_" and "-".');
|
||
|
||
/** Schema for POST /api/cases/:name/worktrees: a new worktree on a new branch. */
|
||
export const CreateWorktreeSchema = z.object({
|
||
name: worktreeNameSchema,
|
||
/** New branch name; default `worktree-<name>`, Claude Code's convention. */
|
||
branch: z.string().min(1).max(200).optional(),
|
||
/** Start point (branch, tag or commit); default the case's current HEAD. */
|
||
base: z.string().min(1).max(200).optional(),
|
||
});
|
||
|
||
/** Query of DELETE /api/cases/:name/worktrees/:worktree. */
|
||
export const RemoveWorktreeQuerySchema = z.object({
|
||
/** Also `git branch -d` the worktree's branch (never `-D`). */
|
||
deleteBranch: z.enum(['true', 'false', '1', '0']).optional(),
|
||
});
|
||
|
||
const RemoteCommandOverridesSchema = z
|
||
.object({
|
||
shell: z.string().min(1).max(300).optional(),
|
||
claude: z.string().min(1).max(300).optional(),
|
||
opencode: z.string().min(1).max(300).optional(),
|
||
codex: z.string().min(1).max(300).optional(),
|
||
gemini: z.string().min(1).max(300).optional(),
|
||
antigravity: z.string().min(1).max(300).optional(),
|
||
pi: z.string().min(1).max(300).optional(),
|
||
grok: z.string().min(1).max(300).optional(),
|
||
deepseek: z.string().min(1).max(300).optional(),
|
||
omp: z.string().min(1).max(300).optional(),
|
||
copilot: z.string().min(1).max(300).optional(),
|
||
})
|
||
.strict()
|
||
.optional();
|
||
|
||
// COD-107 — advanced SSH connection options. These ultimately exec as shell
|
||
// (ProxyCommand etc.), but are OPERATOR-entered host config (never attacker- or
|
||
// terminal-output-influenced), so we validate as defense-in-depth, not as the
|
||
// security boundary. Reject newline/NUL/backtick/`$(` shell-injection vectors.
|
||
const NO_SHELL_INJECTION = /^[^\n\r\0`]*$/;
|
||
const noCommandSubstitution = (s: string) => !s.includes('$(');
|
||
|
||
// `remotePath`/`identityFile` are shell-escaped, and a remote launch reaches `bash -c`
|
||
// single-quoted (`bashCArg()` in tmux-manager). They are also pasted into strings the
|
||
// far end's shells parse, and hosts stored before a launch-quoting change are read with
|
||
// no schema, so `$` and backtick (and newline/CR/NUL) stay rejected at the boundary as
|
||
// defense in depth, whatever the current quoting does with them.
|
||
const NO_SHELL_META = /^[^\n\r\0`$]*$/;
|
||
|
||
export const RemoteHostSchema = z.object({
|
||
id: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid remote host id'),
|
||
label: z.string().min(1).max(100),
|
||
host: z
|
||
.string()
|
||
.min(1)
|
||
.max(255)
|
||
.regex(/^[a-zA-Z0-9._:-]+$/, 'Invalid SSH host'),
|
||
username: z
|
||
.string()
|
||
.min(1)
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._-]+$/, 'Invalid SSH username'),
|
||
port: z.number().int().min(1).max(65535).optional(),
|
||
// Identity (private-key) file PATH only — never key bytes. Reject shell
|
||
// metacharacters ($, backtick) that survive into the `bash -c` launch layer.
|
||
identityFile: z.string().min(1).max(4096).regex(NO_SHELL_META, 'Invalid identity file path').optional(),
|
||
// SOCKS5 proxy as host:port (e.g. 127.0.0.1:1080).
|
||
socksProxy: z
|
||
.string()
|
||
.regex(/^[\w.-]+:\d{1,5}$/, 'SOCKS proxy must be host:port')
|
||
.optional(),
|
||
// SSH jump host: a comma-separated chain of [user@]host[:port] hops. Structural
|
||
// ALLOWLIST (not an open denylist) — only chars valid in user/host/port/IPv6,
|
||
// so no shell metacharacter (;, |, &, space, $, quotes, …) can appear. The value
|
||
// is also shellescaped at command-build time (buildSshConnectionArgs); this is the
|
||
// belt to that suspenders.
|
||
jumpHost: z
|
||
.string()
|
||
.min(1)
|
||
.max(255)
|
||
.regex(
|
||
/^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9.:[\]-]+(?::\d{1,5})?(?:,(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9.:[\]-]+(?::\d{1,5})?)*$/,
|
||
'Jump host must be [user@]host[:port] (comma-separated for multiple hops)'
|
||
)
|
||
.optional(),
|
||
// Arbitrary extra -o KEY=VALUE options (escape hatch); each must be KEY=VALUE.
|
||
extraSshOptions: z
|
||
.array(
|
||
z
|
||
.string()
|
||
.min(3)
|
||
.max(1024)
|
||
.regex(/^[A-Za-z][A-Za-z0-9]*=.+$/, 'Extra SSH option must be KEY=VALUE')
|
||
.regex(NO_SHELL_INJECTION, 'Invalid characters in SSH option')
|
||
.refine(noCommandSubstitution, 'Invalid characters in SSH option')
|
||
)
|
||
.max(32)
|
||
.optional(),
|
||
commands: RemoteCommandOverridesSchema,
|
||
// Wake-on-LAN: a single executable path (no arguments, no shell) run to power a
|
||
// SLEEPING host back on, e.g. `/home/joe/bin/whuff`. Executed via spawn without
|
||
// a shell, so there is no shell layer to escape; the regexes are belt-and-braces
|
||
// (and the no-whitespace rule rejects an argument list before it can fail as a
|
||
// confusing ENOENT at wake time). See docs/remote-sessions.md §Wake-on-LAN.
|
||
wakeCommand: z
|
||
.string()
|
||
.min(1)
|
||
.max(4096)
|
||
.regex(/^\S+$/, 'Wake command must be a single executable path (no arguments)')
|
||
.regex(NO_SHELL_META, 'Invalid characters in wake command')
|
||
.optional(),
|
||
// Wake-on-LAN MAC address(es), comma-separated. Structural: only hex pairs with
|
||
// `:`/`-` separators, so nothing here can be a shell token even by accident (the
|
||
// value never reaches a shell — Codeman builds the magic packet itself).
|
||
wakeMac: z
|
||
.string()
|
||
.min(11)
|
||
.max(128)
|
||
.regex(
|
||
/^[0-9a-fA-F]{2}([:-][0-9a-fA-F]{2}){5}(\s*,\s*[0-9a-fA-F]{2}([:-][0-9a-fA-F]{2}){5})*$/,
|
||
'Wake MAC must be one or more MAC addresses, comma-separated'
|
||
)
|
||
// ⚠ The character cap admits seven MACs while parseMacList takes at most
|
||
// MAX_WAKE_MACS, all-or-nothing. Without this the extra ones validated, persisted,
|
||
// and then resolved to NO wake target, so the host read as unconfigured.
|
||
.refine((value) => value.split(',').length <= MAX_WAKE_MACS, {
|
||
message: `Wake MAC accepts at most ${MAX_WAKE_MACS} comma-separated addresses`,
|
||
})
|
||
.optional(),
|
||
});
|
||
|
||
export const RemoteCaseLinkSchema = z.object({
|
||
name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
|
||
hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid remote host id'),
|
||
remotePath: z
|
||
.string()
|
||
.min(1)
|
||
.max(2000)
|
||
.regex(/^\//, 'Remote path must be absolute')
|
||
.regex(NO_SHELL_META, 'Invalid characters in remote path'),
|
||
});
|
||
|
||
// ========== Docker cases ==========
|
||
//
|
||
// Docker mode is a location overlay on cases (see docs/docker-cases-plan.md),
|
||
// the analog of the remote-SSH schemas above. `image`, `hostWorkspacePath`,
|
||
// `containerWorkdir`, and `container` all reach the `bash -c` launch layer, so they
|
||
// carry NO_SHELL_META (rejects `$`/backtick) exactly like remotePath/identityFile.
|
||
// `--privileged` and any docker-socket mount are structurally unrepresentable
|
||
// (never accepted).
|
||
|
||
const DockerResourceLimitsSchema = z
|
||
.object({
|
||
memory: z
|
||
.string()
|
||
.regex(/^\d+[bkmg]?$/i, 'Memory must be like 512m / 4g')
|
||
.optional(),
|
||
cpus: z
|
||
.string()
|
||
.regex(/^\d+(\.\d+)?$/, 'CPUs must be a number')
|
||
.optional(),
|
||
pidsLimit: z.number().int().positive().max(100000).optional(),
|
||
nofile: z
|
||
.string()
|
||
.regex(/^\d+:\d+$/, 'nofile must be soft:hard')
|
||
.optional(),
|
||
shmSize: z
|
||
.string()
|
||
.regex(/^\d+[bkmg]?$/i, 'shm-size must be like 256m')
|
||
.optional(),
|
||
})
|
||
.strict();
|
||
|
||
export const DockerHostSchema = z.object({
|
||
id: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
|
||
label: z.string().min(1).max(100),
|
||
engine: z.enum(['docker', 'podman']).optional(),
|
||
image: z
|
||
.string()
|
||
.min(1)
|
||
.max(512)
|
||
.regex(/^[a-zA-Z0-9][\w./:@-]*$/, 'Invalid image reference')
|
||
.regex(NO_SHELL_META, 'Invalid characters in image reference'),
|
||
daemonHost: z.string().max(512).regex(NO_SHELL_META, 'Invalid daemon host').optional(),
|
||
context: z
|
||
.string()
|
||
.max(128)
|
||
.regex(/^[a-zA-Z0-9._-]+$/, 'Invalid docker context')
|
||
.optional(),
|
||
network: z.enum(['bridge', 'none', 'custom']).optional(),
|
||
networkName: z
|
||
.string()
|
||
.max(128)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid network name')
|
||
.optional(),
|
||
resources: DockerResourceLimitsSchema.optional(),
|
||
gpus: z
|
||
.string()
|
||
.max(128)
|
||
.regex(/^(all|\d+|device=[a-zA-Z0-9,:._-]+)$/, 'GPUs must be all / a count / device=...')
|
||
.optional(),
|
||
mountCredentials: z.boolean().optional(),
|
||
hooksEnabled: z.boolean().optional(),
|
||
resumeOnStart: z.boolean().optional(),
|
||
commands: RemoteCommandOverridesSchema, // same shell/claude/opencode/codex/gemini/antigravity shape
|
||
extraCreateArgs: z
|
||
.array(
|
||
z
|
||
.string()
|
||
.min(1)
|
||
.max(1024)
|
||
.regex(NO_SHELL_INJECTION, 'Invalid characters in create arg')
|
||
.refine(noCommandSubstitution, 'Invalid characters in create arg')
|
||
)
|
||
.max(32)
|
||
.optional(),
|
||
extraExecArgs: z
|
||
.array(
|
||
z
|
||
.string()
|
||
.min(1)
|
||
.max(1024)
|
||
.regex(NO_SHELL_INJECTION, 'Invalid characters in exec arg')
|
||
.refine(noCommandSubstitution, 'Invalid characters in exec arg')
|
||
)
|
||
.max(32)
|
||
.optional(),
|
||
});
|
||
|
||
export const DockerCaseLinkSchema = z.object({
|
||
name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
|
||
hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
|
||
// No commas: the path is embedded in a `--mount type=bind,src=<path>,dst=<path>`
|
||
// CSV spec, and docker's --mount parser splits fields on commas (shell escaping
|
||
// cannot protect it). Spaces are fine.
|
||
hostWorkspacePath: z
|
||
.string()
|
||
.min(1)
|
||
.max(2000)
|
||
.regex(/^\//, 'Workspace path must be absolute')
|
||
.regex(/^[^,]*$/, 'Workspace path must not contain commas (docker --mount is comma-delimited)')
|
||
.regex(NO_SHELL_META, 'Invalid characters in workspace path'),
|
||
containerWorkdir: z
|
||
.string()
|
||
.min(1)
|
||
.max(2000)
|
||
.regex(/^\//, 'Container workdir must be absolute')
|
||
.regex(/^[^,]*$/, 'Container workdir must not contain commas (docker --mount is comma-delimited)')
|
||
.regex(NO_SHELL_META, 'Invalid characters in container workdir')
|
||
.optional(),
|
||
container: z
|
||
.string()
|
||
.min(2)
|
||
.max(128)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name')
|
||
.optional(),
|
||
});
|
||
|
||
/**
|
||
* ADOPT an already-running container the user built and runs themselves. The
|
||
* container name is REQUIRED (there is nothing to derive it from — we are not
|
||
* creating it), and `hostWorkspacePath` still points at real host bytes so the
|
||
* file routes, watchers and transcript correlation keep working exactly as they
|
||
* do for an owned case. Everything that only makes sense at container-create
|
||
* time (image, network, resources, gpus, credential mounts) is deliberately
|
||
* absent: adoption never runs `docker create`.
|
||
*/
|
||
export const DockerCaseAdoptSchema = z.object({
|
||
name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
|
||
hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
|
||
container: z
|
||
.string()
|
||
.min(2)
|
||
.max(128)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'),
|
||
hostWorkspacePath: z
|
||
.string()
|
||
.min(1)
|
||
.max(2000)
|
||
.regex(/^\//, 'Workspace path must be absolute')
|
||
.regex(/^[^,]*$/, 'Workspace path must not contain commas (docker --mount is comma-delimited)')
|
||
.regex(NO_SHELL_META, 'Invalid characters in workspace path'),
|
||
containerWorkdir: z
|
||
.string()
|
||
.min(1)
|
||
.max(2000)
|
||
.regex(/^\//, 'Container workdir must be absolute')
|
||
.regex(/^[^,]*$/, 'Container workdir must not contain commas (docker --mount is comma-delimited)')
|
||
.regex(NO_SHELL_META, 'Invalid characters in container workdir')
|
||
.optional(),
|
||
});
|
||
|
||
/** Read-only adoption preflight: report on an existing container, link nothing. */
|
||
export const DockerAdoptPreflightSchema = z.object({
|
||
hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
|
||
container: z
|
||
.string()
|
||
.min(2)
|
||
.max(128)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'),
|
||
/** Optional: also verify this path exists INSIDE the container. */
|
||
containerWorkdir: z
|
||
.string()
|
||
.min(1)
|
||
.max(2000)
|
||
.regex(/^\//, 'Container workdir must be absolute')
|
||
.regex(NO_SHELL_META, 'Invalid characters in container workdir')
|
||
.optional(),
|
||
});
|
||
|
||
/** Read-only directory listing inside a container (adoption workdir picker). */
|
||
export const DockerBrowseSchema = z.object({
|
||
hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid docker host id'),
|
||
container: z
|
||
.string()
|
||
.min(2)
|
||
.max(128)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid container name'),
|
||
path: z
|
||
.string()
|
||
.max(2000)
|
||
.regex(/^\//, 'Path must be absolute')
|
||
.regex(NO_SHELL_META, 'Invalid characters in path')
|
||
.optional(),
|
||
});
|
||
|
||
export const DockerExportSchema = z.object({
|
||
mode: z.enum(['full', 'workspace']).optional(),
|
||
});
|
||
|
||
export const DockerImportSchema = z.object({
|
||
// A bare filename resolved WITHIN the exports dir (never an arbitrary path).
|
||
bundle: z
|
||
.string()
|
||
.min(1)
|
||
.max(300)
|
||
.regex(/^[a-zA-Z0-9._-]+\.tgz$/, 'Invalid bundle filename'),
|
||
newCaseName: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
|
||
destWorkspacePath: z
|
||
.string()
|
||
.min(1)
|
||
.max(2000)
|
||
.regex(/^\//, 'Destination path must be absolute')
|
||
.regex(/^[^,]*$/, 'Destination path must not contain commas (docker --mount is comma-delimited)')
|
||
.regex(NO_SHELL_META, 'Invalid characters in destination path'),
|
||
});
|
||
|
||
// One-click "Run in Docker" case creation. name/description behave like a normal
|
||
// case; the docker fields are OPTIONAL overrides of the predefined defaults (the
|
||
// checkbox alone, with no overrides, uses the shared `default` host).
|
||
export const DockerQuickCreateSchema = z.object({
|
||
name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
|
||
description: z.string().max(1000).optional(),
|
||
image: z
|
||
.string()
|
||
.min(1)
|
||
.max(512)
|
||
.regex(/^[a-zA-Z0-9][\w./:@-]*$/, 'Invalid image reference')
|
||
.regex(NO_SHELL_META, 'Invalid characters in image reference')
|
||
.optional(),
|
||
network: z.enum(['bridge', 'none', 'custom']).optional(),
|
||
networkName: z
|
||
.string()
|
||
.max(128)
|
||
.regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]+$/, 'Invalid network name')
|
||
.optional(),
|
||
memory: z
|
||
.string()
|
||
.regex(/^\d+[bkmg]?$/i, 'Memory must be like 512m / 4g')
|
||
.optional(),
|
||
cpus: z
|
||
.string()
|
||
.regex(/^\d+(\.\d+)?$/, 'CPUs must be a number')
|
||
.optional(),
|
||
gpus: z
|
||
.string()
|
||
.max(128)
|
||
.regex(/^(all|\d+|device=[a-zA-Z0-9,:._-]+)$/, 'GPUs must be all / a count / device=...')
|
||
.optional(),
|
||
mountCredentials: z.boolean().optional(),
|
||
});
|
||
|
||
// ========== Quick Start ==========
|
||
|
||
/**
|
||
* Schema for POST /api/quick-start
|
||
* Creates case (if needed) and starts interactive session.
|
||
*/
|
||
export const QuickStartSchema = z.object({
|
||
caseName: z
|
||
.string()
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format. Use only letters, numbers, hyphens, underscores.')
|
||
.optional(),
|
||
/** Display name for the created session tab (e.g. w1-mycase). Cosmetic; the durable
|
||
* mux/container names derive from the session id, not this. Defaults server-side. */
|
||
sessionName: z.string().max(128).optional(),
|
||
/** Session that spawned this one — see parentSessionIdSchema. */
|
||
parentSessionId: parentSessionIdSchema,
|
||
/** Tab group to place the new session in: see tabGroupIdSchema. */
|
||
tabGroupId: tabGroupIdSchema,
|
||
/**
|
||
* Start the session in this git worktree of the case (`<case>/.claude/worktrees/<worktree>`,
|
||
* created through POST /api/cases/:name/worktrees) instead of the case folder. Local cases
|
||
* only: refused (400) for remote and Docker cases. The worktree must be a registered worktree
|
||
* of the case's repository; it is never created here.
|
||
*/
|
||
worktree: worktreeNameSchema.optional(),
|
||
/** Model override written to <case>/.claude/settings.local.json (e.g. "opus[1m]").
|
||
* Empty string clears. Applied for local AND docker cases (the docker workspace is
|
||
* a real host dir, so the settings file crosses the bind mount); rejected for
|
||
* remote cases (the file would be written on the WRONG machine). */
|
||
modelOverride: z.string().max(50).optional(),
|
||
mode: sessionModeSchema().optional(),
|
||
openCodeConfig: OpenCodeConfigSchema,
|
||
codexConfig: CodexConfigSchema,
|
||
geminiConfig: GeminiConfigSchema,
|
||
antigravityConfig: AntigravityConfigSchema,
|
||
piConfig: PiConfigSchema,
|
||
grokConfig: GrokConfigSchema,
|
||
copilotConfig: CopilotConfigSchema,
|
||
deepSeekConfig: DeepSeekConfigSchema,
|
||
ompConfig: OmpConfigSchema,
|
||
envOverrides: safeEnvOverridesSchema,
|
||
/** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
|
||
effort: effortLevelSchema,
|
||
/** Claude advisor model (soft default via --settings, switchable in-session via /advisor) */
|
||
advisorModel: advisorModelSchema,
|
||
/**
|
||
* Who is spawning this worker (`codeman-skill` from the packaged agent skill), or,
|
||
* equivalently, the `X-Codeman-Agent-Origin` header; the body wins when both are
|
||
* present. Used ONLY to label a case directory this request CREATES as an agent
|
||
* scratch workspace, so it can be found and cleaned up later — see
|
||
* `src/agent-case-marker.ts`. Never a permission signal, and an unrecognised token
|
||
* is dropped rather than rejected. `POST /api/sessions` has no equivalent field
|
||
* because it takes an existing `workingDir` and so never creates a directory to label.
|
||
*/
|
||
agentOrigin: z.string().max(64).optional(),
|
||
/**
|
||
* Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md): launches directly
|
||
* on this saved endpoint/model instead of the mode's native backend, computed server-side
|
||
* from the admin-configured endpoint store the same way `POST /api/sessions/:id/custom-
|
||
* model` does — never trusting raw env values from the client. One-shot, launch-time
|
||
* equivalent of that route: no restart, so no visible relaunch (that route's restart-in-
|
||
* place is still what an ALREADY-RUNNING session uses to switch later). Rejected for
|
||
* remote/docker cases, same reasoning as `envOverrides` above. The three confirmation
|
||
* flags mirror that route's fields; see `SessionCustomModelSchema` for why there are
|
||
* two specific ones rather than the single legacy `confirmed`.
|
||
*/
|
||
customModel: z
|
||
.object({
|
||
endpointId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid endpoint id'),
|
||
modelId: z.string().min(1).max(200),
|
||
confirmed: z.boolean().optional(),
|
||
confirmedContext: z.boolean().optional(),
|
||
confirmedSwap: z.boolean().optional(),
|
||
})
|
||
.strict()
|
||
.optional(),
|
||
});
|
||
|
||
// ========== Hook Events ==========
|
||
|
||
/**
|
||
* Schema for POST /api/hook-event
|
||
* Receives Claude Code hook events.
|
||
*/
|
||
export const HookEventSchema = z.object({
|
||
event: z.enum([
|
||
'permission_prompt',
|
||
'elicitation_dialog',
|
||
'elicitation_complete',
|
||
'elicitation_response',
|
||
'idle_prompt',
|
||
'stop',
|
||
'teammate_idle',
|
||
'task_completed',
|
||
// Claude Code's UserPromptSubmit: a first-hand report of the pane's live
|
||
// conversation id. Keep in step with HookEventType in types/api.ts.
|
||
'prompt_submitted',
|
||
// A turn STARTED. Unlike the others this one has no Claude Code hook behind
|
||
// it: it is reported by the DeepSeek Harness status shim, and exists so a
|
||
// dialog answered in the terminal resolves its Approvals Inbox item at once
|
||
// instead of lingering red until the next `stop`.
|
||
'agent_working',
|
||
]),
|
||
sessionId: z.string().min(1),
|
||
data: z.record(z.string(), z.unknown()).nullable().optional(),
|
||
});
|
||
|
||
/**
|
||
* Body of POST /api/approvals/:id/answer (Approvals Inbox).
|
||
* `option` digits are additionally validated against the item's PARSED options
|
||
* in the route; the schema alone must not authorize blind digit-poking.
|
||
*/
|
||
export const ApprovalAnswerSchema = z
|
||
.object({
|
||
action: z.enum(['approve', 'deny', 'option', 'text']),
|
||
option: z.number().int().min(1).max(9).optional(),
|
||
text: z.string().min(1).max(4000).optional(),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* Body of PUT /api/sessions/:id/intent (Read My Mind). The 8192 cap mirrors
|
||
* MAX_GOALS_CHARS in intent-store.ts.
|
||
*/
|
||
export const IntentGoalsSchema = z
|
||
.object({
|
||
goals: z.string().max(8192),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* Body of POST /api/sessions/:id/readmymind (Read My Mind predict). Both
|
||
* fields are the Rethink flow: `rejected` carries suggestions the user
|
||
* dismissed (strong negative signal, fed back verbatim), `steer` an optional
|
||
* free-text correction ("no, I meant the mobile bug").
|
||
*/
|
||
export const ReadMyMindPredictSchema = z
|
||
.object({
|
||
steer: z.string().max(2000).optional(),
|
||
rejected: z.array(z.string().max(1000)).max(10).optional(),
|
||
})
|
||
.strict();
|
||
|
||
// ========== Configuration ==========
|
||
|
||
/**
|
||
* Schema for respawn configuration (partial updates allowed)
|
||
* Used in PUT /api/config and respawn endpoints.
|
||
*/
|
||
export const RespawnConfigSchema = z.object({
|
||
idleTimeoutMs: z.number().int().min(1000).max(600000).optional(),
|
||
updatePrompt: z.string().max(10000).optional(),
|
||
interStepDelayMs: z.number().int().min(100).max(60000).optional(),
|
||
enabled: z.boolean().optional(),
|
||
sendClear: z.boolean().optional(),
|
||
sendInit: z.boolean().optional(),
|
||
kickstartPrompt: z.string().max(10000).optional(),
|
||
completionConfirmMs: z.number().int().min(1000).max(60000).optional(),
|
||
noOutputTimeoutMs: z.number().int().min(5000).max(600000).optional(),
|
||
autoAcceptPrompts: z.boolean().optional(),
|
||
autoAcceptDelayMs: z.number().int().min(1000).max(60000).optional(),
|
||
aiIdleCheckEnabled: z.boolean().optional(),
|
||
aiIdleCheckModel: z.string().max(100).optional(),
|
||
aiIdleCheckMaxContext: z.number().int().min(1000).max(500000).optional(),
|
||
aiIdleCheckTimeoutMs: z.number().int().min(10000).max(300000).optional(),
|
||
aiIdleCheckCooldownMs: z.number().int().min(1000).max(300000).optional(),
|
||
aiPlanCheckEnabled: z.boolean().optional(),
|
||
aiPlanCheckModel: z.string().max(100).optional(),
|
||
aiPlanCheckMaxContext: z.number().int().min(1000).max(500000).optional(),
|
||
aiPlanCheckTimeoutMs: z.number().int().min(10000).max(300000).optional(),
|
||
aiPlanCheckCooldownMs: z.number().int().min(1000).max(300000).optional(),
|
||
adaptiveTimingEnabled: z.boolean().optional(),
|
||
adaptiveMinConfirmMs: z.number().int().min(1000).max(60000).optional(),
|
||
adaptiveMaxConfirmMs: z.number().int().min(1000).max(600000).optional(),
|
||
skipClearWhenLowContext: z.boolean().optional(),
|
||
skipClearThresholdPercent: z.number().int().min(0).max(100).optional(),
|
||
});
|
||
|
||
/**
|
||
* Schema for PUT /api/config
|
||
* Updates application configuration with whitelist of allowed fields.
|
||
*/
|
||
export const ConfigUpdateSchema = z
|
||
.object({
|
||
pollIntervalMs: z.number().int().min(100).max(60000).optional(),
|
||
defaultTimeoutMs: z.number().int().min(1000).max(3600000).optional(),
|
||
maxConcurrentSessions: z.number().int().min(1).max(50).optional(),
|
||
respawn: RespawnConfigSchema.optional(),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* Schema for PUT /api/settings
|
||
* Explicit allowlist of known settings fields — prevents arbitrary key persistence.
|
||
*/
|
||
const NotificationEventSchema = z
|
||
.object({
|
||
enabled: z.boolean().optional(),
|
||
browser: z.boolean().optional(),
|
||
audio: z.boolean().optional(),
|
||
push: z.boolean().optional(),
|
||
})
|
||
.optional();
|
||
|
||
/**
|
||
* Body of `POST /api/reboot-restore/restore`.
|
||
*
|
||
* `sessionIds` restores a subset, and omitting it restores everything the caller
|
||
* can see. The ids are session ids from `GET /api/reboot-restore`, and an id the
|
||
* caller does not own is ignored rather than refused, matching how the session
|
||
* list scopes rather than 403s.
|
||
*/
|
||
export const RebootRestoreRequestSchema = z
|
||
.object({
|
||
sessionIds: z.array(z.string().max(128)).max(200).optional(),
|
||
})
|
||
.strict();
|
||
|
||
export const SettingsUpdateSchema = z
|
||
.object({
|
||
// User-facing product branding. This changes browser/UI copy only; package,
|
||
// CLI, API, storage, and protocol identifiers remain Codeman.
|
||
displayName: z
|
||
.string()
|
||
.trim()
|
||
.min(1)
|
||
.max(40)
|
||
.refine(
|
||
(value) =>
|
||
Array.from(value).every((character) => {
|
||
const codePoint = character.codePointAt(0);
|
||
return codePoint !== undefined && codePoint > 31 && codePoint !== 127;
|
||
}),
|
||
'Display name must not contain control characters'
|
||
)
|
||
.optional(),
|
||
// Paths
|
||
defaultClaudeMdPath: z.string().max(500).optional(),
|
||
defaultWorkingDir: z.string().max(500).optional(),
|
||
lastUsedCase: z.string().max(200).optional(),
|
||
// Feature toggles
|
||
ralphTrackerEnabled: z.boolean().optional(),
|
||
subagentTrackingEnabled: z.boolean().optional(),
|
||
subagentActiveTabOnly: z.boolean().optional(),
|
||
/** Ultracode/Workflow run visualization (default OFF). Gates workflowRunWatcher + the master-detail tab. SYNCED. */
|
||
showUltracodeAgents: z.boolean().optional(),
|
||
/** Floating ultracode run windows w/ tab connector lines (default OFF). Also starts workflowRunWatcher. SYNCED. */
|
||
ultracodeFloatingWindows: z.boolean().optional(),
|
||
imageWatcherEnabled: z.boolean().optional(),
|
||
/**
|
||
* Inject the Codeman agent skill (`skills/codeman`) into each new session's case, in
|
||
* the directory its CLI scans for skills (`capabilities.agentSkillDir`), so an agent
|
||
* inside the session can drive the API (see docs/agent-control-plan.md §2). SYNCED,
|
||
* default ON since 1.50.0: an absent key is on, only an explicit false is off, and a
|
||
* false stored by 1.49.0 or earlier is switched on once at the first 1.50.0 start
|
||
* (agent-skill-default-migration.ts). Injection is add-only at create; a marker keeps
|
||
* user-authored copies untouched.
|
||
*/
|
||
agentSkillEnabled: z.boolean().optional(),
|
||
/**
|
||
* Install Codeman's hooks block into the workspace of every Claude session,
|
||
* not only into cases Codeman scaffolded itself. SYNCED, default ON: without
|
||
* it a linked case or an existing repo runs with no hooks at all, and each
|
||
* hook-driven surface is silently dead there (tab alert, Approvals Inbox,
|
||
* push, respawn's definitive idle signals, the wait endpoints' stop/blocked).
|
||
* Turning it OFF restores the older, narrower behavior — a Codeman hooks
|
||
* block that is already present is still refreshed when stale, but one is
|
||
* never added — for a user who wants Codeman to leave their repos alone.
|
||
*/
|
||
workspaceHooksEnabled: z.boolean().optional(),
|
||
/**
|
||
* Launch every Claude session with `--name` set to its tab name (default OFF: only a
|
||
* name the user chose is pinned). Nothing acts on it in `PUT /api/settings`: it is read
|
||
* fresh from disk by readPinCliSessionNameEnabled() (hooks-config.ts) at every claude
|
||
* create and respawn, like readPlanUsageTelemetryEnabled(), so a toggle applies from the
|
||
* next spawn with no restart.
|
||
*/
|
||
pinCliSessionName: z.boolean().optional(),
|
||
/**
|
||
* Let browser dictation transcribe through this machine's Claude Code login,
|
||
* the same speech-to-text service the CLI's own `/voice` mode uses
|
||
* (docs/claude-voice-plan.md). SYNCED, default OFF: enabling it spends the
|
||
* operator's Claude subscription on transcription for anyone who can reach
|
||
* the UI, and routes microphone audio to Anthropic rather than to whichever
|
||
* provider was configured before. The Deepgram and Web Speech paths are
|
||
* untouched by this flag.
|
||
*/
|
||
claudeVoiceEnabled: z.boolean().optional(),
|
||
/**
|
||
* Approvals Inbox (header bell + drawer, phone overview answer buttons,
|
||
* push Approve/Deny action buttons). SYNCED, default OFF (opt-in): even
|
||
* with items pending, no surface renders and push payloads carry no
|
||
* actions/approvalId until this is enabled. The server-side store and the
|
||
* answer endpoints run regardless, so flipping it ON shows anything
|
||
* already pending immediately.
|
||
*/
|
||
approvalsInboxEnabled: z.boolean().optional(),
|
||
/**
|
||
* Auto-name sessions: a placeholder tab (`w3-case`) takes its first real
|
||
* prompt as a title (`w3-case: fix the login redirect`). Synced, default
|
||
* OFF: the prompt lands in mux-sessions.json, every session:updated
|
||
* broadcast and /api/search, which is the user's choice to make.
|
||
*/
|
||
autoNameSessions: z.boolean().optional(),
|
||
/** Prompt-cache keep-warm default for sessions that have not chosen (Session Options overrides it). */
|
||
promptCacheKeepWarm: z.boolean().optional(),
|
||
/** Hours after the last real prompt during which keep-alives are sent (default 2, DEFAULT_KEEP_WARM_MAX_HOURS). */
|
||
promptCacheKeepWarmMaxHours: z.number().min(0.5).max(24).optional(),
|
||
/**
|
||
* Git fetch on an interval (src/git-fetch-scheduler.ts): `git fetch` for the repositories the Git panel
|
||
* lists, run on a timer instead of only on the panel's Fetch click. SYNCED, default OFF, because the
|
||
* server is what runs it: `git fetch` is the only git command the Git panel runs that writes (cloning
|
||
* and worktree management write too, but only when the user asked for them at the moment they asked), and
|
||
* the only one that can run later by itself, on a timer, and the only one that can run a repository's own
|
||
* hooks (`reference-transaction`, `pre-auto-gc` through the automatic maintenance a fetch triggers, config
|
||
* commands such as `credential.helper`), so nothing runs on a timer until the user turns this on. Cap in seconds between runs (30 to 3600, default 300). A
|
||
* session can override both in Session Options → Git; `null` there clears the override, and sessions
|
||
* sharing one folder are fetched by one run.
|
||
*/
|
||
gitFetchEnabled: z.boolean().optional(),
|
||
gitFetchIntervalSeconds: z.number().int().min(30).max(3600).optional(),
|
||
/**
|
||
* Spawned tabs follow their parent: a session created by another one keeps
|
||
* following its parent's tab (into its group, moving with it) until moved by
|
||
* hand. SYNCED, default OFF, because the server does the placement:
|
||
* TabLayoutService.sessionCreated() reads it at every creation, and with it
|
||
* off the child lands after its parent once and is hand-placed from then on.
|
||
*/
|
||
spawnedTabsFollowParent: z.boolean().optional(),
|
||
/**
|
||
* Read My Mind (docs/readmymind-plan.md): capture the user's submitted
|
||
* prompts into per-case intent profiles. SYNCED, default OFF (opt-in:
|
||
* captured prompts are sensitive). OFF stops capture immediately; already
|
||
* stored profiles stay until DELETE /api/sessions/:id/intent.
|
||
*/
|
||
readMyMindEnabled: z.boolean().optional(),
|
||
/**
|
||
* Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md): the toolbar picker that lets a
|
||
* session point at a user-configured custom OpenAI-compatible endpoint (local or
|
||
* cloud) instead of its native cloud backend. SYNCED, default OFF — endpoint entry,
|
||
* discovery, and the extra toolbar surface are all opt-in.
|
||
*/
|
||
customModelEndpointsEnabled: z.boolean().optional(),
|
||
/**
|
||
* CLI management (docs/cli-enable-disable-plan.md): the Settings UI section that
|
||
* lets an admin enable/disable a stock CLI, trigger its install, and add/edit/
|
||
* remove custom CLI entries — all previously hand-edit-only via ~/.codeman/clis.json.
|
||
* SYNCED, default OFF: this is a machine-configuration surface (like Custom Model
|
||
* Endpoints), not a display preference, and enabling it is what makes the write
|
||
* endpoints (PUT/POST/DELETE /api/clis...) answer instead of refusing outright.
|
||
*/
|
||
cliManagementEnabled: z.boolean().optional(),
|
||
/**
|
||
* MCP server sync (src/mcp-sync.ts): copies each enabled CLI's user-level MCP servers into
|
||
* the other CLIs' own config files. SYNCED, default OFF: it writes other tools' config in
|
||
* the server user's home (including any env values and headers on the servers), so it is
|
||
* opt-in. While OFF, GET/POST /api/mcp-sync answer 403 and the Settings controls are hidden.
|
||
*/
|
||
mcpSyncEnabled: z.boolean().optional(),
|
||
/**
|
||
* Config backups (src/config-backup.ts): timestamped snapshots of the customized config files,
|
||
* taken at startup and whenever their content changes. SYNCED. Absent means ON (the feature
|
||
* protects against an event nobody schedules); the folder defaults to `<data dir>/backups/config`.
|
||
*/
|
||
configBackupEnabled: z.boolean().optional(),
|
||
/** Absolute folder (a leading `~` is expanded); empty or absent = the default folder. */
|
||
configBackupDir: z.string().max(1024).optional(),
|
||
/** Keep at most this many snapshots. */
|
||
configBackupKeepCount: z.number().int().min(2).max(500).optional(),
|
||
/** Also drop snapshots older than this many days; 0 = no age limit. */
|
||
configBackupKeepDays: z.number().int().min(0).max(3650).optional(),
|
||
/**
|
||
* Agent inbox snapshot on disk (src/web/agent-inbox-persistence.ts). SYNCED, default OFF:
|
||
* off means no file is written, and switching it off deletes the snapshot (the in-memory
|
||
* inboxes stay). On, pending messages between agents survive a server restart.
|
||
*/
|
||
agentInboxPersistEnabled: z.boolean().optional(),
|
||
/**
|
||
* Experimental agent coordination (src/web/routes/agent-session-routes.ts): bounded
|
||
* inspection and the guarded stage/submit routes behind `codeman agent inspect|stage|submit`.
|
||
* SYNCED, default OFF: the routes are labeled experimental and may change in a minor or
|
||
* patch release, so automation has to opt in. While OFF, all three routes answer 403.
|
||
*/
|
||
agentCoordinationEnabled: z.boolean().optional(),
|
||
/**
|
||
* Read My Mind predictor model override. Empty/absent = the AI-checker
|
||
* default (opus: prediction quality is the product and it runs only on an
|
||
* explicit press). Shell-safety is validated again at spawn time.
|
||
*/
|
||
readMyMindModel: z.string().max(100).optional(),
|
||
tunnelEnabled: z.boolean().optional(),
|
||
// Action field (NOT persisted): explicit per-request acknowledgment that the
|
||
// operator accepts exposing an UNAUTHENTICATED public tunnel (no CODEMAN_PASSWORD).
|
||
// Lets the UI enable a tunnel after a confirm dialog without the
|
||
// CODEMAN_ALLOW_UNAUTHENTICATED_TUNNEL opt-in. Stripped before persisting.
|
||
acknowledgeUnauthTunnel: z.boolean().optional(),
|
||
tabTwoRows: z.boolean().optional(),
|
||
/**
|
||
* CLI Logos on Tabs. Display key (per-device), default ON: only an explicit
|
||
* false hides the agent logo on session tabs and the desktop home rail
|
||
* (`html[data-tab-logos='off']`, a CSS-only switch). Tile and split headers
|
||
* and the Run menus keep their logos.
|
||
*/
|
||
showTabCliLogos: z.boolean().optional(),
|
||
tabOrientation: z.enum(['horizontal', 'vertical']).optional(),
|
||
tabRailWidth: z.number().int().min(208).max(360).optional(),
|
||
tabRailDetail: z.enum(['simple', 'rich']).optional(),
|
||
/**
|
||
* Vertical rail row order. Display key (per-device).
|
||
* 'activity' = the home screens' order (CodemanSessionOrder): blocked on a
|
||
* human first, then running longest-first, then quiet
|
||
* most-recently-quiet first.
|
||
* 'manual' = the user's tab order, and the only value that leaves the
|
||
* rail drag-reorderable.
|
||
*/
|
||
tabRailSort: z.enum(['activity', 'manual']).optional(),
|
||
/**
|
||
* Tab layout, the arrangement of the tab list (Discussion #426). Display key
|
||
* (per-device).
|
||
* 'classic' = one flat list in tab order, as before. The default.
|
||
* 'state' = a row per state in the header strip (needs you, waiting,
|
||
* working, idle; option C), sections in the flat side rail and
|
||
* the sidebar. Opt-in.
|
||
* 'case' = one cluster per case (option A): a labelled box in the strip,
|
||
* a section in the side rail and the sidebar. Opt-in.
|
||
* 'ledger' = the flat list on an aligned column grid with a status bar
|
||
* per cell (option B). Header strip on desktop only. Opt-in.
|
||
*/
|
||
tabArrangement: z.enum(['state', 'case', 'ledger', 'classic']).optional(),
|
||
/**
|
||
* Which end the state groups start from when `tabArrangement` is 'state'.
|
||
* Display key (per-device). 'urgent-first' = needs you on top (the
|
||
* default); 'urgent-last' = the other way up, needs you in the bottom row.
|
||
*/
|
||
tabStateOrder: z.enum(['urgent-first', 'urgent-last']).optional(),
|
||
/**
|
||
* Session list layout. Display key (per-device).
|
||
* 'header' = horizontal tab strip
|
||
* 'sidebar' = collapsible left sidebar, one compact row per session
|
||
* 'sidebar-rich' = same sidebar, each row carrying the home screen's detail
|
||
* (created/idle/working stamps + status pill)
|
||
* Both sidebar values render the SAME docked column and set
|
||
* data-session-list="sidebar"; they differ only in row detail, which rides
|
||
* on data-sidebar-detail. See applySessionListLayout() in app.js.
|
||
*/
|
||
sessionListLayout: z.enum(['header', 'sidebar', 'sidebar-rich']).optional(),
|
||
/** Session-name text size in vertical navigation. Display key (per-device). */
|
||
sessionSidebarFontSize: z.number().int().min(11).max(18).optional(),
|
||
agentTeamsEnabled: z.boolean().optional(),
|
||
/** Model for new Claude sessions (e.g. "claude-fable-5[1m]", "opus[1m]"); takes precedence over opusContext1mEnabled */
|
||
claudeModel: z.string().max(50).optional(),
|
||
opusContext1mEnabled: z.boolean().optional(),
|
||
// COD-108 remote-session auto-reconnect kill-switch (default ON). When false,
|
||
// the TmuxManager watcher does nothing — dropped remote sessions are NOT
|
||
// auto-reattached.
|
||
remoteAutoReconnect: z.boolean().optional(),
|
||
thinkingEffort: z.string().max(20).optional(),
|
||
/** Advisor model for new Claude sessions ('' = leave it to the CLI's own /advisor choice). */
|
||
claudeAdvisorModel: z
|
||
.string()
|
||
.max(64)
|
||
.refine((value) => value === '' || isAdvisorModel(value), { message: 'Invalid advisor model' })
|
||
.optional(),
|
||
// UI visibility
|
||
showFontControls: z.boolean().optional(),
|
||
showSystemStats: z.boolean().optional(),
|
||
/**
|
||
* How the header draws its WS / CPU / MEM / plan-usage cluster. Display key
|
||
* (per-device), desktop only (the cluster is hidden below 768px).
|
||
* 'classic' = the bars and the 5H · 7D chip, as before
|
||
* 'compact' = two pills (WS/CPU/MEM, the plan windows), a ring beside every value.
|
||
* The default.
|
||
* 'tiles' = label over value with a bar underneath, no icons
|
||
*/
|
||
headerStatsStyle: z.enum(['classic', 'compact', 'tiles']).optional(),
|
||
showTokenCount: z.boolean().optional(),
|
||
showCost: z.boolean().optional(),
|
||
showLifecycleLog: z.boolean().optional(),
|
||
showResponseViewer: z.boolean().optional(),
|
||
showMonitor: z.boolean().optional(),
|
||
showProjectInsights: z.boolean().optional(),
|
||
showFileBrowser: z.boolean().optional(),
|
||
showSubagents: z.boolean().optional(),
|
||
showMultiMonitorButton: z.boolean().optional(),
|
||
// Doubles as the plan-usage telemetry COLLECTION switch, read fresh from
|
||
// disk by readPlanUsageTelemetryEnabled() (hooks-config.ts) at every claude
|
||
// session create/respawn — not just the chip's DISPLAY preference. See that
|
||
// function's doc comment for why one persisted field serves both. Absent
|
||
// means ON there, and the client sends it only on a save that flips the
|
||
// chip (planUsageCollectionFlip in settings-ui.js), never on every save.
|
||
showPlanUsageLimits: z.boolean().optional(),
|
||
showRedrawButton: z.boolean().optional(),
|
||
// Input
|
||
gestureControlEnabled: z.boolean().optional(),
|
||
// Claude CLI settings
|
||
claudeMode: z.string().max(50).optional(),
|
||
allowedTools: z.string().max(2000).optional(),
|
||
// Codex CLI settings
|
||
codexModel: z
|
||
.string()
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9._\-/]*$/)
|
||
.optional(),
|
||
codexReasoningEffort: z.enum(['', ...CODEX_REASONING_EFFORTS]).optional(),
|
||
codexDangerouslyBypassApprovals: z.boolean().optional(),
|
||
codexNetworkAccess: z.boolean().optional(),
|
||
codexAnimationsEnabled: z.boolean().optional(),
|
||
// Terminal history and retention
|
||
terminalScrollbackLines: z
|
||
.number()
|
||
.int()
|
||
.min(MIN_TERMINAL_SCROLLBACK_LINES)
|
||
.max(MAX_TERMINAL_SCROLLBACK_LINES)
|
||
.optional(),
|
||
tmuxHistoryLimit: z.number().int().min(MIN_TERMINAL_SCROLLBACK_LINES).max(MAX_TERMINAL_SCROLLBACK_LINES).optional(),
|
||
terminalBufferMaxBytes: z.number().int().min(MIN_TERMINAL_BUFFER_BYTES).max(MAX_TERMINAL_BUFFER_BYTES).optional(),
|
||
terminalBufferTrimBytes: z.number().int().min(MIN_TERMINAL_BUFFER_BYTES).max(MAX_TERMINAL_BUFFER_BYTES).optional(),
|
||
// CPU priority
|
||
nice: z
|
||
.object({
|
||
enabled: z.boolean().optional(),
|
||
niceValue: z.number().int().min(-20).max(19).optional(),
|
||
})
|
||
.optional(),
|
||
// Notification preferences (cross-device sync)
|
||
notificationPreferences: z
|
||
.object({
|
||
enabled: z.boolean().optional(),
|
||
browserNotifications: z.boolean().optional(),
|
||
audioAlerts: z.boolean().optional(),
|
||
stuckThresholdMs: z.number().optional(),
|
||
toastDurationMs: z.number().optional(),
|
||
browserAutoCloseMs: z.number().optional(),
|
||
muteCritical: z.boolean().optional(),
|
||
muteWarning: z.boolean().optional(),
|
||
muteInfo: z.boolean().optional(),
|
||
eventTypes: z
|
||
.object({
|
||
permission_prompt: NotificationEventSchema,
|
||
elicitation_dialog: NotificationEventSchema,
|
||
idle_prompt: NotificationEventSchema,
|
||
stop: NotificationEventSchema,
|
||
session_error: NotificationEventSchema,
|
||
respawn_cycle: NotificationEventSchema,
|
||
token_milestone: NotificationEventSchema,
|
||
ralph_complete: NotificationEventSchema,
|
||
subagent_spawn: NotificationEventSchema,
|
||
subagent_complete: NotificationEventSchema,
|
||
})
|
||
.optional(),
|
||
_version: z.number().optional(),
|
||
})
|
||
.optional(),
|
||
// Voice settings (cross-device sync)
|
||
voiceSettings: z
|
||
.object({
|
||
/** 'auto' | 'claude' | 'deepgram' | 'webspeech'. Unknown values fall back to auto client-side. */
|
||
provider: z.string().max(20).optional(),
|
||
apiKey: z.string().max(200).optional(),
|
||
language: z.string().max(20).optional(),
|
||
keyterms: z.string().max(500).optional(),
|
||
insertMode: z.string().max(20).optional(),
|
||
})
|
||
.optional(),
|
||
// Run mode preference (cross-device sync)
|
||
runMode: z.string().max(20).optional(),
|
||
// Custom respawn presets (cross-device sync, replaces localStorage-only storage)
|
||
respawnPresets: z
|
||
.array(
|
||
z.object({
|
||
id: z.string().max(100),
|
||
name: z.string().max(100),
|
||
config: z.object({
|
||
idleTimeoutMs: z.number().optional(),
|
||
updatePrompt: z.string().max(5000).optional(),
|
||
interStepDelayMs: z.number().optional(),
|
||
sendClear: z.boolean().optional(),
|
||
sendInit: z.boolean().optional(),
|
||
kickstartPrompt: z.string().max(5000).optional(),
|
||
autoAcceptPrompts: z.boolean().optional(),
|
||
}),
|
||
durationMinutes: z.number().optional(),
|
||
builtIn: z.boolean().optional(),
|
||
createdAt: z.number().optional(),
|
||
})
|
||
)
|
||
.max(20)
|
||
.optional(),
|
||
})
|
||
.strict()
|
||
.superRefine((settings, ctx) => {
|
||
if (
|
||
settings.terminalBufferMaxBytes !== undefined &&
|
||
settings.terminalBufferTrimBytes !== undefined &&
|
||
settings.terminalBufferTrimBytes > settings.terminalBufferMaxBytes
|
||
) {
|
||
ctx.addIssue({
|
||
code: z.ZodIssueCode.custom,
|
||
path: ['terminalBufferTrimBytes'],
|
||
message: 'terminalBufferTrimBytes must be less than or equal to terminalBufferMaxBytes',
|
||
});
|
||
}
|
||
});
|
||
|
||
/**
|
||
* Schema for POST /api/sessions/:id/input with length limit
|
||
*/
|
||
export const SessionInputWithLimitSchema = z.object({
|
||
// One limit for both transports (issue #484): the route's own length check and
|
||
// ws-routes.ts read the same constant, so a schema cap above it only hid which
|
||
// check refused the input.
|
||
input: z.string().max(MAX_INPUT_LENGTH),
|
||
useMux: z.boolean().optional(),
|
||
// Reliable-delivery dedup (optional; absent for curl/legacy clients). The web
|
||
// client tags each input with a stable clientId + a monotonic per-session seq
|
||
// and redelivers anything it hasn't seen ACKed (e.g. a frame silently dropped
|
||
// by a half-open WebSocket on a flaky link). The server applies each (clientId,
|
||
// seq) at-most-once via Session.shouldApplyInput so a redelivery can't type the
|
||
// prompt twice. `.optional()` (not `.nullish()`) — the client omits them when
|
||
// unset rather than sending null. See docs/reliable-input-delivery.md.
|
||
seq: z.number().int().nonnegative().optional(),
|
||
clientId: z.string().max(128).optional(),
|
||
// Send-and-wait (agent orchestration): `true` for the default signal set, or the
|
||
// same grammar as `GET .../wait` — a comma string or an array of signals. Absent
|
||
// means the historical fire-and-forget behavior, byte for byte.
|
||
//
|
||
// `.nullish()`, not `.optional()`: a third-party caller building the body with
|
||
// JSON.stringify keeps an explicit null on the wire, and `.optional()` rejects it
|
||
// with INVALID_INPUT. That gotcha has shipped as a real bug twice.
|
||
wait: z.union([z.boolean(), z.string().max(120), z.array(z.string().max(120)).max(8)]).nullish(),
|
||
// Unbounded above: the effective value is clamped to MAX_WAIT_MS server-side and
|
||
// returned as `data.wait.timeoutMs`, so a caller that asks for 24h sees what it
|
||
// actually got. A `.max()` here would turn the same documented clamp into a 400 for
|
||
// large-enough guesses, which is the one behaviour an agent cannot predict.
|
||
waitTimeout: z.number().int().positive().nullish(),
|
||
});
|
||
|
||
/**
|
||
* Query validation for `GET /api/sessions/:id/wait` (agent wait primitives).
|
||
*
|
||
* Everything arrives as a string. `timeout` is coerced and bounded here, then
|
||
* clamped again to the operator's ceiling by `clampWaitMs()` — the schema bound
|
||
* only keeps an absurd number out of the arithmetic. A non-numeric `timeout` is a
|
||
* 400 rather than a silent fallback, so an agent never believes it asked for a
|
||
* longer wait than it got; the value actually applied comes back as
|
||
* `data.wait.timeoutMs`, which is what makes the clamp observable. `until` is
|
||
* parsed by `parseWaitSignals()`, which reports unknown tokens instead of
|
||
* dropping them.
|
||
*
|
||
* `until` accepts an ARRAY as well as the comma string: `?until=stop&until=exit`
|
||
* is how most HTTP clients express a list, Fastify's query parser delivers a
|
||
* repeated parameter as an array, and `parseWaitSignals()` has always handled
|
||
* both. Rejecting the repeated form left that branch unreachable and 400'd the
|
||
* more natural spelling.
|
||
*/
|
||
export const SessionWaitQuerySchema = z.object({
|
||
until: z.union([z.string().max(120), z.array(z.string().max(120)).max(8)]).optional(),
|
||
// No upper bound on purpose. The contract is "clamped to [MIN_WAIT_MS, MAX_WAIT_MS]",
|
||
// and a `.max()` here contradicted it: `timeout=99999999` was a 400 mid-fan-out while
|
||
// `timeout=600001` was silently clamped, so the same documented rule produced two
|
||
// different outcomes depending on how big the caller's guess was. `clampWaitMs()`
|
||
// bounds every finite value, and `.int()` still rejects `Infinity`/`1e999` and junk.
|
||
timeout: z.coerce.number().int().positive().optional(),
|
||
fresh: z.enum(['0', '1', 'true', 'false']).optional(),
|
||
});
|
||
|
||
/**
|
||
* Query validation for `GET /api/sessions/:id/wait-output`.
|
||
*
|
||
* `match` is a LITERAL substring, never a pattern: `search-service.ts` avoids regex
|
||
* so there is no ReDoS surface, and this endpoint is more exposed still (the pattern
|
||
* would be caller-supplied and the input is a live stream). The length bound is a
|
||
* second reason the carry buffer stays small. The route separately rejects a `regex`
|
||
* parameter outright rather than ignoring it.
|
||
*/
|
||
export const SessionWaitOutputQuerySchema = z.object({
|
||
match: z.string().min(MIN_MATCH_LENGTH).max(MAX_MATCH_LENGTH),
|
||
nocase: z.enum(['0', '1', 'true', 'false']).optional(),
|
||
from: z.enum(['now', 'buffer']).optional(),
|
||
// Unbounded above for the same reason as SessionWaitQuerySchema.timeout: clamping is
|
||
// the documented contract, so a large value must clamp rather than 400.
|
||
timeout: z.coerce.number().int().positive().optional(),
|
||
});
|
||
|
||
// ========== Agent Inbox Routes ==========
|
||
|
||
/**
|
||
* Body for `POST /api/sessions/:id/inbox`. The byte cap (`MAX_MESSAGE_BYTES`) is the
|
||
* store's, checked there in UTF-8 bytes; this bound is only the outer fence so a
|
||
* multi-megabyte body never reaches it. It is 4× the byte cap in characters (a UTF-8
|
||
* character is at most 4 bytes), so every over-size message gets the store's answer,
|
||
* which tells the sender what to do instead. Multi-line text is fine: it is stored and
|
||
* handed back as data, never typed.
|
||
*/
|
||
export const InboxPostSchema = z
|
||
.object({
|
||
text: z
|
||
.string()
|
||
.min(1, 'text must not be empty')
|
||
.max(4 * MAX_MESSAGE_BYTES),
|
||
})
|
||
.strict();
|
||
|
||
/** Query for `GET /api/sessions/:id/inbox`. `wait` follows the wait routes' `timeout`: clamped, never a 400 for size. */
|
||
export const InboxReadQuerySchema = z.object({
|
||
wait: z.coerce.number().int().positive().optional(),
|
||
});
|
||
|
||
/** Body for `POST /api/sessions/:id/inbox/ack`: the ids a read handed out. */
|
||
export const InboxAckSchema = z
|
||
.object({
|
||
ids: z.array(z.string().min(1).max(64)).min(1).max(200),
|
||
})
|
||
.strict();
|
||
|
||
// ========== Session Mutation Routes ==========
|
||
|
||
/** PUT /api/sessions/:id/name */
|
||
export const SessionNameSchema = z.object({
|
||
name: z.string().min(0).max(128),
|
||
});
|
||
|
||
/** PUT /api/sessions/:id/color */
|
||
export const SessionColorSchema = z.object({
|
||
color: z.string().max(30),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/ralph-config */
|
||
export const RalphConfigSchema = z.object({
|
||
enabled: z.boolean().optional(),
|
||
completionPhrase: z.string().max(500).optional(),
|
||
maxIterations: z.number().int().min(0).max(10000).optional(),
|
||
maxTodos: z.number().int().positive().max(10000).optional(),
|
||
todoExpirationMinutes: z.number().int().positive().max(525600).optional(),
|
||
reset: z.union([z.boolean(), z.literal('full')]).optional(),
|
||
disableAutoEnable: z.boolean().optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/fix-plan/import */
|
||
export const FixPlanImportSchema = z.object({
|
||
content: z.string().max(500000),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/ralph-prompt/write */
|
||
export const RalphPromptWriteSchema = z.object({
|
||
content: z.string().max(500000),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/auto-clear */
|
||
export const AutoClearSchema = z.object({
|
||
enabled: z.boolean(),
|
||
threshold: z.number().int().min(0).max(1000000).optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/auto-compact */
|
||
export const AutoCompactSchema = z.object({
|
||
enabled: z.boolean(),
|
||
threshold: z.number().int().min(0).max(1000000).optional(),
|
||
prompt: z.string().max(10000).optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/auto-resume */
|
||
export const AutoResumeSchema = z.object({
|
||
enabled: z.boolean(),
|
||
});
|
||
|
||
/** `POST /api/sessions/:id/keep-warm`: `null` clears the session's choice so the app-wide default applies. */
|
||
export const KeepWarmSchema = z.object({ enabled: z.boolean().nullable() });
|
||
|
||
/**
|
||
* `POST /api/sessions/:id/git-fetch-settings`: `null` clears the session's choice so the app-wide default
|
||
* applies. Both fields are optional, so a row that saves on its own does not clear the other.
|
||
*/
|
||
export const GitFetchSettingsSchema = z.object({
|
||
enabled: z.boolean().nullable().optional(),
|
||
intervalSeconds: z.number().int().min(30).max(3600).nullable().optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/pin (COD-139) — explicit pin state for idempotency. */
|
||
export const PinSessionSchema = z.object({
|
||
pinned: z.boolean(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/image-watcher */
|
||
export const ImageWatcherSchema = z.object({
|
||
enabled: z.boolean(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/flicker-filter */
|
||
export const FlickerFilterSchema = z.object({
|
||
enabled: z.boolean(),
|
||
});
|
||
|
||
/** POST /api/run */
|
||
export const QuickRunSchema = z.object({
|
||
prompt: z.string().min(1).max(100000),
|
||
workingDir: safePathSchema.optional(),
|
||
envOverrides: safeEnvOverridesSchema,
|
||
});
|
||
|
||
/** POST /api/scheduled */
|
||
export const ScheduledRunSchema = z.object({
|
||
prompt: z.string().min(1).max(100000),
|
||
workingDir: safePathSchema.optional(),
|
||
durationMinutes: z.number().int().min(1).max(14400).optional(),
|
||
});
|
||
|
||
// ========== Cron Jobs ==========
|
||
|
||
/** 'HH:MM' 24-hour time. */
|
||
const hhmmSchema = z.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, 'Time must be HH:MM (24-hour)');
|
||
|
||
/** Prompt delivery is single-line only (the submit check cannot reliably recognise a multi-line paste) — reject newlines outright. */
|
||
const noNewlines = (v: string) => !/[\r\n]/.test(v);
|
||
|
||
/** Shared field shape for creating/updating a scheduled job. */
|
||
const CronJobBaseSchema = z.object({
|
||
name: z.string().min(1).max(200),
|
||
agentType: sessionModeSchema(),
|
||
workingDir: safePathSchema,
|
||
launchCommand: z.string().max(2000).refine(noNewlines, 'launchCommand must be a single line').optional(),
|
||
promptMode: z.enum(['inline_text', 'prompt_file_path']),
|
||
promptText: z
|
||
.string()
|
||
.max(100000)
|
||
.refine(noNewlines, 'promptText must be a single line (multi-line prompts are not supported)')
|
||
.optional(),
|
||
promptFilePath: safePathSchema.optional(),
|
||
inputMode: z.enum(['paste', 'typed']),
|
||
scheduleType: z.enum(['once', 'interval', 'daily', 'weekly']),
|
||
runAt: z.number().int().positive().optional(),
|
||
intervalMinutes: z.number().int().min(1).max(525600).optional(),
|
||
dailyTime: hhmmSchema.optional(),
|
||
weeklyDays: z.array(z.number().int().min(0).max(6)).min(1).max(7).optional(),
|
||
weeklyTime: hhmmSchema.optional(),
|
||
enabled: z.boolean(),
|
||
notes: z.string().max(2000).optional(),
|
||
concurrencyPolicy: z.enum(['warn_only', 'skip_if_same_agent_running']),
|
||
autoClosePreviousSession: z.boolean().optional(),
|
||
});
|
||
|
||
/** Cross-field validation: required fields depend on promptMode + scheduleType. */
|
||
function refineCronJob(val: z.infer<typeof CronJobBaseSchema>, ctx: z.RefinementCtx): void {
|
||
const add = (message: string, path: string) => ctx.addIssue({ code: 'custom', message, path: [path] });
|
||
|
||
if (val.promptMode === 'inline_text' && !val.promptText) {
|
||
add('promptText is required when promptMode is inline_text', 'promptText');
|
||
}
|
||
if (val.promptMode === 'prompt_file_path' && !val.promptFilePath) {
|
||
add('promptFilePath is required when promptMode is prompt_file_path', 'promptFilePath');
|
||
}
|
||
if (val.scheduleType === 'once' && val.runAt === undefined) {
|
||
add('runAt is required for a one-time schedule', 'runAt');
|
||
}
|
||
if (val.scheduleType === 'interval' && val.intervalMinutes === undefined) {
|
||
add('intervalMinutes is required for an interval schedule', 'intervalMinutes');
|
||
}
|
||
if (val.scheduleType === 'daily' && !val.dailyTime) {
|
||
add('dailyTime is required for a daily schedule', 'dailyTime');
|
||
}
|
||
if (val.scheduleType === 'weekly' && (!val.weeklyTime || !val.weeklyDays?.length)) {
|
||
add('weeklyDays and weeklyTime are required for a weekly schedule', 'weeklyTime');
|
||
}
|
||
}
|
||
|
||
/** POST /api/cron/jobs — full job definition. */
|
||
export const CronJobSchema = CronJobBaseSchema.superRefine(refineCronJob);
|
||
|
||
/** PUT /api/cron/jobs/:id — partial update. */
|
||
export const CronJobUpdateSchema = CronJobBaseSchema.partial();
|
||
|
||
/** PUT /api/cron/jobs/:id/enabled */
|
||
export const CronJobEnabledSchema = z.object({ enabled: z.boolean() });
|
||
|
||
/** POST /api/cases/link */
|
||
export const LinkCaseSchema = z.object({
|
||
name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
|
||
path: safePathSchema,
|
||
});
|
||
|
||
/** POST /api/cases/:name/rename */
|
||
export const RenameCaseSchema = z
|
||
.object({
|
||
newName: z
|
||
.string()
|
||
.min(1)
|
||
.max(100)
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format. Use only letters, numbers, hyphens, underscores.'),
|
||
/** Linked cases only: also rename the real folder on disk (a case under the cases directory always moves). */
|
||
renameFolder: z.boolean().optional(),
|
||
/** Stop the live sessions that have the folder open, instead of refusing with the list of them. */
|
||
stopSessions: z.boolean().optional(),
|
||
})
|
||
.strict();
|
||
|
||
/** PUT /api/cases/order */
|
||
export const CaseOrderSchema = z.object({
|
||
order: z.array(z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format')),
|
||
});
|
||
|
||
/**
|
||
* PUT /api/cases/:name/default-group — the tab group new sessions of this case
|
||
* land in: one of the caller's own group ids, or null for Ungrouped. Same bounds
|
||
* as tabGroupIdSchema; the route checks the id against the caller's layout.
|
||
*/
|
||
export const CaseDefaultGroupSchema = z.object({
|
||
groupId: z.string().min(1).max(100).nullable(),
|
||
});
|
||
|
||
/** PUT /api/session-order — global tab order (ordered sessionIds), COD-131 */
|
||
export const SessionOrderUpdateSchema = z.object({
|
||
// Bounded defensively: ids are uuid-ish (<=100 chars) and the client pushes only
|
||
// its open-tab order (max sessions is 50 by default, at most 462 via CODEMAN_MAX_SESSIONS,
|
||
// see MAX_CONCURRENT_SESSIONS_CEILING) — 500 leaves enough room while
|
||
// keeping a hostile/buggy client from persisting megabytes into state.json.
|
||
order: z.array(z.string().max(100)).max(500),
|
||
});
|
||
|
||
/** POST /api/auth/revoke */
|
||
export const RevokeSessionSchema = z.object({
|
||
sessionToken: z.string().min(1).max(200).optional(),
|
||
});
|
||
|
||
/** POST /api/generate-plan */
|
||
export const GeneratePlanSchema = z.object({
|
||
taskDescription: z.string().min(1).max(100000),
|
||
detailLevel: z.enum(['brief', 'standard', 'detailed']).optional(),
|
||
});
|
||
|
||
/** POST /api/generate-plan-detailed */
|
||
export const GeneratePlanDetailedSchema = z.object({
|
||
taskDescription: z.string().min(1).max(100000),
|
||
caseName: z.string().max(200).optional(),
|
||
});
|
||
|
||
/** POST /api/cancel-plan-generation */
|
||
export const CancelPlanSchema = z.object({
|
||
orchestratorId: z.string().max(200).optional(),
|
||
});
|
||
|
||
/** PATCH /api/sessions/:id/plan/task/:taskId */
|
||
export const PlanTaskUpdateSchema = z.object({
|
||
status: z.enum(['pending', 'in_progress', 'completed', 'failed', 'blocked']).optional(),
|
||
error: z.string().max(10000).optional(),
|
||
incrementAttempts: z.boolean().optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/plan/task (add task) */
|
||
export const PlanTaskAddSchema = z.object({
|
||
content: z.string().min(1).max(10000),
|
||
priority: z.enum(['P0', 'P1', 'P2']).optional(),
|
||
verificationCriteria: z.string().max(10000).optional(),
|
||
dependencies: z.array(z.string().max(200)).optional(),
|
||
insertAfter: z.string().max(200).optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/cpu-limit */
|
||
export const CpuLimitSchema = z.object({
|
||
cpuLimit: z.number().int().min(0).max(100).optional(),
|
||
ioClass: z.enum(['idle', 'best-effort', 'realtime']).optional(),
|
||
ioLevel: z.number().int().min(0).max(7).optional(),
|
||
});
|
||
|
||
/** PUT /api/execution/model-config */
|
||
export const ModelConfigUpdateSchema = z.record(z.string(), z.unknown());
|
||
|
||
/** PUT /api/subagent-window-states */
|
||
export const SubagentWindowStatesSchema = z
|
||
.object({
|
||
minimized: z.record(z.string(), z.boolean()).optional(),
|
||
open: z.array(z.string()).optional(),
|
||
})
|
||
.passthrough();
|
||
|
||
/** PUT /api/subagent-parents */
|
||
export const SubagentParentMapSchema = z.record(z.string(), z.string());
|
||
|
||
/** POST /api/sessions/:id/interactive */
|
||
export const InteractiveStartSchema = z.object({
|
||
/**
|
||
* COD-118: explicit user-initiated restart — clears a tripped PTY-exit circuit
|
||
* breaker before starting. Automatic reconnect/re-attach callers (e.g. the
|
||
* frontend's selectSession auto-attach) must NOT send this flag.
|
||
*/
|
||
clearBreaker: z.boolean().optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/interactive-respawn */
|
||
export const InteractiveRespawnSchema = z.object({
|
||
respawnConfig: RespawnConfigSchema.optional(),
|
||
durationMinutes: z.number().int().min(1).max(14400).optional(),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/respawn/enable */
|
||
export const RespawnEnableSchema = z.object({
|
||
config: RespawnConfigSchema.optional(),
|
||
durationMinutes: z.number().int().min(1).max(14400).optional(),
|
||
});
|
||
|
||
// ========== Web Push ==========
|
||
|
||
/** POST /api/push/subscribe */
|
||
export const PushSubscribeSchema = z.object({
|
||
endpoint: z
|
||
.string()
|
||
.url()
|
||
.max(2000)
|
||
.refine(isSafePushEndpoint, { message: 'endpoint must be an https URL to a public (non-internal) host' }),
|
||
keys: z.object({
|
||
p256dh: z.string().min(1).max(500),
|
||
auth: z.string().min(1).max(500),
|
||
}),
|
||
userAgent: z.string().max(500).optional(),
|
||
pushPreferences: z.record(z.string(), z.boolean()).optional(),
|
||
});
|
||
|
||
/** PUT /api/push/subscribe/:id */
|
||
export const PushPreferencesUpdateSchema = z.object({
|
||
pushPreferences: z.record(z.string(), z.boolean()),
|
||
});
|
||
|
||
/**
|
||
* PUT /api/webhook. `.strict()` like every settings-shaped schema; `url` is optional so a change of
|
||
* kind or scope never needs the secret re-sent, and an empty string clears it. The kind and scope
|
||
* lists are the store's own, so the schema can never accept a value the store would coerce away.
|
||
*/
|
||
export const WebhookUpdateSchema = z
|
||
.object({
|
||
enabled: z.boolean().optional(),
|
||
kind: z.enum(WEBHOOK_KINDS).optional(),
|
||
scope: z.enum(WEBHOOK_SCOPES).optional(),
|
||
url: z.string().max(2048).optional(),
|
||
})
|
||
.strict();
|
||
|
||
/**
|
||
* PUT /api/discord. `.strict()` and every field optional, so a change of one option never needs the
|
||
* token re-sent; an empty `token` clears it. Option lists are the bridge's own, so the schema cannot
|
||
* accept a value the store would coerce away. Ids are checked again (as snowflakes) by the route.
|
||
*/
|
||
export const DiscordUpdateSchema = z
|
||
.object({
|
||
enabled: z.boolean().optional(),
|
||
token: z.string().max(200).optional(),
|
||
guildId: z.string().max(25).optional(),
|
||
parentChannelId: z.string().max(25).optional(),
|
||
allowedUserIds: z.array(z.string().max(25)).max(20).optional(),
|
||
threadCreation: z.enum(DISCORD_THREAD_CREATION).optional(),
|
||
onSessionDelete: z.enum(DISCORD_ON_DELETE).optional(),
|
||
staleThreads: z.enum(DISCORD_ON_DELETE).optional(),
|
||
pingMode: z.enum(DISCORD_PING_MODES).optional(),
|
||
scope: z.enum(WEBHOOK_SCOPES).optional(),
|
||
startupHint: z.boolean().optional(),
|
||
})
|
||
.strict();
|
||
|
||
/** POST /api/sessions/:id/discord-notify */
|
||
export const DiscordNotifySchema = z
|
||
.object({
|
||
message: z.string().min(1).max(1500),
|
||
urgent: z.boolean().optional(),
|
||
/** Absolute path of a file inside the session's working folder, uploaded with the post. */
|
||
file: z.string().min(1).max(1024).optional(),
|
||
})
|
||
.strict();
|
||
|
||
// ========== Ralph Loop ==========
|
||
|
||
/** POST /api/ralph-loop/start */
|
||
export const RalphLoopStartSchema = z.object({
|
||
caseName: z
|
||
.string()
|
||
.regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format')
|
||
.optional()
|
||
.default('testcase'),
|
||
taskDescription: z.string().min(1).max(100000),
|
||
completionPhrase: z.string().max(100).default('COMPLETE'),
|
||
maxIterations: z.number().int().min(0).max(1000).nullable().default(10),
|
||
enableRespawn: z.boolean().default(false),
|
||
envOverrides: safeEnvOverridesSchema,
|
||
/** Claude CLI effort level (soft default via --settings, switchable in-session via /effort) */
|
||
effort: effortLevelSchema,
|
||
/** Claude advisor model (soft default via --settings, switchable in-session via /advisor) */
|
||
advisorModel: advisorModelSchema,
|
||
planItems: z
|
||
.array(
|
||
z.object({
|
||
content: z.string(),
|
||
priority: z.string().optional(),
|
||
enabled: z.boolean().default(true),
|
||
})
|
||
)
|
||
.optional(),
|
||
});
|
||
|
||
// ========== Orchestrator Loop ==========
|
||
|
||
/** POST /api/orchestrator/start */
|
||
export const OrchestratorStartSchema = z.object({
|
||
goal: z.string().min(1).max(100000),
|
||
config: z
|
||
.object({
|
||
plannerModel: z.string().max(100).optional(),
|
||
researchEnabled: z.boolean().optional(),
|
||
autoApprove: z.boolean().optional(),
|
||
maxPhaseRetries: z.number().int().min(1).max(10).optional(),
|
||
phaseTimeoutMs: z.number().int().min(60000).max(7200000).optional(),
|
||
enableTeamAgents: z.boolean().optional(),
|
||
maxParallelSessions: z.number().int().min(1).max(10).optional(),
|
||
verificationMode: z.enum(['strict', 'moderate', 'lenient']).optional(),
|
||
compactBetweenPhases: z.boolean().optional(),
|
||
})
|
||
.optional(),
|
||
});
|
||
|
||
/** POST /api/orchestrator/reject */
|
||
export const OrchestratorRejectSchema = z.object({
|
||
feedback: z.string().min(1).max(10000),
|
||
});
|
||
|
||
// ========== Cross-Session Search (COD-9) ==========
|
||
|
||
/** Valid federated source kinds for `GET /api/search?types=`. */
|
||
export const SEARCH_SOURCE_TYPES = ['session', 'event', 'file'] as const;
|
||
|
||
/**
|
||
* GET /api/search query validation.
|
||
*
|
||
* Query params arrive as strings: `q` is bounded (1..200 chars), `types` is an
|
||
* optional comma-separated allowlisted CSV, and `limit` is an optional coerced
|
||
* integer clamped to 1..60. Validation is the first line of defense — a missing
|
||
* or oversized `q`, an unknown type, or a non-numeric limit is rejected with 400.
|
||
*/
|
||
export const SearchQuerySchema = z.object({
|
||
q: z.string().trim().min(1, 'Query is required').max(200, 'Query too long (max 200 chars)'),
|
||
types: z
|
||
.string()
|
||
.max(100)
|
||
.optional()
|
||
.refine(
|
||
(v) =>
|
||
v === undefined ||
|
||
v
|
||
.split(',')
|
||
.map((t) => t.trim())
|
||
.filter(Boolean)
|
||
.every((t) => (SEARCH_SOURCE_TYPES as readonly string[]).includes(t)),
|
||
{ message: 'Invalid types value' }
|
||
),
|
||
limit: z.coerce.number().int().min(1).max(60).optional(),
|
||
});
|
||
|
||
// ========== Web Tabs (dashboard URLs) ==========
|
||
|
||
/**
|
||
* A dashboard URL. `isValidWebviewUrl` rejects anything that is not plain
|
||
* http/https, anything carrying embedded credentials, and anything without a
|
||
* hostname. See `src/web/webview-proxy.ts` for why each of those matters.
|
||
*/
|
||
const webviewUrlSchema = z
|
||
.string()
|
||
.trim()
|
||
.min(1, 'URL is required')
|
||
.max(2000, 'URL too long (max 2000 chars)')
|
||
.refine(isValidWebviewUrl, {
|
||
message: 'Invalid URL: must be http(s), with a hostname and no embedded credentials',
|
||
})
|
||
// Egress policy (`webview-egress-policy.ts`): no dashboard lives at a link-local
|
||
// or cloud-metadata address, while an IAM credential does. Refused at save time
|
||
// for the clear message; the proxy re-judges the RESOLVED address at connect time.
|
||
.refine((url) => !isBlockedWebviewUrl(url), {
|
||
message:
|
||
'Blocked URL: link-local and cloud-metadata addresses (169.254.0.0/16, metadata.google.internal, ...) cannot be dashboards',
|
||
});
|
||
|
||
const WebviewBaseSchema = z.object({
|
||
name: z.string().trim().min(1, 'Name is required').max(60, 'Name too long (max 60 chars)'),
|
||
url: webviewUrlSchema,
|
||
/** A single glyph shown on the tab. Bounded generously: one emoji can be several code units. */
|
||
icon: z.string().max(8).optional(),
|
||
embedMode: z.enum(['proxy', 'direct']).optional(),
|
||
/**
|
||
* Opt out of the iframe sandbox. Defaults to false: a proxied page is served
|
||
* from Codeman's own origin, so `allow-same-origin` would let it read this page
|
||
* and call the API that spawns agents.
|
||
*/
|
||
trusted: z.boolean().optional(),
|
||
/**
|
||
* Marks a record Codeman maintains itself. Declared here because a plain
|
||
* `z.object` STRIPS undeclared keys, so an undeclared marker would be dropped
|
||
* on the way in and the dedup it drives would never fire.
|
||
*/
|
||
managed: z.enum(['deepseek-web']).optional(),
|
||
});
|
||
|
||
/** POST /api/webviews */
|
||
export const WebviewCreateSchema = WebviewBaseSchema;
|
||
|
||
/** PATCH /api/webviews/:id, partial update. */
|
||
export const WebviewUpdateSchema = WebviewBaseSchema.partial();
|
||
|
||
/** POST /api/webviews/probe: reachability + framing check for the editor's Test button. */
|
||
export const WebviewProbeSchema = z.object({ url: webviewUrlSchema });
|
||
|
||
/**
|
||
* Ceiling on a stated context length (tokens), shared between the bounds below and
|
||
* discovery (`custom-model-routes.ts`): anything above it reads as nonsense and is
|
||
* ignored, because a bogus figure here overflows the smaller server, which is the exact
|
||
* failure the discovery field exists to prevent.
|
||
*/
|
||
export const MAX_DISCOVERED_CONTEXT_TOKENS = 100_000_000;
|
||
|
||
// Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md) — a
|
||
// user-configured custom OpenAI-compatible endpoint, local (llama.cpp) or cloud
|
||
// (Azure AI Foundry, etc.). Lives below `webviewUrlSchema` because `baseUrl` IS that
|
||
// schema: http(s) only, a real hostname, no embedded credentials, and the link-local /
|
||
// cloud-metadata refusal, the same bar a saved dashboard URL has to clear.
|
||
export const CustomModelHostSchema = z.object({
|
||
id: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid endpoint id'),
|
||
label: z.string().min(1).max(100),
|
||
baseUrl: webviewUrlSchema,
|
||
apiKey: z.string().max(4096).optional(),
|
||
// No 'both': live-tested against a real server, sending both auth header
|
||
// conventions on one request reliably HANGS it — see custom-model-hosts.ts.
|
||
authStyle: z.enum(['bearer', 'api-key']).optional(),
|
||
models: z.array(z.string().max(200)).max(200).optional(),
|
||
lastDiscoveredAt: z.string().max(64).optional(),
|
||
// The Run-menu picker's per-endpoint default; validated against `models` at the
|
||
// route layer (schema-level cross-field checks can't see the array narrowed the
|
||
// same way a `.refine()` closure could, and the route already re-reads the stored
|
||
// host to apply it, so the check belongs there once, not duplicated into a refine
|
||
// that would run on every unrelated field edit too).
|
||
defaultModelId: z.string().max(200).optional(),
|
||
// Server-populated by discovery (custom-model-routes.ts); accepted here only so a client
|
||
// round-tripping the GET response back through PUT (edit-save) doesn't drop it.
|
||
modelContextLengths: z
|
||
.record(z.string().max(200), z.number().int().positive().max(MAX_DISCOVERED_CONTEXT_TOKENS))
|
||
.optional(),
|
||
// Same reasoning as modelContextLengths above.
|
||
modelSlotCounts: z.record(z.string().max(200), z.number().int().positive().max(4096)).optional(),
|
||
// Same reasoning as modelContextLengths above.
|
||
modelSizesGB: z.record(z.string().max(200), z.number().positive().max(100_000)).optional(),
|
||
// User-set fallback for models discovery has no context length for (session-routes.ts);
|
||
// discovery never writes it. Same bound as the modelContextLengths values above.
|
||
defaultContextLength: z.number().int().positive().max(MAX_DISCOVERED_CONTEXT_TOKENS).optional(),
|
||
});
|
||
|
||
// ---------- Local model install (src/web/routes/local-model-routes.ts) ----------
|
||
|
||
/**
|
||
* A model id as the local model catalogue writes it: `name:tag`, lowercase, no slash. The
|
||
* same pattern as `LOCAL_MODEL_ID_PATTERN` in config/local-model-catalog.ts, repeated here as
|
||
* a request-shape check: without a slash an id can never name another registry host. The
|
||
* real gate is the route's own lookup of the id in what the server offers.
|
||
*/
|
||
const localModelId = z
|
||
.string()
|
||
.max(200)
|
||
.regex(/^[a-z0-9][a-z0-9._-]*:[a-z0-9][a-z0-9._-]*$/, 'Invalid model id');
|
||
|
||
/** POST /api/local-model/install: the row the person chose and the size they confirmed. */
|
||
export const LocalModelInstallSchema = z
|
||
.object({
|
||
modelId: localModelId,
|
||
cli: z
|
||
.string()
|
||
.max(64)
|
||
.regex(/^[a-z0-9][a-z0-9_-]*$/, 'Invalid coding agent id'),
|
||
context: z.number().int().positive().max(MAX_DISCOVERED_CONTEXT_TOKENS),
|
||
acknowledgedBytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
|
||
})
|
||
.strict();
|
||
|
||
/** POST /api/local-model/resume. The body may be empty. */
|
||
export const LocalModelResumeSchema = z.object({ newPort: z.boolean().optional() }).strict();
|
||
|
||
/** POST /api/local-model/runtime. */
|
||
export const LocalModelRuntimeSchema = z
|
||
.object({ action: z.enum(['start', 'stop']), newPort: z.boolean().optional() })
|
||
.strict();
|
||
|
||
/** DELETE /api/local-model. The body may be empty. */
|
||
export const LocalModelRemoveSchema = z.object({ removeModel: z.boolean().optional() }).strict();
|
||
|
||
/**
|
||
* A shell-safe bare word, mirroring `config/cli-registry/schema.ts`'s own `shellToken` —
|
||
* duplicated rather than imported, since the REAL safety boundary for anything built from
|
||
* this is `CliEntrySchema` itself, re-applied server-side once the full entry is assembled
|
||
* (`cli-registry-routes.ts`). This is a request-shape sanity check, not the security gate.
|
||
*/
|
||
const cliShellToken = z
|
||
.string()
|
||
.min(1)
|
||
.max(256)
|
||
.regex(/^[A-Za-z0-9._:@=+/,-]+$/, 'must be a plain word with no shell metacharacters');
|
||
|
||
/** PUT /api/clis/:id (Phase 3) — enable/disable an existing entry, stock or custom; `enabled` is the ONLY thing this endpoint can flip. */
|
||
export const CliEnableSchema = z.object({ enabled: z.boolean() });
|
||
|
||
/**
|
||
* POST /api/clis + PUT /api/clis/custom/:id (Phase 5) — a deliberately MINIMAL custom-CLI
|
||
* shape (docs/cli-enable-disable-plan.md, Phase 6 checklist: "scope the FIRST version to the
|
||
* fields most stock entries actually use"), not the full `CliEntry`. `cli-registry-routes.ts`
|
||
* assembles the rest with safe, conservative capability defaults and re-validates the whole
|
||
* thing through `CliEntrySchema` before ever writing it — this schema exists to bound the
|
||
* REQUEST shape, not to BE the safety layer (Decision 3: typed-argv only, no raw shell text).
|
||
*/
|
||
export const CliCustomEntrySchema = z.object({
|
||
id: z.string().regex(/^[a-z][a-z0-9-]{0,23}$/, 'id must be lowercase, start with a letter, at most 24 chars'),
|
||
label: z.string().min(1).max(60),
|
||
shortBadge: z.string().min(1).max(6),
|
||
enabled: z.boolean().optional(),
|
||
binaries: z.array(cliShellToken).min(1).max(4),
|
||
/** Bare argv tokens for the single launch variant — no flags-with-values, no params. */
|
||
argv: z.array(cliShellToken).min(1).max(16),
|
||
});
|
||
|
||
/** POST /api/sessions/:id/custom-model — apply or clear a session's custom-model selection. */
|
||
export const CustomModelSelectionSchema = z.union([
|
||
z.object({
|
||
endpointId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid endpoint id'),
|
||
modelId: z.string().min(1).max(200),
|
||
/**
|
||
* Two DIFFERENT questions can block a launch, and answering one is not consent to
|
||
* the other: `confirmedContext` answers "this model's context window is below the
|
||
* floor for this CLI", which affects only the caller, while `confirmedSwap` answers
|
||
* "loading this will unload the model another session is using", which affects
|
||
* someone else. They were one flag until the context check (which runs first)
|
||
* silently spent the swap answer too, so a user clicking "launch anyway" past a
|
||
* too-small context evicted another session's model without ever being asked.
|
||
*
|
||
* `confirmed` is the original single flag and still means BOTH, because it shipped
|
||
* in the HTTP-API-only cut of this feature and an existing caller must keep working.
|
||
* New callers should send the specific one they actually asked about.
|
||
*/
|
||
confirmed: z.boolean().optional(),
|
||
confirmedContext: z.boolean().optional(),
|
||
confirmedSwap: z.boolean().optional(),
|
||
}),
|
||
z.object({ clear: z.literal(true) }),
|
||
]);
|
||
/**
|
||
* Adopt a FOREIGN tmux session (one a human started outside Codeman).
|
||
*
|
||
* ⚠️ The body carries ONLY the opaque candidate id from `GET /api/mux/foreign`.
|
||
* The socket path, session name and host are re-resolved server-side by re-running
|
||
* discovery, so a browser can never hand the launch chain a path or a session name
|
||
* to interpolate. That is the same discipline that keeps the docker-adopt and
|
||
* remote-attach paths free of caller-supplied command fragments.
|
||
*/
|
||
export const AdoptForeignSessionSchema = z
|
||
.object({
|
||
id: z.string().min(1).max(64),
|
||
/** Optional tab name; defaults to the foreign session's own name. */
|
||
name: z.string().max(128).optional(),
|
||
/** Include docker locations in the re-resolve (must match the listing call). */
|
||
docker: z.boolean().optional(),
|
||
/** Include remote locations in the re-resolve. */
|
||
remote: z.boolean().optional(),
|
||
parentSessionId: z.string().max(64).optional(),
|
||
})
|
||
.strict();
|
||
|
||
/** Agent inspection bounds are bytes of evidence, independent of the JSON envelope. */
|
||
export const AgentInspectQuerySchema = z
|
||
.object({
|
||
maxBytes: z.coerce.number().int().min(1).max(65536).default(8192),
|
||
since: z.string().uuid().optional(),
|
||
})
|
||
.strict();
|
||
export const AgentStageSchema = z.object({ message: z.string().min(1).max(8192) }).strict();
|
||
export const AgentSubmitSchema = z
|
||
.object({ stageId: z.string().uuid(), confirmSha: z.string().regex(/^[a-f0-9]{64}$/) })
|
||
.strict();
|