subharness 0.0.1

package/dist/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAyBA,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAgB,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC","sourcesContent":["import type { ErrorInfo } from '../errors.js';\nimport type { HarnessRequest, NativeSession } from '../adapters/types.js';\n\nexport type TaskState = 'queued' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled' | 'interrupted';\nexport type Delivery = 'queue' | 'steer' | 'interrupt';\nexport interface AgentReference { file: string; subagents: string[] }\nexport interface HarnessReference { kind: 'harness'; harness: HarnessRequest }\nexport type ExecutionReference = AgentReference | HarnessReference;\nexport interface SessionInput { reference: ExecutionReference; cwd: string; env: NodeJS.ProcessEnv; prompt: string; parentToken?: string }\nexport interface DriverInput extends Omit<SessionInput, 'prompt' | 'parentToken'> { token: string; sessionId: string }\nexport type DriverFactory = (input: DriverInput) => Promise<NativeSession>;\nexport interface RecordBase { version: 1; type: string; sessionId: string; taskId: string; state?: TaskState }\nexport interface Observation extends RecordBase { state: TaskState; responseId?: string; text?: string; error?: ErrorInfo }\nexport interface Receipt extends RecordBase { delivery?: Delivery; requestedDelivery?: Delivery; resumed?: boolean }\nexport interface Response extends Observation { type: 'response'; responseId: string; text: string }\nexport interface ChildResult { taskId: string; state: TaskState; text: string }\nexport interface Task {\n  id: string; sessionId: string; prompt: string; parentId?: string; state: TaskState;\n  responses: Response[]; children: Set<string>; inbox: ChildResult[]; nativeActive: boolean;\n  stopping: boolean; stopPromise?: Promise<void>; stopUnconfirmed?: boolean; error?: ErrorInfo; changed: Set<() => void>;\n}\nexport interface Session {\n  id: string; token: string; input: SessionInput; driver?: Promise<NativeSession>;\n  tasks: string[]; active?: string; paused: boolean; commands: Promise<unknown>; controls: number;\n}\nexport const terminal = (state: TaskState) => ['completed', 'failed', 'cancelled', 'interrupted'].includes(state);\n"]}

package/dist/runtime/worker-client.d.ts

@@ -0,0 +1,3 @@
+import type { NativeSession } from '../adapters/types.js';
+import type { DriverInput } from './types.js';
+export declare function createWorker(input: DriverInput): Promise<NativeSession>;

package/dist/runtime/worker-client.js

@@ -0,0 +1,81 @@
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { delimiter } from 'node:path';
+import { AgentError } from '../errors.js';
+import { createSessionLauncher } from './session-launcher.js';
+export async function createWorker(input) {
+    const launcher = await createSessionLauncher(input.env.AGENT_STATE_DIR, input.token);
+    const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    let child;
+    try {
+        child = fork(fileURLToPath(new URL(`./worker.${extension}`, import.meta.url)), [], {
+            cwd: input.cwd, env: { ...input.env, AGENT_PARENT_TOKEN: input.token, AGENT_CLI_PATH: launcher.path,
+                PATH: launcher.directory + delimiter + (input.env.PATH ?? '') },
+            execArgv: extension === 'ts' ? ['--import', import.meta.resolve('tsx')] : [],
+            stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+        });
+    }
+    catch (error) {
+        await launcher.close();
+        throw error;
+    }
+    let nextId = 1;
+    const pending = new Map();
+    let exited = false;
+    const exit = () => {
+        if (exited)
+            return;
+        exited = true;
+        void launcher.close().catch(() => { }).then(() => {
+            for (const waiting of pending.values())
+                waiting.reject(new AgentError('HARNESS_FAILED', 'The session worker exited.'));
+            pending.clear();
+        });
+    };
+    child.once('error', exit);
+    child.once('exit', exit);
+    child.on('message', (message) => {
+        const request = pending.get(message.id);
+        if (!request)
+            return;
+        pending.delete(message.id);
+        if (message.error)
+            request.reject(new AgentError(message.error.code, message.error.message));
+        else
+            request.resolve(message.result);
+    });
+    const request = (method, extra = {}) => new Promise((resolve, reject) => {
+        if (exited) {
+            reject(new AgentError('HARNESS_FAILED', 'The session worker is unavailable.'));
+            return;
+        }
+        const id = nextId++;
+        pending.set(id, { resolve, reject });
+        child.send({ id, method, ...extra }, error => { if (error) {
+            pending.delete(id);
+            reject(new AgentError('HARNESS_FAILED', 'Cannot reach the session worker.'));
+        } });
+    });
+    try {
+        await request('open', { input });
+    }
+    catch (error) {
+        child.kill();
+        await launcher.close();
+        throw error;
+    }
+    return {
+        turn: prompt => request('turn', { prompt }),
+        steer: async (prompt) => { await request('steer', { prompt }); },
+        interrupt: async () => { await request('interrupt'); },
+        resume: () => request('resume'),
+        close: async () => { try {
+            if (!exited)
+                await request('close');
+        }
+        finally {
+            await launcher.close();
+        } },
+    };
+}
+//# sourceMappingURL=worker-client.js.map

