@with-logic/elwood 0.1.0

package/dist/core/simple/turn-gate.js

@@ -0,0 +1,194 @@
+/**
+ * The completion gate for one ergonomic turn (PRD §5.8): a single-producer/single-consumer
+ * async queue that ends a turn DETERMINISTICALLY once the transcript has caught up.
+ *
+ * `observeReady()` (on `ready`) begins completion checks and arms a `catchUpMs` failure cap. The
+ * turn ends when the collected assistant text CONTAINS the Stop hook's expected text (the oracle),
+ * or — with no expected text — after `quietMs` of no new content; if neither happens within
+ * `catchUpMs` of `ready` it fails with `wait_timeout`. `end()`/`fail()` are IDEMPOTENT (first
+ * completion wins). `done()` resolves/rejects at that completion for the runner; `drain()` is the
+ * consumer view and finishes only once the queue is also empty (a completion racing ahead of the
+ * last buffered event never truncates it).
+ */
+import { elwoodError } from "../errors.js";
+import { CompletenessOracle } from "./completeness-oracle.js";
+import { turnEventBytes } from "./events.js";
+// Cap on UNCONSUMED events buffered for a slow/paused consumer; past it the turn fails with a
+// typed `wait_timeout` rather than growing without limit (a turn has no default whole-turn
+// timeout). Large enough that a normally draining consumer never hits it.
+const MAX_PENDING_EVENTS = 100_000;
+// Compact the consumed prefix only past this many consumed events (so a small stream never
+// churns splice on tiny arrays); the `head >= length/2` gate then keeps it amortised O(1).
+const HEAD_COMPACT_MIN = 32;
+// Cap on UNCONSUMED UTF-8 bytes for a slow consumer. The count cap alone cannot bound memory —
+// a single event may carry an arbitrarily large agent-controlled string — so this byte
+// high-water is the real exhaustion guard. 64 MiB: far above any legitimate backlog.
+const MAX_PENDING_BYTES = 64 * 1024 * 1024;
+export class TurnGate {
+    queue = [];
+    head = 0; // index of the next unconsumed event (avoids O(n) Array.shift)
+    pendingBytes = 0; // sum of unconsumed event UTF-8 byte sizes (byte high-water guard)
+    ended = false;
+    error;
+    wake;
+    readyObserved = false; // `ready` seen — completion checks may begin (NOT the turn end)
+    oracle = new CompletenessOracle();
+    quietTimer;
+    catchUpTimer;
+    quietMs;
+    catchUpMs;
+    maxPendingEvents;
+    maxPendingBytes;
+    resolveDone;
+    rejectDone;
+    donePromise;
+    constructor(quietMs, catchUpMs, maxPendingEvents = MAX_PENDING_EVENTS, maxPendingBytes = MAX_PENDING_BYTES) {
+        this.quietMs = quietMs;
+        this.catchUpMs = catchUpMs;
+        this.maxPendingEvents = maxPendingEvents;
+        this.maxPendingBytes = maxPendingBytes;
+        this.donePromise = new Promise((resolve, reject) => {
+            this.resolveDone = resolve;
+            this.rejectDone = reject;
+        });
+        this.donePromise.catch(() => {
+            // Swallow: `done()` may reject before/without a runner awaiting it (e.g. an early
+            // failure); the error still reaches the consumer via `drain()`. No unhandled rejection.
+        });
+    }
+    /** Resolves at the real turn boundary; rejects on failure/timeout. For the turn runner. */
+    done() {
+        return this.donePromise;
+    }
+    /** Backing-array length — the retained storage. A CONTINUOUS stream must keep this bounded. */
+    get backingSize() {
+        return this.queue.length;
+    }
+    observeText(text) {
+        this.oracle.observeText(text);
+        this.reconcile();
+    }
+    /**
+     * Feed one normalized boundary signal. `undefined` is NOT a boundary (a non-`Stop` hook such as
+     * `Notification` arriving after `Stop`) and leaves an installed oracle untouched — else late
+     * assistant text would fall through to the quiet window and leak into the next turn. A string
+     * installs the oracle; an empty one clears it (→ quiet settle).
+     */
+    expectText(text) {
+        if (text === undefined)
+            return;
+        // Installing a NON-EMPTY oracle after `ready` (the Stop hook can lag `ready`) must cancel any
+        // quiet-window fallback already armed: the promised text now governs completion, so the turn
+        // waits for it (or the catch-up cap), not a quiet settle.
+        if (this.oracle.expectText(text) && this.quietTimer) {
+            clearTimeout(this.quietTimer);
+            this.quietTimer = undefined;
+        }
+        this.reconcile();
+    }
+    push(event) {
+        if (this.ended)
+            return;
+        // Bound unconsumed events AND bytes (a stalled consumer must not grow the buffer without
+        // limit) — count catches a flood of small events, bytes a few huge payloads. Report WHICH
+        // bound was hit so the diagnostic doesn't always blame the count.
+        const bytes = turnEventBytes(event);
+        const overCount = this.queue.length - this.head >= this.maxPendingEvents;
+        const overBytes = this.pendingBytes + bytes > this.maxPendingBytes;
+        if (overCount || overBytes) {
+            const reason = overCount ? "events" : "bytes";
+            this.fail(elwoodError("wait_timeout", `turn produced too many unconsumed ${reason}`));
+            return;
+        }
+        this.queue.push({ event, bytes });
+        this.pendingBytes += bytes;
+        if (this.readyObserved)
+            this.armQuiet(); // new content after ready: re-arm the fallback window
+        this.wake?.();
+    }
+    /** `ready` observed — begin completion checks and arm the post-ready catch-up cap. */
+    observeReady() {
+        if (this.ended || this.readyObserved)
+            return;
+        this.readyObserved = true;
+        this.catchUpTimer = setTimeout(() => this.fail(elwoodError("wait_timeout", "transcript did not catch up after ready")), this.catchUpMs);
+        this.catchUpTimer.unref?.();
+        this.reconcile();
+    }
+    /** Complete the turn (idempotent — the first completion wins). */
+    end() {
+        if (this.ended)
+            return;
+        this.dispose();
+        this.ended = true;
+        this.resolveDone();
+        this.wake?.();
+    }
+    /** Fail the turn (idempotent — a late timer cannot overwrite an already-committed end). */
+    fail(error) {
+        if (this.ended)
+            return;
+        this.dispose();
+        this.error = error;
+        this.ended = true;
+        this.rejectDone(error);
+        this.wake?.();
+    }
+    /** Clear every timer (idempotent); called on end/fail. */
+    dispose() {
+        if (this.quietTimer)
+            clearTimeout(this.quietTimer);
+        if (this.catchUpTimer)
+            clearTimeout(this.catchUpTimer);
+        this.quietTimer = undefined;
+        this.catchUpTimer = undefined;
+    }
+    /** End now if the transcript has caught up to the expected text; else arm the fallback. */
+    reconcile() {
+        if (this.ended || !this.readyObserved)
+            return;
+        if (this.oracle.hasExpected) {
+            if (this.oracle.matched)
+                this.end(); // caught up — deterministic
+            return; // still waiting for the transcript to reach the expected text (catch-up cap guards)
+        }
+        this.armQuiet(); // no oracle (pure-tool / empty / StopFailure): bounded quiet settle
+    }
+    armQuiet() {
+        if (this.ended || this.oracle.hasExpected)
+            return;
+        if (this.quietTimer)
+            clearTimeout(this.quietTimer);
+        this.quietTimer = setTimeout(() => this.end(), this.quietMs);
+        this.quietTimer.unref?.();
+    }
+    async *drain() {
+        for (;;) {
+            while (this.head < this.queue.length) {
+                const queued = this.queue[this.head];
+                this.head += 1;
+                this.pendingBytes -= queued.bytes; // precomputed on push — no re-encode here
+                // Compact the consumed prefix once it dominates the array, so consumed events are freed
+                // even in a CONTINUOUS stream that never empties (else the reset below is unreachable and
+                // storage grows unbounded). Gated on head ≥ HALF → amortised O(1) per event, not O(n²).
+                if (this.head >= HEAD_COMPACT_MIN && this.head * 2 >= this.queue.length) {
+                    this.queue.splice(0, this.head);
+                    this.head = 0;
+                }
+                yield queued.event;
+            }
+            // Fully caught up: reset the backing array so nothing lingers between turns.
+            this.queue.length = 0;
+            this.head = 0;
+            if (this.error !== undefined)
+                throw this.error;
+            if (this.ended)
+                return;
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+            this.wake = undefined;
+        }
+    }
+}
+//# sourceMappingURL=turn-gate.js.map

