@alpacakit/agents 0.1.0-beta.19

package/dist/kernel/runtime.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The runtime (design "Kernel"): a registry of agent definitions plus
+ * resolved ports and an explicit base environment — NEVER an implicit
+ * `process.env`. Binding a definition yields an `Agent`; the facet
+ * mirror turns absent capabilities (rule 1 `?`) into `null` (rule 2).
+ */
+import { type Ports } from "../core/ports.js";
+import type { RunHandle } from "../core/run.js";
+import { type StructuredHandle, type StructuredRunOptions } from "../structured/run-structured.js";
+import type { AgentDefinition } from "./definition.js";
+import { type AgentAuth, type AgentDoctor, type AgentLogin, type AgentMcp, type AgentSkills } from "./facets.js";
+import { type RunOptions } from "./options.js";
+export interface Agent<Id extends string = string> {
+    readonly id: Id;
+    run<T>(options: StructuredRunOptions<T>): StructuredHandle<T>;
+    run(options: RunOptions): RunHandle;
+    run<T>(options: RunOptions | StructuredRunOptions<T>): RunHandle | StructuredHandle<T>;
+    auth: AgentAuth | null;
+    login: AgentLogin | null;
+    skills: AgentSkills | null;
+    mcp: AgentMcp | null;
+    doctor: AgentDoctor | null;
+}
+export interface AgentRuntime<Id extends string = string> {
+    agent<I extends Id>(id: I): Agent<I>;
+    agents(): Agent<Id>[];
+    /** The resolved ports — composition layers (fleet) reuse these. */
+    readonly ports: Ports;
+}
+export type AgentRuntimeOptions<Defs extends readonly AgentDefinition[]> = {
+    agents: Defs;
+    ports?: Partial<Ports>;
+    /**
+     * The base environment every run starts from. Required and explicit —
+     * the runtime never falls back to `process.env`, so omitting it can no
+     * longer silently yield an empty env that fails auth at run time. Pass
+     * `processEnv()` for the ambient environment, or `{}` for a hermetic run.
+     */
+    baseEnv: Record<string, string>;
+};
+/**
+ * Shallow per-port merge — except `secrets`, which is a registry, not an
+ * implementation: entries merge additively over the built-in "env"
+ * resolver, so registering "keychain" never silently drops "env".
+ */
+export declare function resolvePorts(ports?: Partial<Ports>): Ports;
+export declare function createAgentRuntime<const Defs extends readonly AgentDefinition[]>(options: AgentRuntimeOptions<Defs>): AgentRuntime<Defs[number]["id"]>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/kernel/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/kernel/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAA6B,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAE1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,EAOjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,cAAc,CAAC;AAGlE,MAAM,WAAW,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IAC/C,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC9D,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,GAAG,CAAC,CAAC,EACH,OAAO,EAAE,UAAU,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAC5C,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACtD,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,IAAI;IACzE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAS1D;AAqED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,EAC7C,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CA8BtE"}

package/dist/kernel/runtime.js