package/dist/runtime/worker-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-client.js","sourceRoot":"","sources":["../../src/runtime/worker-client.ts"],"names":[],"mappings":"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","sourcesContent":["import { fork, type ChildProcess } from 'node:child_process';\nimport { fileURLToPath } from 'node:url';\nimport { delimiter } from 'node:path';\nimport { AgentError, type ErrorInfo } from '../errors.js';\nimport type { NativeSession } from '../adapters/types.js';\nimport type { DriverInput } from './types.js';\nimport { createSessionLauncher } from './session-launcher.js';\n\nexport async function createWorker(input: DriverInput): Promise<NativeSession> {\n  const launcher = await createSessionLauncher(input.env.AGENT_STATE_DIR!,input.token);\n  const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';\n  let child: ChildProcess;\n  try {\n    child = fork(fileURLToPath(new URL(`./worker.${extension}`, import.meta.url)), [], {\n      cwd: input.cwd, env: {...input.env,AGENT_PARENT_TOKEN:input.token,AGENT_CLI_PATH:launcher.path,\n        PATH:launcher.directory + delimiter + (input.env.PATH ?? '')},\n      execArgv: extension === 'ts' ? ['--import', import.meta.resolve('tsx')] : [],\n      stdio: ['ignore','ignore','ignore','ipc'],\n    });\n  } catch (error) { await launcher.close(); throw error; }\n  let nextId = 1;\n  const pending = new Map<number, {resolve(value:unknown):void;reject(error:Error):void}>();\n  let exited = false;\n  const exit = () => {\n    if (exited) return;\n    exited = true;\n    void launcher.close().catch(() => {}).then(() => {\n      for (const waiting of pending.values()) waiting.reject(new AgentError('HARNESS_FAILED','The session worker exited.'));\n      pending.clear();\n    });\n  };\n  child.once('error', exit); child.once('exit', exit);\n  child.on('message', (message: {id:number;result?:unknown;error?:ErrorInfo}) => {\n    const request = pending.get(message.id);\n    if (!request) return;\n    pending.delete(message.id);\n    if (message.error) request.reject(new AgentError(message.error.code, message.error.message));\n    else request.resolve(message.result);\n  });\n  const request = (method:string, extra:Record<string,unknown> = {}) => new Promise<unknown>((resolve,reject) => {\n    if (exited) { reject(new AgentError('HARNESS_FAILED','The session worker is unavailable.')); return; }\n    const id = nextId++;\n    pending.set(id,{resolve,reject});\n    child.send({id,method,...extra}, error => { if (error) { pending.delete(id); reject(new AgentError('HARNESS_FAILED','Cannot reach the session worker.')); } });\n  });\n  try { await request('open',{input}); } catch (error) { child.kill(); await launcher.close(); throw error; }\n  return {\n    turn: prompt => request('turn',{prompt}) as Promise<string>,\n    steer: async prompt => { await request('steer',{prompt}); },\n    interrupt: async () => { await request('interrupt'); },\n    resume: () => request('resume') as Promise<string>,\n    close: async () => { try { if (!exited) await request('close'); } finally { await launcher.close(); } },\n  };\n}\n"]}

package/dist/runtime/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/worker.js

@@ -0,0 +1,67 @@
+import { loadExecutionDefinition } from './definition.js';
+import { loadAccess } from '../config/access.js';
+import { errorInfo } from '../errors.js';
+import { selectNative } from './select-native.js';
+import { NativeOwner } from './native-owner.js';
+import { dirname } from 'node:path';
+import { rm } from 'node:fs/promises';
+import { shellQuote } from '../shell.js';
+let native;
+const owner = new NativeOwner();
+const launcherDirectory = dirname(process.env.AGENT_CLI_PATH);
+let closing;
+const close = () => closing ??= (async () => {
+    try {
+        await owner.close();
+    }
+    finally {
+        await rm(launcherDirectory, { recursive: true, force: true });
+    }
+})();
+const reply = (message) => { if (process.connected)
+    process.send?.(message, () => { }); };
+process.on('message', async (message) => {
+    try {
+        let result;
+        if (message.method === 'open') {
+            native = await owner.open(async () => {
+                const input = message.input;
+                const definition = await loadExecutionDefinition(input.reference);
+                const children = Object.entries(definition.subagents ?? {});
+                const launcher = children.length ? shellQuote(process.env.AGENT_CLI_PATH) : '';
+                const instructions = children.length ? definition.instructions + '\n\nAvailable delegated agents:\n' +
+                    children.map(([name, child]) => `- subagent:${name}: ${child.description}`).join('\n') +
+                    '\nCopy the launcher path and its quoting exactly from the command below. Do not shorten or replace the path. ' +
+                    'Replace only the angle-bracket arguments. Use --prompt-file instead of --prompt when needed.\n' +
+                    `\n\`\`\`sh\n${launcher} run subagent:<name> --cwd <existing-directory> --prompt <task>\n\`\`\`\n` +
+                    'For follow-ups, queue, steer, interrupt, wait, and cancellation, read the help:\n' +
+                    `\n\`\`\`sh\n${launcher} --help\n\`\`\`\n` +
+                    'Include needed task context; child sessions do not inherit your conversation.' : definition.instructions;
+                return selectNative({ ...definition, instructions }, input.cwd, process.env, await loadAccess(input.cwd));
+            });
+        }
+        else if (message.method === 'turn')
+            result = await native.turn(message.prompt);
+        else if (message.method === 'steer')
+            result = await native.steer(message.prompt);
+        else if (message.method === 'interrupt')
+            result = await native.interrupt();
+        else if (message.method === 'resume')
+            result = await native.resume();
+        else if (message.method === 'close') {
+            await close();
+            reply({ id: message.id, result: null });
+            if (process.connected)
+                process.disconnect();
+            return;
+        }
+        else
+            throw new Error('Unknown worker operation');
+        reply({ id: message.id, result: result ?? null });
+    }
+    catch (error) {
+        reply({ id: message.id, error: errorInfo(error) });
+    }
+});
+process.on('disconnect', () => { void close().catch(() => { }).finally(() => process.exit()); });
+//# sourceMappingURL=worker.js.map

package/dist/runtime/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/runtime/worker.ts"],"names":[],"mappings":"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","sourcesContent":["import { loadExecutionDefinition } from './definition.js';\nimport { loadAccess } from '../config/access.js';\nimport { errorInfo } from '../errors.js';\nimport { selectNative } from './select-native.js';\nimport { NativeOwner } from './native-owner.js';\nimport type { DriverInput } from './types.js';\nimport type { NativeSession } from '../adapters/types.js';\nimport { dirname } from 'node:path';\nimport { rm } from 'node:fs/promises';\nimport { shellQuote } from '../shell.js';\n\nlet native: NativeSession | undefined;\nconst owner = new NativeOwner();\nconst launcherDirectory = dirname(process.env.AGENT_CLI_PATH!);\nlet closing: Promise<void> | undefined;\nconst close = () => closing ??= (async () => {\n  try { await owner.close(); }\n  finally { await rm(launcherDirectory,{recursive:true,force:true}); }\n})();\nconst reply = (message: unknown) => { if (process.connected) process.send?.(message as object, () => {}); };\nprocess.on('message', async (message: {id:number;method:string;input?:DriverInput;prompt?:string}) => {\n  try {\n    let result: unknown;\n    if (message.method === 'open') {\n      native = await owner.open(async () => {\n      const input = message.input!;\n      const definition = await loadExecutionDefinition(input.reference);\n      const children = Object.entries(definition.subagents ?? {});\n      const launcher = children.length ? shellQuote(process.env.AGENT_CLI_PATH!) : '';\n      const instructions = children.length ? definition.instructions + '\\n\\nAvailable delegated agents:\\n' +\n        children.map(([name, child]) => `- subagent:${name}: ${child.description}`).join('\\n') +\n        '\\nCopy the launcher path and its quoting exactly from the command below. Do not shorten or replace the path. ' +\n        'Replace only the angle-bracket arguments. Use --prompt-file instead of --prompt when needed.\\n' +\n        `\\n\\`\\`\\`sh\\n${launcher} run subagent:<name> --cwd <existing-directory> --prompt <task>\\n\\`\\`\\`\\n` +\n        'For follow-ups, queue, steer, interrupt, wait, and cancellation, read the help:\\n' +\n        `\\n\\`\\`\\`sh\\n${launcher} --help\\n\\`\\`\\`\\n` +\n        'Include needed task context; child sessions do not inherit your conversation.' : definition.instructions;\n      return selectNative({...definition,instructions}, input.cwd, process.env, await loadAccess(input.cwd));\n      });\n    } else if (message.method === 'turn') result = await native!.turn(message.prompt!);\n    else if (message.method === 'steer') result = await native!.steer(message.prompt!);\n    else if (message.method === 'interrupt') result = await native!.interrupt();\n    else if (message.method === 'resume') result = await native!.resume();\n    else if (message.method === 'close') { await close(); reply({id:message.id,result:null}); if (process.connected) process.disconnect(); return; }\n    else throw new Error('Unknown worker operation');\n    reply({id:message.id,result:result ?? null});\n  } catch (error) { reply({id:message.id,error:errorInfo(error)}); }\n});\nprocess.on('disconnect', () => { void close().catch(() => {}).finally(() => process.exit()); });\n"]}

package/dist/sdk/definitions.d.ts

@@ -0,0 +1,6 @@
+import type { AgentDefinition, ClaudeCodeConfig, ClaudeCodeOptions, CodexConfig, CodexOptions, FxConfig, FxOptions } from "./types.js";
+export declare function codex(options: CodexOptions): CodexConfig;
+export declare function claudeCode(options: ClaudeCodeOptions): ClaudeCodeConfig;
+export declare function fx(options: FxOptions): FxConfig;
+export declare function agent(definition: AgentDefinition): AgentDefinition;
+export declare function validateAgent(value: unknown, ancestors?: Set<unknown>): asserts value is AgentDefinition;

package/dist/sdk/definitions.js

@@ -0,0 +1,72 @@
+import { invalid, nonempty, object, validName } from "./validation.js";
+import { validateTool } from "./tools.js";
+function validateHarness(value, configured = false) {
+    object(value, configured ? ["kind", "model", "effort", "fast"] : ["model", "effort", "fast"]);
+    nonempty(value.model, "Model");
+    if (value.effort !== undefined)
+        nonempty(value.effort, "Effort");
+    if (value.fast !== undefined && typeof value.fast !== "boolean")
+        invalid("fast must be a boolean.");
+    if (configured && value.kind !== "codex" && value.kind !== "claudeCode" && value.kind !== "fx")
+        invalid("Unsupported harness kind.");
+    if (configured && value.kind === "fx" && "fast" in value)
+        invalid("Unknown configuration field.");
+    if (configured && value.kind === "claudeCode")
+        validateClaudeEffort(value.effort);
+}
+function validateClaudeEffort(effort) {
+    if (effort !== undefined && !["low", "medium", "high", "xhigh", "max"].includes(effort)) {
+        invalid("Claude effort must be low, medium, high, xhigh, or max.");
+    }
+}
+export function codex(options) {
+    validateHarness(options);
+    return Object.freeze({ ...options, kind: "codex", fast: options.fast ?? false });
+}
+export function claudeCode(options) {
+    validateHarness(options);
+    validateClaudeEffort(options.effort);
+    return Object.freeze({ ...options, kind: "claudeCode", fast: options.fast ?? false });
+}
+export function fx(options) {
+    object(options, ["model", "effort"]);
+    nonempty(options.model, "Model");
+    if (options.effort !== undefined)
+        nonempty(options.effort, "Effort");
+    return Object.freeze({ ...options, kind: "fx" });
+}
+export function agent(definition) {
+    validateAgent(definition);
+    return Object.freeze({
+        ...definition,
+        ...(Array.isArray(definition.harness) ? { harness: Object.freeze([...definition.harness]) } : {}),
+        ...(definition.tools ? { tools: Object.freeze({ ...definition.tools }) } : {}),
+        ...(definition.subagents ? { subagents: Object.freeze({ ...definition.subagents }) } : {}),
+    });
+}
+export function validateAgent(value, ancestors = new Set()) {
+    object(value, ["name", "description", "instructions", "harness", "tools", "subagents"]);
+    if (ancestors.has(value))
+        invalid("Subagent definitions cannot contain recursive references.");
+    validName(value.name);
+    nonempty(value.description, "Description");
+    nonempty(value.instructions, "Instructions");
+    const harnesses = Array.isArray(value.harness) ? value.harness : [value.harness];
+    if (!harnesses.length)
+        invalid("At least one harness is required.");
+    harnesses.forEach((harness) => validateHarness(harness, true));
+    if (value.tools !== undefined) {
+        object(value.tools);
+        Object.keys(value.tools).forEach(validName);
+        Object.values(value.tools).forEach(validateTool);
+    }
+    if (value.subagents !== undefined) {
+        object(value.subagents);
+        const next = new Set(ancestors).add(value);
+        for (const [name, child] of Object.entries(value.subagents)) {
+            validName(name);
+            validateAgent(child, next);
+        }
+    }
+}
+//# sourceMappingURL=definitions.js.map

package/dist/sdk/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/sdk/definitions.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AgentDefinition,\n  ClaudeCodeConfig,\n  ClaudeCodeOptions,\n  CodexConfig,\n  CodexOptions,\n  FxConfig,\n  FxOptions,\n  HarnessConfig,\n} from \"./types.js\";\nimport { invalid, nonempty, object, validName } from \"./validation.js\";\nimport { validateTool } from \"./tools.js\";\n\nfunction validateHarness(value: unknown, configured = false): void {\n  object(value, configured ? [\"kind\", \"model\", \"effort\", \"fast\"] : [\"model\", \"effort\", \"fast\"]);\n  nonempty(value.model, \"Model\");\n  if (value.effort !== undefined) nonempty(value.effort, \"Effort\");\n  if (value.fast !== undefined && typeof value.fast !== \"boolean\") invalid(\"fast must be a boolean.\");\n  if (configured && value.kind !== \"codex\" && value.kind !== \"claudeCode\" && value.kind !== \"fx\") invalid(\"Unsupported harness kind.\");\n  if (configured && value.kind === \"fx\" && \"fast\" in value) invalid(\"Unknown configuration field.\");\n  if (configured && value.kind === \"claudeCode\") validateClaudeEffort(value.effort);\n}\n\nfunction validateClaudeEffort(effort: unknown): void {\n  if (effort !== undefined && ![\"low\", \"medium\", \"high\", \"xhigh\", \"max\"].includes(effort as string)) {\n    invalid(\"Claude effort must be low, medium, high, xhigh, or max.\");\n  }\n}\n\nexport function codex(options: CodexOptions): CodexConfig {\n  validateHarness(options);\n  return Object.freeze({ ...options, kind: \"codex\", fast: options.fast ?? false });\n}\n\nexport function claudeCode(options: ClaudeCodeOptions): ClaudeCodeConfig {\n  validateHarness(options);\n  validateClaudeEffort(options.effort);\n  return Object.freeze({ ...options, kind: \"claudeCode\", fast: options.fast ?? false });\n}\n\nexport function fx(options: FxOptions): FxConfig {\n  object(options, [\"model\", \"effort\"]);\n  nonempty(options.model, \"Model\");\n  if (options.effort !== undefined) nonempty(options.effort, \"Effort\");\n  return Object.freeze({ ...options, kind: \"fx\" });\n}\n\nexport function agent(definition: AgentDefinition): AgentDefinition {\n  validateAgent(definition);\n  return Object.freeze({\n    ...definition,\n    ...(Array.isArray(definition.harness) ? { harness: Object.freeze([...definition.harness]) } : {}),\n    ...(definition.tools ? { tools: Object.freeze({ ...definition.tools }) } : {}),\n    ...(definition.subagents ? { subagents: Object.freeze({ ...definition.subagents }) } : {}),\n  });\n}\n\nexport function validateAgent(value: unknown, ancestors = new Set<unknown>()): asserts value is AgentDefinition {\n  object(value, [\"name\", \"description\", \"instructions\", \"harness\", \"tools\", \"subagents\"]);\n  if (ancestors.has(value)) invalid(\"Subagent definitions cannot contain recursive references.\");\n  validName(value.name);\n  nonempty(value.description, \"Description\");\n  nonempty(value.instructions, \"Instructions\");\n  const harnesses = Array.isArray(value.harness) ? value.harness : [value.harness];\n  if (!harnesses.length) invalid(\"At least one harness is required.\");\n  harnesses.forEach((harness) => validateHarness(harness, true));\n  if (value.tools !== undefined) {\n    object(value.tools);\n    Object.keys(value.tools).forEach(validName);\n    Object.values(value.tools).forEach(validateTool);\n  }\n  if (value.subagents !== undefined) {\n    object(value.subagents);\n    const next = new Set(ancestors).add(value);\n    for (const [name, child] of Object.entries(value.subagents)) {\n      validName(name);\n      validateAgent(child, next);\n    }\n  }\n}\n"]}