package/dist/core/simple/turn-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-gate.js","sourceRoot":"","sources":["../../../src/core/simple/turn-gate.ts"],"names":[],"mappings":"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"}

package/dist/core/simple/turn-queue.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Serializes ergonomic turns in CALL order (PRD §5.8, C-API-50). A turn's slot is reserved
+ * SYNCHRONOUSLY when `enqueue` is called (not when the generator is iterated), so
+ * `stream("a"); stream("b")` submits a before b even if b is consumed first. Each turn holds
+ * its slot until its REAL boundary (`RunningTurn.boundary` — the agent genuinely settled, NOT
+ * the consumer-facing `completion`, which can resolve on a timeout while the agent still runs),
+ * so a consumer that abandons or times out a stream never lets the next turn bind to this turn's
+ * still-arriving trailing events.
+ */
+import type { TurnEvent } from "./events.ts";
+import type { RunningTurn } from "./turn.ts";
+export declare class TurnQueue {
+    private tail;
+    /**
+     * Reserve a serialized slot now and return the turn's consumer generator. The turn STARTS
+     * (via `run`) as soon as the predecessor settles — EAGERLY, independent of whether the
+     * consumer iterates — so a turn whose consumer is not yet reading still runs in call order
+     * and does not deadlock a later turn that IS being consumed. The slot is held until the
+     * turn's real `boundary`; the returned generator only reads the started turn's events.
+     */
+    enqueue(run: () => Promise<RunningTurn>): AsyncGenerator<TurnEvent>;
+}
+//# sourceMappingURL=turn-queue.d.ts.map