@@ -0,0 +1,108 @@
+/**
+ * The runtime (design "Kernel"): a registry of agent definitions plus
+ * resolved ports and an explicit base environment — NEVER an implicit
+ * `process.env`. Binding a definition yields an `Agent`; the facet
+ * mirror turns absent capabilities (rule 1 `?`) into `null` (rule 2).
+ */
+import { envResolver } from "../auth/secrets.js";
+import { applyEnvPatch } from "../core/env.js";
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { fetchHttp, nodeExec, systemClock } from "../core/node-ports.js";
+import { noopLogger, noopTelemetry } from "../core/ports.js";
+import { isStructuredRunOptions, resolveStructuredRunOptions, startStructuredRun, } from "../structured/run-structured.js";
+import { bindAuth, bindDoctor, bindLogin, bindMcp, bindSkills, } from "./facets.js";
+import { resolveRunOptions } from "./options.js";
+import { startRun } from "./run.js";
+/**
+ * Shallow per-port merge — except `secrets`, which is a registry, not an
+ * implementation: entries merge additively over the built-in "env"
+ * resolver, so registering "keychain" never silently drops "env".
+ */
+export function resolvePorts(ports) {
+    return {
+        exec: ports?.exec ?? nodeExec,
+        clock: ports?.clock ?? systemClock,
+        secrets: { env: envResolver(), ...ports?.secrets },
+        http: ports?.http ?? fetchHttp,
+        telemetry: ports?.telemetry ?? noopTelemetry,
+        logger: ports?.logger ?? noopLogger,
+    };
+}
+function bindAgent(definition, ports, baseEnv) {
+    const binding = {
+        agentId: definition.id,
+        env: baseEnv,
+        exec: ports.exec,
+        http: ports.http,
+        clock: ports.clock,
+        logger: ports.logger,
+        secrets: ports.secrets,
+    };
+    function runRaw(options) {
+        const resolved = resolveRunOptions(options);
+        return startRun({
+            definition,
+            options: resolved,
+            callerSignal: options.signal ?? null,
+            env: applyEnvPatch(baseEnv, resolved.env),
+            ports,
+        });
+    }
+    function run(options) {
+        if (isStructuredRunOptions(options)) {
+            const { runOptions, contract } = resolveStructuredRunOptions(options);
+            return startStructuredRun({
+                agentId: definition.id,
+                options: runOptions,
+                contract,
+                runAttempt: runRaw,
+            });
+        }
+        return runRaw(options);
+    }
+    return {
+        id: definition.id,
+        run,
+        auth: definition.auth === undefined ? null : bindAuth(definition.auth, binding),
+        login: definition.login === undefined
+            ? null
+            : bindLogin(definition.login, binding),
+        skills: definition.skills === undefined
+            ? null
+            : bindSkills(definition.skills, binding),
+        mcp: definition.mcp === undefined ? null : bindMcp(definition.mcp, binding),
+        doctor: definition.doctor === undefined
+            ? null
+            : bindDoctor(definition.doctor, binding),
+    };
+}
+export function createAgentRuntime(options) {
+    const ports = resolvePorts(options.ports);
+    const baseEnv = options.baseEnv;
+    const bound = new Map();
+    for (const definition of options.agents) {
+        if (bound.has(definition.id)) {
+            throw new AgentError({
+                code: AGENT_ERROR_CODE.invalidInput,
+                message: `Duplicate agent id "${definition.id}"`,
+                data: { reason: `agent id "${definition.id}" registered twice` },
+            });
+        }
+        bound.set(definition.id, bindAgent(definition, ports, baseEnv));
+    }
+    return {
+        ports,
+        agent: (id) => {
+            const agent = bound.get(id);
+            if (agent === undefined) {
+                throw new AgentError({
+                    code: AGENT_ERROR_CODE.invalidInput,
+                    message: `Unknown agent id "${id}"`,
+                    data: { reason: `no agent registered with id "${id}"` },
+                });
+            }
+            return agent;
+        },
+        agents: () => [...bound.values()],
+    };
+}

package/dist/keyring/index.d.ts

@@ -0,0 +1,2 @@
+export { keyringResolver, type KeyringResolverOptions, } from "./resolver.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/keyring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAC"}

package/dist/keyring/index.js

@@ -0,0 +1 @@
+export { keyringResolver, } from "./resolver.js";

package/dist/keyring/resolver.d.ts

@@ -0,0 +1,9 @@
+import type { SecretResolver } from "../core/ports.js";
+export type KeyringResolverOptions = {
+    readonly service: string;
+};
+type KeyringModuleLoader = () => Promise<unknown>;
+export declare function keyringResolver(options: KeyringResolverOptions): SecretResolver;
+export declare function createKeyringResolver(options: KeyringResolverOptions, loader: KeyringModuleLoader): SecretResolver;
+export {};
+//# sourceMappingURL=resolver.d.ts.map

package/dist/keyring/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/keyring/resolver.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,mBAAmB,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAiBlD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAEhB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,mBAAmB,GAC1B,cAAc,CA0BhB"}

package/dist/keyring/resolver.js