package/dist/sdk/tool-result.d.ts

@@ -0,0 +1,23 @@
+export type ToolContent = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+};
+declare const toolResultBrand: unique symbol;
+export interface ToolResult {
+    readonly [toolResultBrand]: true;
+}
+export type ExecutedToolResult = string | {
+    readonly kind: "content";
+    readonly content: readonly ToolContent[];
+};
+export declare function toolResult(result: {
+    readonly content: readonly ToolContent[];
+}): ToolResult;
+export declare function richToolResult(value: unknown): {
+    readonly content: readonly ToolContent[];
+} | undefined;
+export {};

package/dist/sdk/tool-result.js

@@ -0,0 +1,95 @@
+import { AgentError } from "../errors.js";
+const registryKey = Symbol.for("subharness.tool-results.v1");
+const results = sharedRegistry();
+export function toolResult(result) {
+    const token = Object.freeze({});
+    results.set(token, result);
+    return token;
+}
+export function richToolResult(value) {
+    if ((typeof value !== "object" || value === null) || !results.has(value))
+        return undefined;
+    return validateRichResult(results.get(value));
+}
+function sharedRegistry() {
+    const host = globalThis;
+    const existing = host[registryKey];
+    if (existing instanceof WeakMap)
+        return existing;
+    const registry = new WeakMap();
+    Object.defineProperty(host, registryKey, { value: registry, enumerable: false, configurable: false, writable: false });
+    return registry;
+}
+function validateRichResult(value) {
+    if (!plainObject(value) || !hasOnlyKeys(value, ["content"]) || !Array.isArray(value.content) || value.content.length === 0) {
+        throw invalidResult();
+    }
+    let images = 0;
+    let textBytes = 0;
+    const content = [];
+    for (const block of value.content) {
+        if (!plainObject(block) || typeof block.type !== "string")
+            throw invalidResult();
+        if (block.type === "text") {
+            if (!hasOnlyKeys(block, ["type", "text"]) || typeof block.text !== "string")
+                throw invalidResult();
+            textBytes += Buffer.byteLength(block.text, "utf8");
+            content.push(Object.freeze({ type: "text", text: block.text }));
+            continue;
+        }
+        if (block.type !== "image" || !hasOnlyKeys(block, ["type", "data", "mimeType"])
+            || typeof block.data !== "string" || !isMimeType(block.mimeType))
+            throw invalidResult();
+        images++;
+        if (images > 8)
+            throw tooLargeResult();
+        if (Buffer.byteLength(block.data, "utf8") > 5 * 1024 * 1024)
+            throw tooLargeResult();
+        const bytes = decodeCanonicalBase64(block.data);
+        if (!matchesMimeType(bytes, block.mimeType))
+            throw invalidResult();
+        content.push(Object.freeze({ type: "image", data: block.data, mimeType: block.mimeType }));
+    }
+    if (textBytes > 1024 * 1024)
+        throw tooLargeResult();
+    if (Buffer.byteLength(JSON.stringify(content), "utf8") > 8 * 1024 * 1024)
+        throw tooLargeResult();
+    return Object.freeze({ content: Object.freeze(content) });
+}
+function plainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasOnlyKeys(value, expected) {
+    const keys = Object.keys(value);
+    return keys.length === expected.length && expected.every(key => Object.hasOwn(value, key));
+}
+function isMimeType(value) {
+    return value === "image/png" || value === "image/jpeg" || value === "image/webp" || value === "image/gif";
+}
+function decodeCanonicalBase64(data) {
+    if (data.length === 0 || data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*(?:={1,2})?$/u.test(data))
+        throw invalidResult();
+    const decoded = Buffer.from(data, "base64");
+    if (decoded.toString("base64") !== data)
+        throw invalidResult();
+    return decoded;
+}
+function matchesMimeType(data, mimeType) {
+    if (mimeType === "image/png")
+        return data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+    if (mimeType === "image/jpeg")
+        return data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;
+    if (mimeType === "image/gif")
+        return data.subarray(0, 6).toString("ascii") === "GIF87a" || data.subarray(0, 6).toString("ascii") === "GIF89a";
+    return data.subarray(0, 4).toString("ascii") === "RIFF" && data.subarray(8, 12).toString("ascii") === "WEBP";
+}
+function invalidResult() {
+    return new AgentError("TOOL_RESULT_INVALID", "Tool returned invalid rich content.");
+}
+function tooLargeResult() {
+    return new AgentError("TOOL_RESULT_TOO_LARGE", "Tool result exceeds the documented size limits.");
+}
+//# sourceMappingURL=tool-result.js.map

