@automatalabs/acp-agents 0.1.0

package/dist/runner.js

@@ -0,0 +1,211 @@
+// AcpAgentRunner — the AgentRunner seam implementation (the LEAF the engine injects against).
+// One method, two backend strategies behind it. Per run():
+//   1. pick the backend by model/tier (cross-provider routing = which ACP server to spawn)
+//   2. ACQUIRE a pooled connection + session/new { cwd } (per-session cwd = worktree isolation;
+//      the PROCESS is pool-managed and REUSED across runs — never spawned/killed per run)
+//   3. select the model via session/set_config_option (onModelResolved / onModelFallback)
+//   4. apply the schema per backend (Claude: at session/new; Codex: per-turn _meta)
+//   5. prompt + drain; enforce the tool allow/deny policy via permission auto-responses
+//   6. schema  -> native -> validate -> re-prompt ladder -> SCHEMA_NONCOMPLIANCE
+//      no schema -> final assistant text (empty -> AGENT_EMPTY_OUTPUT, recoverable)
+//      provider wall (thrown) -> PROVIDER_USAGE_LIMIT (non-recoverable, resetHint)
+//      pooled process crash (thrown) -> recoverable AGENT_EXECUTION_ERROR (engine retries on a
+//        fresh process; the dead connection is evicted from the pool)
+//   7. usage -> onUsage on BOTH the success and error paths; honor opts.signal (-> session/cancel)
+//   8. RELEASE the session (session/close) WITHOUT killing the process; return it to the pool
+//
+// Timeout and abort are the ENGINE's job: we honor opts.signal (wired to ACP session/cancel)
+// and re-throw on abort, but never implement our own timeout.
+import { WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
+import { AcpAgentPool } from "./pool.js";
+import { ClaudeBackend } from "./backends/claude.js";
+import { CodexBackend } from "./backends/codex.js";
+import { mapThrownError } from "./errors-map.js";
+import { resolveStructuredOutput } from "./structured-output.js";
+export class AcpAgentRunner {
+    pool;
+    constructor(options = {}) {
+        this.pool = new AcpAgentPool(options);
+    }
+    async run(prompt, options = {}) {
+        const opts = options;
+        const schema = opts.schema;
+        const backend = selectBackend(opts);
+        const policy = { allow: opts.toolNames, deny: opts.disallowedToolNames };
+        const cwd = opts.cwd ?? process.cwd();
+        const session = await this.pool.acquire(backend, {
+            cwd,
+            schema,
+            policy,
+            signal: opts.signal,
+            mcpServers: opts.mcpServers,
+            // Engine correlation id -> session/new _meta (META_KEYS.runId). Additive; never hashed.
+            runId: opts.runId,
+        });
+        try {
+            opts.signal?.throwIfAborted();
+            await applyModelSelection(session, opts);
+            const text = buildPrompt(prompt, opts, Boolean(schema));
+            const promptMeta = backend.promptMeta(schema);
+            const response = await session.prompt(text, promptMeta);
+            opts.signal?.throwIfAborted();
+            // Inspect the turn's stop reason BEFORE the text/schema path: a refusal or truncation
+            // must surface distinctly here, never be misread as empty output or burned through the
+            // schema-repair ladder into SCHEMA_NONCOMPLIANCE.
+            assertNormalStopReason(response.stopReason, opts.label);
+            if (schema) {
+                const structuredSession = {
+                    prompt: async (repromptText) => {
+                        const repromptResponse = await session.prompt(repromptText, promptMeta);
+                        // A repair turn that refuses / truncates / cancels must also surface distinctly
+                        // instead of silently continuing the ladder.
+                        assertNormalStopReason(repromptResponse.stopReason, opts.label);
+                    },
+                    lastText: () => session.currentTurnText(),
+                    tryNative: () => backend.nativeStructured(session),
+                };
+                const result = await resolveStructuredOutput(structuredSession, schema, {
+                    maxSchemaRetries: opts.maxSchemaRetries,
+                    signal: opts.signal,
+                    label: opts.label,
+                });
+                return result;
+            }
+            const finalText = session.currentTurnText().trim();
+            if (!finalText) {
+                throw new WorkflowError("Subagent produced no assistant output", WorkflowErrorCode.AGENT_EMPTY_OUTPUT, {
+                    recoverable: true,
+                    agentLabel: opts.label,
+                });
+            }
+            return finalText;
+        }
+        catch (error) {
+            // Abort is the engine's concern (throwIfAborted before/after the call) — re-throw it raw.
+            if (opts.signal?.aborted)
+                throw error;
+            throw mapThrownError(error, opts.label);
+        }
+        finally {
+            // Read real usage on BOTH success and error so partial usage is never lost.
+            try {
+                opts.onUsage?.(session.usage.toAgentUsage());
+            }
+            catch {
+                // usage is best-effort; never let it mask the real result/error.
+            }
+            try {
+                opts.onHistory?.(session.history);
+            }
+            catch {
+                // history is diagnostic only.
+            }
+            // Release the SESSION (best-effort session/close) WITHOUT killing the pooled process.
+            try {
+                await session.release();
+            }
+            catch {
+                // release is best-effort (session already untracked); never mask the real result/error.
+            }
+        }
+    }
+    /** Tear down the whole pool (close every long-lived process). Call when the run ends / the
+     *  runner is disposed. Beyond the AgentRunner seam (additive) — never enters the resume hash. */
+    async dispose() {
+        await this.pool.dispose();
+    }
+}
+/** Factory the mcp-server composition root calls to inject the runner into the engine. The pool
+ *  size is a runner-level option (default 1, else AGENTPRISM_ACP_POOL_SIZE) — NOT a RunOptions
+ *  field, so it never enters hashAgentCall / the resume identity. */
+export function createAcpRunner(options) {
+    return new AcpAgentRunner(options);
+}
+/**
+ * Map a PromptResponse.stopReason onto the seam's error contract. `end_turn` (and any
+ * unknown future reason) is a normal completion — fall through to the text/schema path.
+ * The abnormal reasons each get a DISTINCT, non-recoverable failure so the engine never
+ * retries a refused/truncated prompt (burning the retry budget) and never mistakes it for
+ * recoverable empty output:
+ *   - refusal             -> AGENT_EXECUTION_ERROR "model refused to respond"
+ *   - max_tokens / max_turn_requests -> AGENT_EXECUTION_ERROR "output truncated"
+ *   - cancelled           -> WORKFLOW_ABORTED
+ */
+function assertNormalStopReason(stopReason, label) {
+    switch (stopReason) {
+        case "refusal":
+            throw new WorkflowError("model refused to respond", WorkflowErrorCode.AGENT_EXECUTION_ERROR, {
+                recoverable: false,
+                agentLabel: label,
+            });
+        case "max_tokens":
+        case "max_turn_requests":
+            throw new WorkflowError(`output truncated (stop reason: ${stopReason})`, WorkflowErrorCode.AGENT_EXECUTION_ERROR, { recoverable: false, agentLabel: label });
+        case "cancelled":
+            throw new WorkflowError("workflow aborted", WorkflowErrorCode.WORKFLOW_ABORTED, {
+                recoverable: false,
+                agentLabel: label,
+            });
+        default:
+            // "end_turn" and any unrecognized future reason: normal completion.
+            return;
+    }
+}
+async function applyModelSelection(session, opts) {
+    // `model` wins; `tier` is consulted only when `model` is unset (frozen contract).
+    const spec = opts.model ?? opts.tier;
+    if (!spec)
+        return;
+    const { matched, resolved, modifierFallbacks } = await session.selectModel(spec);
+    if (matched)
+        opts.onModelResolved?.(resolved ?? spec);
+    else
+        opts.onModelFallback?.(spec);
+    // Symmetric to model fallback: a requested reasoning_effort / Fast-mode value the catalog
+    // does not advertise is a silent no-op in the session. Surface it on the SAME channel so
+    // incorrect tiering is observable (best-effort — reported, never thrown).
+    for (const fallback of modifierFallbacks ?? [])
+        opts.onModelFallback?.(fallback);
+}
+function buildPrompt(prompt, opts, structured) {
+    const parts = [];
+    if (opts.instructions)
+        parts.push(opts.instructions);
+    if (opts.label)
+        parts.push(`Task label: ${opts.label}`);
+    parts.push(prompt);
+    if (structured) {
+        parts.push([
+            "Final output contract:",
+            "- Your FINAL message MUST be a single JSON object that conforms to the required output schema.",
+            "- Output ONLY that JSON object — no prose, no explanation, and no markdown code fences.",
+            "- If you need to inspect files or run commands first, do so, then emit the JSON object as your final message.",
+        ].join("\n"));
+    }
+    return parts.join("\n\n");
+}
+/** Pick the backend by model/tier. Cross-provider routing = which ACP server to spawn. */
+export function selectBackend(opts) {
+    const id = backendIdForSpec(opts.model) ?? backendIdForSpec(opts.tier) ?? defaultBackendId();
+    return id === "codex" ? new CodexBackend() : new ClaudeBackend();
+}
+function backendIdForSpec(spec) {
+    if (!spec)
+        return undefined;
+    const lower = spec.toLowerCase();
+    const slash = lower.indexOf("/");
+    const provider = slash > 0 ? lower.slice(0, slash) : "";
+    if (provider === "openai" || provider === "codex")
+        return "codex";
+    if (provider === "anthropic" || provider === "claude")
+        return "claude";
+    const id = slash > 0 ? lower.slice(slash + 1) : lower;
+    if (/codex|gpt|openai|\bo\d/.test(id))
+        return "codex";
+    if (/claude|opus|sonnet|haiku|anthropic/.test(id))
+        return "claude";
+    return undefined;
+}
+function defaultBackendId() {
+    return process.env.AGENTPRISM_DEFAULT_BACKEND?.toLowerCase() === "codex" ? "codex" : "claude";
+}

package/dist/schema-strict.d.ts

@@ -0,0 +1,11 @@
+import type { TSchema } from "typebox";
+/** Deep-clone a typebox schema into a plain JSON Schema object (Claude `outputFormat.schema`). */
+export declare function toJsonSchema(schema: TSchema): Record<string, unknown>;
+/**
+ * Deep-clone a typebox schema and normalize it to OpenAI STRICT rules (Codex
+ * `turn/start.outputSchema`): every property required, additionalProperties:false,
+ * unsupported validation keywords stripped. Operates on the clone only — the schema that
+ * feeds hashAgentCall is never mutated.
+ */
+export declare function toStrictJsonSchema(schema: TSchema): Record<string, unknown>;
+//# sourceMappingURL=schema-strict.d.ts.map

package/dist/schema-strict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-strict.d.ts","sourceRoot":"","sources":["../src/schema-strict.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AA6LD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG3E"}

package/dist/schema-strict.js

@@ -0,0 +1,189 @@
+/** Deep-clone a typebox schema into a plain JSON Schema object (Claude `outputFormat.schema`). */
+export function toJsonSchema(schema) {
+    return JSON.parse(JSON.stringify(schema));
+}
+// JSON-Schema keywords OpenAI strict structured output does NOT accept. Stripped on the
+// COPY before sending to Codex (turn/start.outputSchema is sent in strict mode). Structural
+// keywords (type/properties/items/enum/anyOf/oneOf/allOf/$ref/$defs/definitions/const/
+// description/required/additionalProperties) are preserved.
+const STRICT_UNSUPPORTED_KEYWORDS = new Set([
+    "$schema",
+    "$id",
+    "title",
+    "default",
+    "examples",
+    "format",
+    "pattern",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "minContains",
+    "maxContains",
+    "minProperties",
+    "maxProperties",
+    "contentEncoding",
+    "contentMediaType",
+    "patternProperties",
+    "additionalItems",
+    "unevaluatedProperties",
+    "unevaluatedItems",
+    "dependencies",
+    "dependentRequired",
+    "dependentSchemas",
+    "propertyNames",
+    "readOnly",
+    "writeOnly",
+    "deprecated",
+]);
+function normalizeStrictNode(node) {
+    if (Array.isArray(node))
+        return node.map(normalizeStrictNode);
+    if (node === null || typeof node !== "object")
+        return node;
+    // OpenAI strict rejects `allOf` (composition). Flatten the trivial object-merge case;
+    // anything non-trivial throws a clear schema error rather than silently shipping invalid
+    // strict schema. Flattening happens BEFORE keyword processing so the merged node then
+    // takes the normal object-schema path below.
+    let input = node;
+    if (input["allOf"] !== undefined) {
+        input = flattenAllOf(input);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (STRICT_UNSUPPORTED_KEYWORDS.has(key))
+            continue;
+        // OpenAI strict accepts `anyOf` but not `oneOf` — map it over (its branches are an
+        // exclusive subset of anyOf, so this only widens acceptance, never the validated set
+        // beyond what the client-side typebox Check re-narrows).
+        const targetKey = key === "oneOf" ? "anyOf" : key;
+        out[targetKey] = normalizeStrictNode(value);
+    }
+    // OpenAI strict rule: every object must set additionalProperties:false and list EVERY
+    // property in `required`. Treat a node as an object schema when it declares properties
+    // (type may be "object" or omitted by some generators).
+    const properties = out["properties"];
+    const isObjectSchema = out["type"] === "object" || (out["type"] === undefined && properties !== undefined);
+    if (isObjectSchema && properties !== null && typeof properties === "object") {
+        const propObj = properties;
+        const keys = Object.keys(propObj);
+        // Forcing all-required would make originally-OPTIONAL props un-omittable. Keep them
+        // expressible by unioning their type with "null" — the model may emit null for "absent".
+        // Optionality is read from the node's ORIGINAL `required` (before we overwrite it).
+        const originallyRequired = new Set(toStringArray(input["required"]));
+        for (const key of keys) {
+            if (!originallyRequired.has(key))
+                propObj[key] = makeNullable(propObj[key]);
+        }
+        out["additionalProperties"] = false;
+        out["required"] = keys;
+    }
+    return out;
+}
+/** Pick out the string members of a JSON-Schema `required` array (tolerating junk). */
+function toStringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+/**
+ * Make a (already strict-normalized) property schema accept `null`, so an originally-optional
+ * field stays expressible once strict mode forces it into `required`:
+ *   - a union (`anyOf`): add a `{ type: "null" }` branch if absent;
+ *   - a string `type`: widen to `[type, "null"]`;
+ *   - an array `type`: append "null" if absent;
+ *   - anything else (a bare `$ref`, an empty schema, etc.): wrap in `anyOf:[schema,{null}]`.
+ */
+function makeNullable(schema) {
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const node = schema;
+    if (Array.isArray(node["anyOf"])) {
+        const branches = node["anyOf"];
+        if (!branches.some(isNullTypeSchema))
+            branches.push({ type: "null" });
+        return node;
+    }
+    const type = node["type"];
+    if (typeof type === "string") {
+        if (type !== "null")
+            node["type"] = [type, "null"];
+        return node;
+    }
+    if (Array.isArray(type)) {
+        if (!type.includes("null"))
+            type.push("null");
+        return node;
+    }
+    // No `type` and no `anyOf` to widen (e.g. a bare `$ref`): wrap it in a nullable union.
+    return { anyOf: [node, { type: "null" }] };
+}
+function isNullTypeSchema(node) {
+    return (node !== null && typeof node === "object" && node["type"] === "null");
+}
+/**
+ * Flatten an `allOf` node into a single object schema for OpenAI strict mode (which rejects
+ * `allOf`). Only the TRIVIAL case is supported: every member (plus any sibling keywords on the
+ * node itself) is an object schema, so their `properties`/`required` merge into one object.
+ * Any member that is a non-object schema (a scalar/array constraint, a `$ref`, etc.) cannot be
+ * trivially merged and throws a clear error — the caller must rewrite the schema without
+ * `allOf` for strict structured output.
+ */
+function flattenAllOf(node) {
+    const allOf = node["allOf"];
+    if (!Array.isArray(allOf)) {
+        throw new Error('OpenAI strict schema: "allOf" must be an array to be flattened.');
+    }
+    const { allOf: _drop, ...siblings } = node;
+    const parts = [siblings, ...allOf];
+    const mergedProps = {};
+    const mergedRequired = [];
+    const merged = {};
+    let sawProperties = false;
+    for (const part of parts) {
+        if (part === null || typeof part !== "object" || Array.isArray(part)) {
+            throw new Error('OpenAI strict schema: cannot flatten an "allOf" whose member is not an object schema.');
+        }
+        let p = part;
+        if (p["allOf"] !== undefined)
+            p = flattenAllOf(p); // recurse into nested allOf first
+        const props = p["properties"];
+        const hasProps = props !== null && typeof props === "object" && !Array.isArray(props);
+        const type = p["type"];
+        const objectLike = hasProps || type === "object" || type === undefined;
+        if (!objectLike) {
+            throw new Error(`OpenAI strict schema: cannot flatten "allOf" containing a non-object subschema (type: ${JSON.stringify(type)}); rewrite the schema without allOf for strict structured output.`);
+        }
+        if (hasProps) {
+            sawProperties = true;
+            Object.assign(mergedProps, props);
+        }
+        mergedRequired.push(...toStringArray(p["required"]));
+        for (const [key, value] of Object.entries(p)) {
+            if (key === "properties" || key === "required" || key === "type")
+                continue;
+            merged[key] = value;
+        }
+    }
+    if (!sawProperties) {
+        throw new Error('OpenAI strict schema: "allOf" had no object subschemas to flatten.');
+    }
+    merged["type"] = "object";
+    merged["properties"] = mergedProps;
+    merged["required"] = [...new Set(mergedRequired)];
+    return merged;
+}
+/**
+ * Deep-clone a typebox schema and normalize it to OpenAI STRICT rules (Codex
+ * `turn/start.outputSchema`): every property required, additionalProperties:false,
+ * unsupported validation keywords stripped. Operates on the clone only — the schema that
+ * feeds hashAgentCall is never mutated.
+ */
+export function toStrictJsonSchema(schema) {
+    const clone = JSON.parse(JSON.stringify(schema));
+    return normalizeStrictNode(clone);
+}

package/dist/structured-output.d.ts

@@ -0,0 +1,37 @@
+import type { TSchema } from "typebox";
+/**
+ * Find a JSON object/array in free-form text: a fenced ```json block if present, else the
+ * first balanced {...} or [...]. Best-effort (the schema check is the real gate). Returns the
+ * raw JSON string, or undefined when none is found. (Ported VERBATIM from pi agent.ts.)
+ */
+export declare function findJsonBlock(text: string): string | undefined;
+/** Coerce an already-parsed value toward the schema and accept it only if it then validates. */
+export declare function validateValue(value: unknown, schema: TSchema): unknown;
+/**
+ * Last-resort structured-output recovery: extract a JSON block from prose, coerce it toward
+ * the schema, and accept it only if it then validates. Never fabricates — returns undefined
+ * unless the parsed value genuinely satisfies the schema. (Ported VERBATIM from pi agent.ts.)
+ */
+export declare function extractValidated(text: string, schema: TSchema): unknown;
+/** Minimal session surface the structured-output ladder needs (real ACP session or a test double). */
+export interface StructuredSession {
+    /** Send one more (re-prompt) turn and drain it. */
+    prompt(text: string): Promise<void>;
+    /** The latest turn's assistant text (for prose extraction). */
+    lastText(): string;
+    /** The backend's native structured result for the latest turn (unvalidated), or undefined. */
+    tryNative(): unknown;
+}
+export interface ResolveOptions {
+    /** Extra repair turns before giving up. Leaf default 2 (matches pi). */
+    maxSchemaRetries?: number;
+    signal?: AbortSignal;
+    label?: string;
+}
+/**
+ * Resolve a schema agent's result via the ladder above. Returns the validated value (typed
+ * unknown at this layer; the caller casts to the seam's AgentResult<S>). Throws
+ * SCHEMA_NONCOMPLIANCE (non-recoverable) when no valid value is produced after the retries.
+ */
+export declare function resolveStructuredOutput(session: StructuredSession, schema: TSchema, options: ResolveOptions): Promise<unknown>;
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIvC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAa9D;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAQtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAUvE;AAED,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,+DAA+D;IAC/D,QAAQ,IAAI,MAAM,CAAC;IACnB,8FAA8F;IAC9F,SAAS,IAAI,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CA0BlB"}

package/dist/structured-output.js

@@ -0,0 +1,88 @@
+import { Check, Convert } from "typebox/value";
+import { WorkflowError, WorkflowErrorCode } from "@automatalabs/shared-types";
+/**
+ * Find a JSON object/array in free-form text: a fenced ```json block if present, else the
+ * first balanced {...} or [...]. Best-effort (the schema check is the real gate). Returns the
+ * raw JSON string, or undefined when none is found. (Ported VERBATIM from pi agent.ts.)
+ */
+export function findJsonBlock(text) {
+    const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fence?.[1])
+        return fence[1].trim();
+    const start = text.search(/[{[]/);
+    if (start === -1)
+        return undefined;
+    const open = text[start];
+    const close = open === "{" ? "}" : "]";
+    let depth = 0;
+    for (let i = start; i < text.length; i++) {
+        if (text[i] === open)
+            depth++;
+        else if (text[i] === close && --depth === 0)
+            return text.slice(start, i + 1);
+    }
+    return undefined;
+}
+/** Coerce an already-parsed value toward the schema and accept it only if it then validates. */
+export function validateValue(value, schema) {
+    try {
+        const converted = Convert(schema, value);
+        if (Check(schema, converted))
+            return converted;
+    }
+    catch {
+        // typebox can throw on exotic schemas; treat as no match.
+    }
+    return undefined;
+}
+/**
+ * Last-resort structured-output recovery: extract a JSON block from prose, coerce it toward
+ * the schema, and accept it only if it then validates. Never fabricates — returns undefined
+ * unless the parsed value genuinely satisfies the schema. (Ported VERBATIM from pi agent.ts.)
+ */
+export function extractValidated(text, schema) {
+    const json = findJsonBlock(text);
+    if (json === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    return validateValue(parsed, schema);
+}
+const REPROMPT_TEXT = [
+    "Your previous reply did not return valid JSON matching the required output schema.",
+    "Reply now with ONLY a single JSON object that conforms to the schema —",
+    "no prose, no explanation, and no markdown code fences.",
+].join(" ");
+/**
+ * Resolve a schema agent's result via the ladder above. Returns the validated value (typed
+ * unknown at this layer; the caller casts to the seam's AgentResult<S>). Throws
+ * SCHEMA_NONCOMPLIANCE (non-recoverable) when no valid value is produced after the retries.
+ */
+export async function resolveStructuredOutput(session, schema, options) {
+    const tryResolve = () => {
+        const native = session.tryNative();
+        if (native !== undefined && native !== null) {
+            const validated = validateValue(native, schema);
+            if (validated !== undefined)
+                return validated;
+        }
+        return extractValidated(session.lastText(), schema);
+    };
+    let resolved = tryResolve();
+    if (resolved !== undefined)
+        return resolved;
+    const maxRetries = Math.max(0, options.maxSchemaRetries ?? 2);
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        options.signal?.throwIfAborted();
+        await session.prompt(REPROMPT_TEXT);
+        resolved = tryResolve();
+        if (resolved !== undefined)
+            return resolved;
+    }
+    throw new WorkflowError("Subagent did not produce valid structured output after repair attempts", WorkflowErrorCode.SCHEMA_NONCOMPLIANCE, { recoverable: false, agentLabel: options.label });
+}

package/dist/usage.d.ts

@@ -0,0 +1,21 @@
+import type { AgentUsage } from "@automatalabs/shared-types";
+import type { Cost, Usage } from "@agentclientprotocol/sdk";
+export declare class UsageAccumulator {
+    private promptUsage;
+    private costAmount;
+    private contextUsedTokens;
+    private contextSizeTokens;
+    /** Record the authoritative per-turn token usage from a PromptResponse. */
+    recordPromptUsage(usage: Usage | null | undefined): void;
+    /** Record the latest cumulative dollar cost carried by a usage_update notification. */
+    recordCost(cost: Cost | null | undefined): void;
+    /**
+     * Record the token counts carried by a usage_update notification: `used` (tokens
+     * currently in context) and `size` (context window). These feed `total` as a fallback
+     * for backends that report tokens via usage_update but never via PromptResponse.usage,
+     * so AgentUsage.total is non-zero whenever the backend reported ANY token count.
+     */
+    recordContextTokens(used: number | null | undefined, size?: number | null | undefined): void;
+    toAgentUsage(): AgentUsage;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAE5D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,iBAAiB,CAAK;IAE9B,2EAA2E;IAC3E,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAIxD,uFAAuF;IACvF,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAM/C;;;;;OAKG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAK5F,YAAY,IAAI,UAAU;CAuB3B"}

package/dist/usage.js

@@ -0,0 +1,52 @@
+export class UsageAccumulator {
+    promptUsage;
+    costAmount = 0;
+    contextUsedTokens = 0;
+    contextSizeTokens = 0;
+    /** Record the authoritative per-turn token usage from a PromptResponse. */
+    recordPromptUsage(usage) {
+        if (usage)
+            this.promptUsage = usage;
+    }
+    /** Record the latest cumulative dollar cost carried by a usage_update notification. */
+    recordCost(cost) {
+        if (cost && typeof cost.amount === "number" && Number.isFinite(cost.amount)) {
+            this.costAmount = cost.amount;
+        }
+    }
+    /**
+     * Record the token counts carried by a usage_update notification: `used` (tokens
+     * currently in context) and `size` (context window). These feed `total` as a fallback
+     * for backends that report tokens via usage_update but never via PromptResponse.usage,
+     * so AgentUsage.total is non-zero whenever the backend reported ANY token count.
+     */
+    recordContextTokens(used, size) {
+        if (typeof used === "number" && Number.isFinite(used) && used >= 0)
+            this.contextUsedTokens = used;
+        if (typeof size === "number" && Number.isFinite(size) && size >= 0)
+            this.contextSizeTokens = size;
+    }
+    toAgentUsage() {
+        const u = this.promptUsage;
+        if (u) {
+            return {
+                input: u.inputTokens ?? 0,
+                output: u.outputTokens ?? 0,
+                cacheRead: u.cachedReadTokens ?? 0,
+                cacheWrite: u.cachedWriteTokens ?? 0,
+                total: u.totalTokens ?? 0,
+                cost: this.costAmount,
+            };
+        }
+        // No authoritative per-turn breakdown: fall back to the usage_update context tokens so
+        // `total` reflects what the backend reported (0 only when NEITHER channel fired).
+        return {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: this.contextUsedTokens,
+            cost: this.costAmount,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@automatalabs/acp-agents",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.0.0",
+    "@agentclientprotocol/claude-agent-acp": "0.53.0",
+    "@automatalabs/codex-acp": "1.0.2",
+    "typebox": "1.3.2",
+    "@automatalabs/shared-types": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test \"test/**/*.test.ts\""
+  }
+}