@@ -0,0 +1,62 @@
+// biome-ignore-all lint/style/useNamingConvention: Keyring peer exports mirror upstream PascalCase names.
+import { AGENT_ERROR_CODE, AgentError, NOT_AVAILABLE_CAUSE, } from "../core/error.js";
+const KEYRING_PEER_PACKAGE = "@napi-rs/keyring";
+const KEYRING_ENTRY_EXPORT = "Entry";
+const EMPTY_SECRET_VALUE = "";
+const defaultKeyringModuleLoader = () => import(KEYRING_PEER_PACKAGE);
+export function keyringResolver(options) {
+    return createKeyringResolver(options, defaultKeyringModuleLoader);
+}
+export function createKeyringResolver(options, loader) {
+    const service = options.service;
+    let modulePromise = null;
+    const load = () => {
+        modulePromise ??= loadKeyringModule(loader);
+        return modulePromise;
+    };
+    return {
+        resolve: async (id) => {
+            const module = await load();
+            try {
+                // Absent entries are the `null` return (`Entry.getPassword():
+                // string | null` in @napi-rs/keyring); anything thrown is a real
+                // keychain failure, never "missing secret".
+                const value = await new module.Entry(service, id).getPassword();
+                return value === EMPTY_SECRET_VALUE ? null : value;
+            }
+            catch (error) {
+                throw new AgentError({
+                    code: AGENT_ERROR_CODE.failed,
+                    message: `Keyring secret "${id}" could not be read`,
+                    data: { exitCode: null, stdoutTail: null, stderrTail: null },
+                    cause: error,
+                });
+            }
+        },
+    };
+}
+async function loadKeyringModule(loader) {
+    let loaded;
+    try {
+        loaded = await loader();
+    }
+    catch (error) {
+        throw keyringNotInstalledError(error);
+    }
+    if (typeof loaded !== "object" || loaded === null) {
+        throw keyringNotInstalledError(null);
+    }
+    const entry = Reflect.get(loaded, KEYRING_ENTRY_EXPORT);
+    if (typeof entry !== "function") {
+        throw keyringNotInstalledError(null);
+    }
+    return { Entry: entry };
+}
+function keyringNotInstalledError(cause) {
+    return new AgentError({
+        code: AGENT_ERROR_CODE.notAvailable,
+        message: "Keyring peer is not installed",
+        data: { cause: NOT_AVAILABLE_CAUSE.notInstalled },
+        cause,
+    });
+}

package/dist/run-agent.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `runAgent` — the zero-config sugar for the minimal persona. This is
+ * the ONLY place `process.env` is a documented default, and v1's 1-hour
+ * total timeout lives here as a documented default rather than kernel
+ * magic.
+ */
+import { type BuiltinAgentId } from "./agents/builtin.js";
+import type { Ports } from "./core/ports.js";
+import type { RunHandle } from "./core/run.js";
+import type { AgentDefinition } from "./kernel/definition.js";
+import type { RunOptions } from "./kernel/options.js";
+export type RunAgentOptions = RunOptions & {
+    agent: BuiltinAgentId | AgentDefinition;
+    ports?: Partial<Ports>;
+    /** Defaults to the current process env; pass explicitly to override. */
+    baseEnv?: Record<string, string>;
+};
+export declare function runAgent(options: RunAgentOptions): RunHandle;
+//# sourceMappingURL=run-agent.d.ts.map

package/dist/run-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent.d.ts","sourceRoot":"","sources":["../src/run-agent.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKtD,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IACzC,KAAK,EAAE,cAAc,GAAG,eAAe,CAAC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CAe5D"}

package/dist/run-agent.js

@@ -0,0 +1,25 @@
+/**
+ * `runAgent` — the zero-config sugar for the minimal persona. This is
+ * the ONLY place `process.env` is a documented default, and v1's 1-hour
+ * total timeout lives here as a documented default rather than kernel
+ * magic.
+ */
+import { builtinAgentFactories, } from "./agents/builtin.js";
+import { processEnv } from "./core/env.js";
+import { createAgentRuntime } from "./kernel/runtime.js";
+const DEFAULT_TOTAL_TIMEOUT_MS = 3_600_000;
+export function runAgent(options) {
+    const { agent, ports, baseEnv, ...runOptions } = options;
+    const definition = typeof agent === "string" ? builtinAgentFactories[agent]() : agent;
+    const runtime = createAgentRuntime({
+        agents: [definition],
+        ...(ports === undefined ? {} : { ports }),
+        baseEnv: baseEnv ?? processEnv(),
+    });
+    return runtime.agent(definition.id).run({
+        ...runOptions,
+        // The documented default applies per field (rule 1): supplying
+        // `limits.idleMs` must not silently drop the 1h total cap.
+        limits: { totalMs: DEFAULT_TOTAL_TIMEOUT_MS, ...runOptions.limits },
+    });
+}

package/dist/structured/extract.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Extraction strategy chain (S1) and resilient JSON parsing (S2): kept
+ * from v1 because it is hard-won robustness against truncated streams,
+ * generalized to neutral configurable markers.
+ */
+export type Markers = {
+    start: string;
+    end: string;
+};
+export declare const DEFAULT_MARKERS: Markers;
+/** A strategy returns the candidate block text, or null to pass. */
+export type ExtractionStrategy = (text: string, markers: Markers) => string | null;
+export declare const defaultExtractionStrategies: readonly ExtractionStrategy[];
+export declare function extractBlock(text: string, markers: Markers, strategies?: readonly ExtractionStrategy[]): string | null;
+export type JsonParseOutcome = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse with the v1 resilience chain: direct → control-char escaping →
+ * truncation repair (both fixes composed for the last attempt).
+ */
+export declare function parseJsonResilient(text: string): JsonParseOutcome;
+//# sourceMappingURL=extract.d.ts.map

