@visual-z/xeno 0.5.0 → 0.7.0

package/src/core/agent-profile.ts

@@ -0,0 +1,130 @@
+/** R13 / D13: explicit role layers share tool, model, workflow and budget ownership. */
+import { isWorkflowMode, type WorkflowMode } from "./workflow-mode.ts";
+import { isToolProfile, parsePermissionRule, type PermissionRule, type ToolSelection } from "./permissions.ts";
+import { asThinkingLevel, type ThinkingLevel } from "./thinking.ts";
+
+export interface AgentProfile {
+  readonly name: string;
+  readonly description?: string;
+  readonly mode?: WorkflowMode;
+  readonly instructions?: string;
+  readonly model?: { readonly provider: string; readonly id: string; readonly thinking?: ThinkingLevel };
+  readonly tools?: ToolSelection;
+  readonly permissions?: readonly PermissionRule[];
+  /** maxTurns is a hard cap; timeBudgetMs retains the existing advisory semantics. */
+  readonly budget?: { readonly maxTurns?: number; readonly timeBudgetMs?: number };
+}
+export type AgentProfileField = Exclude<keyof AgentProfile, "name">;
+export interface AgentProfileSource { readonly kind: "builtin" | "user" | "project" | "cli"; readonly path?: string }
+export interface AgentProfileLayer { readonly source: AgentProfileSource; readonly profiles: readonly AgentProfile[] }
+export interface ResolvedAgentProfile {
+  readonly profile: AgentProfile;
+  readonly sources: readonly AgentProfileSource[];
+  readonly provenance: Readonly<Partial<Record<AgentProfileField, AgentProfileSource>>>;
+}
+export interface AgentProfileParse { readonly profiles: readonly AgentProfile[]; readonly diagnostics: readonly string[] }
+
+/** Named builtins are explicit selectable presets; they never fill missing fields in another role. */
+export function builtinAgentProfileLayer(): AgentProfileLayer {
+  return { source: { kind: "builtin" }, profiles: [{ name: "build", mode: "build", tools: { profile: "foundation" } }, { name: "plan", mode: "plan", tools: { profile: "foundation" } },
+    { name: "reviewer", mode: "plan", tools: { profile: "readonly" },
+      instructions: "Review current code for actionable defects. Cite concrete evidence and paths; do not edit the workspace." }] };
+}
+
+const FIELDS: readonly AgentProfileField[] = ["description", "mode", "instructions", "model", "tools", "permissions", "budget"];
+export function isAgentProfileName(value: string): boolean { return /^[a-z][a-z0-9_-]{0,63}$/.test(value); }
+function record(value: unknown, label: string, allowed: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error(`${label} must be an object`);
+  const obj = value as Record<string, unknown>;
+  const unknown = Object.keys(obj).find(key => !allowed.includes(key));
+  if (unknown) throw Error(`${label} has unknown field ${unknown}`);
+  return obj;
+}
+function text(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim() || value.includes("\0")) throw Error(`${label} must be a nonempty string`);
+  return value;
+}
+function strings(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim()) || new Set(value).size !== value.length) throw Error(`${label} must contain unique nonempty names`);
+  return [...value] as string[];
+}
+
+export function parseAgentProfile(value: unknown): AgentProfile {
+  const obj = record(value, "agent profile", ["name", ...FIELDS]);
+  const name = text(obj["name"], "agent name");
+  if (!isAgentProfileName(name)) throw Error("agent name must begin with a lowercase letter and contain only letters, digits, _ or - (max 64)");
+  const profile: { name: string; description?: string; mode?: WorkflowMode; instructions?: string;
+    model?: NonNullable<AgentProfile["model"]>; tools?: ToolSelection; permissions?: PermissionRule[]; budget?: NonNullable<AgentProfile["budget"]> } = { name };
+  if (obj["description"] !== undefined) profile.description = text(obj["description"], "agent description");
+  if (obj["instructions"] !== undefined) profile.instructions = text(obj["instructions"], "agent instructions");
+  if (obj["mode"] !== undefined) {
+    if (typeof obj["mode"] !== "string" || !isWorkflowMode(obj["mode"])) throw Error("agent mode must be build or plan");
+    profile.mode = obj["mode"];
+  }
+  if (obj["model"] !== undefined) {
+    const model = record(obj["model"], "agent model", ["provider", "id", "thinking"]);
+    const provider = text(model["provider"], "agent model provider"), id = text(model["id"], "agent model id");
+    const thinking = asThinkingLevel(model["thinking"]);
+    if (model["thinking"] !== undefined && thinking === undefined) throw Error("agent model thinking is invalid");
+    profile.model = { provider, id, ...(thinking !== undefined ? { thinking } : {}) };
+  }
+  if (obj["tools"] !== undefined) {
+    const tools = record(obj["tools"], "agent tools", ["profile", "only", "exclude", "none", "noBuiltin"]);
+    const selected: { profile?: NonNullable<ToolSelection["profile"]>; only?: string[]; exclude?: string[]; none?: boolean; noBuiltin?: boolean } = {};
+    if (tools["profile"] !== undefined) {
+      if (typeof tools["profile"] !== "string" || !isToolProfile(tools["profile"])) throw Error("agent tool profile is invalid");
+      selected.profile = tools["profile"];
+    }
+    if (tools["only"] !== undefined) selected.only = strings(tools["only"], "agent tools.only");
+    if (tools["exclude"] !== undefined) selected.exclude = strings(tools["exclude"], "agent tools.exclude");
+    for (const key of ["none", "noBuiltin"] as const) {
+      if (tools[key] !== undefined) { if (typeof tools[key] !== "boolean") throw Error(`agent tools.${key} must be boolean`); selected[key] = tools[key]; }
+    }
+    profile.tools = selected;
+  }
+  if (obj["permissions"] !== undefined) {
+    if (!Array.isArray(obj["permissions"])) throw Error("agent permissions must be an array");
+    profile.permissions = obj["permissions"].map(parsePermissionRule);
+  }
+  if (obj["budget"] !== undefined) {
+    const budget = record(obj["budget"], "agent budget", ["maxTurns", "timeBudgetMs"]);
+    const selected: { maxTurns?: number; timeBudgetMs?: number } = {};
+    for (const key of ["maxTurns", "timeBudgetMs"] as const) {
+      if (budget[key] !== undefined) {
+        if (!Number.isSafeInteger(budget[key]) || Number(budget[key]) < 1) throw Error(`agent budget.${key} must be a positive safe integer`);
+        selected[key] = Number(budget[key]);
+      }
+    }
+    profile.budget = selected;
+  }
+  return profile;
+}
+
+/** A malformed document contributes no partial authority. */
+export function parseAgentProfiles(value: unknown): AgentProfileParse {
+  try {
+    const obj = record(value, "agents document", ["profiles"]);
+    if (!Array.isArray(obj["profiles"])) throw Error("agents document profiles must be an array");
+    const profiles = obj["profiles"].map(parseAgentProfile);
+    if (new Set(profiles.map(profile => profile.name)).size !== profiles.length) throw Error("agents document contains duplicate profile names");
+    return { profiles, diagnostics: [] };
+  } catch (error) { return { profiles: [], diagnostics: [error instanceof Error ? error.message : "Invalid agents document"] }; }
+}
+
+/** Caller supplies low-to-high layers; whole-field replacement stays explainable. */
+export function resolveAgentProfile(name: string, layers: readonly AgentProfileLayer[]): ResolvedAgentProfile | null {
+  let profile: AgentProfile | undefined;
+  const sources: AgentProfileSource[] = [], provenance: Partial<Record<AgentProfileField, AgentProfileSource>> = {};
+  for (const layer of layers) {
+    const matching = layer.profiles.find(item => item.name === name);
+    if (!matching) continue;
+    const source = structuredClone(layer.source);
+    sources.push(source); profile = { ...profile, ...structuredClone(matching) };
+    for (const field of FIELDS) if (matching[field] !== undefined) provenance[field] = structuredClone(source);
+  }
+  return profile ? { profile, sources, provenance } : null;
+}
+
+export function agentProfileNames(layers: readonly AgentProfileLayer[]): string[] {
+  return [...new Set(layers.flatMap(layer => layer.profiles.map(profile => profile.name)))].sort();
+}