package/dist/sdk/tool-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.js","sourceRoot":"","sources":["../../src/sdk/tool-result.ts"],"names":[],"mappings":"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","sourcesContent":["import { AgentError } from \"../errors.js\";\n\nexport type ToolContent =\n  | { readonly type: \"text\"; readonly text: string }\n  | {\n      readonly type: \"image\";\n      readonly data: string;\n      readonly mimeType: \"image/png\" | \"image/jpeg\" | \"image/webp\" | \"image/gif\";\n    };\n\ndeclare const toolResultBrand: unique symbol;\n\nexport interface ToolResult {\n  readonly [toolResultBrand]: true;\n}\n\nexport type ExecutedToolResult =\n  | string\n  | { readonly kind: \"content\"; readonly content: readonly ToolContent[] };\n\nconst registryKey = Symbol.for(\"subharness.tool-results.v1\");\nconst results = sharedRegistry();\n\nexport function toolResult(result: { readonly content: readonly ToolContent[] }): ToolResult {\n  const token = Object.freeze({});\n  results.set(token, result);\n  return token as ToolResult;\n}\n\nexport function richToolResult(value: unknown): { readonly content: readonly ToolContent[] } | undefined {\n  if ((typeof value !== \"object\" || value === null) || !results.has(value)) return undefined;\n  return validateRichResult(results.get(value));\n}\n\nfunction sharedRegistry(): WeakMap<object, unknown> {\n  const host = globalThis as unknown as Record<PropertyKey, unknown>;\n  const existing = host[registryKey];\n  if (existing instanceof WeakMap) return existing;\n  const registry = new WeakMap<object, unknown>();\n  Object.defineProperty(host, registryKey, { value: registry, enumerable: false, configurable: false, writable: false });\n  return registry;\n}\n\nfunction validateRichResult(value: unknown): { readonly content: readonly ToolContent[] } {\n  if (!plainObject(value) || !hasOnlyKeys(value, [\"content\"]) || !Array.isArray(value.content) || value.content.length === 0) {\n    throw invalidResult();\n  }\n\n  let images = 0;\n  let textBytes = 0;\n  const content: ToolContent[] = [];\n  for (const block of value.content) {\n    if (!plainObject(block) || typeof block.type !== \"string\") throw invalidResult();\n    if (block.type === \"text\") {\n      if (!hasOnlyKeys(block, [\"type\", \"text\"]) || typeof block.text !== \"string\") throw invalidResult();\n      textBytes += Buffer.byteLength(block.text, \"utf8\");\n      content.push(Object.freeze({ type: \"text\", text: block.text }));\n      continue;\n    }\n    if (block.type !== \"image\" || !hasOnlyKeys(block, [\"type\", \"data\", \"mimeType\"])\n      || typeof block.data !== \"string\" || !isMimeType(block.mimeType)) throw invalidResult();\n    images++;\n    if (images > 8) throw tooLargeResult();\n    if (Buffer.byteLength(block.data, \"utf8\") > 5 * 1024 * 1024) throw tooLargeResult();\n    const bytes = decodeCanonicalBase64(block.data);\n    if (!matchesMimeType(bytes, block.mimeType)) throw invalidResult();\n    content.push(Object.freeze({ type: \"image\", data: block.data, mimeType: block.mimeType }));\n  }\n\n  if (textBytes > 1024 * 1024) throw tooLargeResult();\n  if (Buffer.byteLength(JSON.stringify(content), \"utf8\") > 8 * 1024 * 1024) throw tooLargeResult();\n  return Object.freeze({ content: Object.freeze(content) });\n}\n\nfunction plainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  const prototype = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\nfunction hasOnlyKeys(value: Record<string, unknown>, expected: readonly string[]): boolean {\n  const keys = Object.keys(value);\n  return keys.length === expected.length && expected.every(key => Object.hasOwn(value, key));\n}\n\nfunction isMimeType(value: unknown): value is Extract<ToolContent, { type: \"image\" }>[\"mimeType\"] {\n  return value === \"image/png\" || value === \"image/jpeg\" || value === \"image/webp\" || value === \"image/gif\";\n}\n\nfunction decodeCanonicalBase64(data: string): Buffer {\n  if (data.length === 0 || data.length % 4 !== 0 || !/^[A-Za-z0-9+/]*(?:={1,2})?$/u.test(data)) throw invalidResult();\n  const decoded = Buffer.from(data, \"base64\");\n  if (decoded.toString(\"base64\") !== data) throw invalidResult();\n  return decoded;\n}\n\nfunction matchesMimeType(data: Buffer, mimeType: Extract<ToolContent, { type: \"image\" }>[\"mimeType\"]): boolean {\n  if (mimeType === \"image/png\") return data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));\n  if (mimeType === \"image/jpeg\") return data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;\n  if (mimeType === \"image/gif\") return data.subarray(0, 6).toString(\"ascii\") === \"GIF87a\" || data.subarray(0, 6).toString(\"ascii\") === \"GIF89a\";\n  return data.subarray(0, 4).toString(\"ascii\") === \"RIFF\" && data.subarray(8, 12).toString(\"ascii\") === \"WEBP\";\n}\n\nfunction invalidResult(): AgentError {\n  return new AgentError(\"TOOL_RESULT_INVALID\", \"Tool returned invalid rich content.\");\n}\n\nfunction tooLargeResult(): AgentError {\n  return new AgentError(\"TOOL_RESULT_TOO_LARGE\", \"Tool result exceeds the documented size limits.\");\n}\n"]}