package/dist/core/simple/turn-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-queue.d.ts","sourceRoot":"","sources":["../../../src/core/simple/turn-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,qBAAa,SAAS;IAEpB,OAAO,CAAC,IAAI,CAAuC;IAEnD;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,cAAc,CAAC,SAAS,CAAC;CAoBpE"}

package/dist/core/simple/turn-queue.js

@@ -0,0 +1,43 @@
+/**
+ * Serializes ergonomic turns in CALL order (PRD §5.8, C-API-50). A turn's slot is reserved
+ * SYNCHRONOUSLY when `enqueue` is called (not when the generator is iterated), so
+ * `stream("a"); stream("b")` submits a before b even if b is consumed first. Each turn holds
+ * its slot until its REAL boundary (`RunningTurn.boundary` — the agent genuinely settled, NOT
+ * the consumer-facing `completion`, which can resolve on a timeout while the agent still runs),
+ * so a consumer that abandons or times out a stream never lets the next turn bind to this turn's
+ * still-arriving trailing events.
+ */
+export class TurnQueue {
+    // The tail of the serialized-turn chain: each turn awaits the previous one's real boundary.
+    tail = Promise.resolve();
+    /**
+     * Reserve a serialized slot now and return the turn's consumer generator. The turn STARTS
+     * (via `run`) as soon as the predecessor settles — EAGERLY, independent of whether the
+     * consumer iterates — so a turn whose consumer is not yet reading still runs in call order
+     * and does not deadlock a later turn that IS being consumed. The slot is held until the
+     * turn's real `boundary`; the returned generator only reads the started turn's events.
+     */
+    enqueue(run) {
+        const predecessor = this.tail;
+        let releaseSlot;
+        this.tail = new Promise((resolve) => {
+            releaseSlot = resolve;
+        });
+        // Start the turn as its slot comes up, decoupled from consumption. The predecessor's tail
+        // ALWAYS resolves (a failed turn still releases its slot below), so a prior turn's failure
+        // never blocks a later turn. Hold this slot until the agent turn's real BOUNDARY — NOT its
+        // consumer `completion`: a consumer-facing failure (timeout/catch-up/backlog) resolves
+        // `completion` while the agent may still be running, so releasing on `completion` would let
+        // the next turn bind to this turn's still-arriving activity. `boundary` resolves only when
+        // the agent genuinely settles (ready/terminal), even after a consumer failure.
+        const started = predecessor.then(() => run());
+        void started.then((turn) => turn.boundary.then(releaseSlot), () => releaseSlot());
+        return drainStarted(started);
+    }
+}
+/** Yield the (eagerly-started) turn's events once it has started; propagates a start failure. */
+async function* drainStarted(started) {
+    const turn = await started; // rejects if session start / run() failed — surfaced to the consumer
+    yield* turn.events;
+}
+//# sourceMappingURL=turn-queue.js.map

