agentenkit 0.1.0

package/dist/core/follow.js

@@ -0,0 +1,153 @@
+/** Every event on a thread, replay first and then live, as one sequence.
+ *
+ *  The ordering here is the whole point, and it is easy to get wrong in a route
+ *  handler:
+ *
+ *   1. **Subscribe before replaying.** An event published between the replay
+ *      finishing and the tail starting is otherwise lost for ever.
+ *   2. **Never emit at or below the cursor.** The client would render it twice.
+ *   3. **`seq === 0` is a bus-only notice** (heartbeats, death notices).
+ *      Always forward it, never let it move the cursor.
+ *
+ *  Framework-neutral on purpose: an async iterable is something Express, Hono,
+ *  Nest, Next and a plain worker can each consume in their own way. */
+export async function* followEvents(deps, threadId, options = {}) {
+    const since = options.since ?? -1;
+    const { signal } = options;
+    let lastSeq = since;
+    let live = false;
+    let closed = false;
+    /** Published while the replay is still running. */
+    const pending = [];
+    /** Published once live, waiting for the consumer. */
+    const queue = [];
+    let wake = null;
+    const notify = () => {
+        const w = wake;
+        wake = null;
+        w?.();
+    };
+    // Rule 1: subscribe FIRST.
+    const unsubscribe = await deps.bus.subscribe(threadId, (event) => {
+        if (!live) {
+            pending.push(event);
+            return;
+        }
+        queue.push(event);
+        notify();
+    });
+    const onAbort = () => {
+        closed = true;
+        notify();
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    /** Rules 2 and 3 in one place, so no caller has to remember them. */
+    const admit = (event) => {
+        if (event.seq === 0)
+            return true; // a notice: forward, but do not advance
+        if (event.seq <= lastSeq)
+            return false;
+        lastSeq = event.seq;
+        return true;
+    };
+    try {
+        if (signal?.aborted)
+            return;
+        // …then the durable log…
+        for (const event of await deps.storage.events.listSince(threadId, since)) {
+            if (admit(event))
+                yield event;
+        }
+        // …then whatever arrived behind it, in order.
+        for (const event of pending.sort((a, b) => a.seq - b.seq)) {
+            if (admit(event))
+                yield event;
+        }
+        pending.length = 0;
+        live = true;
+        while (!closed && !signal?.aborted) {
+            while (queue.length > 0) {
+                const event = queue.shift();
+                if (admit(event))
+                    yield event;
+            }
+            if (closed || signal?.aborted)
+                break;
+            await new Promise((resolve) => {
+                wake = resolve;
+            });
+        }
+    }
+    finally {
+        // Runs on abort, on a consumer that stops iterating, and on error alike —
+        // a subscription that outlives its reader is a leak on every reconnect.
+        signal?.removeEventListener('abort', onAbort);
+        try {
+            await unsubscribe();
+        }
+        catch {
+            // A bus that fails to unsubscribe must not mask the reason we stopped.
+        }
+    }
+}
+/** Headers an SSE response needs. `X-Accel-Buffering` is for nginx, which
+ *  otherwise buffers the stream and makes it look like nothing is happening. */
+export const SSE_HEADERS = {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+};
+/** One event as an SSE frame.
+ *
+ *  A bus-only notice (`seq === 0`) is sent WITHOUT an `id:` line. EventSource
+ *  stores any id it sees and sends it back as `Last-Event-ID` on reconnect —
+ *  so stamping `id: 0` on a heartbeat would rewind the client's cursor to the
+ *  beginning of the thread and replay everything. */
+export function sseFrame(event) {
+    const data = JSON.stringify(event);
+    return event.seq === 0 ? `data: ${data}\n\n` : `id: ${event.seq}\ndata: ${data}\n\n`;
+}
+/** The event sequence, encoded as Server-Sent Events.
+ *
+ *  Returns the stream and the headers rather than a `Response`, because half
+ *  the ecosystem does not have one. */
+export function toSseStream(events, options = {}) {
+    const encoder = new TextEncoder();
+    let started = false;
+    const stream = new ReadableStream({
+        // `pull` rather than `start`: the consumer sets the pace, and a slow client
+        // does not make an unbounded queue of encoded frames.
+        async pull(controller) {
+            if (!started) {
+                started = true;
+                if (options.retryMs !== undefined) {
+                    controller.enqueue(encoder.encode(`retry: ${options.retryMs}\n\n`));
+                    return;
+                }
+            }
+            try {
+                const { value, done } = await events.next();
+                if (done) {
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(encoder.encode(sseFrame(value)));
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        // The client hung up: stop the generator so its `finally` unsubscribes.
+        async cancel() {
+            try {
+                await events.return(undefined);
+            }
+            catch {
+                // already finished
+            }
+        },
+    });
+    return { stream, headers: SSE_HEADERS };
+}
+//# sourceMappingURL=follow.js.map

package/dist/core/follow.js.map

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

package/dist/core/hitl.d.ts

@@ -0,0 +1,98 @@
+import type { RuntimePorts } from '../ports/runtime.js';
+import type { RespondInput, RespondResult } from '../ports/runtime.js';
+import type { NestedDescriptor, ResumeInfo } from './types.js';
+export declare const HITL_TTL_MS: number;
+/** Result value a parked `requiresConfirmation` tool returns (§2.5). The
+ *  engine scans a step's tool results for this marker to end the run segment;
+ *  it is never persisted as a tool result — the resumed segment appends the
+ *  user's verdict (or the timeout denial) instead. */
+export declare const HITL_PARKED = "__hitl_parked__";
+export declare const hitlKey: (toolCallId: string) => string;
+export interface HitlResponse {
+    approved: boolean;
+    payload?: unknown;
+}
+/** One tool call left waiting on an approval further down (§2.7). A park by
+ *  the main agent has none; a park inside a nested run has one per level, the
+ *  innermost waiter first. `agentId` names the stream the waiting call lives
+ *  in — `null` for the main agent. */
+export interface HitlFrame {
+    agentId: string | null;
+    toolCallId: string;
+    /** How to re-enter the owner's loop when this frame unwinds. Absent for the
+     *  main agent, whose loop the engine re-enters itself. */
+    nested?: NestedDescriptor;
+}
+export interface ParkInput {
+    threadId: string;
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    agentId?: string | null;
+    /** The calls waiting on this answer, innermost first (§2.7). Empty for a
+     *  main-agent park, which reduces this to the plain §2.5 flow. */
+    frames?: HitlFrame[];
+    /** The nested run that raised this park; absent when the main agent did. */
+    nested?: NestedDescriptor;
+    /** Dispatch ticket persisted in the INPUT_REQUIRED payload (§2.5) */
+    resume: ResumeInfo;
+}
+/** Wrap every marked tool so a call parks (§2.5) instead of executing: the
+ *  request is persisted as INPUT_REQUIRED and the wrapper returns the park
+ *  sentinel — nothing blocks. The real tool runs when the park is resolved
+ *  (see resumePendingHitl), in whichever stream owns it.
+ *
+ *  Shared by the main agent and every nested run (§2.7): the only difference
+ *  is the `agentId` asking and the `frames` waiting on the answer. */
+export declare function withHitl(deps: RuntimePorts, threadId: string, tools: Record<string, any>, ctx: {
+    resume: ResumeInfo;
+    agentId?: string | null;
+    frames?: HitlFrame[];
+    nested?: NestedDescriptor;
+}): Record<string, any>;
+/** The §2.5 suspension as a durable state transition — NO process waits.
+ *  Flips WAITING_FOR_INPUT on both homes and appends INPUT_REQUIRED to the
+ *  replayable event log (with the resume ticket). The engine then ends the
+ *  run segment; /api/agent/respond (or the expiry job below) resumes it via
+ *  the queue.
+ *
+ *  The park also schedules its OWN expiry: one delayed dispatch of the same
+ *  run, timed for just after the TTL. Without it the deadline only exists
+ *  while somebody happens to be watching the thread — close the tab and the
+ *  approval never times out at all. The delayed job holds no process; the
+ *  queue holds it, exactly like the original dispatch (§2.8).
+ *
+ *  It carries the PARKED run's id, so the answer and the expiry are two
+ *  deliveries of one run: whichever resolves the park first wins, and the
+ *  run lock makes the other a no-op. */
+export declare function parkForApproval(deps: RuntimePorts, i: ParkInput): Promise<void>;
+/** The pending request behind a WAITING_FOR_INPUT thread, hydrated from the
+ *  durable event log (§2.5). */
+export interface PendingHitl {
+    toolCallId: string;
+    toolName: string;
+    agentId: string | null;
+    arguments: unknown;
+    /** Calls waiting on this answer, innermost first (§2.7). */
+    frames: HitlFrame[];
+    /** The nested run that raised it; absent for a main-agent park. */
+    nested?: NestedDescriptor;
+    /** Epoch ms of the INPUT_REQUIRED event — the TTL clock (§2.5) */
+    requestedAt: number;
+}
+export declare function loadPendingHitl(deps: RuntimePorts, threadId: string): Promise<PendingHitl | null>;
+/** Every approval on the thread that is still open (§2.7).
+ *
+ *  Derived from durable state, never cached: a request is settled once a tool
+ *  result carries its `toolCallId` — in whichever stream owns it — or an
+ *  INPUT_EXPIRED event names it. Both are already written on the settling
+ *  path. A cached set would be a read-modify-write race between exactly the
+ *  concurrent siblings this exists to serve, since Kv has no set operations. */
+export declare function loadOpenHitls(deps: RuntimePorts, threadId: string): Promise<PendingHitl[]>;
+/** The §5.4 behavior: heal orphans first (§2.5), then record the answer in
+ *  the handoff key and resume the run segment via the queue (§2.8) — the
+ *  resumed worker appends the tool result and continues the loop.
+ *  Answer-latest policy: only the most recent pending INPUT_REQUIRED is
+ *  answerable (§2.7). */
+export declare function respond(deps: RuntimePorts, input: RespondInput): Promise<RespondResult>;
+//# sourceMappingURL=hitl.d.ts.map

package/dist/core/hitl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","sourceRoot":"","sources":["../../src/core/hitl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAc,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK3E,eAAO,MAAM,WAAW,QAAc,CAAC;AAEvC;;;sDAGsD;AACtD,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAE7C,eAAO,MAAM,OAAO,GAAI,YAAY,MAAM,WAA+B,CAAC;AAE1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;sCAGsC;AACtC,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB;8DAC0D;IAC1D,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;sEACkE;IAClE,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qEAAqE;IACrE,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;sEAMsE;AACtE,wBAAgB,QAAQ,CACtB,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,GAAG,EAAE;IACH,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,GACA,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA0BrB;AAED;;;;;;;;;;;;;;wCAcwC;AACxC,wBAAsB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCrF;AAED;gCACgC;AAChC,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,mEAAmE;IACnE,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAI7B;AAuBD;;;;;;gFAMgF;AAChF,wBAAsB,aAAa,CACjC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,EAAE,CAAC,CAqBxB;AAED;;;;yBAIyB;AACzB,wBAAsB,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAgE7F"}

package/dist/core/hitl.js

@@ -0,0 +1,199 @@
+import { randomUUID } from 'node:crypto';
+import { publish, setThreadState } from './publish.js';
+import { currentRunId } from './keys.js';
+import { reclaimGraceAfterMs, reclaimIfOrphaned } from './reclaim.js';
+export const HITL_TTL_MS = 15 * 60_000;
+/** Result value a parked `requiresConfirmation` tool returns (§2.5). The
+ *  engine scans a step's tool results for this marker to end the run segment;
+ *  it is never persisted as a tool result — the resumed segment appends the
+ *  user's verdict (or the timeout denial) instead. */
+export const HITL_PARKED = '__hitl_parked__';
+export const hitlKey = (toolCallId) => `agent:hitl:${toolCallId}`;
+/** Wrap every marked tool so a call parks (§2.5) instead of executing: the
+ *  request is persisted as INPUT_REQUIRED and the wrapper returns the park
+ *  sentinel — nothing blocks. The real tool runs when the park is resolved
+ *  (see resumePendingHitl), in whichever stream owns it.
+ *
+ *  Shared by the main agent and every nested run (§2.7): the only difference
+ *  is the `agentId` asking and the `frames` waiting on the answer. */
+export function withHitl(deps, threadId, tools, ctx) {
+    const out = {};
+    for (const [name, t] of Object.entries(tools)) {
+        if (!t?.requiresConfirmation) {
+            out[name] = t;
+            continue;
+        }
+        out[name] = {
+            ...t,
+            execute: async (args, opts) => {
+                const toolCallId = opts?.toolCallId ?? randomUUID();
+                await parkForApproval(deps, {
+                    threadId,
+                    toolCallId,
+                    toolName: name,
+                    args,
+                    agentId: ctx.agentId ?? null,
+                    frames: ctx.frames ?? [],
+                    ...(ctx.nested ? { nested: ctx.nested } : {}),
+                    resume: ctx.resume,
+                });
+                return { [HITL_PARKED]: toolCallId };
+            },
+        };
+    }
+    return out;
+}
+/** The §2.5 suspension as a durable state transition — NO process waits.
+ *  Flips WAITING_FOR_INPUT on both homes and appends INPUT_REQUIRED to the
+ *  replayable event log (with the resume ticket). The engine then ends the
+ *  run segment; /api/agent/respond (or the expiry job below) resumes it via
+ *  the queue.
+ *
+ *  The park also schedules its OWN expiry: one delayed dispatch of the same
+ *  run, timed for just after the TTL. Without it the deadline only exists
+ *  while somebody happens to be watching the thread — close the tab and the
+ *  approval never times out at all. The delayed job holds no process; the
+ *  queue holds it, exactly like the original dispatch (§2.8).
+ *
+ *  It carries the PARKED run's id, so the answer and the expiry are two
+ *  deliveries of one run: whichever resolves the park first wins, and the
+ *  run lock makes the other a no-op. */
+export async function parkForApproval(deps, i) {
+    await deps.kv.set(`agent:state:${i.threadId}`, 'WAITING_FOR_INPUT');
+    await setThreadState(deps, i.threadId, 'WAITING_FOR_INPUT', i.resume.model);
+    await publish(deps, i.threadId, 'INPUT_REQUIRED', {
+        toolCallId: i.toolCallId,
+        toolName: i.toolName,
+        agentId: i.agentId ?? null,
+        arguments: i.args,
+        inputSchema: null,
+        // The unwind chain (§2.7) — empty for a main-agent park.
+        frames: i.frames ?? [],
+        ...(i.nested ? { nested: i.nested } : {}),
+        resume: i.resume,
+    });
+    await publish(deps, i.threadId, 'STATE_CHANGE', { state: 'WAITING_FOR_INPUT' });
+    // Best-effort, and deliberately last. The park is ALREADY durable by this
+    // point — state flipped on both homes, INPUT_REQUIRED on the event log — so
+    // a queue that cannot schedule must not be allowed to throw back through the
+    // tool call and fail the run. Reclamation (§2.5) covers the thread instead.
+    //
+    // Arriving early is equally harmless: an unexpired, unanswered request
+    // resolves to nothing and the job is a no-op (see resumePendingHitl).
+    try {
+        await deps.queue.enqueue({
+            threadId: i.threadId,
+            runId: await currentRunId(deps, i.threadId),
+            model: i.resume.model,
+            agent: i.resume.agent,
+            ...(i.resume.tokenBudget !== undefined ? { tokenBudget: i.resume.tokenBudget } : {}),
+            ...(i.resume.providerOptions ? { providerOptions: i.resume.providerOptions } : {}),
+            ...(i.resume.state ? { state: i.resume.state } : {}),
+        }, { delaySeconds: Math.ceil(reclaimGraceAfterMs(deps) / 1000) });
+    }
+    catch {
+        // No expiry scheduled — the thread still heals on first touch (§2.5).
+    }
+}
+export async function loadPendingHitl(deps, threadId) {
+    const pending = await deps.storage.events.latest(threadId, 'INPUT_REQUIRED');
+    if (!pending)
+        return null;
+    return fromInputRequired(pending);
+}
+function fromInputRequired(pending) {
+    const p = pending.payload;
+    return {
+        toolCallId: p.toolCallId,
+        toolName: p.toolName,
+        agentId: p.agentId ?? null,
+        arguments: p.arguments,
+        // A park recorded before frames existed unwinds as a main-agent park.
+        frames: p.frames ?? [],
+        ...(p.nested ? { nested: p.nested } : {}),
+        requestedAt: new Date(pending.createdAt).getTime(),
+    };
+}
+/** Every approval on the thread that is still open (§2.7).
+ *
+ *  Derived from durable state, never cached: a request is settled once a tool
+ *  result carries its `toolCallId` — in whichever stream owns it — or an
+ *  INPUT_EXPIRED event names it. Both are already written on the settling
+ *  path. A cached set would be a read-modify-write race between exactly the
+ *  concurrent siblings this exists to serve, since Kv has no set operations. */
+export async function loadOpenHitls(deps, threadId) {
+    const requested = await deps.storage.events.listByType(threadId, 'INPUT_REQUIRED');
+    if (requested.length === 0)
+        return [];
+    const expired = new Set((await deps.storage.events.listByType(threadId, 'INPUT_EXPIRED')).map((e) => e.payload?.toolCallId));
+    const answered = new Set();
+    for (const m of await deps.storage.messages.list(threadId, undefined)) {
+        if (m.role !== 'tool')
+            continue;
+        for (const part of Array.isArray(m.content) ? m.content : []) {
+            const id = part?.toolCallId;
+            if (id)
+                answered.add(id);
+        }
+    }
+    return requested
+        .map((e) => fromInputRequired(e))
+        .filter((p) => !answered.has(p.toolCallId) && !expired.has(p.toolCallId));
+}
+/** The §5.4 behavior: heal orphans first (§2.5), then record the answer in
+ *  the handoff key and resume the run segment via the queue (§2.8) — the
+ *  resumed worker appends the tool result and continues the loop.
+ *  Answer-latest policy: only the most recent pending INPUT_REQUIRED is
+ *  answerable (§2.7). */
+export async function respond(deps, input) {
+    await reclaimIfOrphaned(deps, input.threadId);
+    const thread = await deps.storage.threads.get(input.threadId);
+    // ANY open request is answerable, not just the newest (§2.7): one parent
+    // step can park several nested runs at once, and each is answered on its
+    // own. The run resumes when the last of them is settled.
+    const open = await loadOpenHitls(deps, input.threadId);
+    const match = open.find((p) => p.toolCallId === input.toolCallId);
+    if (thread?.state !== 'WAITING_FOR_INPUT' || !match) {
+        return { delivered: false, error: 'No matching pending input request' };
+    }
+    // Remaining-TTL expiry so a stale answer can never outlive its request: the
+    // key vanishing is what makes the resumed segment treat the request as
+    // unanswered (§2.5)
+    const remainingSec = Math.max(60, Math.floor((deps.config.hitlTtlMs - (Date.now() - match.requestedAt)) / 1000));
+    await deps.kv.set(hitlKey(input.toolCallId), JSON.stringify({ approved: input.approved, payload: input.payload }), { exSeconds: remainingSec });
+    // Bus-only fast-path notice (seq 0 = never persisted) for live UIs (§2.5)
+    await deps.bus.publish(input.threadId, {
+        threadId: input.threadId,
+        seq: 0,
+        type: 'HITL_RESPONSE',
+        payload: { toolCallId: input.toolCallId, approved: input.approved },
+        createdAt: new Date(),
+    });
+    // Resume the run segment through the queue — same dispatch path as the
+    // original run, rebuilt from the ticket persisted in the event payload.
+    // A legacy park without a ticket falls back to the default handle.
+    const requested = await deps.storage.events.listByType(input.threadId, 'INPUT_REQUIRED');
+    const event = requested.find((e) => e.payload?.toolCallId === input.toolCallId);
+    const resume = event?.payload?.resume;
+    // REUSE the parked run's id, never mint a new one: this dispatch and the
+    // park's expiry job are the same run, and the lock must be able to tell
+    // that. Bumping here would let both run and reply twice (§2.5).
+    const runId = await currentRunId(deps, input.threadId);
+    await deps.queue.enqueue({
+        threadId: input.threadId,
+        runId,
+        model: resume?.model ?? thread.model,
+        ...(resume
+            ? {
+                agent: resume.agent,
+                ...(resume.tokenBudget !== undefined ? { tokenBudget: resume.tokenBudget } : {}),
+                ...(resume.providerOptions ? { providerOptions: resume.providerOptions } : {}),
+                // The answer resumes the SAME run, so it must scope storage the same
+                // way the parked segment did (§2.10).
+                ...(resume.state ? { state: resume.state } : {}),
+            }
+            : {}),
+    });
+    return { delivered: true };
+}
+//# sourceMappingURL=hitl.js.map

package/dist/core/hitl.js.map

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

package/dist/core/keys.d.ts

@@ -0,0 +1,26 @@
+import type { RuntimePorts } from '../ports/runtime.js';
+/** The thread's CURRENT run id (§2.1).
+ *
+ *  Stop and start-a-new-run both write `agent:state:{threadId}`, so the state
+ *  key alone can never tell a worker its run is over: a user who stops and
+ *  then sends another message overwrites CANCELLED with RUNNING before the
+ *  worker's poll ever reads it, and the old run keeps going.
+ *
+ *  This key only moves forward. A worker whose id no longer matches knows it
+ *  has been replaced, whatever the state key says. */
+export declare const runIdKey: (threadId: string) => string;
+/** Re-dispatch counter for a job that keeps finding the run lock held by an
+ *  OLDER run (§2.8). Separate from `agent:attempts:` — a blocked job has not
+ *  failed, it simply has not started yet. */
+export declare const redriveKey: (threadId: string) => string;
+/** The run that owns the thread right now, or null on a thread that predates
+ *  run ids. Resuming a parked run (§2.5) REUSES this — a resume is the same
+ *  run continuing, not a new one, so it must never bump the id. */
+export declare function currentRunId(deps: RuntimePorts, threadId: string): Promise<string | undefined>;
+/** Claim the thread for a brand new run and return its id (§2.1).
+ *
+ *  Always called BEFORE the state key is written: bumping this id is what
+ *  retires an older worker, and it must not depend on the state key that the
+ *  new run is about to overwrite. */
+export declare function claimRun(deps: RuntimePorts, threadId: string): Promise<string>;
+//# sourceMappingURL=keys.d.ts.map

package/dist/core/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/core/keys.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;sDAQsD;AACtD,eAAO,MAAM,QAAQ,GAAI,UAAU,MAAM,WAA4B,CAAC;AAEtE;;6CAE6C;AAC7C,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,WAAgC,CAAC;AAE5E;;mEAEmE;AACnE,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED;;;;qCAIqC;AACrC,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIpF"}

package/dist/core/keys.js

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+/** The thread's CURRENT run id (§2.1).
+ *
+ *  Stop and start-a-new-run both write `agent:state:{threadId}`, so the state
+ *  key alone can never tell a worker its run is over: a user who stops and
+ *  then sends another message overwrites CANCELLED with RUNNING before the
+ *  worker's poll ever reads it, and the old run keeps going.
+ *
+ *  This key only moves forward. A worker whose id no longer matches knows it
+ *  has been replaced, whatever the state key says. */
+export const runIdKey = (threadId) => `agent:run:${threadId}`;
+/** Re-dispatch counter for a job that keeps finding the run lock held by an
+ *  OLDER run (§2.8). Separate from `agent:attempts:` — a blocked job has not
+ *  failed, it simply has not started yet. */
+export const redriveKey = (threadId) => `agent:redrive:${threadId}`;
+/** The run that owns the thread right now, or null on a thread that predates
+ *  run ids. Resuming a parked run (§2.5) REUSES this — a resume is the same
+ *  run continuing, not a new one, so it must never bump the id. */
+export async function currentRunId(deps, threadId) {
+    return (await deps.kv.get(runIdKey(threadId))) ?? undefined;
+}
+/** Claim the thread for a brand new run and return its id (§2.1).
+ *
+ *  Always called BEFORE the state key is written: bumping this id is what
+ *  retires an older worker, and it must not depend on the state key that the
+ *  new run is about to overwrite. */
+export async function claimRun(deps, threadId) {
+    const runId = randomUUID();
+    await deps.kv.set(runIdKey(threadId), runId);
+    return runId;
+}
+//# sourceMappingURL=keys.js.map

package/dist/core/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/core/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;;;sDAQsD;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC,aAAa,QAAQ,EAAE,CAAC;AAEtE;;6CAE6C;AAC7C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC,iBAAiB,QAAQ,EAAE,CAAC;AAE5E;;mEAEmE;AACnE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAkB,EAClB,QAAgB;IAEhB,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;AAC9D,CAAC;AAED;;;;qCAIqC;AACrC,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAkB,EAAE,QAAgB;IACjE,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;IAC7C,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/loop.d.ts

@@ -0,0 +1,105 @@
+import type { LanguageModel } from 'ai';
+import type { RuntimePorts } from '../ports/runtime.js';
+import type { AgentKind, ProviderOptions } from './types.js';
+import type { RegisteredAgent } from './agent.js';
+import { type TokenAttribution } from './usage.js';
+/** True for the sentinel a parked `requiresConfirmation` tool returns (§2.5).
+ *  It is never a real tool result and is never persisted. */
+export declare const isParked: (result: unknown) => boolean;
+/** One platform-owned step (§2.1, §5.6): a single SDK round-trip with
+ *  maxSteps: 1. The SDK executes the step's tool calls and reports a
+ *  structured result; whether to continue is the loop's decision, never
+ *  the SDK's. */
+export interface StepResult {
+    text: string;
+    finishReason: string;
+    usage: Record<string, number> | undefined;
+    /** Assistant + tool messages this step produced — appended to the
+     *  conversation (in memory AND storage) before the next step. */
+    responseMessages: Array<{
+        role: string;
+        content: unknown;
+    }>;
+    /** The step's executed tool calls and their results. */
+    toolResults: Array<{
+        toolCallId: string;
+        toolName: string;
+        result: unknown;
+    }>;
+    /** Provider metadata for this step — the only place a cache hit is reported
+     *  (§2.6). Without carrying it, cachedInputTokens can never be anything but
+     *  zero. */
+    providerMetadata?: Record<string, Record<string, unknown> | undefined>;
+}
+export declare function executeStep(agent: RegisteredAgent, call: {
+    kind: AgentKind;
+    model: LanguageModel;
+    messages: Array<any>;
+    tools: Record<string, any>;
+    providerOptions?: ProviderOptions;
+    abortSignal: AbortSignal;
+    onChunk?: (chunk: unknown) => Promise<void>;
+    /** Overrides the user's spec args — a nested run brings its own persona
+     *  and must not inherit the parent's (§2.7). */
+    system?: string;
+    /** Move the system prompt into `messages` as a stamped message so it can
+     *  carry a cache breakpoint (§2.6). As the SDK's `system:` string it
+     *  reaches the provider with no metadata channel and never caches. */
+    cacheSystemPrompt?: boolean;
+}): Promise<StepResult>;
+/** Tokens a run has spent, main agent and nested runs together (§2.7). Shared
+ *  by reference so a child's spend counts against the run's safety cap the
+ *  moment it happens — a budget that ignores delegated work is not a budget. */
+export interface RunLedger {
+    tokensUsed: number;
+}
+export interface LoopInput {
+    /** Whose stream this loop persists to (§2.7). `null` is the main agent. */
+    agentId: string | null;
+    /** The run these steps belong to (§2.9) — a thread has many runs, so a step
+     *  marker without it cannot be attributed to one. */
+    runId?: string;
+    kind: AgentKind;
+    model: LanguageModel;
+    /** Seeded context: compacted history for the main agent, the brief plus its
+     *  own persisted turns for a nested run. Mutated as steps are appended. */
+    messages: Array<any>;
+    tools: Record<string, any>;
+    maxSteps: number;
+    abortSignal: AbortSignal;
+    providerOptions?: ProviderOptions;
+    /** Cumulative cap for the whole run, checked against the shared ledger. */
+    tokenBudget?: number;
+    onChunk?: (chunk: unknown) => Promise<void>;
+    /** Persona for a nested run; omitted, the agent's own spec `system` stands. */
+    system?: string;
+    /** Carry the system prompt as a stamped message rather than the SDK's
+     *  `system:` string, so it can hold a cache breakpoint (§2.6). */
+    cacheSystemPrompt?: boolean;
+}
+export interface LoopOutcome {
+    text: string;
+    finishReason: string;
+    /** What THIS loop spent — the caller records it against its own agentId. */
+    attribution: TokenAttribution;
+    tokensUsed: number;
+    /** A requiresConfirmation tool parked: the segment ends here (§2.5). */
+    parked: boolean;
+    /** The parked call, when `parked`. */
+    parkedToolCallId?: string;
+    /** The abort signal fired mid-loop — a user stop (§2.1). */
+    aborted: boolean;
+    /** Iterations this loop completed (§2.9). */
+    steps: number;
+}
+/** The platform-owned loop (§2.1, §5.6), run by the main agent and by every
+ *  nested run alike (§2.7).
+ *
+ *  One single-round-trip step per iteration. After EVERY step the produced
+ *  messages are persisted under this loop's `agentId`, so a worker that dies
+ *  mid-run resumes from the last step — and so a parked nested run can be
+ *  re-entered later instead of restarted. Every continuation decision — tool
+ *  results ready, budget spent, step ceiling, HITL park, user stop — is made
+ *  here between steps, never inside the SDK. */
+export declare function runLoop(deps: RuntimePorts, agent: RegisteredAgent, threadId: string, input: LoopInput, ledger: RunLedger): Promise<LoopOutcome>;
+//# sourceMappingURL=loop.d.ts.map