package/dist/sdk/tools.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+import { type ExecutedToolResult } from "./tool-result.js";
+export { toolResult } from "./tool-result.js";
+export type { ToolContent, ToolResult } from "./tool-result.js";
+export declare function tool<S extends z.ZodObject>(definition: ToolDefinition<S>): ToolDefinition<S>;
+export declare function validateTool(definition: unknown): asserts definition is ToolDefinition<any>;
+export declare function toolJsonSchema(definition: ToolDefinition<any>): Record<string, unknown>;
+export declare function executeTool(definition: ToolDefinition<any>, input: unknown): Promise<ExecutedToolResult>;

package/dist/sdk/tools.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { AgentError } from "../errors.js";
+import { richToolResult } from "./tool-result.js";
+import { invalid, nonempty, object } from "./validation.js";
+export { toolResult } from "./tool-result.js";
+export function tool(definition) {
+    validateTool(definition);
+    return Object.freeze({ ...definition });
+}
+export function validateTool(definition) {
+    object(definition, ["description", "inputSchema", "execute"]);
+    nonempty(definition.description, "Tool description");
+    if (!(definition.inputSchema instanceof z.ZodObject))
+        invalid("Tools require a Zod 4 object schema.");
+    if (typeof definition.execute !== "function")
+        invalid("Tool execute must be a function.");
+    toolJsonSchema(definition);
+}
+export function toolJsonSchema(definition) {
+    try {
+        return z.toJSONSchema(definition.inputSchema, { io: "input" });
+    }
+    catch {
+        return invalid("Tool input schema cannot be represented as JSON Schema.");
+    }
+}
+export async function executeTool(definition, input) {
+    let parsed;
+    try {
+        parsed = await definition.inputSchema.safeParseAsync(input);
+        if (!parsed.success)
+            throw new Error();
+    }
+    catch {
+        throw new AgentError("TOOL_INPUT_INVALID", "Tool arguments do not match the declared schema.");
+    }
+    let result;
+    try {
+        result = await definition.execute(parsed.data);
+    }
+    catch {
+        throw new AgentError("TOOL_EXECUTION_FAILED", "The custom tool failed during execution.");
+    }
+    let rich;
+    try {
+        rich = richToolResult(result);
+    }
+    catch (error) {
+        if (error instanceof AgentError)
+            throw error;
+        throw new AgentError("TOOL_RESULT_INVALID", "Tool returned invalid rich content.");
+    }
+    if (rich)
+        return { kind: "content", content: rich.content };
+    let text;
+    try {
+        text = typeof result === "string" ? result : JSON.stringify(result, (_key, value) => {
+            if (["undefined", "function", "symbol", "bigint"].includes(typeof value)
+                || (typeof value === "number" && !Number.isFinite(value)))
+                throw new Error();
+            return value;
+        });
+    }
+    catch {
+        throw new AgentError("TOOL_RESULT_INVALID", "Tool result must be a string or JSON-serializable value.");
+    }
+    if (text === undefined)
+        throw new AgentError("TOOL_RESULT_INVALID", "Tool result must be a string or JSON-serializable value.");
+    if (Buffer.byteLength(text, "utf8") > 1024 * 1024)
+        throw new AgentError("TOOL_RESULT_TOO_LARGE", "Tool result exceeds 1 MiB.");
+    return text;
+}
+//# sourceMappingURL=tools.js.map