package/dist/core/simple/turn-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-queue.js","sourceRoot":"","sources":["../../../src/core/simple/turn-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,OAAO,SAAS;IACpB,4FAA4F;IACpF,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEnD;;;;;;OAMG;IACH,OAAO,CAAC,GAA+B;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC;QAC9B,IAAI,WAAwB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACxC,WAAW,GAAG,OAAO,CAAC;QACxB,CAAC,CAAC,CAAC;QACH,0FAA0F;QAC1F,2FAA2F;QAC3F,2FAA2F;QAC3F,uFAAuF;QACvF,4FAA4F;QAC5F,2FAA2F;QAC3F,+EAA+E;QAC/E,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QAC9C,KAAK,OAAO,CAAC,IAAI,CACf,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EACzC,GAAG,EAAE,CAAC,WAAW,EAAE,CACpB,CAAC;QACF,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,iGAAiG;AACjG,KAAK,SAAS,CAAC,CAAC,YAAY,CAAC,OAA6B;IACxD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,CAAC,qEAAqE;IACjG,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC"}

package/dist/core/simple/turn-types.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Types and conformance probes for one ergonomic turn (PRD §5.8, C-API-48/53). Separated from
+ * the `runTurn` runner (turn.ts) so both stay under the file-size cap. Defines the loose
+ * boundary-hook shape the oracle reads, the compile-time drift guard adapters assert against,
+ * the narrow turn-capable session surface, and the turn's options and result shapes.
+ */
+import type { ElwoodAgentSession, ElwoodCommonEventMap } from "../agent-session.ts";
+import type { ImageInput } from "../images/types.ts";
+import type { TurnEvent } from "./events.ts";
+/**
+ * The MINIMAL turn-boundary `hook` fields the completeness oracle reads. Deliberately
+ * adapter-neutral (core must not depend on adapter hook types) — the `hook` listener accepts
+ * this loose shape, but each adapter asserts CONFORMANCE against `TurnBoundaryContract` below
+ * so a contract change (renamed/removed `last_assistant_message`) fails to compile.
+ */
+export type TurnBoundaryHook = {
+    readonly hook_event_name?: string;
+    readonly last_assistant_message?: string | null;
+    readonly prompt?: string;
+};
+/**
+ * The turn-boundary fields the oracle DEPENDS ON. `TurnBoundaryHook` is deliberately loose (a
+ * missing/`null` value just means "no oracle" → quiet settle), but a `Stop` payload that
+ * RENAMED or DROPPED `last_assistant_message` would silently disable the oracle, so
+ * `AssertStopBoundary` enforces each adapter's real `Stop` event still DECLARES these keys.
+ */
+export type TurnBoundaryContract = {
+    readonly hook_event_name: string | undefined;
+    readonly last_assistant_message: string | null | undefined;
+};
+/**
+ * NORMALIZES a raw adapter `hook` event into the core's completeness signal. The two outcomes
+ * are DISTINCT: `undefined` means "not a turn boundary" (the runner ignores the event — an
+ * installed oracle stays installed), while a string means "a turn boundary whose expected final
+ * assistant text is this" — an EMPTY string is a boundary that carries no text (`null`/absent
+ * `last_assistant_message`, e.g. `StopFailure`) and clears the oracle → quiet-window settle.
+ * This is the ONE seam where adapter hook shape meets the adapter-neutral runner: `runTurn`
+ * consumes only this normalized signal, never raw `hook_event_name`/`last_assistant_message`, so
+ * the core is not coupled to adapter hook fields. Each `SessionBase` subclass supplies its own
+ * reader (a compile-time REQUIREMENT), so a new adapter cannot wire up turns without one.
+ */
+export type BoundarySignalReader = (hookEvent: TurnBoundaryHook) => string | undefined;
+/** Normalizes shared hook evidence into positive acceptance for one exact prompt. */
+export type AcceptanceSignalReader = (hookEvent: TurnBoundaryHook, prompt: string) => boolean;
+/**
+ * The default reader: a `Stop` hook is the turn boundary and its `last_assistant_message` the
+ * completeness signal (`""` when null/absent → no oracle); any other hook is not a boundary.
+ */
+export declare const defaultBoundarySignal: BoundarySignalReader;
+/** Shared Claude/Codex acceptance: the matching submit hook or any Stop boundary. */
+export declare const defaultAcceptanceSignal: AcceptanceSignalReader;
+/**
+ * Compile-time conformance probe: `true` only if `T` declares every `TurnBoundaryContract` key
+ * (`keyof extends keyof T` — a renamed/dropped key → `never`) with an assignable value
+ * (`Required<T>` reads the type ignoring optionality, so an optional key passes but a type
+ * change → `never`). Either drift makes the adapter assertion fail to compile.
+ *
+ * One of two turn-capability guards. `SessionBase` requires each subclass to implement the
+ * abstract `readBoundarySignal` (a hook→expected-text normalizer), so the runner never reads raw
+ * adapter hook fields and a new adapter cannot wire turns WITHOUT a boundary reader. This
+ * assertion is the complement: it pins the adapter's REAL `Stop` payload so `readBoundarySignal`'s
+ * field access can't drift silently. (A `SessionBase<S extends TurnSession>` bound would NOT
+ * enforce hook-capability — method-parameter bivariance lets a hook-less `on` satisfy the `hook`
+ * overload — which is why the abstract method + this assertion, not a generic bound, are the guard.)
+ */
+export type AssertStopBoundary<T> = keyof TurnBoundaryContract extends keyof T ? Pick<Required<T>, keyof TurnBoundaryContract & keyof T> extends TurnBoundaryContract ? true : never : never;
+/**
+ * The narrow session surface a turn drives: the common events plus the adapter `hook`
+ * event (whose `Stop` payload's `last_assistant_message` is the completeness oracle). Any
+ * Elwood session satisfies this — both `ClaudeEventMap` and `CodexEventMap` carry `hook`.
+ */
+export type TurnSession = Pick<ElwoodAgentSession, "status" | "sendMessage"> & {
+    on<E extends keyof ElwoodCommonEventMap>(event: E, handler: (event: ElwoodCommonEventMap[E]) => void): () => void;
+    on(event: "hook", handler: (event: TurnBoundaryHook) => void): () => void;
+};
+/** Per-call PUBLIC turn options (the caller-facing subset of `StreamTurnOptions`). */
+export type TurnOptions = {
+    /** Opt-in whole-turn ceiling → `wait_timeout`. Default NONE — a turn may run for hours. */
+    readonly timeoutMs?: number;
+    /** Cap on transcript catch-up AFTER `ready` (default 10s); a stalled flush → `wait_timeout`. */
+    readonly catchUpMs?: number;
+    /** Readable images attached, in order, to this same user turn. */
+    readonly images?: readonly ImageInput[];
+};
+export type StreamTurnOptions = {
+    /** Optional whole-turn ceiling; default NONE — a live turn may run for hours. */
+    readonly timeoutMs?: number;
+    /** Cap on transcript catch-up after `ready` (default 10s); a stalled flush → `wait_timeout`. */
+    readonly catchUpMs?: number;
+    /** Readable images attached, in order, to this same user turn. */
+    readonly images?: readonly ImageInput[];
+    /** Quiet-window for a no-oracle turn to settle after `ready` (default 2000ms). */
+    readonly fallbackQuietMs?: number;
+    /** Cap on unconsumed buffered events before failing (default 100000); internal/tests. */
+    readonly maxPendingEvents?: number;
+    /** Cap on unconsumed buffered bytes before failing (default 64 MiB); internal/tests. */
+    readonly maxPendingBytes?: number;
+    /** Post-failure `ready` transcript-drain settle (default 750ms); internal/tests. */
+    readonly drainMs?: number;
+    /**
+     * Normalizes an adapter `hook` event into the completeness signal (default:
+     * `defaultBoundarySignal`, the `Stop` hook's `last_assistant_message`). `SessionBase` subclasses
+     * pass their own so the runner never reads raw adapter hook fields.
+     */
+    readonly readBoundarySignal?: BoundarySignalReader;
+};
+/** A running turn: `events`/`completion` are the consumer view; `boundary` gates the serializer. */
+export type RunningTurn = {
+    /** The turn's simplified content events; abandoning this does NOT stop the turn. */
+    readonly events: AsyncGenerator<TurnEvent>;
+    /**
+     * Always-resolving GATE-settlement signal. The runner drives it EAGERLY — it resolves when the
+     * gate settles (success or a consumer-facing failure) whether or not `events` was ever
+     * consumed; the turn's error, if any, is carried by `events`, never thrown here. It is NOT the
+     * serializer boundary (a timeout/backlog failure settles this while the agent still runs) — use
+     * `boundary` for that. Named `completion` because it marks the consumer's view of the turn done.
+     */
+    readonly completion: Promise<void>;
+    /**
+     * The serializer's slot-release signal: resolves only when the AGENT genuinely settles. On the
+     * SUCCESS path that is the gate's real end (the transcript drained); on a consumer FAILURE it is
+     * a real `ready` (a busy agent is `running`, not ready) or a terminal status, then a short drain.
+     * It does NOT resolve on the consumer failure itself, so the next turn never binds this turn's
+     * still-arriving activity.
+     */
+    readonly boundary: Promise<void>;
+};
+//# sourceMappingURL=turn-types.d.ts.map