package/src/core/control-protocol.ts

@@ -9,12 +9,19 @@ const turn = { ...thread, turnId: identity };
 export const CONTROL_METHODS = {
   initialize: object({ clientInfo: object({ name: identity, version: identity }) }),
   initialized: object({}),
+  "thread/list": object({}),
+  "thread/new": object({ name: identity }, []),
+  "thread/resume": object({ session: text }),
+  "thread/fork": object({ ...thread, name: identity }, ["threadId"]),
+  "thread/close": object(thread),
+  "thread/mode": object({ ...thread, mode: { enum: ["build", "plan"] } }),
   "thread/read": object(thread),
   "thread/subscribe": object({ ...thread, after: object({ streamId: identity, sequence: { type: "integer", minimum: 0 } }) }, ["threadId"]),
   "turn/start": object({ ...thread, input: text }),
   "turn/steer": object({ ...turn, input: text }),
   "turn/interrupt": object(turn),
   "approval/respond": object({ ...turn, approvalId: identity, choice: { enum: ["once", "command", "tool", "deny"] } }),
+  "question/respond": object({ ...turn, requestId: text, reply: text }),
   "acceptance/accept": object({ ...thread, requestId: identity, criterionId: identity }),
   "context/read": object({ ...thread, focus: { enum: ["messages", "omitted", "history"] }, offset: { type: "integer", minimum: 0 },
     limit: { type: "integer", minimum: 1, maximum: 100 } }, ["threadId", "focus"]),
@@ -24,7 +31,7 @@ export const CONTROL_METHODS = {
 } as const;
 export const CONTROL_SCHEMA = { protocol: "xeno-control/0.1", experimental: true,
   transport: "JSONL; JSON-RPC envelopes with jsonrpc omitted", methods: CONTROL_METHODS,
-  notifications: ["turn/started", "turn/event", "item/completed", "turn/completed", "turn/error", "turn/steeringQueued", "approval/request", "approval/resolved", "thread/statusChanged"],
+  notifications: ["turn/started", "turn/event", "item/completed", "turn/completed", "turn/error", "turn/steeringQueued", "approval/request", "approval/resolved", "question/request", "question/resolved", "thread/statusChanged"],
   recovery: "subscribe first, then use the returned snapshot cursor; gaps or a new streamId require a snapshot and paginated item/list, never replaying commands",
   identity: "threadId hashes the resolved session directory path; turnId is the original user event ID; item identity is node plus event ID",
   limits: { frameBytes: 1048576, queuedRequests: 32, outputBytes: 2097152 } } as const;

package/src/core/file-precondition.ts

@@ -26,6 +26,12 @@ export const isFileDigest = (value: unknown): value is string => typeof value ==
 export function latestObservedFileVersion(events: readonly LogEvent[], resource: string, identify: (path: string) => string): string | undefined {
   for (let index = events.length - 1; index >= 0; index--) {
     const event = events[index]!;
+    // P.3: multi-file Patch and captured commands observe each actual resulting version.
+    if (event.t === "checkpoint" && event.phase === "applied") {
+      for (const [path, change] of Object.entries(event.changes))
+        if (identify(path) === resource) return change.after?.sha256;
+      continue;
+    }
     if (event.t !== "tool_result") continue;
     const effect = event.effect;
     if ((effect?.kind === "read" || effect?.kind === "edit") && identify(effect.path) === resource)

package/src/core/git-status.ts

@@ -0,0 +1,29 @@
+/** Counts from Git porcelain v2, distinct from agent tool effects. No path decoding needed. */
+export interface GitStatus {
+  readonly branch: string | null;
+  readonly staged: number;
+  readonly changed: number;
+  readonly untracked: number;
+  readonly conflicted: number;
+  readonly ahead: number;
+  readonly behind: number;
+}
+export function parseGitStatus(output: string): GitStatus {
+  let branch: string | null = null, staged = 0, changed = 0, untracked = 0, conflicted = 0, ahead = 0, behind = 0;
+  const records = output.split("\0");
+  for (let index = 0; index < records.length; index++) {
+    const line = records[index]!;
+    if (line.startsWith("# branch.head ")) branch = line.slice(14).trim();
+    else if (line.startsWith("# branch.ab ")) {
+      const match = /^# branch.ab \+(\d+) -(\d+)$/.exec(line.trim());
+      if (match) { ahead = Number(match[1]); behind = Number(match[2]); }
+    } else if (line.startsWith("? ")) untracked++;
+    else if (/^[12u] [A-Z?.]{2} /.test(line)) {
+      if (line[2] !== ".") staged++;
+      if (line[3] !== ".") changed++;
+      if (line[0] === "u") conflicted++;
+      if (line[0] === "2") index++; // Rename's next NUL field is a path, never a status record.
+    }
+  }
+  return { branch, staged, changed, untracked, conflicted, ahead, behind };
+}

package/src/core/image-limits.ts

@@ -0,0 +1,72 @@
+/** Admission, model detail and preview memory are separate budgets (D8). */
+export const MAX_IMAGE_SOURCE_BYTES = 64 * 1024 * 1024;
+/** Matches the native decoder's area cap; inspect headers before WASM allocates. */
+export const MAX_IMAGE_SOURCE_PIXELS = 25_000_000;
+/** More readable screenshots than 2000px, with at most 32 MiB RGBA per preview. */
+export const MAX_MODEL_IMAGE_SIDE = 4096;
+export const MAX_MODEL_IMAGE_PIXELS = 8 * 1024 * 1024;
+export interface ImageDimensions { readonly width: number; readonly height: number }
+
+/** Header-only probe. Decoders still validate the complete image afterward. */
+export function imageDimensions(bytes: Uint8Array, mime: string): ImageDimensions | undefined {
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const result = (width: number, height: number): ImageDimensions | undefined =>
+    Number.isSafeInteger(width) && Number.isSafeInteger(height) && width > 0 && height > 0 ? { width, height } : undefined;
+  if (mime === "image/png" && bytes.length >= 24) return result(v.getUint32(16), v.getUint32(20));
+  if (mime === "image/gif" && bytes.length >= 10) return result(v.getUint16(6, true), v.getUint16(8, true));
+  if (mime === "image/bmp" && bytes.length >= 26) {
+    const header = v.getUint32(14, true);
+    if (header === 12) return result(v.getUint16(18, true), v.getUint16(20, true));
+    if (header >= 40) return result(v.getInt32(18, true), Math.abs(v.getInt32(22, true)));
+    return undefined;
+  }
+  if (mime === "image/jpeg") {
+    let offset = 2;
+    while (offset + 3 < bytes.length) {
+      if (bytes[offset++] !== 255) return undefined;
+      while (bytes[offset] === 255) offset++;
+      const marker = bytes[offset++];
+      if (marker === undefined || marker === 0xda || marker === 0xd9) return undefined;
+      if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) continue;
+      if (offset + 2 > bytes.length) return undefined;
+      const size = v.getUint16(offset);
+      if (size < 2 || offset + size > bytes.length) return undefined;
+      if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+        return size >= 8 ? result(v.getUint16(offset + 5), v.getUint16(offset + 3)) : undefined;
+      }
+      offset += size;
+    }
+  }
+  if (mime === "image/webp") {
+    for (let offset = 12; offset + 8 <= bytes.length;) {
+      const size = v.getUint32(offset + 4, true), start = offset + 8;
+      if (start + size > bytes.length) return undefined;
+      const kind = String.fromCharCode(...bytes.subarray(offset, offset + 4));
+      const u24 = (at: number) => v.getUint8(at) | v.getUint8(at + 1) << 8 | v.getUint8(at + 2) << 16;
+      if (kind === "VP8X" && size >= 10) return result(u24(start + 4) + 1, u24(start + 7) + 1);
+      if (kind === "VP8L" && size >= 5 && bytes[start] === 0x2f) {
+        const packed = v.getUint32(start + 1, true);
+        return result((packed & 0x3fff) + 1, ((packed >>> 14) & 0x3fff) + 1);
+      }
+      if (kind === "VP8 " && size >= 10 && bytes[start + 3] === 0x9d && bytes[start + 4] === 1 && bytes[start + 5] === 0x2a)
+        return result(v.getUint16(start + 6, true) & 0x3fff, v.getUint16(start + 8, true) & 0x3fff);
+      offset = start + size + size % 2;
+    }
+  }
+  return undefined;
+}
+
+/** Floors keep the area bound exact; small inputs are never upscaled. */
+export function modelImageDimensions(image: ImageDimensions): ImageDimensions {
+  const scale = Math.min(1, MAX_MODEL_IMAGE_SIDE / image.width, MAX_MODEL_IMAGE_SIDE / image.height,
+    Math.sqrt(MAX_MODEL_IMAGE_PIXELS / image.width / image.height));
+  return { width: Math.max(1, Math.floor(image.width * scale)), height: Math.max(1, Math.floor(image.height * scale)) };
+}
+
+/** Pi rotates EXIF before resizing and rounds the short side; symmetric bounds preserve both orientations. */
+export function modelImageSide(image: ImageDimensions): number {
+  const long = Math.max(image.width, image.height), short = Math.min(image.width, image.height);
+  let side = Math.max(...Object.values(modelImageDimensions(image)));
+  while (side * Math.max(1, Math.round(short * side / long)) > MAX_MODEL_IMAGE_PIXELS) side--;
+  return side;
+}

package/src/core/lsp-framing.ts

@@ -0,0 +1,34 @@
+/** LSP 3.17 uses byte-counted Content-Length, not line-delimited JSON. */
+export type LspFrame = { body: Uint8Array; consumed: number };
+// Operational ceiling for optional server output; this is not a context segment threshold.
+export const MAX_LSP_FRAME = 8 * 1024 * 1024;
+// An operational bound, independent of context-segment thresholds: reject unbounded headers.
+export const MAX_LSP_HEADER = 8192;
+export function nextLspFrame(bytes: Uint8Array): LspFrame | null {
+  let end = -1;
+  for (let i = 0; i + 3 < bytes.length; i++) if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) { end = i; break; }
+  if (end < 0) { if (bytes.length > MAX_LSP_HEADER) throw Error("LSP header exceeds 8 KiB"); return null; }
+  if (end > MAX_LSP_HEADER || bytes.subarray(0, end).some(byte => byte > 127)) throw Error("invalid LSP ASCII header");
+  const headers = new TextDecoder("ascii").decode(bytes.subarray(0, end)).split("\r\n");
+  if (headers.some(header => !/^[a-zA-Z0-9-]+:[\t\x20-\x7e]*$/.test(header))) throw Error("invalid LSP header field");
+  const lengths = headers.filter(header => /^content-length:/i.test(header));
+  if (lengths.length !== 1 || !/^content-length:\s*[0-9]+\s*$/i.test(lengths[0]!)) throw Error("invalid LSP Content-Length");
+  const types = headers.filter(header => /^content-type:/i.test(header));
+  if (types.length > 1) throw Error("ambiguous LSP Content-Type");
+  const charsets = types.flatMap(header => header.split(";").slice(1).filter(parameter => /^\s*charset\s*=/i.test(parameter)));
+  if (charsets.length > 1 || charsets.some(parameter => !/^\s*charset\s*=\s*(utf-?8|"utf-?8")\s*$/i.test(parameter))) throw Error("unsupported LSP charset");
+  const length = Number(lengths[0]!.split(":")[1]!.trim());
+  if (!Number.isSafeInteger(length) || length > MAX_LSP_FRAME) throw Error("LSP frame exceeds 8 MiB");
+  const consumed = end + 4 + length;
+  return bytes.length < consumed ? null : { body: bytes.slice(end + 4, consumed), consumed };
+}
+/** Unversioned server diagnostics cannot prove that they describe the current owned file. */
+export function diagnosticFreshness(observedVersion: number | undefined, currentVersion: number): "current" | "stale" | "unversioned" {
+  return observedVersion === undefined ? "unversioned" : observedVersion === currentVersion ? "current" : "stale";
+}
+export function encodeLspFrame(value: unknown): Uint8Array {
+  const body = new TextEncoder().encode(JSON.stringify(value));
+  if (body.length > MAX_LSP_FRAME) throw Error("LSP frame exceeds 8 MiB");
+  const header = new TextEncoder().encode(`Content-Length: ${body.length}\r\n\r\n`);
+  const frame = new Uint8Array(header.length + body.length); frame.set(header); frame.set(body, header.length); return frame;
+}