package/dist/sdk/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/sdk/tools.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport { AgentError } from \"../errors.js\";\nimport type { ToolDefinition } from \"./types.js\";\nimport { richToolResult, type ExecutedToolResult } from \"./tool-result.js\";\nimport { invalid, nonempty, object } from \"./validation.js\";\n\nexport { toolResult } from \"./tool-result.js\";\nexport type { ToolContent, ToolResult } from \"./tool-result.js\";\n\nexport function tool<S extends z.ZodObject>(definition: ToolDefinition<S>): ToolDefinition<S> {\n  validateTool(definition);\n  return Object.freeze({ ...definition });\n}\n\nexport function validateTool(definition: unknown): asserts definition is ToolDefinition<any> {\n  object(definition, [\"description\", \"inputSchema\", \"execute\"]);\n  nonempty(definition.description, \"Tool description\");\n  if (!(definition.inputSchema instanceof z.ZodObject)) invalid(\"Tools require a Zod 4 object schema.\");\n  if (typeof definition.execute !== \"function\") invalid(\"Tool execute must be a function.\");\n  toolJsonSchema(definition as unknown as ToolDefinition);\n}\n\nexport function toolJsonSchema(definition: ToolDefinition<any>): Record<string, unknown> {\n  try {\n    return z.toJSONSchema(definition.inputSchema, { io: \"input\" });\n  } catch {\n    return invalid(\"Tool input schema cannot be represented as JSON Schema.\");\n  }\n}\n\nexport async function executeTool(definition: ToolDefinition<any>, input: unknown): Promise<ExecutedToolResult> {\n  let parsed;\n  try {\n    parsed = await definition.inputSchema.safeParseAsync(input);\n    if (!parsed.success) throw new Error();\n  } catch {\n    throw new AgentError(\"TOOL_INPUT_INVALID\", \"Tool arguments do not match the declared schema.\");\n  }\n  let result: unknown;\n  try {\n    result = await definition.execute(parsed.data);\n  } catch {\n    throw new AgentError(\"TOOL_EXECUTION_FAILED\", \"The custom tool failed during execution.\");\n  }\n  let rich;\n  try {\n    rich = richToolResult(result);\n  } catch (error) {\n    if (error instanceof AgentError) throw error;\n    throw new AgentError(\"TOOL_RESULT_INVALID\", \"Tool returned invalid rich content.\");\n  }\n  if (rich) return { kind: \"content\", content: rich.content };\n  let text: string | undefined;\n  try {\n    text = typeof result === \"string\" ? result : JSON.stringify(result, (_key, value: unknown) => {\n      if ([\"undefined\", \"function\", \"symbol\", \"bigint\"].includes(typeof value)\n        || (typeof value === \"number\" && !Number.isFinite(value))) throw new Error();\n      return value;\n    });\n  } catch {\n    throw new AgentError(\"TOOL_RESULT_INVALID\", \"Tool result must be a string or JSON-serializable value.\");\n  }\n  if (text === undefined) throw new AgentError(\"TOOL_RESULT_INVALID\", \"Tool result must be a string or JSON-serializable value.\");\n  if (Buffer.byteLength(text, \"utf8\") > 1024 * 1024) throw new AgentError(\"TOOL_RESULT_TOO_LARGE\", \"Tool result exceeds 1 MiB.\");\n  return text;\n}\n"]}