package/dist/core/simple/turn-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-types.d.ts","sourceRoot":"","sources":["../../../src/core/simple/turn-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC5D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,SAAS,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;AAEvF,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAAG,CAAC,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,oBACiD,CAAC;AAEtF,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,EAAE,sBAEqC,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,MAAM,oBAAoB,SAAS,MAAM,CAAC,GAC1E,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,oBAAoB,GAAG,MAAM,CAAC,CAAC,SAAS,oBAAoB,GAClF,IAAI,GACJ,KAAK,GACP,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,aAAa,CAAC,GAAG;IAC7E,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,EACrC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,IAAI,GAChD,MAAM,IAAI,CAAC;IACd,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3E,CAAC;AAEF,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,kFAAkF;IAClF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,yFAAyF;IACzF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,wFAAwF;IACxF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;CACpD,CAAC;AAEF,oGAAoG;AACpG,MAAM,MAAM,WAAW,GAAG;IACxB,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,CAAC"}

package/dist/core/simple/turn-types.js

@@ -0,0 +1,15 @@
+/**
+ * Types and conformance probes for one ergonomic turn (PRD §5.8, C-API-48/53). Separated from
+ * the `runTurn` runner (turn.ts) so both stay under the file-size cap. Defines the loose
+ * boundary-hook shape the oracle reads, the compile-time drift guard adapters assert against,
+ * the narrow turn-capable session surface, and the turn's options and result shapes.
+ */
+/**
+ * The default reader: a `Stop` hook is the turn boundary and its `last_assistant_message` the
+ * completeness signal (`""` when null/absent → no oracle); any other hook is not a boundary.
+ */
+export const defaultBoundarySignal = (event) => event.hook_event_name === "Stop" ? (event.last_assistant_message ?? "") : undefined;
+/** Shared Claude/Codex acceptance: the matching submit hook or any Stop boundary. */
+export const defaultAcceptanceSignal = (event, prompt) => event.hook_event_name === "Stop" ||
+    (event.hook_event_name === "UserPromptSubmit" && event.prompt === prompt);
+//# sourceMappingURL=turn-types.js.map