package/dist/structured/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/structured/extract.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,eAAe,EAAE,OAG7B,CAAC;AAEF,oEAAoE;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,KACb,MAAM,GAAG,IAAI,CAAC;AAoCnB,eAAO,MAAM,2BAA2B,EAAE,SAAS,kBAAkB,EAIpE,CAAC;AA2CF,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,SAAS,kBAAkB,EAAgC,GACtE,MAAM,GAAG,IAAI,CAQf;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA+EjC;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAYjE"}

package/dist/structured/extract.js

@@ -0,0 +1,188 @@
+/**
+ * Extraction strategy chain (S1) and resilient JSON parsing (S2): kept
+ * from v1 because it is hard-won robustness against truncated streams,
+ * generalized to neutral configurable markers.
+ */
+export const DEFAULT_MARKERS = {
+    start: "<<<AGENT_OUTPUT_START>>>",
+    end: "<<<AGENT_OUTPUT_END>>>",
+};
+const markedBlock = (text, markers) => {
+    const start = text.lastIndexOf(markers.start);
+    const end = text.lastIndexOf(markers.end);
+    if (start === -1 || end === -1 || end <= start) {
+        return null;
+    }
+    return text.slice(start + markers.start.length, end).trim();
+};
+const unclosedMarkedBlock = (text, markers) => {
+    const start = text.lastIndexOf(markers.start);
+    if (start === -1) {
+        return null;
+    }
+    return text.slice(start + markers.start.length).trim();
+};
+const firstJsonValue = (text) => {
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (char !== "{" && char !== "[") {
+            continue;
+        }
+        const candidate = balancedJsonCandidate(text, index);
+        if (candidate === null) {
+            return text.slice(index).trim();
+        }
+        if (tryParse(candidate).ok) {
+            return candidate.trim();
+        }
+    }
+    return null;
+};
+export const defaultExtractionStrategies = [
+    markedBlock,
+    unclosedMarkedBlock,
+    firstJsonValue,
+];
+function balancedJsonCandidate(text, start) {
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < text.length; index += 1) {
+        const char = text[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && inString) {
+            escaped = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (char === "{") {
+            stack.push("}");
+            continue;
+        }
+        if (char === "[") {
+            stack.push("]");
+            continue;
+        }
+        if (char === "}" || char === "]") {
+            if (stack.pop() !== char) {
+                return text.slice(start, index + 1);
+            }
+            if (stack.length === 0) {
+                return text.slice(start, index + 1);
+            }
+        }
+    }
+    return null;
+}
+export function extractBlock(text, markers, strategies = defaultExtractionStrategies) {
+    for (const strategy of strategies) {
+        const block = strategy(text, markers);
+        if (block !== null && block !== "") {
+            return block;
+        }
+    }
+    return null;
+}
+function tryParse(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+const CONTROL_CHAR_ESCAPES = {
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+};
+/** Escape raw control characters that appear inside string literals. */
+function escapeControlCharsInStrings(text) {
+    let result = "";
+    let inString = false;
+    let escaped = false;
+    for (const char of text) {
+        if (inString && !escaped && char in CONTROL_CHAR_ESCAPES) {
+            result += CONTROL_CHAR_ESCAPES[char];
+            continue;
+        }
+        result += char;
+        if (escaped) {
+            escaped = false;
+        }
+        else if (char === "\\" && inString) {
+            escaped = true;
+        }
+        else if (char === '"') {
+            inString = !inString;
+        }
+    }
+    return result;
+}
+/** Close whatever a truncated stream left open: strings, arrays, objects. */
+function repairTruncation(text) {
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    for (const char of text) {
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && inString) {
+            escaped = true;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            stack.push(char);
+        }
+        else if (char === "}" || char === "]") {
+            stack.pop();
+        }
+    }
+    let repaired = text.trimEnd();
+    if (inString) {
+        repaired += '"';
+    }
+    repaired = repaired.replace(/,\s*$/, "");
+    for (const open of stack.reverse()) {
+        repaired += open === "{" ? "}" : "]";
+    }
+    return repaired;
+}
+/**
+ * Parse with the v1 resilience chain: direct → control-char escaping →
+ * truncation repair (both fixes composed for the last attempt).
+ */
+export function parseJsonResilient(text) {
+    const direct = tryParse(text);
+    if (direct.ok) {
+        return direct;
+    }
+    const escapedText = escapeControlCharsInStrings(text);
+    const escapedParse = tryParse(escapedText);
+    if (escapedParse.ok) {
+        return escapedParse;
+    }
+    const repaired = tryParse(repairTruncation(escapedText));
+    return repaired.ok ? repaired : direct;
+}