package/dist/sdk/types.d.ts

@@ -0,0 +1,49 @@
+import type { z } from "zod";
+export type HarnessKind = "codex" | "claudeCode" | "fx";
+export interface CodexConfig {
+    readonly kind: "codex";
+    readonly model: string;
+    readonly effort?: string;
+    readonly fast: boolean;
+}
+export interface ClaudeCodeConfig {
+    readonly kind: "claudeCode";
+    readonly model: string;
+    readonly effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    readonly fast: boolean;
+}
+export interface FxConfig {
+    readonly kind: "fx";
+    readonly model: string;
+    readonly effort?: string;
+}
+export type HarnessConfig = CodexConfig | ClaudeCodeConfig | (FxConfig & {
+    readonly fast?: never;
+});
+export interface CodexOptions {
+    readonly model: string;
+    readonly effort?: string;
+    readonly fast?: boolean;
+}
+export interface ClaudeCodeOptions {
+    readonly model: string;
+    readonly effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    readonly fast?: boolean;
+}
+export interface FxOptions {
+    readonly model: string;
+    readonly effort?: string;
+}
+export interface ToolDefinition<S extends z.ZodObject = z.ZodObject> {
+    readonly description: string;
+    readonly inputSchema: S;
+    readonly execute: (input: z.output<S>) => unknown | Promise<unknown>;
+}
+export interface AgentDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly instructions: string;
+    readonly harness: HarnessConfig | readonly HarnessConfig[];
+    readonly tools?: Readonly<Record<string, ToolDefinition<any>>>;
+    readonly subagents?: Readonly<Record<string, AgentDefinition>>;
+}