package/dist/core/simple/turn-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-types.js","sourceRoot":"","sources":["../../../src/core/simple/turn-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6CH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAyB,CAAC,KAAK,EAAE,EAAE,CACnE,KAAK,CAAC,eAAe,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAEtF,qFAAqF;AACrF,MAAM,CAAC,MAAM,uBAAuB,GAA2B,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAC/E,KAAK,CAAC,eAAe,KAAK,MAAM;IAChC,CAAC,KAAK,CAAC,eAAe,KAAK,kBAAkB,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC"}

package/dist/core/simple/turn.d.ts

@@ -0,0 +1,37 @@
+/**
+ * One ergonomic turn: submit a prompt and drive the agent turn to its REAL boundary,
+ * feeding a gate the consumer reads (PRD §5.8, C-API-48/49/50).
+ *
+ * The turn boundary is a COMPLETENESS ORACLE, not a timer. A turn's assistant text is
+ * transcript-sourced (C-CLAUDE-15) and the transcript is written ASYNCHRONOUSLY, arriving
+ * shortly AFTER the `ready` status. The turn-boundary `Stop` hook carries
+ * `last_assistant_message` — the final assistant text of the just-completed turn — used
+ * ONLY as a completeness signal (never displayed — it can be ghost text): the turn ends
+ * once the transcript-collected assistant text CONTAINS it. With no such signal (a
+ * pure-tool turn, or an empty/`null` `last_assistant_message`) the turn ends after a
+ * bounded quiet window with no new content.
+ *
+ * The runner is decoupled from its consumer. `completion` always resolves when the consumer
+ * settles; its error travels through `events`. The serializer instead holds `boundary`, which
+ * resolves on a successful oracle/quiet settle or terminal status. After consumer failure it
+ * waits for real `ready`/terminal evidence plus transcript drain, so abandoned streams cannot
+ * release their slot while the agent is still producing.
+ *
+ * Timeouts: a turn may run for HOURS (a test suite, a PR poll), so there is NO whole-turn
+ * timeout by default; callers may pass an opt-in `timeoutMs`, armed only AFTER submission (a
+ * turn begins on submission — the timer must never reject a caller for a prompt still queued
+ * behind readiness that then submits anyway). The tight cap is `catchUpMs` (default 10s),
+ * armed only ONCE `ready` fires — the flush should be near-instant, so a longer stall rejects
+ * with `wait_timeout`. A terminal status ends the turn at once.
+ */
+import { type RunningTurn, type StreamTurnOptions, type TurnSession } from "./turn-types.ts";
+export type { AcceptanceSignalReader, AssertStopBoundary, BoundarySignalReader, RunningTurn, StreamTurnOptions, TurnBoundaryContract, TurnBoundaryHook, TurnSession, } from "./turn-types.ts";
+export { defaultAcceptanceSignal, defaultBoundarySignal } from "./turn-types.ts";
+/**
+ * Start a turn: attach listeners, submit the prompt, and drive the gate to the turn's real
+ * boundary. Returns the consumer `events` generator, an always-resolving `completion` signal,
+ * and the `boundary` promise the serializer holds its slot on (so the next turn never starts
+ * before the AGENT settles — see `RunningTurn` and the file docstring).
+ */
+export declare function runTurn(session: TurnSession, prompt: string, options?: StreamTurnOptions): RunningTurn;
+//# sourceMappingURL=turn.d.ts.map

package/dist/core/simple/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../../src/core/simple/turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAOjF;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,iBAAsB,GAC9B,WAAW,CAmIb"}