package/dist/structured/run-structured.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Structured output (design "Structured output"): a decorator over
+ * kernel runs. Repair happens WITHIN one candidate — it composes below
+ * the fleet, never inside it. Exhausted repairs fail with
+ * `output_rejected` carrying the issue list.
+ */
+import { type Issue } from "../core/error.js";
+import type { RunEvent, RunHandle, RunResult } from "../core/run.js";
+import type { RunOptions } from "../kernel/options.js";
+import { type ExtractionStrategy, type Markers } from "./extract.js";
+import type { StandardSchemaV1 } from "./standard-schema.js";
+export declare const CONTRACT_PROMPT_PLACEMENT: {
+    readonly append: "append";
+    readonly embedded: "embedded";
+};
+export type ContractPromptPlacement = (typeof CONTRACT_PROMPT_PLACEMENT)[keyof typeof CONTRACT_PROMPT_PLACEMENT];
+export type ParseOutcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: Issue[];
+};
+export type RepairContext = {
+    basePrompt: string;
+    contractInstruction: string;
+    attempt: number;
+    issues: Issue[];
+    previousBlock: string | null;
+    markers: Markers;
+};
+export type OutputContract<T> = {
+    readonly schema: StandardSchemaV1<unknown, T> | ((blockText: string) => ParseOutcome<T>);
+    readonly markers?: Markers;
+    readonly extractionStrategies?: readonly ExtractionStrategy[];
+    readonly renderContract?: (markers: Markers) => string;
+    /** Whether the driver appends the rendered contract to the base prompt. */
+    readonly promptPlacement: ContractPromptPlacement;
+    readonly repair?: {
+        readonly maxAttempts?: number;
+        readonly shouldRetry?: (issues: Issue[], attempt: number) => boolean;
+        readonly renderRepairPrompt?: (ctx: RepairContext) => string;
+    };
+    /** Semantic validation hook (S3); empty list = valid (rule 3). */
+    validate?(value: T): Issue[] | Promise<Issue[]>;
+};
+export type StructuredRunOptions<T> = Omit<RunOptions, "contract"> & {
+    contract: OutputContract<T>;
+};
+export type StructuredAttempt = {
+    runId: string;
+    issues: Issue[];
+    block: string | null;
+};
+export type StructuredResult<T> = {
+    output: T;
+    result: RunResult;
+    attempts: StructuredAttempt[];
+};
+/**
+ * Awaitable handle mirroring `RunHandle`: `await agent.run({ ..., contract })`
+ * yields the `StructuredResult`, and `.events` streams every repair
+ * attempt's run events in order, so a caller can watch progress across the
+ * whole extract/validate/repair loop — not just the final run.
+ */
+export type StructuredHandle<T> = Promise<StructuredResult<T>> & {
+    readonly events: AsyncIterable<RunEvent>;
+    readonly result: Promise<StructuredResult<T>>;
+};
+export type StructuredRunDriverInput<T> = {
+    readonly agentId: string;
+    readonly options: RunOptions;
+    readonly contract: OutputContract<T>;
+    readonly runAttempt: (options: RunOptions) => RunHandle;
+};
+export type ResolvedStructuredRunOptions<T> = {
+    readonly runOptions: RunOptions;
+    readonly contract: OutputContract<T>;
+};
+export declare function isStructuredRunOptions<T = unknown>(options: RunOptions | StructuredRunOptions<T>): options is StructuredRunOptions<T>;
+export declare function resolveStructuredRunOptions<T>(options: StructuredRunOptions<T>): ResolvedStructuredRunOptions<T>;
+export declare function startStructuredRun<T>(input: StructuredRunDriverInput<T>): StructuredHandle<T>;
+//# sourceMappingURL=run-structured.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-structured.d.ts","sourceRoot":"","sources":["../../src/structured/run-structured.ts"],"names":[],"mappings":"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"}