subharness 0.0.4 → 0.0.7

package/dist/sdk/runner.js

@@ -0,0 +1,107 @@
+import { AgentError } from '../errors.js';
+import { Coordinator } from '../runtime/coordinator.js';
+import { captureDefinition } from './execution-definition.js';
+import { executionDriver } from './execution-driver.js';
+import { delivery, observeOptions, runCwd, runnerConfiguration, validateCwd, validatePrompt, watchOptions } from './execution-options.js';
+export function createRunner(options) { return createApplicationRunner(options); }
+/** Internal test seam replacing only the external native adapter boundary. */
+export function createRunnerWithNativeOpener(options, open) {
+    return createApplicationRunner(options, open);
+}
+function createApplicationRunner(options, open) {
+    const configuration = runnerConfiguration(options);
+    let coordinator;
+    coordinator = new Coordinator(input => executionDriver(coordinator, configuration.access, open)(input));
+    return new ApplicationRunner(coordinator, configuration.env);
+}
+class ApplicationRunner {
+    coordinator;
+    env;
+    accepting = true;
+    constructor(coordinator, env) {
+        this.coordinator = coordinator;
+        this.env = env;
+    }
+    async createSession(definition, options) {
+        this.assertAccepting();
+        const captured = captureDefinition(definition);
+        const cwd = await validateCwd(runCwd(options));
+        this.assertAccepting();
+        const id = this.coordinator.createSession({ reference: { kind: 'inline', definition: captured }, cwd, env: { ...this.env } });
+        return this.session(id);
+    }
+    session(id) {
+        this.coordinator.sessionSnapshot(id);
+        return new ApplicationSession(this, this.coordinator, id);
+    }
+    task(id) {
+        const snapshot = this.coordinator.snapshot(id);
+        return new ApplicationTask(this.coordinator, snapshot.taskId, snapshot.sessionId);
+    }
+    async respond(requestId, response) {
+        this.assertAccepting();
+        this.coordinator.respondSdk(requestId, response);
+    }
+    async close() { this.accepting = false; await this.coordinator.close(); }
+    assertAccepting() { if (!this.accepting)
+        throw new AgentError('RUNNER_CLOSED', 'The application runner is closing or closed.'); }
+}
+class ApplicationSession {
+    runner;
+    coordinator;
+    id;
+    constructor(runner, coordinator, id) {
+        this.runner = runner;
+        this.coordinator = coordinator;
+        this.id = id;
+    }
+    async prompt(text, options) {
+        this.runner.assertAccepting();
+        validatePrompt(text);
+        const requestedDelivery = delivery(options);
+        let receipt;
+        try {
+            receipt = await this.coordinator.send(this.id, text, requestedDelivery);
+        }
+        catch (error) {
+            if (error instanceof AgentError && error.code === 'COORDINATOR_UNAVAILABLE')
+                throw new AgentError('RUNNER_CLOSED', 'The application runner is closing or closed.');
+            throw error;
+        }
+        return { task: new ApplicationTask(this.coordinator, receipt.taskId, receipt.sessionId), requestedDelivery,
+            effectiveDelivery: receipt.delivery ?? requestedDelivery,
+            ...(receipt.paused ? { paused: true, blockedByTaskId: receipt.blockedByTaskId } : {}) };
+    }
+    snapshot() { return this.coordinator.sdkSessionSnapshot(this.id); }
+    async close() { await this.coordinator.closeSession(this.id); }
+}
+class ApplicationTask {
+    coordinator;
+    id;
+    sessionId;
+    resultPromise;
+    constructor(coordinator, id, sessionId) {
+        this.coordinator = coordinator;
+        this.id = id;
+        this.sessionId = sessionId;
+    }
+    get result() {
+        if (!this.resultPromise) {
+            this.resultPromise = this.coordinator.taskResult(this.id);
+            void this.resultPromise.catch(() => undefined);
+        }
+        return this.resultPromise;
+    }
+    async snapshot() { return this.coordinator.sdkTaskSnapshot(this.id); }
+    async inspect() { return this.coordinator.taskDetails(this.id); }
+    watch(options) {
+        const selected = watchOptions(options);
+        return this.coordinator.watchTask(this.id, selected.signal);
+    }
+    responses(options) {
+        const selected = observeOptions(options);
+        return this.coordinator.taskResponses(this.id, selected.after, selected.signal);
+    }
+    async cancel() { await this.coordinator.cancel(this.id); return this.snapshot(); }
+}
+//# sourceMappingURL=runner.js.map