package/src/core/mcp-config.ts

@@ -0,0 +1,68 @@
+/** Explicit MCP configuration is authority; remote tool annotations never grant permissions (D11/D13). */
+import { webUrl } from "./web-content.ts";
+
+export interface McpOAuthConfig { clientId?: string; clientSecretEnv?: string; scope?: string; redirectUrl?: string }
+interface McpCommonConfig { enabled?: boolean; timeoutMs?: number }
+export type McpServerConfig = McpCommonConfig & ({ transport: "stdio"; command: string; args?: string[]; env?: Record<string, string> }
+  | { transport: "http"; url: string; bearerTokenEnv?: string; headers?: Record<string, string>; headersEnv?: Record<string, string>; oauth?: boolean | McpOAuthConfig });
+export type McpServers = Readonly<Record<string, McpServerConfig>>;
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw Error(`${label} must be an object`);
+  return value as Record<string, unknown>;
+}
+function strings(value: unknown, label: string, envNames = false): Record<string, string> {
+  const source = object(value, label), result: Record<string, string> = Object.create(null);
+  for (const [key, entry] of Object.entries(source)) {
+    if (typeof entry !== "string" || /[\r\n\u0000]/.test(entry) || /[\r\n\u0000]/.test(key)) throw Error(`${label} must contain single-line string values`);
+    if (envNames && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(entry)) throw Error(`${label} values must name environment variables`);
+    result[key] = entry;
+  }
+  return result;
+}
+function optionalString(source: Record<string, unknown>, key: string, envName = false): string | undefined {
+  const value = source[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value || /[\r\n\u0000]/.test(value) || envName && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) throw Error(`${key} must be a valid ${envName ? "environment variable name" : "single-line string"}`);
+  return value;
+}
+export function mcpCallbackUrl(value: string): string {
+  const parsed = new URL(webUrl(value));
+  if (parsed.protocol !== "http:" || parsed.hostname !== "127.0.0.1" || parsed.search || !parsed.port || !parsed.pathname.startsWith("/"))
+    throw Error("OAuth redirectUrl must be an HTTP 127.0.0.1 URL with an explicit port and no query");
+  return parsed.href;
+}
+function oauth(value: unknown): boolean | McpOAuthConfig {
+  if (typeof value === "boolean") return value;
+  const source = object(value, "oauth");
+  if (Object.keys(source).some(key => !["clientId", "clientSecretEnv", "scope", "redirectUrl"].includes(key))) throw Error("oauth has an unsupported field");
+  const clientId = optionalString(source, "clientId"), clientSecretEnv = optionalString(source, "clientSecretEnv", true), scope = optionalString(source, "scope"), redirectUrl = optionalString(source, "redirectUrl");
+  if (clientSecretEnv && !clientId) throw Error("oauth.clientSecretEnv requires oauth.clientId");
+  return { ...(clientId ? { clientId } : {}), ...(clientSecretEnv ? { clientSecretEnv } : {}), ...(scope ? { scope } : {}), ...(redirectUrl ? { redirectUrl: mcpCallbackUrl(redirectUrl) } : {}) };
+}
+export function parseMcpServers(value: unknown): McpServers {
+  if (value === undefined || value === null) return {};
+  const source = object(value, "mcpServers"), result: Record<string, McpServerConfig> = Object.create(null);
+  for (const [name, raw] of Object.entries(source)) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) throw Error("MCP server names must contain 1 to 64 letters, digits, underscores or hyphens");
+    const config = object(raw, `MCP server ${name}`), enabled = config["enabled"], timeout = config["timeoutMs"];
+    if (enabled !== undefined && typeof enabled !== "boolean") throw Error(`MCP server ${name}.enabled must be boolean`);
+    // Assumed cap protects startup and tool execution from a misconfigured peer, not an OS sandbox.
+    if (timeout !== undefined && (!Number.isSafeInteger(timeout) || Number(timeout) < 1 || Number(timeout) > 300_000)) throw Error("MCP timeoutMs must be an integer from 1 to 300000");
+    const common = { ...(typeof enabled === "boolean" ? { enabled } : {}), ...(typeof timeout === "number" ? { timeoutMs: timeout } : {}) };
+    if (config["transport"] === "stdio") {
+      if (Object.keys(config).some(key => !["transport", "command", "args", "env", "enabled", "timeoutMs"].includes(key))) throw Error(`MCP server ${name} has an unsupported stdio field`);
+      const command = optionalString(config, "command"), args = config["args"], env = config["env"];
+      if (!command) throw Error(`MCP server ${name}.command is required`);
+      if (args !== undefined && (!Array.isArray(args) || !args.every(arg => typeof arg === "string" && !arg.includes("\u0000")))) throw Error("MCP args must be strings without NUL");
+      result[name] = { transport: "stdio", command, ...common, ...(Array.isArray(args) ? { args: args.slice() as string[] } : {}), ...(env === undefined ? {} : { env: strings(env, "env") }) };
+    } else if (config["transport"] === "http") {
+      if (Object.keys(config).some(key => !["transport", "url", "bearerTokenEnv", "headers", "headersEnv", "oauth", "enabled", "timeoutMs"].includes(key))) throw Error(`MCP server ${name} has an unsupported HTTP field`);
+      const token = optionalString(config, "bearerTokenEnv", true), headers = config["headers"], headersEnv = config["headersEnv"];
+      if (config["oauth"] && token) throw Error("Use bearerTokenEnv or oauth for one MCP server, not both");
+      result[name] = { transport: "http", url: webUrl(config["url"]), ...common, ...(token ? { bearerTokenEnv: token } : {}),
+        ...(headers === undefined ? {} : { headers: strings(headers, "headers") }), ...(headersEnv === undefined ? {} : { headersEnv: strings(headersEnv, "headersEnv", true) }),
+        ...(config["oauth"] === undefined ? {} : { oauth: oauth(config["oauth"]) }) };
+    } else throw Error(`MCP server ${name}.transport must be stdio or http`);
+  }
+  return result;
+}