package/dist/sdk/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sdk/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sdk/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { z } from \"zod\";\n\nexport type HarnessKind = \"codex\" | \"claudeCode\" | \"fx\";\n\nexport interface CodexConfig {\n  readonly kind: \"codex\";\n  readonly model: string;\n  readonly effort?: string;\n  readonly fast: boolean;\n}\n\nexport interface ClaudeCodeConfig {\n  readonly kind: \"claudeCode\";\n  readonly model: string;\n  readonly effort?: \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n  readonly fast: boolean;\n}\n\nexport interface FxConfig {\n  readonly kind: \"fx\";\n  readonly model: string;\n  readonly effort?: string;\n}\n\nexport type HarnessConfig = CodexConfig | ClaudeCodeConfig | (FxConfig & { readonly fast?: never });\n\nexport interface CodexOptions {\n  readonly model: string;\n  readonly effort?: string;\n  readonly fast?: boolean;\n}\n\nexport interface ClaudeCodeOptions {\n  readonly model: string;\n  readonly effort?: \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n  readonly fast?: boolean;\n}\n\nexport interface FxOptions {\n  readonly model: string;\n  readonly effort?: string;\n}\n\nexport interface ToolDefinition<S extends z.ZodObject = z.ZodObject> {\n  readonly description: string;\n  readonly inputSchema: S;\n  readonly execute: (input: z.output<S>) => unknown | Promise<unknown>;\n}\n\nexport interface AgentDefinition {\n  readonly name: string;\n  readonly description: string;\n  readonly instructions: string;\n  readonly harness: HarnessConfig | readonly HarnessConfig[];\n  readonly tools?: Readonly<Record<string, ToolDefinition<any>>>;\n  readonly subagents?: Readonly<Record<string, AgentDefinition>>;\n}\n"]}

package/dist/sdk/validation.d.ts

@@ -0,0 +1,5 @@
+export declare const namePattern: RegExp;
+export declare function invalid(message: string): never;
+export declare function object(value: unknown, fields?: readonly string[]): asserts value is Record<string, unknown>;
+export declare function nonempty(value: unknown, label: string): asserts value is string;
+export declare function validName(value: unknown): asserts value is string;

package/dist/sdk/validation.js

@@ -0,0 +1,20 @@
+import { AgentError } from "../errors.js";
+export const namePattern = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+export function invalid(message) {
+    throw new AgentError("INVALID_DEFINITION", message);
+}
+export function object(value, fields) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid("Expected a configuration object.");
+    if (fields && Object.keys(value).some((key) => !fields.includes(key)))
+        invalid("Unknown configuration field.");
+}
+export function nonempty(value, label) {
+    if (typeof value !== "string" || !value.trim())
+        invalid(`${label} must be a nonempty string.`);
+}
+export function validName(value) {
+    if (typeof value !== "string" || !namePattern.test(value))
+        invalid("Names must start with a letter and contain at most 64 letters, digits, underscores, or hyphens.");
+}
+//# sourceMappingURL=validation.js.map