package/dist/sdk/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/sdk/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAqB,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,mBAAmB,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI1I,MAAM,UAAU,YAAY,CAAC,OAAsB,IAAW,OAAO,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACxG,8EAA8E;AAC9E,MAAM,UAAU,4BAA4B,CAAC,OAA+B,EAAC,IAAiB;IAC5F,OAAO,uBAAuB,CAAC,OAAO,EAAC,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,uBAAuB,CAAC,OAAsB,EAAC,IAAkB;IACxE,MAAM,aAAa,GAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACjD,IAAI,WAAwB,CAAC;IAC7B,WAAW,GAAC,IAAI,WAAW,CAAC,KAAK,CAAA,EAAE,CAAA,eAAe,CAAC,WAAW,EAAC,aAAa,CAAC,MAAM,EAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAClG,OAAO,IAAI,iBAAiB,CAAC,WAAW,EAAC,aAAa,CAAC,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,iBAAiB;IAEQ,WAAW;IAA8B,GAAG;IADjE,SAAS,GAAC,IAAI,CAAC;IACvB,YAA6B,WAAuB,EAAkB,GAAqB;2BAA9D,WAAW;mBAA8B,GAAG;IAAqB,CAAC;IAE/F,KAAK,CAAC,aAAa,CAAC,UAA0B,EAAC,OAA6B;QAC1E,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAC7C,MAAM,GAAG,GAAC,MAAM,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,EAAE,GAAC,IAAI,CAAC,WAAW,CAAC,aAAa,CAAC,EAAC,SAAS,EAAC,EAAC,IAAI,EAAC,QAAQ,EAAC,UAAU,EAAC,QAAQ,EAAC,EAAC,GAAG,EAAC,GAAG,EAAC,EAAC,GAAG,IAAI,CAAC,GAAG,EAAC,EAAC,CAAC,CAAC;QAC/G,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,CAAC,EAAS;QACf,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;QACrC,OAAO,IAAI,kBAAkB,CAAC,IAAI,EAAC,IAAI,CAAC,WAAW,EAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,CAAC,EAAS;QACZ,MAAM,QAAQ,GAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC7C,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,WAAW,EAAC,QAAQ,CAAC,MAAM,EAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClF,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,SAAgB,EAAC,QAAyB;QACtD,IAAI,CAAC,eAAe,EAAE,CAAC;QAAC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,EAAC,QAAQ,CAAC,CAAC;IAC1E,CAAC;IACD,KAAK,CAAC,KAAK,KAAmB,IAAI,CAAC,SAAS,GAAC,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACrF,eAAe,KAAK,IAAI,CAAC,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,UAAU,CAAC,eAAe,EAAC,8CAA8C,CAAC,CAAC,CAAC,CAAC;CACjI;AAED,MAAM,kBAAkB;IACO,MAAM;IAAoC,WAAW;IAAsB,EAAE;IAA1G,YAA6B,MAAwB,EAAkB,WAAuB,EAAU,EAAS;sBAApF,MAAM;2BAAoC,WAAW;kBAAsB,EAAE;IAAU,CAAC;IACrH,KAAK,CAAC,MAAM,CAAC,IAAW,EAAC,OAAsC;QAC7D,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,iBAAiB,GAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YAAC,OAAO,GAAC,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAC,IAAI,EAAC,iBAAiB,CAAC,CAAC;QAAC,CAAC;QAC5E,OAAM,KAAK,EAAE,CAAC;YACZ,IAAI,KAAK,YAAY,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,yBAAyB;gBACzE,MAAM,IAAI,UAAU,CAAC,eAAe,EAAC,8CAA8C,CAAC,CAAC;YACvF,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,EAAC,IAAI,EAAC,IAAI,eAAe,CAAC,IAAI,CAAC,WAAW,EAAC,OAAO,CAAC,MAAM,EAAC,OAAO,CAAC,SAAS,CAAC,EAAC,iBAAiB;YACnG,iBAAiB,EAAC,OAAO,CAAC,QAAQ,IAAI,iBAAiB;YACvD,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAC,MAAM,EAAC,IAAa,EAAC,eAAe,EAAC,OAAO,CAAC,eAAgB,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAC,CAAC;IAChG,CAAC;IACD,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACnE,KAAK,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CAChE;AAED,MAAM,eAAe;IAEU,WAAW;IAAsB,EAAE;IAAiB,SAAS;IADlF,aAAa,CAAqD;IAC1E,YAA6B,WAAuB,EAAU,EAAS,EAAU,SAAgB;2BAApE,WAAW;kBAAsB,EAAE;yBAAiB,SAAS;IAAU,CAAC;IACrG,IAAI,MAAM;QACR,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,IAAI,CAAC,aAAa,GAAC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxD,KAAK,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,GAAE,EAAE,CAAA,SAAS,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IACD,KAAK,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACtE,KAAK,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjE,KAAK,CAAC,OAAuC;QAC3C,MAAM,QAAQ,GAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnG,CAAC;IACD,SAAS,CAAC,OAA8D;QACtE,MAAM,QAAQ,GAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,EAAC,QAAQ,CAAC,KAAK,EAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxH,CAAC;IACD,KAAK,CAAC,MAAM,KAA2B,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;CACzG","sourcesContent":["import { AgentError } from '../errors.js';\nimport { Coordinator } from '../runtime/coordinator.js';\nimport type { ApprovalResponse } from '../runtime/task-data.js';\nimport type { TaskSnapshot } from './execution-types.js';\nimport { captureDefinition } from './execution-definition.js';\nimport { executionDriver, type NativeOpener } from './execution-driver.js';\nimport { delivery, observeOptions, runCwd, runnerConfiguration, validateCwd, validatePrompt, watchOptions } from './execution-options.js';\nimport type { Delivery, PromptReceipt, Runner, RunnerOptions, SessionHandle, TaskHandle } from './execution-types.js';\nimport type { AgentDefinition } from './types.js';\n\nexport function createRunner(options?:RunnerOptions):Runner { return createApplicationRunner(options); }\n/** Internal test seam replacing only the external native adapter boundary. */\nexport function createRunnerWithNativeOpener(options:RunnerOptions|undefined,open:NativeOpener):Runner {\n  return createApplicationRunner(options,open);\n}\n\nfunction createApplicationRunner(options?:RunnerOptions,open?:NativeOpener):Runner {\n  const configuration=runnerConfiguration(options);\n  let coordinator!:Coordinator;\n  coordinator=new Coordinator(input=>executionDriver(coordinator,configuration.access,open)(input));\n  return new ApplicationRunner(coordinator,configuration.env);\n}\n\nclass ApplicationRunner implements Runner {\n  private accepting=true;\n  constructor(private readonly coordinator:Coordinator,private readonly env:NodeJS.ProcessEnv) {}\n\n  async createSession(definition:AgentDefinition,options:{readonly cwd:string}):Promise<SessionHandle> {\n    this.assertAccepting();\n    const captured=captureDefinition(definition);\n    const cwd=await validateCwd(runCwd(options));\n    this.assertAccepting();\n    const id=this.coordinator.createSession({reference:{kind:'inline',definition:captured},cwd,env:{...this.env}});\n    return this.session(id);\n  }\n  session(id:string):SessionHandle {\n    this.coordinator.sessionSnapshot(id);\n    return new ApplicationSession(this,this.coordinator,id);\n  }\n  task(id:string):TaskHandle {\n    const snapshot=this.coordinator.snapshot(id);\n    return new ApplicationTask(this.coordinator,snapshot.taskId,snapshot.sessionId);\n  }\n  async respond(requestId:string,response:ApprovalResponse):Promise<void> {\n    this.assertAccepting(); this.coordinator.respondSdk(requestId,response);\n  }\n  async close():Promise<void> { this.accepting=false; await this.coordinator.close(); }\n  assertAccepting() { if (!this.accepting) throw new AgentError('RUNNER_CLOSED','The application runner is closing or closed.'); }\n}\n\nclass ApplicationSession implements SessionHandle {\n  constructor(private readonly runner:ApplicationRunner,private readonly coordinator:Coordinator,readonly id:string) {}\n  async prompt(text:string,options?:{readonly delivery?:Delivery}):Promise<PromptReceipt> {\n    this.runner.assertAccepting(); validatePrompt(text);\n    const requestedDelivery=delivery(options);\n    let receipt;\n    try { receipt=await this.coordinator.send(this.id,text,requestedDelivery); }\n    catch(error) {\n      if (error instanceof AgentError && error.code === 'COORDINATOR_UNAVAILABLE')\n        throw new AgentError('RUNNER_CLOSED','The application runner is closing or closed.');\n      throw error;\n    }\n    return {task:new ApplicationTask(this.coordinator,receipt.taskId,receipt.sessionId),requestedDelivery,\n      effectiveDelivery:receipt.delivery ?? requestedDelivery,\n      ...(receipt.paused ? {paused:true as const,blockedByTaskId:receipt.blockedByTaskId!} : {})};\n  }\n  snapshot() { return this.coordinator.sdkSessionSnapshot(this.id); }\n  async close() { await this.coordinator.closeSession(this.id); }\n}\n\nclass ApplicationTask implements TaskHandle {\n  private resultPromise?:Promise<import('./execution-types.js').TaskResult>;\n  constructor(private readonly coordinator:Coordinator,readonly id:string,readonly sessionId:string) {}\n  get result() {\n    if (!this.resultPromise) {\n      this.resultPromise=this.coordinator.taskResult(this.id);\n      void this.resultPromise.catch(()=>undefined);\n    }\n    return this.resultPromise;\n  }\n  async snapshot() { return this.coordinator.sdkTaskSnapshot(this.id); }\n  async inspect() { return this.coordinator.taskDetails(this.id); }\n  watch(options?:{readonly signal?:AbortSignal}) {\n    const selected=watchOptions(options); return this.coordinator.watchTask(this.id,selected.signal);\n  }\n  responses(options?:{readonly after?:string;readonly signal?:AbortSignal}) {\n    const selected=observeOptions(options); return this.coordinator.taskResponses(this.id,selected.after,selected.signal);\n  }\n  async cancel():Promise<TaskSnapshot> { await this.coordinator.cancel(this.id); return this.snapshot(); }\n}\n"]}

