subharness 0.0.1

package/dist/config/resolve-access.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseEnv } from "node:util";
+import { AgentError } from "../errors.js";
+import { configError, parseConnection } from "./access.js";
+import { resolveProject } from "./project.js";
+import { validateOidc } from "./oidc.js";
+export async function resolveAccess(connection, harness, cwd, env = process.env) {
+    parseConnection(connection);
+    const kind = typeof harness === "string" ? harness : harness.kind;
+    if (connection.type === "subscription") {
+        if (kind === "fx")
+            throw new AgentError("ACCESS_UNAVAILABLE", "fx does not support subscription access.");
+        return { type: "subscription" };
+    }
+    if (kind === "fx" && connection.type === "api-key") {
+        throw new AgentError("UNSUPPORTED_OPTION", "fx does not support direct provider API keys.");
+    }
+    const variable = connection.env ?? (connection.type === "api-key"
+        ? kind === "codex" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY"
+        : connection.type === "vercel-api-key" ? "AI_GATEWAY_API_KEY" : "VERCEL_OIDC_TOKEN");
+    const { mainRoot } = await resolveProject(cwd);
+    let token;
+    if (connection.envFile !== undefined) {
+        try {
+            token = parseEnv(await readFile(resolve(mainRoot, connection.envFile), "utf8"))[variable];
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                throw new AgentError("ACCESS_UNAVAILABLE", `Credential file is missing: ${connection.envFile}`);
+            configError(`Cannot read credential variable ${variable} from its configured file.`);
+        }
+    }
+    else
+        token = env[variable];
+    if (!token?.trim())
+        throw new AgentError("ACCESS_UNAVAILABLE", `Credential variable ${variable} is missing or empty.`);
+    if (connection.type === "vercel-oidc")
+        await validateOidc(token, mainRoot, connection.project, env);
+    return { type: connection.type, token };
+}
+//# sourceMappingURL=resolve-access.js.map

package/dist/config/resolve-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-access.js","sourceRoot":"","sources":["../../src/config/resolve-access.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAyB,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAA4B,EAC5B,OAAoC,EACpC,GAAW,EACX,GAAG,GAAsB,OAAO,CAAC,GAAG;IAEpC,eAAe,CAAC,UAAU,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAClE,IAAI,UAAU,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QACvC,IAAI,IAAI,KAAK,IAAI;YAAE,MAAM,IAAI,UAAU,CAAC,oBAAoB,EAAE,0CAA0C,CAAC,CAAC;QAC1G,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAClC,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACnD,MAAM,IAAI,UAAU,CAAC,oBAAoB,EAAE,+CAA+C,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS;QAC/D,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB;QAC3D,CAAC,CAAC,UAAU,CAAC,IAAI,KAAK,gBAAgB,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACvF,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,KAAyB,CAAC;IAC9B,IAAI,UAAU,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACrC,IAAI,CAAC;YAAC,KAAK,GAAG,QAAQ,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAAC,CAAC;QAClG,OAAO,KAAK,EAAE,CAAC;YACb,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,IAAI,UAAU,CAAC,oBAAoB,EAAE,+BAA+B,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;YACxJ,WAAW,CAAC,mCAAmC,QAAQ,4BAA4B,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;;QAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE;QAAE,MAAM,IAAI,UAAU,CAAC,oBAAoB,EAAE,uBAAuB,QAAQ,uBAAuB,CAAC,CAAC;IACvH,IAAI,UAAU,CAAC,IAAI,KAAK,aAAa;QAAE,MAAM,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACpG,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { parseEnv } from \"node:util\";\nimport type { ResolvedAccess } from \"../adapters/types.js\";\nimport { AgentError } from \"../errors.js\";\nimport type { HarnessConfig, HarnessKind } from \"../sdk/types.js\";\nimport { type AccessConnection, configError, parseConnection } from \"./access.js\";\nimport { resolveProject } from \"./project.js\";\nimport { validateOidc } from \"./oidc.js\";\n\nexport async function resolveAccess(\n  connection: AccessConnection,\n  harness: HarnessKind | HarnessConfig,\n  cwd: string,\n  env: NodeJS.ProcessEnv = process.env,\n): Promise<ResolvedAccess> {\n  parseConnection(connection);\n  const kind = typeof harness === \"string\" ? harness : harness.kind;\n  if (connection.type === \"subscription\") {\n    if (kind === \"fx\") throw new AgentError(\"ACCESS_UNAVAILABLE\", \"fx does not support subscription access.\");\n    return { type: \"subscription\" };\n  }\n  if (kind === \"fx\" && connection.type === \"api-key\") {\n    throw new AgentError(\"UNSUPPORTED_OPTION\", \"fx does not support direct provider API keys.\");\n  }\n  const variable = connection.env ?? (connection.type === \"api-key\"\n    ? kind === \"codex\" ? \"OPENAI_API_KEY\" : \"ANTHROPIC_API_KEY\"\n    : connection.type === \"vercel-api-key\" ? \"AI_GATEWAY_API_KEY\" : \"VERCEL_OIDC_TOKEN\");\n  const { mainRoot } = await resolveProject(cwd);\n  let token: string | undefined;\n  if (connection.envFile !== undefined) {\n    try { token = parseEnv(await readFile(resolve(mainRoot, connection.envFile), \"utf8\"))[variable]; }\n    catch (error) {\n      if ((error as NodeJS.ErrnoException).code === \"ENOENT\") throw new AgentError(\"ACCESS_UNAVAILABLE\", `Credential file is missing: ${connection.envFile}`);\n      configError(`Cannot read credential variable ${variable} from its configured file.`);\n    }\n  } else token = env[variable];\n  if (!token?.trim()) throw new AgentError(\"ACCESS_UNAVAILABLE\", `Credential variable ${variable} is missing or empty.`);\n  if (connection.type === \"vercel-oidc\") await validateOidc(token, mainRoot, connection.project, env);\n  return { type: connection.type, token };\n}\n"]}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class AgentError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type ErrorInfo = {
+    code: string;
+    message: string;
+};
+export declare function errorInfo(error: unknown): ErrorInfo;

