subharness 0.0.5 → 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":"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","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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "subharness",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "engines": {
     "node": ">=22.18.0"
@@ -35,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",
@@ -52,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

package/sdk/adapter-contract.md

@@ -1,5 +1,7 @@
 # Native Adapter Contract
 
+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.
+
 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.
@@ -14,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.

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";

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

package/sdk/completion-notifications.md

@@ -1,5 +1,7 @@
 # Responses and Task Completion
 
+The [execution SDK](execution.md) provides complete-response cursors and task snapshot observation directly to application code. It does not provide token deltas or native tool-progress events. UI disconnects detach observers. Embedded runner lifetime is application-owned; shared coordinator work survives connected-client disconnect.
+
 Returning a response, completing a task, and starting another caller model turn are separate operations. The CLI returns control after each complete native response from the requested agent. It includes task/session identity, response identity, and the task state. It does not continuously forward token streams, native tool events, or descendants' transcripts.
 
 The adapter captures complete responses automatically. Agents do not need a reporting tool, special JSON format, or a classifier that recognizes questions. A question is delivered through the same response mechanism as any other text.

package/sdk/distribution.md

@@ -10,7 +10,9 @@ Node.js 22.18 or newer is required. The SDK is ESM and includes TypeScript decla
 
 The public npm package is `subharness`, with an initial release version of `0.0.1`. Install the CLI globally with `npm install --global subharness`, or run it without a global installation using `npx subharness`. Registry installation does not require access to the internal source repository. The root package is publishable; the documentation workspace remains private.
 
-For project-local use, install `subharness` with `npm install --save-dev subharness` and invoke its CLI with `npx subharness`. This also makes SDK imports resolve from repository agent definitions. A global CLI installation alone does not make SDK imports resolve from project-local definitions. Global definitions need an SDK dependency reachable from their own directory under normal Node package resolution.
+Application backends install `subharness` with `npm install subharness` and import the [execution SDK](execution.md). Native executables remain external dependencies; the package does not require a globally installed Subharness CLI for SDK execution.
+
+For project-local CLI use, install `subharness` with `npm install --save-dev subharness` and invoke its CLI with `npx subharness`. This also makes SDK imports resolve from repository agent definitions. A global CLI installation alone does not make SDK imports resolve from project-local definitions. Global definitions need an SDK dependency reachable from their own directory under normal Node package resolution.
 
 Source development uses pnpm 11.20.0, pinned in the root `packageManager` field. `pnpm-workspace.yaml` includes the root SDK and `apps/docs`, with one committed `pnpm-lock.yaml`. Run `pnpm install --frozen-lockfile` from the repository root, then `pnpm run build`. Run the local CLI with `node dist/cli/main.js`; this requires no global link. Direct harness targets do not need a consumer SDK dependency. For use in another project, build a tarball with `pnpm pack` and install that tarball in the consumer so its agent definitions can resolve SDK imports.
 
@@ -22,7 +24,7 @@ A tarball built from a source checkout can differ from the registry release with
 
 Packages built from this source contain the built JavaScript, declaration files and source maps under `dist/`, SDK Markdown documentation under `sdk/`, the README, the Apache License 2.0, and package metadata. Source maps embed the original TypeScript so debuggers can display it without a separate source checkout. Website code, development agents, skills, source assets, tests, `.context`, personal settings, and environment files are excluded.
 
-Packing builds the SDK from the current source before assembling its files. The CLI's `--version` output matches the package version. A clean consumer must be able to import the SDK and discover a TypeScript agent definition using the installed executable without access to the source checkout or a paid model call. `pnpm run check:package` packs with pnpm and verifies this clean-consumer behavior and the packaged file boundary without running a coding model. It requires network access to install dependencies from the public npm registry and disables install lifecycle scripts in the temporary consumer.
+Packing builds the SDK from the current source before assembling its files. The CLI's `--version` output matches the package version. A clean consumer must be able to import the execution SDK, run an inline definition against a controlled native protocol fixture, and discover a TypeScript agent definition using the installed executable without access to the source checkout or a paid model call. `pnpm run check:package` packs with pnpm and verifies this clean-consumer behavior and the packaged file boundary without running a coding model. It requires network access to install dependencies from the public npm registry and disables install lifecycle scripts in the temporary consumer.
 
 The committed lockfile pins dependency content with integrity hashes and does not embed company registry URLs. pnpm resolves packages through the configured registry, which defaults to the public npm registry. Installation and package verification do not change the developer's global npm registry configuration. Registry authentication remains with npm.
 

package/sdk/examples/chat-tool.ts

@@ -0,0 +1,126 @@
+import {
+  createRunner,
+  type AgentDefinition,
+  type ApprovalResponse,
+  type CompleteResponse,
+  type PromptReceipt,
+  type RunnerOptions,
+  type SessionHandle,
+  type TaskHandle,
+  type TaskResult,
+  type TaskSnapshot,
+} from "subharness";
+
+type StringField = Readonly<{
+  type: "string";
+  description: string;
+  minLength: number;
+}>;
+
+interface HostTool<Input, Output> {
+  readonly description: string;
+  readonly inputSchema: Readonly<{
+    type: "object";
+    properties: Readonly<Record<keyof Input, StringField>>;
+    required: readonly (keyof Input)[];
+    additionalProperties: false;
+  }>;
+  execute(input: Input): Promise<Output>;
+}
+
+export interface ChatToolApplication {
+  readonly consultation: HostTool<{ prompt: string }, ObservedTask>;
+  readonly followup: HostTool<{ prompt: string }, ObservedTask>;
+  responses(taskId: string, options?: { readonly after?: string; readonly signal?: AbortSignal }): AsyncIterable<CompleteResponse>;
+  watch(taskId: string, options?: { readonly signal?: AbortSignal }): AsyncIterable<TaskSnapshot>;
+  answerApproval(requestId: string, response: ApprovalResponse): Promise<void>;
+  cancel(taskId: string): Promise<TaskSnapshot>;
+  dispose(): Promise<void>;
+}
+
+export interface ObservedTask {
+  readonly taskId: string;
+  readonly sessionId: string;
+  readonly result: TaskResult;
+}
+
+export function createChatToolApplication(options: {
+  readonly definition: AgentDefinition;
+  /** An existing absolute directory, validated by the runner when consultation starts. */
+  readonly cwd: string;
+  readonly runner?: RunnerOptions;
+  /** Called at task admission so the host can expose approval, observation, and stop controls immediately. */
+  readonly onTask?: (task: TaskHandle) => void;
+}): ChatToolApplication {
+  const runner = createRunner(options.runner);
+  const tasks = new Map<string, TaskHandle>();
+  let session: SessionHandle | undefined;
+  let sessionStarting = false;
+
+  const ownedTask = (taskId: string): TaskHandle => {
+    const task = tasks.get(taskId);
+    if (!task) throw new Error("The task does not belong to this chat execution scope.");
+    return task;
+  };
+  const remember = (task: TaskHandle): TaskHandle => {
+    tasks.set(task.id, task);
+    return task;
+  };
+  const observeTask = async (task: TaskHandle): Promise<ObservedTask> => {
+    const owned = remember(task);
+    options.onTask?.(owned);
+    return {taskId: owned.id, sessionId: owned.sessionId, result: await owned.result};
+  };
+
+  return {
+    consultation: {
+      description: "Consult the configured coding agent.",
+      inputSchema: promptSchema("The self-contained task and context for the specialist."),
+      execute: async ({ prompt }) => {
+        if (session || sessionStarting) throw new Error("This chat scope already has a specialist session; use followup.");
+        sessionStarting = true;
+        try {
+          const created = await runner.createSession(options.definition, { cwd: options.cwd });
+          let admitted: PromptReceipt;
+          try { admitted = await created.prompt(prompt); }
+          catch (error) { await created.close(); throw error; }
+          session = created;
+          return observeTask(admitted.task);
+        } finally {
+          sessionStarting = false;
+        }
+      },
+    },
+    followup: {
+      description: "Send a follow-up to the retained specialist session and observe its task.",
+      inputSchema: promptSchema("Additional context or a follow-up request for the specialist."),
+      execute: async ({ prompt }) => {
+        if (!session) throw new Error("Start a consultation before sending a follow-up.");
+        const sent = await session.prompt(prompt);
+        return observeTask(sent.task);
+      },
+    },
+    responses: (taskId, responseOptions) => ownedTask(taskId).responses(responseOptions),
+    watch: (taskId, watchOptions) => ownedTask(taskId).watch(watchOptions),
+    // The host must authenticate this route and submit an action offered by the request.
+    // Resolution only acknowledges the answer; keep observing to learn the outcome.
+    answerApproval: (requestId, content) => runner.respond(requestId, content),
+    cancel: taskId => ownedTask(taskId).cancel(),
+    dispose: () => runner.close(),
+  };
+}
+
+function promptSchema(description: string) {
+  return {
+    type: "object" as const,
+    properties: { prompt: { type: "string" as const, description, minLength: 1 } },
+    required: ["prompt"] as const,
+    additionalProperties: false as const,
+  };
+}
+
+// Keep one factory instance per authenticated, bounded chat/job scope. The host schedules
+// its next chat turn after receiving the result. Complete response replay can include `waiting`
+// and task completion alone does not prove the caller's objective succeeded.
+// Passing an AbortSignal to responses/watch disconnects only that reader. Use cancel for an
+// explicit Stop action, and dispose when the whole scope ends (not on browser disconnect).