package/dist/sdk/tools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { AgentError } from "../errors.js";
 import { richToolResult } from "./tool-result.js";
+import { isHostedError } from "./hosted-error.js";
 import { invalid, nonempty, object } from "./validation.js";
 export { toolResult } from "./tool-result.js";
 export function tool(definition) {
@@ -38,7 +39,9 @@ export async function executeTool(definition, input) {
     try {
         result = await definition.execute(parsed.data);
     }
-    catch {
+    catch (error) {
+        if (isHostedError(error))
+            throw error;
         throw new AgentError("TOOL_EXECUTION_FAILED", "The custom tool failed during execution.");
     }
     let rich;

package/dist/sdk/tools.js.map

@@ -1 +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"]}
+{"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 { isHostedError } from \"./hosted-error.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 (error) {\n    if (isHostedError(error)) throw error;\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

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-export type HarnessKind = "codex" | "claudeCode" | "fx";
+export type HarnessKind = "codex" | "claudeCode" | "fx" | "opencode" | "copilot" | "cursor";
 export interface CodexConfig {
     readonly kind: "codex";
     readonly model: string;
@@ -24,8 +24,36 @@ export interface FxConfig {
     readonly effort?: string;
     readonly permissionMode?: "ask" | "auto" | "full-access";
 }
+export interface OpencodeOptions {
+    readonly model: string;
+}
+export interface OpencodeConfig extends OpencodeOptions {
+    readonly kind: "opencode";
+}
+export interface CopilotOptions {
+    readonly model: string;
+}
+export interface CopilotConfig extends CopilotOptions {
+    readonly kind: "copilot";
+}
+export interface CursorOptions {
+    readonly model: string;
+    readonly sandboxMode?: "enabled" | "disabled";
+}
+export interface CursorConfig extends CursorOptions {
+    readonly kind: "cursor";
+}
 export type HarnessConfig = CodexConfig | ClaudeCodeConfig | (FxConfig & {
     readonly fast?: never;
+}) | (OpencodeConfig & {
+    readonly effort?: never;
+    readonly fast?: never;
+}) | (CopilotConfig & {
+    readonly effort?: never;
+    readonly fast?: never;
+}) | (CursorConfig & {
+    readonly effort?: never;
+    readonly fast?: never;
 });
 export interface CodexOptions {
     readonly model: string;

package/dist/sdk/types.js.map

@@ -1 +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  readonly approvalPolicy?: \"never\" | \"on-request\" | \"untrusted\";\n  readonly sandboxMode?: \"read-only\" | \"workspace-write\" | \"danger-full-access\";\n  readonly networkAccessEnabled?: 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  readonly permissionMode?: \"default\" | \"acceptEdits\" | \"bypassPermissions\" | \"plan\" | \"dontAsk\" | \"auto\";\n  readonly allowedTools?: readonly string[];\n  readonly disallowedTools?: readonly string[];\n}\n\nexport interface FxConfig {\n  readonly kind: \"fx\";\n  readonly model: string;\n  readonly effort?: string;\n  readonly permissionMode?: \"ask\" | \"auto\" | \"full-access\";\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  readonly approvalPolicy?: \"never\" | \"on-request\" | \"untrusted\";\n  readonly sandboxMode?: \"read-only\" | \"workspace-write\" | \"danger-full-access\";\n  readonly networkAccessEnabled?: boolean;\n}\n\nexport interface ClaudeCodeOptions {\n  readonly model: string;\n  readonly effort?: \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n  readonly fast?: boolean;\n  readonly permissionMode?: \"default\" | \"acceptEdits\" | \"bypassPermissions\" | \"plan\" | \"dontAsk\" | \"auto\";\n  readonly allowedTools?: readonly string[];\n  readonly disallowedTools?: readonly string[];\n}\n\nexport interface FxOptions {\n  readonly model: string;\n  readonly effort?: string;\n  readonly permissionMode?: \"ask\" | \"auto\" | \"full-access\";\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"]}
+{"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\" | \"opencode\" | \"copilot\" | \"cursor\";\n\nexport interface CodexConfig {\n  readonly kind: \"codex\";\n  readonly model: string;\n  readonly effort?: string;\n  readonly fast: boolean;\n  readonly approvalPolicy?: \"never\" | \"on-request\" | \"untrusted\";\n  readonly sandboxMode?: \"read-only\" | \"workspace-write\" | \"danger-full-access\";\n  readonly networkAccessEnabled?: 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  readonly permissionMode?: \"default\" | \"acceptEdits\" | \"bypassPermissions\" | \"plan\" | \"dontAsk\" | \"auto\";\n  readonly allowedTools?: readonly string[];\n  readonly disallowedTools?: readonly string[];\n}\n\nexport interface FxConfig {\n  readonly kind: \"fx\";\n  readonly model: string;\n  readonly effort?: string;\n  readonly permissionMode?: \"ask\" | \"auto\" | \"full-access\";\n}\n\nexport interface OpencodeOptions {\n  readonly model: string;\n}\n\nexport interface OpencodeConfig extends OpencodeOptions {\n  readonly kind: \"opencode\";\n}\n\nexport interface CopilotOptions {\n  readonly model: string;\n}\n\nexport interface CopilotConfig extends CopilotOptions {\n  readonly kind: \"copilot\";\n}\n\nexport interface CursorOptions {\n  readonly model: string;\n  readonly sandboxMode?: \"enabled\" | \"disabled\";\n}\n\nexport interface CursorConfig extends CursorOptions {\n  readonly kind: \"cursor\";\n}\n\nexport type HarnessConfig =\n  | CodexConfig\n  | ClaudeCodeConfig\n  | (FxConfig & { readonly fast?: never })\n  | (OpencodeConfig & { readonly effort?: never; readonly fast?: never })\n  | (CopilotConfig & { readonly effort?: never; readonly fast?: never })\n  | (CursorConfig & { readonly effort?: never; readonly fast?: never });\n\nexport interface CodexOptions {\n  readonly model: string;\n  readonly effort?: string;\n  readonly fast?: boolean;\n  readonly approvalPolicy?: \"never\" | \"on-request\" | \"untrusted\";\n  readonly sandboxMode?: \"read-only\" | \"workspace-write\" | \"danger-full-access\";\n  readonly networkAccessEnabled?: boolean;\n}\n\nexport interface ClaudeCodeOptions {\n  readonly model: string;\n  readonly effort?: \"low\" | \"medium\" | \"high\" | \"xhigh\" | \"max\";\n  readonly fast?: boolean;\n  readonly permissionMode?: \"default\" | \"acceptEdits\" | \"bypassPermissions\" | \"plan\" | \"dontAsk\" | \"auto\";\n  readonly allowedTools?: readonly string[];\n  readonly disallowedTools?: readonly string[];\n}\n\nexport interface FxOptions {\n  readonly model: string;\n  readonly effort?: string;\n  readonly permissionMode?: \"ask\" | \"auto\" | \"full-access\";\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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "subharness",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "type": "module",
   "engines": {
     "node": ">=22.18.0"
@@ -22,8 +22,11 @@
   ],
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.278",
+    "@cursor/sdk": "1.0.32",
+    "@github/copilot-sdk": "1.0.14",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "string-width": "8.2.1",
+    "strip-ansi": "7.2.0",
     "tsx": "4.23.15",
     "zod": "4.6.5"
   },
@@ -32,7 +35,7 @@
     "errore": "0.14.1",
     "typescript": "7.0.2"
   },
-  "description": "Run native coding agents and coordinate optional specialists through a local CLI.",
+  "description": "Run native coding agents from application code or a local CLI, with sessions and optional specialists.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -49,7 +52,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('dist/cli/main.js', 0o755)\"",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test test/*.test.ts",
+    "test": "node --import tsx --test --test-concurrency=2 test/*.test.ts",
     "test:evals": "node --import tsx --test test/eval-*.test.ts",
     "evals": "node --import tsx evals/main.ts",
     "check": "pnpm run build && pnpm run typecheck && pnpm test",

package/sdk/access-config.md

@@ -1,5 +1,7 @@
 # Personal Access Configuration
 
+Embedded [execution SDK](execution.md) runners accept explicit `RunnerOptions.access` and an environment snapshot. They use the connection rules here without implicitly loading personal settings or modifying Git excludes. Connected sessions use the same project-based personal settings discovery as the CLI, with the caller's captured environment.
+
 The optional `.subharness/agents.local.json` file selects access independently of versioned agent definitions. In linked Git worktrees it is read from the main checkout. Without Git, it is read from the execution project root. Global definitions still use the selected project's access preferences.
 
 ```json
@@ -26,19 +28,73 @@ This example explicitly enables subscription-to-Gateway fallback for Codex befor
 
 | `type` | Credential source | Default `env` |
 | --- | --- | --- |
-| `subscription` | The harness's current native subscription login | Not applicable |
-| `api-key` | Direct native provider API key | `OPENAI_API_KEY` for Codex, `ANTHROPIC_API_KEY` for Claude Code |
+| `subscription` | The harness's saved native login for the selected route | Not applicable |
+| `api-key` | Direct native provider API key | `OPENAI_API_KEY` for Codex, `ANTHROPIC_API_KEY` for Claude Code, `CURSOR_API_KEY` for Cursor |
 | `vercel-api-key` | AI Gateway API key | `AI_GATEWAY_API_KEY` |
 | `vercel-oidc` | Project OIDC token | `VERCEL_OIDC_TOKEN` |
 
-`subscription` accepts only `type`. Other connections optionally accept `env` and `envFile`. `vercel-oidc` also accepts `project`, defaulting to `.`. Unknown fields are errors. Variable names match `[A-Za-z_][A-Za-z0-9_]*`. Tokens and API keys must never appear directly in this file.
+The connection shapes are:
+
+```ts
+type AccessConnection =
+  | { type: "subscription"; provider?: string }
+  | {
+      type: "api-key";
+      provider?: string;
+      env?: string;
+      envFile?: string;
+      baseUrl?: string;
+      wireApi?: "completions" | "responses";
+      apiVersion?: string;
+      wireModel?: string;
+    }
+  | { type: "vercel-api-key"; env?: string; envFile?: string }
+  | { type: "vercel-oidc"; env?: string; envFile?: string; project?: string };
+```
+
+`provider` selects a native authentication or inference provider; it does not change the agent definition. Its meaning is harness-specific:
+
+| Harness | `subscription` | Direct `api-key` |
+| --- | --- | --- |
+| Codex | Native Codex login; no `provider` field | OpenAI; defaults to `OPENAI_API_KEY`; no provider options |
+| Claude Code | Native Claude Code login; no `provider` field | Anthropic; defaults to `ANTHROPIC_API_KEY`; no provider options |
+| Cursor | Native Cursor CLI login; no `provider` field | Cursor; defaults to `CURSOR_API_KEY`; no provider options |
+| OpenCode | Required `provider`: `openai`, `github-copilot`, or `xai` | Required `provider` and explicit `env`; supported providers are defined in [OpenCode](opencode.md) |
+| Copilot | Native Copilot or GitHub CLI login; no `provider` field | Required `provider`: `github`, `openai`, `anthropic`, or `azure` |
+| fx | Required `provider`: `gateway`, `codex`, or `grok` | Required `provider` naming an existing native custom connection and explicit `env` |
+
+For Copilot API keys, default variables are respectively `COPILOT_GITHUB_TOKEN`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `AZURE_OPENAI_API_KEY`. A GitHub token selects GitHub Copilot billing; the other three providers select direct provider billing. An explicit `env` replaces the default rather than adding credential discovery.
+
+`baseUrl` is supported only for OpenCode direct API keys and Copilot BYOK providers. It must be an absolute HTTP or HTTPS URL without user information, query, or fragment; credentials belong in environment references. OpenCode preserves the selected provider's native endpoint when it is omitted. Copilot defaults OpenAI to `https://api.openai.com/v1` and Anthropic to `https://api.anthropic.com`; Azure requires an explicit `baseUrl`. OpenAI-compatible endpoints use Copilot `provider: "openai"` with an explicit URL. This does not define custom OpenCode provider or model metadata.
+
+`wireApi` is supported only for Copilot OpenAI/Azure routes, defaulting to `completions`. `apiVersion` is supported only for Copilot Azure and maps to the native Azure API version; omission preserves its native versionless route. `wireModel` is supported only for Copilot BYOK and supplies the provider model or deployment name when it differs from the agent's native behavior model. Omission uses the agent's model for both. These fields are not accepted for GitHub-token, subscription, or Gateway routes. No arbitrary headers, token callbacks, or native configuration objects are accepted.
+
+Gateway connection shapes and billing behavior are unchanged; they do not accept provider overrides. `vercel-oidc` accepts `project`, defaulting to `.`. Unknown or inapplicable fields and missing required provider/source selections fail before native startup. Variable names match `[A-Za-z_][A-Za-z0-9_]*`. Tokens and API keys must never appear directly in this file. Native logins are completed through each harness's own login command, outside Subharness.
 
 Without `envFile`, the named variable is read from the invoking environment. With `envFile`, only that variable is read from that explicit UTF-8 dotenv file; its other values are not imported, and the process environment does not override the selected file. File and project paths resolve relative to the main checkout, or project root outside Git. Shell expansion and command execution in dotenv values are not supported. Sources are read at native session startup; changing a file does not refresh a token already supplied to a running harness.
 
-Omitting `codex` or `claudeCode` retains native subscription discovery. A nonempty array replaces discovery with the listed connections in order. An empty array disables that harness. Supported keys are `codex`, `claudeCode`, and `fx`. Omitting `fx` does not enable any connection because its adapter requires explicit Gateway access; see [fx access](fx.md). Missing credentials make a connection unavailable before submission; malformed settings, malformed tokens, expired tokens, and project mismatches are errors. Only known unavailability permits advancing to another explicitly enabled connection or harness. Failures after submission never automatically migrate or replay the task.
+Omitting `codex` or `claudeCode` retains native subscription discovery. A nonempty array replaces discovery with the listed connections in order. An empty array disables that harness. Supported keys are `codex`, `claudeCode`, `fx`, `opencode`, `copilot`, and `cursor`. The last four require an explicit connection; omission enables no access, even when a native login or ambient key exists. fx, OpenCode, and Copilot accept their documented native login, direct-key, and Gateway routes. Cursor accepts native CLI login or Cursor SDK API-key access and rejects Gateway connections. Each connection selects one billing route without implicit substitution. See [fx](fx.md), [OpenCode](opencode.md), [Copilot](copilot.md), and [Cursor](cursor.md).
+
+Missing credentials make a connection unavailable before submission; malformed settings, malformed tokens, expired OIDC tokens, and project mismatches are errors. Only known unavailability permits advancing to another explicitly enabled connection or harness. Native status and configuration checks do not prove remote credential validity, quota, or plan eligibility. Failures after submission never automatically migrate or replay the task.
 
 `subharness check` resolves these settings and tries eligible connections and declared harness alternatives exactly as `run` does before submission. It does not infer readiness from environment variables or duplicate adapter authentication checks. A successful check applies only to the connection and harness selected by that fallback process at that moment.
 
+## Access context in errors
+
+Schema validation locations and distinct OIDC temporal errors are defined in [error diagnostics](diagnostics.md). A settings validation failure identifies the file and structural location before native access selection begins.
+
+When a connection fails during native startup, `check` and `run` include the harness and attempted connection type in the diagnostic. They retain the original error code and fallback rules. A model configuration failure reported by an already opened session also includes its selected connection context. This context describes the connection attempted by Subharness; it does not claim that the native harness authenticated successfully through that connection.
+
+Diagnostics distinguish explicitly configured connections from default native subscription discovery. For settings loaded from disk, they identify the absolute personal settings path in the main checkout, or the execution project outside Git. If the file is absent, the diagnostic says that native subscription discovery was used because no personal access settings were found there. If the file exists but omits the harness's access entry, the diagnostic says that the entry is omitted. An explicit connection identifies its type and its position in the configured list, so multiple connections of the same type remain distinguishable.
+
+When the current personal settings file is absent and an entry exists at the former `.agents/agents.local.json` location, the diagnostic also identifies that legacy path and explains that it is not read. Detecting the legacy entry does not read its contents, migrate it, or change connection selection. Failure to inspect the legacy location does not replace the original startup error. Settings presence and selection context are captured when access settings are loaded, so a later file change does not rewrite the explanation for an existing session.
+
+Claude model mismatch diagnostics identify whether the mismatch was observed during startup settings validation, native initialization, or retained-session validation before submission. They do not infer that a mismatch is transient or that missing access settings caused it. A mismatch still fails without automatic retry, model substitution, or task replay.
+
+For example, a startup mismatch with a missing access file reports the model validation failure together with `claudeCode`, the attempted `subscription` connection, and `No personal access settings were found at "/project/.subharness/agents.local.json"; using native subscription discovery.` Explicit Gateway access instead reports the configured `vercel-oidc` or `vercel-api-key` connection and its list position.
+
+Added diagnostic context contains only connection-selection metadata and settings paths. It never includes credential values, environment contents, settings-file contents, or raw native output. Paths are quoted with C0 and C1 control characters, DEL, and Unicode line separators escaped so one path cannot inject terminal controls or extra diagnostic lines. Successful command output and the public error record shape remain unchanged.
+
 ## OIDC project selection
 
 The selected project directory must contain `.vercel/project.json` with `projectId` and `orgId`. In a deployment without local linkage, `VERCEL_PROJECT_ID` and `VERCEL_ORG_ID` identify the expected project and organization when `project` is omitted. A supplied `project` always requires its explicit linkage. Token claims must match the expected project and organization and be within their validity interval. Local claim checks prevent accidental selection errors; the Gateway authenticates the token.

package/sdk/adapter-contract.md

@@ -1,8 +1,12 @@
 # Native Adapter Contract
 
-Adapters create native Codex, Claude Code, or fx conversations in the caller-supplied directory. Their implementation interface is internal and is not an SDK extension API. A session supplies `turn(prompt)`, `steer(prompt)`, `interrupt()`, `resume()`, and `close()`. A turn resolves with its complete text; execution failures reject with a stable error code. Interrupt resolves only when active execution has stopped. Unsupported operations return explicit capability errors. The [fx contract](fx.md) specifies its native ACP transport, Gateway access, and capability limits.
+The [execution SDK](execution.md) reuses native adapters. Embedded runners use an in-process session driver and host-owned custom tools; connected clients use coordinator-owned captured definitions and native sessions. It exposes complete responses and task snapshots, without promising a native token/tool-progress stream.
 
-Adapter startup receives the selected harness configuration, loaded agent definition, execution directory, environment, and resolved personal access. Startup verifies compatibility and access before submitting any task. A direct CLI harness target supplies no specialist instructions, custom tools, or declared children. Its internal execution configuration may request a native default model; public SDK constructors still require explicit models. Default resolution happens before the first prompt, within the authorized access route, and the resolved model is retained for follow-ups. An unavailable or unverifiable default fails with guidance to supply `--model`, without probing it through a paid generation. Explicit model and effort validation remains effective. `HARNESS_UNAVAILABLE` and `ACCESS_UNAVAILABLE` permit trying another declared alternative before submission. Invalid configuration and unsupported explicit options do not. No adapter performs automatic fallback after turn submission.
+Adapters create native Codex, Claude Code, fx, OpenCode, GitHub Copilot, or Cursor conversations in the caller-supplied directory. Their implementation interface is internal and is not an SDK extension API. A session supplies `turn(prompt)`, `steer(prompt)`, `interrupt()`, `resume()`, and `close()`. A turn resolves with its complete text; machine-reported execution failures reject with a stable error code. The Cursor subscription ACP route has the documented limitation that some native backend failures arrive only as assistant text. Interrupt resolves only when active execution has stopped. Unsupported operations return explicit capability errors. Harness-specific contracts are defined for [fx](fx.md), [OpenCode](opencode.md), [Copilot](copilot.md), and [Cursor](cursor.md).
+
+[Error diagnostics](diagnostics.md) defines startup failure classification, safe native failure categories, and process termination context. Unexpected Claude account-inspection or model-catalog exceptions are harness failures, not evidence that another access route should be tried.
+
+Adapter startup receives the selected harness configuration, loaded agent definition, execution directory, environment, and resolved personal access. Startup verifies compatibility and access before submitting any task. A direct CLI harness target supplies no specialist instructions, custom tools, or declared children. Codex, Claude Code, and fx may request a verifiable native default model internally; OpenCode, Copilot, and Cursor require an explicit CLI model. Public SDK constructors always require a model. Default resolution happens before the first prompt, within the authorized access route, and the resolved model is retained for follow-ups. An unavailable or unverifiable default fails with guidance to supply `--model`, without probing it through a paid generation. Explicit model and effort validation remains effective. `HARNESS_UNAVAILABLE` and `ACCESS_UNAVAILABLE` permit trying another declared alternative before submission. Invalid configuration and unsupported explicit options do not. No adapter performs automatic fallback after turn submission.
 
 The CLI readiness check uses this same startup and pre-submission fallback path in an isolated worker, then closes the native session without calling `turn`. It therefore verifies only capabilities observable during startup. It does not probe quota with generation, exercise native tools, or establish shell and child-launch permissions. Startup may create an empty native conversation and private temporary files; normal close removes library-owned temporary files under the adapter lifecycle rules.
 
@@ -12,6 +16,12 @@ Agent instructions supplement native instructions. The adapter exposes declared
 
 Codex uses its native App Server protocol. Claude Code uses its native Agent SDK with the installed Claude executable. A Claude session accepts queued native turns and interruption. Its native steering method reports `UNSUPPORTED_DELIVERY` before any mutation; the coordinator converts that request to the documented interrupt operation and reports the effective delivery mode. Codex steering targets the active native turn. Neither adapter synthesizes native recovery by replaying the original prompt; unavailable recovery returns `RECOVERY_UNSUPPORTED`.
 
+Adapter selection loads only the adapter being attempted. Claude's Agent SDK runs in a private worker for each session because its module initialization can change process environment variables. The worker receives a copy of the captured session environment and never shares the application's `process.env`. This boundary is internal and does not change the public session or tool interfaces.
+
+The host retains the original tool schemas, closures, validation, and callback admission and draining. The worker receives tool descriptions and JSON schemas and forwards calls to those original host tools; it does not reconstruct application schemas or execute application callbacks. Native approval requests, answers, and withdrawals cross the same private boundary without changing offered permissions or admitting stale answers. No environment or credential values enter bridge diagnostics.
+
+The host owns Claude's concrete native subprocess and private configuration cleanup, including when the worker fails. The SDK's custom process hook bridges native streams and process events to the worker with backpressure. Closing confirms native termination and drains admitted callbacks before reporting completion; terminating the worker alone is insufficient. A close requested during startup waits for that attempt to settle and closes any resulting session without submitting a turn; it does not impose a startup deadline. Interruption confirms that the active native turn has stopped and drains its admitted callbacks while retaining the session. Cleanup failures retain ownership for retry. Unexpected worker or bridge failures are execution failures, not reasons to replay input or switch providers.
+
 Personal subscription selection must verify native subscription access. Ambient API keys, alternate endpoints, provider overrides, and native API-key helpers must not silently change the selected billing method. Explicit API or Gateway selections supply only the selected credential route. Credentials are never included in CLI records or diagnostic output.
 
 Unsupported approval and interactive-input diagnostics use `INPUT_REQUIRED`. Claude diagnostics may identify a bounded native tool name; Codex diagnostics identify the recognized fixed approval method and category. Diagnostics do not expose raw tool arguments, settings or credentials. Supported approval requests expose the bounded action context needed for the caller's decision under the [approval contract](approvals.md), separately from error diagnostics.
@@ -22,7 +32,7 @@ Claude accelerated mode with subscription access is rejected in v1 because it re
 
 ## Native default selection
 
-Direct CLI targets resolve omitted models through the native session's effective configuration before submitting user input. Codex uses the model returned by App Server `thread/start`, verifies the selected provider and subscription catalog when applicable, and retains that model in subsequent turns. fx uses the Gateway provider and model reported by ACP `session/new`, then verifies any explicit effort through the existing configuration control.
+Direct CLI targets resolve omitted models through the native session's effective configuration before submitting user input. Codex uses the model returned by App Server `thread/start`, verifies the selected provider and subscription catalog when applicable, and retains that model in subsequent turns. fx uses the selected native provider and model reported by ACP `session/new`, then verifies any explicit effort through the existing configuration control.
 
 Claude Code resolves its effective model through a capability-checked native settings control. Only applied model and effort fields are retained; merged settings and credential-bearing source details are never logged or included in output. The adapter pins the resolved model for the session through the native model control and verifies the applied result before input is admitted. If the installed SDK or executable cannot expose a verifiable applied model before submission, omitted-model startup fails with `INVALID_CONFIG` and guidance to supply `--model`. Explicit models retain compatibility with native versions that lack that introspection, along with the existing catalog and initialization checks.
 

package/sdk/additional-harnesses.md

@@ -0,0 +1,43 @@
+# Additional native harnesses
+
+OpenCode, GitHub Copilot, and Cursor are native harness targets. The SDK exports `opencode`, `copilot`, and `cursor`. Their configuration discriminators, personal access keys, and reserved CLI targets are respectively `opencode`, `copilot`, and `cursor`.
+
+```ts
+import { opencode, copilot, cursor } from "subharness";
+
+opencode({ model: "anthropic/claude-sonnet-5" });
+copilot({ model: "openai/gpt-6-astra" });
+cursor({ model: "CURSOR_MODEL_ID", sandboxMode: "enabled" });
+
+interface OpencodeOptions { readonly model: string }
+interface CopilotOptions { readonly model: string }
+interface OpencodeConfig extends OpencodeOptions { readonly kind: "opencode" }
+interface CopilotConfig extends CopilotOptions { readonly kind: "copilot" }
+```
+
+Constructors return immutable configurations. Models must be nonempty. These options deliberately expose only verified capabilities. `fast`, `effort`, unknown fields, and permission options for other harnesses are rejected. Cursor's additional sandbox option and native lifecycle are specified in [Cursor](cursor.md).
+
+All three direct CLI targets require an explicit `--model` and reject `--effort`. An omitted or unverifiable model fails with `INVALID_CONFIG` and guidance to supply `--model`, without a generation to discover it. SDK constructors always require the model. OpenCode and Copilot Gateway models use the Gateway's `creator/model` identifier; adapters translate native provider prefixes internally and never silently select a different model.
+
+## Access routes
+
+OpenCode and Copilot accept explicit native saved-login, direct API-key, and Vercel AI Gateway connections. Each route is selected independently; Gateway is optional. The provider selectors, credential variables, endpoint options, and route-specific model IDs are defined in [personal access](access-config.md), [OpenCode](opencode.md), and [Copilot](copilot.md). Cursor accepts native CLI `subscription` or Cursor SDK `api-key` access and does not support Gateway connections. Omitting any of the three access keys enables no connections. Empty arrays disable them. No ambient credential enables spending.
+```json
+{
+  "access": {
+    "opencode": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
+    "copilot": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
+    "cursor": [{ "type": "api-key", "env": "CURSOR_API_KEY" }]
+  }
+}
+```
+
+Existing credential reference, main-checkout path, OIDC identity/expiry, fallback, and credential redaction rules apply. Gateway API keys default to `AI_GATEWAY_API_KEY`, OIDC defaults to `VERCEL_OIDC_TOKEN`, and Cursor API keys default to `CURSOR_API_KEY`. Unsupported explicit connections fail before native startup, without choosing another billing route.
+
+## CLI and coordination
+
+The built-in catalog lists `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` in that order before specialists. Same-named specialists require a scope qualifier. Direct targets bypass catalog evaluation. These labels are accepted by the dashboard and execution records. Readiness checks use the same selection and cleanup path as runs and never submit a prompt.
+
+The existing queue, declared-child launcher, task/result, interruption, and fallback contracts apply. These adapters do not expose verified active steering or prompt-free recovery. Steering uses the coordinator's documented interrupt behavior; `resume` returns `RECOVERY_UNSUPPORTED`. Unsupported interactive input fails with `INPUT_REQUIRED` without automatically granting permission. An adapter reports interruption only after native execution has stopped and admitted custom tool callbacks have settled. Native processes and resources must be closed before readiness can succeed.
+
+The eval runner's named scenarios remain limited to the existing Codex, Claude Code, and fx matrix. Adding runtime harnesses does not implicitly add paid eval scenarios or native credentials.

package/sdk/agent-skill.md

@@ -14,7 +14,7 @@ The installer reads the source repository, so installation requires access to [v
 
 ## Location and discovery
 
-The skill's entry point is `skills/subharness/SKILL.md` at the repository root, with its credential helper in `skills/subharness/scripts/refresh-vercel-oidc.mjs`. Its frontmatter `name` is `subharness`, and its `description` states that the skill applies when the human asks the agent to delegate, parallelize, or hand off work to Codex, Claude Code, or fx, or to follow up on, check, or cancel delegated work.
+The skill's entry point is `skills/subharness/SKILL.md` at the repository root, with its credential helper in `skills/subharness/scripts/refresh-vercel-oidc.mjs`. Its frontmatter `name` is `subharness`, and its `description` states that the skill applies when the human asks the agent to delegate, parallelize, or hand off work to Codex, Claude Code, fx, OpenCode, GitHub Copilot, or Cursor, or to follow up on, check, or cancel delegated work.
 
 `npx skills add vercel-labs/subharness` offers only this skill. The repository's development skills under `.agents/skills/` set `metadata.internal: true` in their frontmatter, which the installer hides by default. That field does not change how native harnesses read those skills.
 
@@ -25,7 +25,7 @@ The skill is not part of the npm package. [Package Distribution](distribution.md
 The skill is concise, task-oriented guidance for the main agent. It agrees with the [CLI](cli/index.md), [Output](cli/output.md), [Message delivery](message-delivery.md), and [Sessions](sessions.md), and [Responding to Native Permission Requests](approvals.md) references and introduces no commands, flags, defaults, or behavior they do not document. It covers:
 
 - When to delegate: independent, well-scoped work that can run while the conversation continues, and when the human names a harness.
-- Choosing a target: the reserved `claude`, `codex`, and `fx` direct targets, and `subharness list` for discovered specialists.
+- Choosing a target: the reserved `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` direct targets, and `subharness list` for discovered specialists.
 - Starting work with `subharness run <target> [--cwd <directory>] <prompt>`, `--prompt`, or `--prompt-file`, including quoting a positional prompt and giving the child explicit task context, because children do not receive the main conversation's transcript or loaded skills.
 - Preferring a single `subharness run <target> <prompt>` through the host's background-task controls when that capability is known to be available. The caller collects that hosted command's output later; a separate `--detach` and `wait` sequence is unnecessary for its first response.
 - Using `subharness run <target> --detach <prompt>` when background-command support is unavailable or uncertain, returning after admission and retaining the task identifier. `wait` returns or awaits the first response and runs only after useful independent work, when the caller is ready to wait. The minimal example contains only `run --detach` and `wait`; `status` is a separate optional nonblocking snapshot, not an unconditional step before or after `wait`.

package/sdk/agent.md

@@ -1,6 +1,6 @@
 # Defining an Agent
 
-Import definitions from `subharness`. The helpers are synchronous declarations: they do not start harnesses, authenticate, call models, or execute tools. Execution uses the CLI.
+Import definitions from `subharness`. The helpers are synchronous declarations: they do not start harnesses, authenticate, call models, or execute tools. Execution uses either the CLI or the application-owned [execution SDK](execution.md).
 
 ```ts
 import { agent, codex, claudeCode } from "subharness";
@@ -45,12 +45,14 @@ Children do not inherit loaded skill contents or the parent's transcript. Includ
 
 `codex(options)` and `claudeCode(options)` return configurations. Both require `model`, accept native `effort`, and accept `fast?: boolean`, defaulting to `false`. Options are typed independently to preserve each harness's capabilities. Codex effort values depend on the native model catalog; Claude effort accepts `low`, `medium`, `high`, `xhigh`, and `max`, subject to native model restrictions.
 
-`fx(options)` requires `model` and accepts optional native `effort`. It has no `fast` option. Its readonly configuration has `kind: "fx"`; see the [fx contract](fx.md) for Gateway access, native capabilities, and permission limits. `HarnessConfig` is the union of the native harness configurations, so narrowing by `kind` exposes the options supported by that harness.
+`fx(options)` requires `model` and accepts optional native `effort`. It has no `fast` option. Its readonly configuration has `kind: "fx"`; see the [fx contract](fx.md) for supported access routes, native capabilities, and permission limits. `HarnessConfig` is the union of the native harness configurations, so narrowing by `kind` exposes the options supported by that harness.
 
-The package exports `CodexOptions`, `ClaudeCodeOptions`, and `FxOptions` together with their readonly return types `CodexConfig`, `ClaudeCodeConfig`, and `FxConfig`. Runtime validation also enforces Claude's listed effort values when TypeScript checking is absent; unsupported values fail with `INVALID_DEFINITION` before native execution.
+`opencode(options)` and `copilot(options)` require only `model`. Their readonly configurations use `kind: "opencode"` and `kind: "copilot"`. `cursor(options)` requires `model` and accepts `sandboxMode?: "enabled" | "disabled"`; omission preserves Cursor's native default. These constructors reject `effort`, `fast`, and permission fields belonging to other harnesses. See [Additional native harnesses](additional-harnesses.md), [OpenCode](opencode.md), [Copilot](copilot.md), and [Cursor](cursor.md).
+
+The package exports the corresponding `Options` and readonly `Config` types for all six constructors. Runtime validation also enforces Claude's listed effort values and Cursor's sandbox values when TypeScript checking is absent; unsupported values fail with `INVALID_DEFINITION` before native execution.
 
 The `harness` property always uses that name, even for an array. Alternatives are considered in declaration order; an array does not mean parallel execution. [Personal access settings](access-config.md) determine which connections are eligible without editing a shared agent.
 
 ## Native permission options
 
-Harness constructors also accept the native permission options defined in [Native Permissions](permissions.md). Options are typed and validated independently for each harness. Omitted values preserve native settings; explicit values configure only the new native session and remain fixed for follow-ups. There is no permission profile registry.
+The Codex, Claude Code, and fx constructors also accept the native permission options defined in [Native Permissions](permissions.md). Options are typed and validated independently for each harness. Omitted values preserve native settings; explicit values configure only the new native session and remain fixed for follow-ups. Cursor's `sandboxMode` selects the SDK sandbox for API-key access; subscription ACP access rejects explicit sandbox settings. OpenCode and Copilot expose no public permission option. There is no permission profile registry.

package/sdk/approvals.md

@@ -1,5 +1,7 @@
 # Responding to Native Permission Requests
 
+The [execution SDK](execution.md#unified-approval-types) exposes normalized approval actions through task snapshots. `runner.respond` and `client.approvals.respond` select an advertised action ID, with explicit permission grants when required. They resolve the same retained requests as the native-schema CLI and hosted-tool flow below. These are separate response formats: SDK callers use `{ actionId, grants? }`; CLI and hosted tools use request-specific native schema content. Neither response completes or restarts the task. The internal native approval callback remains adapter-facing.
+
 A native tool permission request suspends the operation that needs authorization while its original native turn stays open. Subharness returns a structured request to the observing caller. The caller can answer the request and then observe the same task. Permission handling never replays a prompt, creates a replacement task, changes the selected native policy, or automatically approves an operation. Independent native operations and sibling tasks may continue.
 
 ## Observe and respond
@@ -70,6 +72,8 @@ Claude tool approvals expose allow-once and denial. Session-scoped reuse is offe
 
 fx retains the actual ACP option identifiers and descriptive labels. In the supported fx integration, `allow_always` means the session, not a permanent grant. The adapter accepts only offered options and translates the selected ID to the original ACP response. Native cancellation remains distinct from a chosen denial.
 
+OpenCode exposes only its native once and rejection decisions for supported active permission requests. Copilot exposes only the specific offered approve-once and rejection decisions. Neither adapter exposes or invents a reusable grant. Their bounded action context and withdrawal behavior are defined in [OpenCode](opencode.md) and [Copilot](copilot.md). Cursor subscription sessions expose offered ACP allow-once and reject-once options, retaining native IDs and bounded tool context; persistent choices are excluded. Its API-key SDK route has no interactive approval bridge. Other Cursor interactive requests fail with `INPUT_REQUIRED` as defined in [Cursor](cursor.md).
+
 Requests which cannot be represented faithfully, unsupported interactive input, and startup-time interactions fail explicitly with `INPUT_REQUIRED`. Policies such as `never` or `dontAsk` may suppress native requests entirely; hard sandbox denials cannot be approved through this mechanism. Omitted native settings remain unchanged.
 
 These answer objects illustrate different schemas; submit one only when its fields and values are offered by the actual request:
@@ -102,7 +106,7 @@ These signatures describe an internal implementation boundary, not new package e
 type ApprovalContent = Record<string, string | number | boolean | string[]>;
 interface NativeApprovalRequest {
   kind: "permission";
-  harness: "codex" | "claudeCode" | "fx";
+  harness: "codex" | "claudeCode" | "fx" | "opencode" | "copilot" | "cursor";
   message: string;
   requestedSchema: ApprovalSchema;
   context?: Record<string, unknown>;

package/sdk/authentication.md

@@ -2,7 +2,7 @@
 
 Login belongs to the selected native harness or access provider. The library selects compatible access at startup and does not create a separate subscription account or transfer subscription tokens between harnesses.
 
-Without personal settings, the library discovers eligible native subscription access for the agent's declared harness alternatives. An API credential in the environment does not enable API billing. If the integration cannot establish that a native login uses subscription access, it reports that access is unavailable instead of assuming OAuth implies a subscription.
+Without personal settings, Codex and Claude Code retain native subscription discovery. Other harnesses require an explicit connection. An API credential in the environment does not enable API billing. Saved-login routes verify the native credential source according to each adapter contract; they do not infer plan eligibility, free usage, or a spending cap from OAuth alone. The fx saved Vercel login is a native-login route that still bills AI Gateway.
 
 Users can mix subscription, direct API, Gateway API-key, and Gateway OIDC access in one project. Preferences belong to the user, separately from versioned agent definitions. Two contributors can run the same definition through different declared harness alternatives and compatible connections.
 

package/sdk/cli/dashboard-design.md

@@ -72,3 +72,9 @@ The overview remains a small snapshot. An open history requests only metadata fo
 Inspection never sends prompts, steers, cancels, resumes or acknowledges work, starts execution, or restarts the coordinator. The private transport is defined in [Inspection transport](dashboard-inspection.md).
 
 Snapshots require finished-history and grouped-context capabilities. A missing capability or the exact legacy unknown-operation response reports `COORDINATOR_OUTDATED` with restart guidance. Opening history against a coordinator without the history operation reports the same error rather than presenting incomplete history. Other malformed or failed reads report `COORDINATOR_UNAVAILABLE` after terminal cleanup. Restarting a coordinator discards retained history and is never performed automatically.
+
+## Shared presentation boundary
+
+The terminal command and website demonstration reuse the internal ANSI renderer, layout, history/detail formatting, text sanitization, input decoding and key-action dispatch. Presentation code accepts explicit dimensions, data and time; it does not discover workspaces, access credentials, read files or contact the coordinator. This boundary adds no public SDK method. The terminal command preserves its existing process lifecycle, serialized reads and backpressure behavior. The website supplies fictional read-only projections and owns its browser terminal lifecycle.
+
+The internal `dispatchDashboardKey(renderer, key)` function in `src/cli/dashboard-controller.ts` applies a `DashboardKey` to a `DashboardRenderer` and returns `{ interrupt: boolean; refreshInspection: boolean }`. Interrupt requests process exit only in the CLI host; the browser host instead releases focus. `refreshInspection` is true when a successful open, toggle, leave or selected-request change invalidates the previous inspection read, including collapsing an expanded request by changing selection. Hosts cancel obsolete reads or load their local sample projection after that signal. Overview movement and scrolling an unchanged expansion do not request new detail reads. The dispatcher never fetches data or schedules timers.