package/dist/errors.js

@@ -0,0 +1,14 @@
+export class AgentError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AgentError";
+    }
+}
+export function errorInfo(error) {
+    return error instanceof AgentError
+        ? { code: error.code, message: error.message }
+        : { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message : String(error) };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,UAAW,SAAQ,KAAK;IACP,IAAI;IAAhC,YAA4B,IAAY,EAAE,OAAe;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;oBADW,IAAI;QAE9B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAID,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,KAAK,YAAY,UAAU;QAChC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE;QAC9C,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAClG,CAAC","sourcesContent":["export class AgentError extends Error {\n  constructor(public readonly code: string, message: string) {\n    super(message);\n    this.name = \"AgentError\";\n  }\n}\n\nexport type ErrorInfo = { code: string; message: string };\n\nexport function errorInfo(error: unknown): ErrorInfo {\n  return error instanceof AgentError\n    ? { code: error.code, message: error.message }\n    : { code: \"INTERNAL_ERROR\", message: error instanceof Error ? error.message : String(error) };\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { agent, codex, claudeCode, fx } from "./sdk/definitions.js";
+export { tool, toolResult } from "./sdk/tools.js";
+export type { ToolContent, ToolResult } from "./sdk/tools.js";
+export type { AgentDefinition, ClaudeCodeConfig, ClaudeCodeOptions, CodexConfig, CodexOptions, FxConfig, FxOptions, HarnessConfig, HarnessKind, ToolDefinition, } from "./sdk/types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { agent, codex, claudeCode, fx } from "./sdk/definitions.js";
+export { tool, toolResult } from "./sdk/tools.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["export { agent, codex, claudeCode, fx } from \"./sdk/definitions.js\";\nexport { tool, toolResult } from \"./sdk/tools.js\";\nexport type { ToolContent, ToolResult } from \"./sdk/tools.js\";\nexport type {\n  AgentDefinition,\n  ClaudeCodeConfig,\n  ClaudeCodeOptions,\n  CodexConfig,\n  CodexOptions,\n  FxConfig,\n  FxOptions,\n  HarnessConfig,\n  HarnessKind,\n  ToolDefinition,\n} from \"./sdk/types.js\";\n"]}

package/dist/runtime/client.d.ts

@@ -0,0 +1,9 @@
+import type { OutputRecord } from '../cli/output.js';
+import { type Endpoint } from './state.js';
+interface ConnectionOptions {
+    directory?: string;
+    timeoutMs?: number;
+}
+export declare function connect(start: boolean, options?: ConnectionOptions): Promise<Endpoint>;
+export declare function request(endpoint: Endpoint, body: unknown): AsyncGenerator<OutputRecord>;
+export {};

package/dist/runtime/client.js

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import { open, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { AgentError } from '../errors.js';
+import { localProgram, privateDirectory, readEndpoint, stateDirectory, removeStaleStartupLock } from './state.js';
+export async function connect(start, options = {}) {
+    const directory = options.directory ?? stateDirectory();
+    const available = await readEndpoint(directory);
+    if (available)
+        return available;
+    if (!start)
+        throw new AgentError('UNKNOWN_SESSION', 'No coordinator is reachable from this environment. Its sessions may have ended, or native permissions may block access to its local endpoint.');
+    await privateDirectory(directory);
+    const lock = join(directory, 'startup.lock');
+    const deadline = Date.now() + (options.timeoutMs ?? 15_000);
+    for (;;) {
+        let owner;
+        try {
+            owner = await open(lock, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            await removeStaleStartupLock(lock);
+        }
+        if (owner) {
+            try {
+                await owner.writeFile(String(process.pid));
+                await owner.close();
+                const existing = await readEndpoint(directory);
+                if (existing)
+                    return existing;
+                const program = localProgram('daemon');
+                const child = spawn(process.execPath, [...program.execArgv, program.file], { detached: true, stdio: 'ignore', env: { ...process.env, AGENT_STATE_DIR: directory } });
+                let spawnError = false;
+                child.once('error', () => { spawnError = true; });
+                child.unref();
+                while (Date.now() < deadline && !spawnError) {
+                    await delay(50);
+                    const endpoint = await readEndpoint(directory);
+                    if (endpoint)
+                        return endpoint;
+                }
+                throw new AgentError('STARTUP_FAILED', 'The local coordinator could not start.');
+            }
+            finally {
+                await owner.close().catch(() => { });
+                await unlink(lock).catch(() => { });
+            }
+        }
+        if (Date.now() >= deadline)
+            throw new AgentError('STARTUP_FAILED', 'Another command did not finish coordinator startup.');
+        await delay(50);
+        const endpoint = await readEndpoint(directory);
+        if (endpoint)
+            return endpoint;
+    }
+}
+export async function* request(endpoint, body) {
+    let response;
+    try {
+        response = await fetch(endpoint.url, { method: 'POST', headers: { authorization: `Bearer ${endpoint.token}`, 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    }
+    catch {
+        throw new AgentError('COORDINATOR_UNAVAILABLE', 'Connection to the local coordinator failed. The task was not automatically retried.');
+    }
+    if (!response.ok || !response.body)
+        throw new AgentError('COORDINATOR_UNAVAILABLE', 'The coordinator rejected the request.');
+    let buffer = '';
+    const decoder = new TextDecoder();
+    try {
+        for await (const chunk of response.body) {
+            buffer += decoder.decode(chunk, { stream: true });
+            let newline;
+            while ((newline = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                if (line)
+                    yield JSON.parse(line);
+            }
+        }
+        buffer += decoder.decode();
+        if (buffer.trim())
+            throw new Error('Incomplete response record');
+    }
+    catch {
+        throw new AgentError('COORDINATOR_UNAVAILABLE', 'The coordinator response was interrupted or invalid. The task was not automatically retried.');
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/runtime/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/runtime/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAiB,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAIjI,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAAc,EAAE,OAAO,GAAsB,EAAE;IAC3E,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,cAAc,EAAE,CAAC;IACxD,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,UAAU,CAAC,iBAAiB,EAAC,+IAA+I,CAAC,CAAC;IACpM,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAC,cAAc,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC,CAAC;IAC5D,SAAS,CAAC;QACR,IAAI,KAAK,CAAC;QACV,IAAI,CAAC;YAAC,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAC,IAAI,EAAC,KAAK,CAAC,CAAC;QAAC,CAAC;QAC5C,OAAO,KAAK,EAAE,CAAC;YACb,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;YACpE,MAAM,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAC,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;gBAChE,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;gBAC/C,IAAI,QAAQ;oBAAE,OAAO,QAAQ,CAAC;gBAC9B,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACvC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAC,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAC,OAAO,CAAC,IAAI,CAAC,EAAC,EAAC,QAAQ,EAAC,IAAI,EAAC,KAAK,EAAC,QAAQ,EAAC,GAAG,EAAC,EAAC,GAAG,OAAO,CAAC,GAAG,EAAC,eAAe,EAAC,SAAS,EAAC,EAAC,CAAC,CAAC;gBACvJ,IAAI,UAAU,GAAG,KAAK,CAAC;gBACvB,KAAK,CAAC,IAAI,CAAC,OAAO,EAAC,GAAE,EAAE,GAAC,UAAU,GAAC,IAAI,CAAC,CAAA,CAAC,CAAC,CAAC;gBAAC,KAAK,CAAC,KAAK,EAAE,CAAC;gBAC1D,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,IAAI,CAAC,UAAU,EAAE,CAAC;oBAC5C,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC;oBAChB,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;oBAC/C,IAAI,QAAQ;wBAAE,OAAO,QAAQ,CAAC;gBAChC,CAAC;gBACD,MAAM,IAAI,UAAU,CAAC,gBAAgB,EAAC,wCAAwC,CAAC,CAAC;YAClF,CAAC;oBAAS,CAAC;gBAAC,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAE,EAAE,GAAC,CAAC,CAAC,CAAC;gBAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAE,EAAE,GAAC,CAAC,CAAC,CAAC;YAAC,CAAC;QACpF,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,MAAM,IAAI,UAAU,CAAC,gBAAgB,EAAC,qDAAqD,CAAC,CAAC;QACzH,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC;QAChB,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;IAChC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,CAAC,QAAkB,EAAE,IAAa;IAC9D,IAAI,QAA6B,CAAC;IAClC,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAC,EAAC,MAAM,EAAC,MAAM,EAAC,OAAO,EAAC,EAAC,aAAa,EAAC,UAAU,QAAQ,CAAC,KAAK,EAAE,EAAC,cAAc,EAAC,kBAAkB,EAAC,EAAC,IAAI,EAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAC,CAAC,CAAC;IACtK,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,UAAU,CAAC,yBAAyB,EAAC,qFAAqF,CAAC,CAAC;IAAC,CAAC;IAClJ,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;QAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,EAAC,uCAAuC,CAAC,CAAC;IAC5H,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAC,EAAC,MAAM,EAAC,IAAI,EAAC,CAAC,CAAC;YAC9C,IAAI,OAAO,CAAC;YACZ,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAC,OAAO,CAAC,CAAC;gBAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;gBACzE,IAAI,IAAI;oBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAiB,CAAC;YACnD,CAAC;QACH,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QAC3B,IAAI,MAAM,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,UAAU,CAAC,yBAAyB,EAAC,8FAA8F,CAAC,CAAC;IACjJ,CAAC;AACH,CAAC","sourcesContent":["import { spawn } from 'node:child_process';\nimport { open, unlink } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { setTimeout as delay } from 'node:timers/promises';\nimport { AgentError } from '../errors.js';\nimport type { OutputRecord } from '../cli/output.js';\nimport { type Endpoint, localProgram, privateDirectory, readEndpoint, stateDirectory, removeStaleStartupLock } from './state.js';\n\ninterface ConnectionOptions { directory?: string; timeoutMs?: number }\n\nexport async function connect(start: boolean, options: ConnectionOptions = {}): Promise<Endpoint> {\n  const directory = options.directory ?? stateDirectory();\n  const available = await readEndpoint(directory);\n  if (available) return available;\n  if (!start) throw new AgentError('UNKNOWN_SESSION','No coordinator is reachable from this environment. Its sessions may have ended, or native permissions may block access to its local endpoint.');\n  await privateDirectory(directory);\n  const lock = join(directory,'startup.lock');\n  const deadline = Date.now() + (options.timeoutMs ?? 15_000);\n  for (;;) {\n    let owner;\n    try { owner = await open(lock,'wx',0o600); }\n    catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;\n      await removeStaleStartupLock(lock);\n    }\n    if (owner) {\n      try {\n        await owner.writeFile(String(process.pid)); await owner.close();\n        const existing = await readEndpoint(directory);\n        if (existing) return existing;\n        const program = localProgram('daemon');\n        const child = spawn(process.execPath,[...program.execArgv,program.file],{detached:true,stdio:'ignore',env:{...process.env,AGENT_STATE_DIR:directory}});\n        let spawnError = false;\n        child.once('error',()=>{spawnError=true;}); child.unref();\n        while (Date.now() < deadline && !spawnError) {\n          await delay(50);\n          const endpoint = await readEndpoint(directory);\n          if (endpoint) return endpoint;\n        }\n        throw new AgentError('STARTUP_FAILED','The local coordinator could not start.');\n      } finally { await owner.close().catch(()=>{}); await unlink(lock).catch(()=>{}); }\n    }\n    if (Date.now() >= deadline) throw new AgentError('STARTUP_FAILED','Another command did not finish coordinator startup.');\n    await delay(50);\n    const endpoint = await readEndpoint(directory);\n    if (endpoint) return endpoint;\n  }\n}\n\nexport async function* request(endpoint: Endpoint, body: unknown): AsyncGenerator<OutputRecord> {\n  let response: globalThis.Response;\n  try {\n    response = await fetch(endpoint.url,{method:'POST',headers:{authorization:`Bearer ${endpoint.token}`,'content-type':'application/json'},body:JSON.stringify(body)});\n  } catch { throw new AgentError('COORDINATOR_UNAVAILABLE','Connection to the local coordinator failed. The task was not automatically retried.'); }\n  if (!response.ok || !response.body) throw new AgentError('COORDINATOR_UNAVAILABLE','The coordinator rejected the request.');\n  let buffer = '';\n  const decoder = new TextDecoder();\n  try {\n    for await (const chunk of response.body) {\n      buffer += decoder.decode(chunk,{stream:true});\n      let newline;\n      while ((newline = buffer.indexOf('\\n')) >= 0) {\n        const line = buffer.slice(0,newline); buffer = buffer.slice(newline + 1);\n        if (line) yield JSON.parse(line) as OutputRecord;\n      }\n    }\n    buffer += decoder.decode();\n    if (buffer.trim()) throw new Error('Incomplete response record');\n  } catch {\n    throw new AgentError('COORDINATOR_UNAVAILABLE','The coordinator response was interrupted or invalid. The task was not automatically retried.');\n  }\n}\n"]}

package/dist/runtime/coordinator.d.ts

@@ -0,0 +1,61 @@
+import { type DriverFactory, type Observation, type Receipt, type SessionInput, type Delivery } from './types.js';
+export declare class Coordinator {
+    private readonly factory;
+    private sessions;
+    private tasks;
+    constructor(factory: DriverFactory);
+    parentContext(token: string): {
+        taskId: string;
+        reference: import("./types.js").ExecutionReference;
+        cwd: string;
+    };
+    run(input: SessionInput): Receipt;
+    send(id: string, prompt: string, delivery: Delivery, parentToken?: string): Promise<Receipt>;
+    observe(id: string, after?: string, readerToken?: string, signal?: AbortSignal): Promise<Observation>;
+    private acknowledge;
+    status(id: string, full?: boolean): {
+        version: number;
+        type: string;
+        taskId: string;
+        sessionId: string;
+        state: import("./types.js").TaskState;
+        error?: import("../errors.js").ErrorInfo | undefined;
+        response?: {
+            responseId: string;
+            text: string;
+            truncated: boolean;
+        } | undefined;
+    };
+    queue(id: string): {
+        version: number;
+        type: string;
+        sessionId: string;
+        paused: boolean;
+        active?: {
+            taskId: string;
+            state: import("./types.js").TaskState;
+            description: string;
+        } | undefined;
+        tasks: {
+            taskId: string;
+            state: import("./types.js").TaskState;
+            description: string;
+        }[];
+    };
+    resume(id: string): Promise<Receipt>;
+    close(): Promise<void>;
+    cancel(id: string): Promise<Receipt>;
+    private command;
+    private stop;
+    private finishStop;
+    private admit;
+    private validateAdmission;
+    private dispatch;
+    private execute;
+    private pending;
+    private deliver;
+    private continueParent;
+    private notify;
+    private task;
+    private session;
+}

package/dist/runtime/coordinator.js

@@ -0,0 +1,296 @@
+import { randomUUID } from 'node:crypto';
+import { waitForChange } from './observation.js';
+import { AgentError, errorInfo } from '../errors.js';
+import { terminal } from './types.js';
+export class Coordinator {
+    factory;
+    sessions = new Map();
+    tasks = new Map();
+    constructor(factory) {
+        this.factory = factory;
+    }
+    parentContext(token) {
+        const session = [...this.sessions.values()].find(session => session.token === token);
+        const task = session?.active ? this.task(session.active) : undefined;
+        if (!session || !task || task.stopping || terminal(task.state))
+            throw new AgentError('INVALID_PARENT', 'The parent context is no longer active.');
+        return { taskId: task.id, reference: session.input.reference, cwd: session.input.cwd };
+    }
+    run(input) {
+        this.validateAdmission(undefined, input.prompt, input.parentToken);
+        const session = { id: `ses_${randomUUID()}`, token: randomUUID(), input,
+            tasks: [], paused: false, commands: Promise.resolve(), controls: 0 };
+        this.sessions.set(session.id, session);
+        return this.admit(session, input.prompt, false, input.parentToken);
+    }
+    async send(id, prompt, delivery, parentToken) {
+        const session = this.session(id);
+        const operation = async () => {
+            if (!['queue', 'steer', 'interrupt'].includes(delivery))
+                throw new AgentError('INVALID_ARGUMENT', 'Unknown delivery mode.');
+            this.validateAdmission(session, prompt, parentToken, delivery !== 'queue');
+            if (delivery === 'queue')
+                return this.admit(session, prompt, false, parentToken);
+            const task = session.active ? this.task(session.active) : undefined;
+            if (delivery === 'steer') {
+                if (!task || terminal(task.state) || task.stopping)
+                    throw new AgentError('NO_ACTIVE_TASK', 'There is no active task accepting steering.');
+                if (!task.nativeActive) {
+                    void this.execute(task, prompt);
+                    return { version: 1, type: 'accepted', sessionId: id, taskId: task.id, delivery: 'steer' };
+                }
+                try {
+                    await (await session.driver).steer(prompt);
+                    return { version: 1, type: 'accepted', sessionId: id, taskId: task.id, delivery: 'steer' };
+                }
+                catch (error) {
+                    if (!(error instanceof AgentError) || error.code !== 'UNSUPPORTED_DELIVERY')
+                        throw error;
+                }
+            }
+            if (task && (!terminal(task.state) || task.stopUnconfirmed || task.state === 'failed'))
+                await this.stop(task, 'interrupted');
+            session.paused = false;
+            const receipt = this.admit(session, prompt, true, parentToken);
+            return { ...receipt, requestedDelivery: delivery, delivery: 'interrupt' };
+        };
+        return this.command(session, operation);
+    }
+    async observe(id, after, readerToken, signal) {
+        const task = this.task(id);
+        const position = after ? task.responses.findIndex(response => response.responseId === after) : -1;
+        if (after && position === -1)
+            throw new AgentError('UNKNOWN_RESPONSE', 'The response does not belong to this task.');
+        for (;;) {
+            const response = task.responses[position + 1];
+            if (response) {
+                if (terminal(response.state))
+                    this.acknowledge(task, readerToken);
+                return response;
+            }
+            if (terminal(task.state)) {
+                this.acknowledge(task, readerToken);
+                return { version: 1, type: 'terminal', taskId: id,
+                    sessionId: task.sessionId, state: task.state, ...(task.error ? { error: task.error } : {}) };
+            }
+            await waitForChange(task.changed, signal);
+        }
+    }
+    acknowledge(task, readerToken) {
+        if (!readerToken || !task.parentId || task.stopUnconfirmed)
+            return;
+        const parent = this.task(task.parentId);
+        if (this.session(parent.sessionId).token === readerToken && parent.nativeActive)
+            parent.inbox = parent.inbox.filter(result => result.taskId !== task.id);
+    }
+    status(id, full = false) {
+        const task = this.task(id), response = task.responses.at(-1);
+        return { version: 1, type: 'status', taskId: id, sessionId: task.sessionId, state: task.state,
+            ...(task.error ? { error: task.error } : {}), ...(response ? { response: {
+                    responseId: response.responseId, text: full ? response.text : response.text.slice(0, 4000),
+                    truncated: !full && response.text.length > 4000
+                } } : {}) };
+    }
+    queue(id) {
+        const session = this.session(id);
+        const summary = (task) => ({ taskId: task.id, state: task.state, description: task.prompt.slice(0, 120) });
+        return { version: 1, type: 'queue', sessionId: id, paused: session.paused,
+            ...(session.active ? { active: summary(this.task(session.active)) } : {}),
+            tasks: session.tasks.map(id => summary(this.task(id))) };
+    }
+    async resume(id) {
+        const session = this.session(id);
+        return this.command(session, async () => {
+            const task = session.active ? this.task(session.active) : undefined;
+            if (!task || task.state !== 'failed')
+                throw new AgentError('NOT_FAILED', 'This session has no failed task to resume.');
+            if (task.stopUnconfirmed || task.stopPromise)
+                throw new AgentError('CANCEL_FAILED', 'Confirm cancellation of the affected executions before recovery.');
+            task.stopping = false;
+            task.error = undefined;
+            session.paused = false;
+            void this.execute(task, '', true);
+            return { version: 1, type: 'started', sessionId: id, taskId: task.id, state: task.state, resumed: true };
+        });
+    }
+    async close() {
+        await Promise.allSettled([...this.sessions.values()].map(async (session) => (await session.driver)?.close()));
+    }
+    async cancel(id) {
+        const task = this.task(id);
+        return this.command(this.session(task.sessionId), async () => {
+            if (!terminal(task.state) || task.stopUnconfirmed)
+                await this.stop(task, 'cancelled');
+            else if (task.state === 'failed') {
+                const session = this.session(task.sessionId);
+                if (session.active === task.id) {
+                    session.active = undefined;
+                    session.paused = false;
+                }
+            }
+            return { version: 1, type: 'cancelled', taskId: id, sessionId: task.sessionId, state: task.state };
+        });
+    }
+    command(session, operation) {
+        session.controls++;
+        const result = session.commands.then(operation, operation).finally(() => {
+            session.controls--;
+            this.dispatch(session);
+        });
+        session.commands = result.catch(() => undefined);
+        return result;
+    }
+    stop(task, outcome) {
+        if (task.stopPromise)
+            return task.stopPromise;
+        task.stopPromise = this.finishStop(task, outcome).finally(() => {
+            task.stopPromise = undefined;
+            this.dispatch(this.session(task.sessionId));
+        });
+        return task.stopPromise;
+    }
+    async finishStop(task, outcome) {
+        const session = this.session(task.sessionId);
+        task.stopping = true;
+        session.tasks = session.tasks.filter(id => id !== task.id);
+        try {
+            const stops = [...task.children].map(id => this.task(id)).filter(child => !terminal(child.state) || child.stopUnconfirmed).map(child => this.stop(child, 'cancelled'));
+            if (task.nativeActive && session.driver)
+                stops.push(session.driver.then(async (driver) => {
+                    await driver.interrupt();
+                    task.nativeActive = false;
+                }));
+            const outcomes = await Promise.allSettled(stops);
+            if (outcomes.some(outcome => outcome.status === 'rejected'))
+                throw new Error('Cancellation unconfirmed');
+        }
+        catch {
+            task.state = 'failed';
+            task.error = { code: 'CANCEL_FAILED', message: 'Native execution could not be confirmed stopped.' };
+            task.stopUnconfirmed = true;
+            session.paused = true;
+            this.notify(task);
+            throw new AgentError('CANCEL_FAILED', task.error.message);
+        }
+        task.nativeActive = false;
+        task.state = outcome;
+        task.stopUnconfirmed = false;
+        task.error = undefined;
+        if (session.active === task.id) {
+            session.active = undefined;
+            session.paused = false;
+        }
+        this.notify(task);
+        this.deliver(task);
+    }
+    admit(session, prompt, front = false, parentToken) {
+        const parent = this.validateAdmission(session, prompt, parentToken, front);
+        const task = { id: `tsk_${randomUUID()}`, sessionId: session.id, prompt,
+            parentId: parent?.id, state: 'queued', responses: [], children: new Set(), inbox: [], nativeActive: false, stopping: false, changed: new Set() };
+        this.tasks.set(task.id, task);
+        parent?.children.add(task.id);
+        if (front)
+            session.tasks.unshift(task.id);
+        else
+            session.tasks.push(task.id);
+        this.dispatch(session);
+        return { version: 1, type: 'started', sessionId: session.id, taskId: task.id, state: task.state };
+    }
+    validateAdmission(session, prompt, parentToken, replacement = false) {
+        if (typeof prompt !== 'string' || !prompt.trim() || Buffer.byteLength(prompt) > 1024 * 1024)
+            throw new AgentError('INVALID_ARGUMENT', 'Prompt must contain text and cannot exceed 1 MiB.');
+        if (!replacement && session && session.tasks.length >= 100)
+            throw new AgentError('QUEUE_FULL', 'The session already has 100 queued tasks.');
+        const parent = parentToken ? this.task(this.parentContext(parentToken).taskId) : undefined;
+        let depth = 0, ancestor = parent;
+        while (ancestor) {
+            if (ancestor.sessionId === session?.id)
+                throw new AgentError('INVALID_PARENT', 'A managed task cannot queue work in its own or an ancestor session.');
+            depth++;
+            ancestor = ancestor.parentId ? this.task(ancestor.parentId) : undefined;
+        }
+        if (depth > 8)
+            throw new AgentError('DELEGATION_LIMIT', 'Maximum delegation depth is 8.');
+        return parent;
+    }
+    dispatch(session) {
+        if (session.active || session.paused || session.controls)
+            return;
+        const id = session.tasks.shift();
+        if (!id)
+            return;
+        session.active = id;
+        void this.execute(this.task(id), this.task(id).prompt);
+    }
+    async execute(task, prompt, recovering = false) {
+        const session = this.session(task.sessionId);
+        task.state = 'running';
+        task.nativeActive = true;
+        try {
+            session.driver ??= this.factory({ ...session.input, sessionId: session.id, token: session.token });
+            const driver = await session.driver;
+            if (task.stopping)
+                return;
+            const text = recovering ? await driver.resume() : await driver.turn(prompt);
+            if (task.stopping)
+                return;
+            if (Buffer.byteLength(text) > 1024 * 1024)
+                throw new AgentError('OUTPUT_TOO_LARGE', 'The response exceeds 1 MiB.');
+            task.nativeActive = false;
+            task.state = this.pending(task) ? 'waiting' : 'completed';
+            task.responses.push({ version: 1, type: 'response', sessionId: session.id, taskId: task.id,
+                responseId: `rsp_${randomUUID()}`, state: task.state, text });
+            this.notify(task);
+            if (task.state === 'completed') {
+                session.active = undefined;
+                this.deliver(task);
+                this.dispatch(session);
+            }
+            else
+                this.continueParent(task);
+        }
+        catch (error) {
+            if (task.stopping)
+                return;
+            task.nativeActive = false;
+            task.stopping = true;
+            const stopped = await Promise.allSettled([...task.children].map(id => this.task(id)).filter(child => !terminal(child.state) || child.stopUnconfirmed).map(child => this.stop(child, 'cancelled')));
+            task.stopUnconfirmed = stopped.some(result => result.status === 'rejected');
+            task.state = 'failed';
+            task.error = task.stopUnconfirmed
+                ? { code: 'CANCEL_FAILED', message: 'Descendant execution could not be confirmed stopped.' } : errorInfo(error);
+            session.paused = true;
+            this.notify(task);
+            this.deliver(task);
+        }
+    }
+    pending(task) {
+        return task.inbox.length > 0 || [...task.children].some(id => !terminal(this.task(id).state) || this.task(id).stopUnconfirmed);
+    }
+    deliver(child) {
+        if (!child.parentId || child.stopUnconfirmed)
+            return;
+        const parent = this.task(child.parentId);
+        if (parent.stopping || terminal(parent.state))
+            return;
+        parent.inbox.push({ taskId: child.id, state: child.state,
+            text: child.error?.message ?? child.responses.at(-1)?.text ?? child.state });
+        // Let an attached child command acknowledge delivery through its native tool output first.
+        setImmediate(() => this.continueParent(parent));
+    }
+    continueParent(task) {
+        if (task.nativeActive || task.stopping || terminal(task.state) || !task.inbox.length)
+            return;
+        const results = task.inbox.splice(0);
+        const prompt = 'Delegated task outcomes (continue the current task):\n' +
+            results.map(result => `${result.taskId} [${result.state}]:\n${result.text}`).join('\n\n');
+        void this.execute(task, prompt);
+    }
+    notify(task) { for (const resolve of task.changed)
+        resolve(); task.changed.clear(); }
+    task(id) { const task = this.tasks.get(id); if (!task)
+        throw new AgentError('UNKNOWN_TASK', 'Task is unavailable in this coordinator.'); return task; }
+    session(id) { const session = this.sessions.get(id); if (!session)
+        throw new AgentError('UNKNOWN_SESSION', 'Session is unavailable in this coordinator.'); return session; }
+}
+//# sourceMappingURL=coordinator.js.map