package/src/core/patch.ts

@@ -0,0 +1,130 @@
+/** Codex patch grammar with exact, unambiguous matching (D9 / R4). No I/O. */
+import { assertNever } from "./exhaustive.ts";
+
+// Assumed resource ceilings, not measured: reject oversized plans before retaining hunks.
+export const MAX_PATCH_CHARS = 2 * 1024 * 1024;
+export const MAX_PATCH_FILES = 100;
+export interface PatchChunk {
+  oldLines: readonly string[];
+  newLines: readonly string[];
+  anchor?: string;
+  endOfFile: boolean;
+}
+export type PatchOperation =
+  | { kind: "add"; path: string; content: string }
+  | { kind: "delete"; path: string }
+  | { kind: "update"; path: string; movePath?: string; chunks: readonly PatchChunk[] };
+export class PatchError extends Error {
+  readonly code: "invalid_input" | "not_found" | "ambiguous_edit";
+  constructor(code: PatchError["code"], message: string) { super(message); this.code = code; }
+}
+const invalid = (message: string): never => { throw new PatchError("invalid_input", message); };
+const pathValue = (text: string): string => {
+  if (!text.trim() || text.includes("\0")) return invalid("patch paths must be nonempty and contain no NUL");
+  return text;
+};
+const fileHeader = (line: string) => /^\*\*\* (?:Add|Delete|Update) File: /.test(line);
+
+/** Parse all operations before the store resolves any target or changes a byte. */
+export function parsePatch(text: string): PatchOperation[] {
+  if (text.length > MAX_PATCH_CHARS) return invalid("patch exceeds the character budget");
+  const lines = text.replaceAll("\r\n", "\n").trim().split("\n");
+  if (lines[0] !== "*** Begin Patch" || lines.at(-1) !== "*** End Patch")
+    return invalid("patch must begin with *** Begin Patch and end with *** End Patch");
+  const operations: PatchOperation[] = [];
+  let index = 1;
+  while (index < lines.length - 1) {
+    if (operations.length >= MAX_PATCH_FILES) return invalid("patch exceeds the file budget");
+    const header = lines[index++]!;
+    if (header.startsWith("*** Add File: ")) {
+      const path = pathValue(header.slice("*** Add File: ".length));
+      const added: string[] = [];
+      while (index < lines.length - 1 && !fileHeader(lines[index]!)) {
+        const line = lines[index++]!;
+        if (!line.startsWith("+")) return invalid(`added lines must start with +: ${path}`);
+        added.push(line.slice(1));
+      }
+      operations.push({ kind: "add", path, content: added.length ? added.join("\n") + "\n" : "" });
+      continue;
+    }
+    if (header.startsWith("*** Delete File: ")) {
+      operations.push({ kind: "delete", path: pathValue(header.slice("*** Delete File: ".length)) });
+      continue;
+    }
+    if (!header.startsWith("*** Update File: ")) return invalid(`unexpected patch line ${index}: ${header}`);
+    const path = pathValue(header.slice("*** Update File: ".length));
+    const moveLine = lines[index];
+    const movePath = moveLine?.startsWith("*** Move to: ") ? pathValue(moveLine.slice("*** Move to: ".length)) : undefined;
+    if (movePath !== undefined) index++;
+    const chunks: PatchChunk[] = [];
+    while (index < lines.length - 1 && !fileHeader(lines[index]!)) {
+      const marker = lines[index++]!;
+      if (marker !== "@@" && !marker.startsWith("@@ ")) return invalid(`update hunks must start with @@: ${path}`);
+      const oldLines: string[] = [], newLines: string[] = [];
+      let endOfFile = false, changed = false;
+      while (index < lines.length - 1 && !fileHeader(lines[index]!) && !lines[index]!.startsWith("@@")) {
+        const line = lines[index++]!;
+        if (line === "*** End of File") { endOfFile = true; break; }
+        const prefix = line[0];
+        if (prefix !== " " && prefix !== "+" && prefix !== "-") return invalid(`invalid update line: ${path}`);
+        if (prefix !== "+") oldLines.push(line.slice(1));
+        if (prefix !== "-") newLines.push(line.slice(1));
+        if (prefix !== " ") changed = true;
+      }
+      if (!changed) return invalid(`update hunk makes no change: ${path}`);
+      chunks.push({ oldLines, newLines, endOfFile, ...(marker === "@@" ? {} : { anchor: marker.slice(3) }) });
+      if (endOfFile && index < lines.length - 1 && !fileHeader(lines[index]!)) return invalid(`End of File must finish the update: ${path}`);
+    }
+    if (!chunks.length && movePath === undefined) return invalid(`update has no hunks: ${path}`);
+    operations.push({ kind: "update", path, chunks, ...(movePath === undefined ? {} : { movePath }) });
+  }
+  if (!operations.length) return invalid("patch is empty");
+  return operations;
+}
+
+/** Keep BOM, line endings and final-newline status; ambiguous contexts require a reread. */
+export function applyPatchChunks(before: string, chunks: readonly PatchChunk[]): string {
+  const bom = before.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const body = before.slice(bom.length);
+  const ending = body.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = body.replaceAll("\r\n", "\n");
+  if (normalized.includes("\r")) return invalid("patch updates do not support bare CR line endings");
+  if (ending === "\r\n" && body.replaceAll("\r\n", "").includes("\n"))
+    return invalid("patch updates require a consistent line ending; mixed LF/CRLF bytes were preserved");
+  const finalNewline = normalized.endsWith("\n");
+  const lines = normalized ? normalized.split("\n") : [];
+  if (finalNewline) lines.pop();
+  let cursor = 0;
+  for (const chunk of chunks) {
+    let start = cursor;
+    if (chunk.anchor !== undefined) {
+      const anchors = lines.flatMap((line, at) => at >= cursor && line === chunk.anchor ? [at] : []);
+      if (anchors.length !== 1) throw new PatchError(anchors.length ? "ambiguous_edit" : "not_found", "patch anchor must match exactly once after the preceding hunk");
+      start = anchors[0]! + 1;
+    }
+    const matches: number[] = [];
+    for (let at = start; at <= lines.length - chunk.oldLines.length; at++) {
+      if (chunk.endOfFile && at + chunk.oldLines.length !== lines.length) continue;
+      if (chunk.oldLines.every((line, offset) => lines[at + offset] === line)) matches.push(at);
+    }
+    if (!chunk.oldLines.length && !chunk.endOfFile) {
+      if (chunk.anchor !== undefined || lines.length === 0) matches.splice(0, matches.length, start);
+      else throw new PatchError("ambiguous_edit", "insertion needs an anchor, End of File, or an empty source");
+    }
+    if (matches.length !== 1) throw new PatchError(matches.length ? "ambiguous_edit" : "not_found", "patch context must match exactly once; read current content and add context");
+    const at = matches[0]!;
+    lines.splice(at, chunk.oldLines.length, ...chunk.newLines);
+    cursor = at + chunk.newLines.length;
+  }
+  return bom + lines.join(ending) + (finalNewline && lines.length ? ending : "");
+}
+
+export function patchPaths(operations: readonly PatchOperation[]): string[] {
+  return operations.flatMap(operation => {
+    switch (operation.kind) {
+      case "add": case "delete": return [operation.path];
+      case "update": return operation.movePath === undefined ? [operation.path] : [operation.path, operation.movePath];
+      default: return assertNever(operation, "patchPaths");
+    }
+  });
+}