gemi 0.60.0 → 0.61.0

package/dist/ai/signing.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Signing for pending tool calls.
+ *
+ * A pending call travels through the browser and comes back — in stateless mode
+ * the whole history does — so the server cannot trust that what it gets back is
+ * what it sent. Without a signature the client asserts not just *that* a call
+ * was approved but *what* was approved, and nothing would stop it from
+ * returning `approve: true` against an input it rewrote on the way. Signing is
+ * what makes the round trip safe, and it is why approvals need no server-side
+ * storage at all.
+ *
+ * What is signed, and what deliberately is not:
+ *
+ *   signed — `runId`, `toolCallId`, the tool `name`, the `kind` of pending call
+ *            and a canonical serialization of the input, plus a nonce, an
+ *            expiry, and — for a call a sub-agent asked — the `path` of
+ *            tool-call ids it is nested under.
+ *   not    — the client's answer. `approve: true` / `approve: false` and a
+ *            question's output are the *point* of asking; a client that flips
+ *            its own answer has refused, not forged. What the signature buys is
+ *            that the answer is bound to the call the server actually made,
+ *            with the input the server actually saw.
+ *
+ * A verified token is not yet an answer the server may act on: it says the
+ * question was asked, not that it is still open. `consumePendingCall` at the
+ * bottom of this file spends the nonce, which is what makes an approval
+ * single-use — see the note there for what that guarantee is worth.
+ *
+ * `kind` is in there for a specific attack: an `approval`-kind call is one the
+ * *server* runs, so a client that reused its signature on the "here is the
+ * output" arm of `ClientToolResult` would be fabricating a server tool's result
+ * rather than approving it. Binding the kind makes that a forgery instead of a
+ * shape the caller has to remember to check.
+ */
+/** Everything the signature commits to. */
+export type PendingCallClaims = {
+    runId: string;
+    toolCallId: string;
+    name: string;
+    kind: "approval" | "question" | "client";
+    input: unknown;
+    /**
+     * The chain of tool-call ids the call is nested under, outermost first.
+     * Absent — or empty, which means the same thing — for a top-level call.
+     *
+     * A sub-agent's question reaches the user through its parent's pending list,
+     * so `toolCallId` stops being an address on its own: two sub-runs under two
+     * different tools can each hold a call the outer run never made. Binding the
+     * path is what stops a token minted for a call nested under tool call X from
+     * being replayed as a top-level call, or as one nested under Y.
+     */
+    path?: string[];
+};
+export type SignOptions = {
+    /** Overrides `process.env.SECRET`. Exists for tests; apps use the app key. */
+    secret?: string;
+    /**
+     * Default 24 hours. An approval waits on a human, and humans go to lunch —
+     * a short expiry turns "I approved it after standup" into an unexplained
+     * failure. Long enough to survive a working day, short enough that a token
+     * lifted from a log is not useful next month.
+     */
+    ttlMs?: number;
+    /** Injected clock, so the expiry path is testable without waiting. */
+    now?: number;
+};
+export type VerifyOptions = {
+    secret?: string;
+    now?: number;
+};
+/**
+ * A discriminated result rather than a boolean, because the two failures are
+ * different events: `expired` is a sentence to show the user, `forged` is worth
+ * logging and possibly alerting on. Collapsing them loses the only signal that
+ * says someone is probing.
+ */
+export type VerifyResult = {
+    ok: true;
+    runId: string;
+    nonce: string;
+    expiresAt: number;
+} | {
+    ok: false;
+    reason: "malformed" | "expired" | "forged";
+};
+/**
+ * Serializes a value so that the same value always produces the same string.
+ *
+ * `JSON.stringify` is not enough: it preserves insertion order, so an input
+ * that made a round trip through a client — parsed and re-serialized, with the
+ * keys in whatever order the parser produced — would hash differently and a
+ * legitimate approval would come back looking forged. Keys are sorted,
+ * `undefined` members are dropped (they do not survive JSON anyway), and arrays
+ * keep their order because in an array order *is* the value.
+ */
+export declare function canonicalize(value: unknown): string;
+/** `agt1.<runId>.<nonce>.<expiry>.<mac>`, all base64url or base36. */
+export declare function signPendingCall(claims: PendingCallClaims, options?: SignOptions): string;
+/**
+ * The metadata a signature carries in the clear.
+ *
+ * `Agent` needs the issuing `runId` before it can verify anything: the call was
+ * signed under the run that made it, and the turn answering it is a *new* run
+ * with a new id. Reading it out of the token is safe because the token's own
+ * MAC covers it — a client that edits the runId here fails verification, so
+ * this is "which run does this claim to belong to", not "which run does the
+ * client say it belongs to".
+ */
+export declare function readSignature(signature: string): {
+    runId: string;
+    nonce: string;
+    expiresAt: number;
+} | null;
+export declare function verifyPendingCall(signature: string, claims: PendingCallClaims, options?: VerifyOptions): VerifyResult;
+/**
+ * What a parked sub-run's record is signed over.
+ *
+ * `ToolCallPart.nested` is the parent's own record of where a sub-run stopped,
+ * and in stateless mode it makes the same trip through the browser a pending
+ * call does. The next turn *runs a tool* on the strength of that record — the
+ * tool is re-entered because the record says a sub-run under it is waiting on
+ * the question being answered — so an unsigned record lets the client choose
+ * which tools run, with what input, before any answer is verified. A MAC over
+ * what the server actually recorded is what makes the record safe to carry.
+ *
+ * Only a parked record is signed, because only a parked record executes
+ * anything: a finished sub-run is replayed out of its transcript and spends
+ * nothing, and a client that forges one has fed its own tool a made-up answer,
+ * which a client-carried history already allows everywhere.
+ *
+ * Deliberately not signed: the transcript. The sub-run resumes from messages
+ * the client carried, exactly as the parent does in stateless mode, and the
+ * same argument applies — what the signature pins is that the server parked
+ * *here*, on *these* calls, with *this* input, and not what was said on the
+ * way.
+ */
+export type NestedRunClaims = {
+    /** The root run's id, the one every pending call of the tree is minted under. */
+    runId: string;
+    /**
+     * Tool-call ids from the root down to and including the call the record
+     * hangs off. A sub-run's id is not an address on its own for the same reason
+     * a nested call's is not: two sub-runs under two different tools can carry
+     * the same one.
+     */
+    path: string[];
+    /** The sub-run's own id, so a record cannot be moved between sub-runs. */
+    nestedRunId: string;
+    /** The tool calls the sub-run is waiting on: every call left open in its transcript. */
+    open: string[];
+    /**
+     * The input the tool that parked was running on, as the transcript carries
+     * it. Re-entry runs the tool body with the input the history holds, and the
+     * history is the client's — so a record that pinned where the sub-run parked
+     * but not what its tool was given would let the client keep the run and
+     * rewrite the arguments to anything the schema accepts. The same bargain a
+     * pending call makes: the input executed is the input signed.
+     */
+    input: unknown;
+};
+/**
+ * Same shape as a pending call's token, so the same reader serves both — nonce
+ * included, and the nonce is spent, by `consumeNestedRun` below. A verified
+ * record is permission to run the tool it hangs off, and the tool body runs
+ * before the sub-run gets to look at the answer's own nonce; a record that
+ * could be presented twice would run the body twice before anything refused
+ * the replay. Every park mints a fresh record, so spending one costs a
+ * legitimate re-park nothing.
+ */
+export declare function signNestedRun(claims: NestedRunClaims, options?: SignOptions): string;
+/**
+ * The run that verifies a record is never the run that minted it — the turn
+ * answering a question is a new run with a new id — so the minting run's id is
+ * read out of the token rather than asked of the caller, which has no other
+ * source for it. The MAC covers it, so a client that edits the id in the clear
+ * fails here rather than being believed.
+ */
+export declare function verifyNestedRun(signature: string, claims: Omit<NestedRunClaims, "runId">, options?: VerifyOptions): VerifyResult;
+/**
+ * Spends a signature's nonce. `false` means it was already spent — the answer
+ * is a replay and must not be acted on.
+ *
+ * Separate from `verifyPendingCall` rather than folded into it, because verify
+ * is a pure question a caller may want to ask twice (logging a forgery, say)
+ * and this one is a state change that must happen exactly once per answer.
+ */
+export declare function consumePendingCall(signature: string, options?: VerifyOptions): boolean;
+/**
+ * Spends a parked-run record's nonce, on the same registry and the same terms.
+ * `false` means the record has already re-entered its tool once — the turn is
+ * a replay of a history from before the answer was delivered, and the body
+ * must not run again on it.
+ */
+export declare function consumeNestedRun(signature: string, options?: VerifyOptions): boolean;
+//# sourceMappingURL=signing.d.ts.map

package/dist/ai/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../ai/signing.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC;AAkB9D;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYnD;AAkDD,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAO5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE5D;AA6BD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAwBd;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAmBF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAOxF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,EACtC,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAwBd;AA2CD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAExF"}

package/dist/ai/store/LiveRuns.d.ts

@@ -0,0 +1,142 @@
+import type { AgentRun } from "../Agent";
+import type { LiveRuns } from "../AgentController";
+import type { AgentStreamEvent, AgentStreamFrame } from "../types";
+/**
+ * A cursor older than anything still buffered.
+ *
+ * Deliberately an error rather than "here is the tail I still have". A client
+ * that asked for frame 12 and silently got frame 300 onwards has a transcript
+ * with a hole in it and no way to know — it will render a half-message, or an
+ * `awaiting-input` for a tool call it never saw. Saying so lets the client do
+ * the only correct thing, which is to reload the thread from the store.
+ */
+export declare class FrameCursorEvictedError extends Error {
+    readonly runId: string;
+    readonly requested: number;
+    readonly oldest: number;
+    readonly code = "frame_cursor_evicted";
+    constructor(runId: string, requested: number, oldest: number);
+}
+/**
+ * No run under that id in *this* process.
+ *
+ * Which is the honest answer, and the one worth being loud about: the run may
+ * well be alive on the box next door. See the note on `MemoryLiveRuns` — behind
+ * a round-robin load balancer this is what a refresh hits roughly (n-1)/n of
+ * the time, and an explicit miss is the difference between a bug someone finds
+ * in an hour and one that presents as "reattach sometimes does nothing".
+ */
+export declare class LiveRunNotFoundError extends Error {
+    readonly runId: string;
+    readonly code = "live_run_not_found";
+    constructor(runId: string);
+}
+export type RegisterParams = {
+    threadId?: string;
+    /**
+     * The client's own name for this run, minted before the run had one.
+     *
+     * `runId` does not reach the client until `run-start`, and a stateless first
+     * turn has no `threadId` either, so for the length of a network round trip
+     * plus the provider's time to first token there is nothing for `/stop` to
+     * name — which is exactly the window a user cancels in. `useChat` sends a
+     * `clientRunId` with every turn it starts; recording it here is what makes
+     * that window stoppable.
+     */
+    clientRunId?: string;
+    /**
+     * Called once per frame, in order, off the buffering path.
+     *
+     * The controller's `on*` hooks hang off this. It is a callback rather than a
+     * second `run.frames()` subscription because every extra subscriber is
+     * another consumer of a generator whose multi-subscriber behaviour we do not
+     * own, and one pump is one thing to reason about.
+     */
+    onEvent?: (event: AgentStreamEvent) => void | Promise<void>;
+    /** Reported failures: a hook that threw, or a run whose frame iterator did.
+     *  Injectable so tests can assert on it instead of reading stderr. */
+    onInternalError?: (error: unknown) => void;
+};
+/**
+ * The runs currently in flight in this process, and their recent frames.
+ *
+ * PER-PROCESS IS NOT AN IMPLEMENTATION SHORTCUT THAT A BETTER STORE FIXES. A
+ * running generator lives in one process, and a second server cannot attach to
+ * it — no amount of Redis moves an in-flight async iterator across a socket.
+ * Reattachment therefore needs the request to land where the run is: one
+ * server, sticky routing, or a proxy that forwards by `runId`. Worth saying out
+ * loud, because the failure mode behind a round-robin load balancer is a
+ * refresh that usually works.
+ *
+ * `find` and `replay` are built so that failure is an explicit miss — a 404
+ * naming the run, a 410 naming the cursor — and never an SSE stream that opens,
+ * says nothing and closes. An empty stream is indistinguishable from a run that
+ * finished quietly, which is exactly the confusion this is supposed to avoid.
+ */
+export declare class MemoryLiveRuns implements LiveRuns {
+    ttlMs: number;
+    readonly maxFrames: number;
+    private runs;
+    /** Thread to the most recently registered run for it. */
+    private byThread;
+    /** The client's pre-`run-start` name for a run, to the run. */
+    private byClientRun;
+    constructor(params?: {
+        ttlMs?: number;
+        maxFrames?: number;
+    });
+    /**
+     * Takes ownership of a run: starts buffering its frames and holds it until
+     * `ttlMs` past the end.
+     */
+    register(run: AgentRun, params?: RegisterParams): void;
+    /**
+     * The run a client named before the server had named it.
+     *
+     * Deliberately not folded into `find`, whose parameter is part of the
+     * read-side `LiveRuns` interface an app may already implement — widening that
+     * parameter would break every such implementation, and this lookup is only
+     * ever asked by `/stop`.
+     */
+    findByClientRunId(clientRunId: string): string | null;
+    /** What the client asks after a refresh: is anything still going here? */
+    find(params: {
+        threadId: string;
+    }): Promise<{
+        runId: string;
+        seq: number;
+    } | null>;
+    get(runId: string): AgentRun | null;
+    /**
+     * The buffered frames from `from` onwards, followed by live ones until the
+     * run ends.
+     *
+     * Throws before returning anything, so an evicted cursor and an unknown run
+     * are still HTTP statuses rather than events on a stream that already
+     * committed to a 200.
+     *
+     * `from` omitted means "start wherever you still can", not "start at 0".
+     * These are genuinely different requests: a client that names a cursor is
+     * telling us where its transcript ends, and handing it a later frame leaves
+     * an invisible hole — that is the 410. A client with no cursor at all — the
+     * browser reattaching on mount, which is the case `/attach` exists for — has
+     * no transcript to put a hole in, and refusing it the tail because the run is
+     * older than the buffer would 410 every run past `maxFrames`, i.e. every run
+     * long enough to be worth reattaching to.
+     */
+    replay(runId: string, from?: number): AsyncIterable<AgentStreamFrame>;
+    /** Test seam: drops everything and cancels the pending eviction timers. */
+    clear(): void;
+    get size(): number;
+    private pump;
+    private drain;
+    private wait;
+    private notify;
+    private scheduleEviction;
+}
+/**
+ * The process-wide default, shared by every `AgentController` that does not
+ * bring its own. One map per process is the whole point — see the class note.
+ */
+export declare const liveRuns: MemoryLiveRuns;
+//# sourceMappingURL=LiveRuns.d.ts.map

package/dist/ai/store/LiveRuns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveRuns.d.ts","sourceRoot":"","sources":["../../../ai/store/LiveRuns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAqCnE;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAI9C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM;IALzB,QAAQ,CAAC,IAAI,0BAA0B;gBAG5B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM;CAO1B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAGjC,QAAQ,CAAC,KAAK,EAAE,MAAM;IAFlC,QAAQ,CAAC,IAAI,wBAAwB;gBAEhB,KAAK,EAAE,MAAM;CAGnC;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D;0EACsE;IACtE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C,CAAC;AAqCF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,IAAI,CAA4B;IACxC,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAA6B;IAC7C,+DAA+D;IAC/D,OAAO,CAAC,WAAW,CAA6B;gBAEpC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAK/D;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAE,cAAmB,GAAG,IAAI;IAuB1D;;;;;;;OAOG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKrD,0EAA0E;IACpE,IAAI,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAexF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAInC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,gBAAgB,CAAC;IAcrE,2EAA2E;IAC3E,KAAK,IAAI,IAAI;IAeb,IAAI,IAAI,IAAI,MAAM,CAEjB;YAEa,IAAI;YA4CH,KAAK;IA4CpB,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,gBAAgB;CAqBzB;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,gBAAuB,CAAC"}

package/dist/ai/store/MemoryAgentStore.d.ts

@@ -0,0 +1,61 @@
+import type { AgentStore } from "../AgentController";
+import type { AgentMessage } from "../types";
+/**
+ * The default store: conversations last as long as the process.
+ *
+ * It exists so that `threadId` works out of the box, not so that anything is
+ * durable — a restart loses every thread, and a second server never had them.
+ * That is the honest default for a framework store, and it is why stateless is
+ * still the mode an app gets without asking: the client carrying its own
+ * history survives a deploy, and this does not.
+ *
+ * Expiry is swept lazily rather than on a timer. A `setTimeout` per thread is a
+ * timer per conversation and a reference the GC cannot collect, and an interval
+ * running forever keeps a process alive that has nothing else to do — so the
+ * sweep happens on access, at most once a minute, and an untouched process
+ * simply stops sweeping.
+ *
+ * A thread the store does not have is `null` from `loadThread` and an error
+ * from `appendMessages`, never an empty conversation. It used to be the other
+ * way, and the three ways a thread goes missing — it expired, the id was
+ * mistyped, it lived on an instance that was scaled in — all read as a fresh
+ * chat: the history was gone with no signal, and the next turn was persisted
+ * under the dead id as though it were the first. `clientOwnedIds` is the one
+ * setup where an unknown id is not a lost thread, because the client minted it.
+ */
+export declare class MemoryAgentStore implements AgentStore {
+    readonly ttlMs: number;
+    /** The ids come from the client, not from `createThread`, so an id this
+     *  store has never seen is a conversation starting rather than one lost. */
+    readonly clientOwnedIds: boolean;
+    private threads;
+    private lastSweep;
+    constructor(params?: {
+        ttlMs?: number;
+        clientOwnedIds?: boolean;
+    });
+    createThread(params: {
+        userId?: string | number;
+    }): Promise<{
+        threadId: string;
+    }>;
+    loadThread(threadId: string): Promise<AgentMessage[] | null>;
+    appendMessages(threadId: string, messages: AgentMessage[]): Promise<void>;
+    /** Test seam, and a way for an app to drop a conversation on request. */
+    delete(threadId: string): void;
+    get size(): number;
+    sweep(now?: number): void;
+}
+/**
+ * The process-wide default every `AgentController` uses unless it is given
+ * another.
+ *
+ * It has to be a shared instance, not a field initializer. A gemi controller is
+ * constructed per request — `RouteHandler.run()` does `new Controller()` every
+ * time — so `store = new MemoryAgentStore()` written in a controller field is a
+ * brand new, empty store on every turn, and a threaded conversation would read
+ * back nothing while looking like it was configured correctly. Anything
+ * process-lived that a controller holds has to be created outside it.
+ */
+export declare const defaultAgentStore: MemoryAgentStore;
+//# sourceMappingURL=MemoryAgentStore.d.ts.map

package/dist/ai/store/MemoryAgentStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryAgentStore.d.ts","sourceRoot":"","sources":["../../../ai/store/MemoryAgentStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAgB7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;gFAC4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAK;gBAEV,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO;IAK/D,YAAY,CAAC,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAWjF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;IAiB5D,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC/E,yEAAyE;IACzE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,CAAC,GAAG,SAAa,GAAG,IAAI;CAW9B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,kBAAyB,CAAC"}

package/dist/ai/store/index.d.ts

@@ -0,0 +1,4 @@
+export { defaultAgentStore, MemoryAgentStore } from "./MemoryAgentStore";
+export { FrameCursorEvictedError, LiveRunNotFoundError, liveRuns, MemoryLiveRuns, type RegisterParams, } from "./LiveRuns";
+export { encodeFrame, sseHeaders, sseResponse } from "./sse";
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../ai/store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC"}

package/dist/ai/store/sse.d.ts

@@ -0,0 +1,58 @@
+import type { AgentStreamFrame } from "../types";
+/**
+ * One frame, one SSE event.
+ *
+ * `id:` carries the frame's `seq`, which is what makes the browser's own
+ * `Last-Event-ID` the right cursor on reconnect — the transport asks the
+ * question the run already knows how to answer, and the client never has to
+ * track a position of its own.
+ */
+export declare function encodeFrame(frame: AgentStreamFrame): string;
+/**
+ * How long a connection may sit idle before a comment line goes out.
+ *
+ * The nearest ceiling is not a proxy but our own server: Bun's `idleTimeout`
+ * counts socket silence, a streaming body included, and gemi runs at its
+ * 10-second default unless `SERVER_IDLE_TIMEOUT` says otherwise. A comment
+ * line every 25 seconds was measured to lose the connection at 12; every 5
+ * keeps it open, with room for a write that lands late. Azure App Service's
+ * front end, at about 230 seconds, is the far ceiling, and 5 clears it by the
+ * same margin. A thousand quiet streams cost two hundred thirteen-byte writes
+ * a second, which is nothing. Both encoders read this one value, so the two
+ * cannot drift apart.
+ */
+export declare const SSE_KEEPALIVE_INTERVAL_MS = 5000;
+/**
+ * The comment line itself. A line starting with `:` is a comment under the SSE
+ * spec: every parser on our side skips it, and so does the browser's own
+ * `EventSource`.
+ */
+export declare const SSE_KEEPALIVE = ": keepalive\n\n";
+/**
+ * Writes a keepalive whenever the stream has been silent for the interval.
+ *
+ * Armed on creation because the silence before the first frame is real
+ * silence too — a model thinking is the common case. `touch()` after every
+ * frame is what makes it measure silence rather than elapsed time; `stop()`
+ * on close or cancel is what keeps a finished stream from holding a timer.
+ *
+ * The write is guarded because a cancel can land between the timer firing and
+ * the enqueue, and a closed controller throws. There is nothing to do about
+ * that except stop. `arm` checks `stopped` too, so a `touch()` that arrives
+ * after `stop()` cannot hand a finished stream a timer for one more interval.
+ */
+export declare function sseKeepalive(controller: ReadableStreamDefaultController<Uint8Array>, intervalMs?: number): {
+    touch(): void;
+    stop(): void;
+};
+export declare function sseHeaders(): Record<string, string>;
+/**
+ * Encodes an async iterable of frames as an SSE response.
+ *
+ * Pulls one frame per `pull` rather than looping inside `start`: a `start` that
+ * awaits the whole run does not resolve until the run is over, and the stream
+ * is not readable until it does — which would turn every streamed answer into a
+ * single delivery at the end.
+ */
+export declare function sseResponse(frames: AsyncIterable<AgentStreamFrame>, status?: number): Response;
+//# sourceMappingURL=sse.d.ts.map

package/dist/ai/store/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../ai/store/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAI7D;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,+BAA+B,CAAC,UAAU,CAAC,EACvD,UAAU,SAA4B,GACrC;IAAE,KAAK,IAAI,IAAI,CAAC;IAAC,IAAI,IAAI,IAAI,CAAA;CAAE,CA4BjC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWnD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,EAAE,MAAM,SAAM,GAAG,QAAQ,CAwC3F"}

package/dist/ai/store/stubAgentRun.d.ts

@@ -0,0 +1,56 @@
+import type { AgentRun, AgentRunResult } from "../Agent";
+import type { AgentStreamEvent, AgentStreamFrame, ToolShapes } from "../types";
+/**
+ * A hand-driven `AgentRun`, for tests of everything that consumes one.
+ *
+ * It lives in source rather than in a test file because both the `LiveRuns`
+ * tests and the controller tests need the same fake, and a test file that
+ * imports another test file gets that file's suites collected twice.
+ *
+ * It is deliberately a *stub satisfying the interface*, not a shrunken `Agent`:
+ * the real agent is a separate slice, and a test that imported it would be
+ * testing whichever half of the module was written last.
+ */
+export declare class StubAgentRun implements AgentRun<ToolShapes, unknown> {
+    readonly runId: string;
+    stopped: boolean;
+    stopReason: string | undefined;
+    /** Every `frames()` call ever made, so a test can assert on subscribers. */
+    subscriptions: number;
+    private buffer;
+    /**
+     * Frames are numbered from 1, because `AgentRunImpl` numbers them from 1.
+     *
+     * This used to start at 0, and the difference was not cosmetic: `LiveRuns`
+     * decided whether a cursor had been evicted by comparing it against the
+     * oldest buffered `seq`, which is 1 on a real run that has evicted nothing
+     * and 0 on this one. Every test here passed against a stub that could not
+     * express the case, and a ten-frame run answered a refresh with 410.
+     */
+    private nextSeq;
+    private done;
+    private wake;
+    /** See the note on `Entry.version` in `LiveRuns`: same missed-wakeup window,
+     *  same fix. */
+    private version;
+    private outcome;
+    private settle;
+    private settled;
+    constructor(runId?: string);
+    /** Pushes one event onto the run, numbering it the way a real run would. */
+    emit(event: AgentStreamEvent): AgentStreamFrame;
+    /** Ends the run. Everything parked on `frames()` or `result()` unblocks. */
+    finish(result?: Partial<AgentRunResult<ToolShapes, unknown>>): void;
+    frames(from?: number): AsyncIterable<AgentStreamFrame>;
+    [Symbol.asyncIterator](): AsyncGenerator<AgentStreamEvent, void, void>;
+    toResponse(params?: {
+        from?: number;
+    }): Response;
+    result(): Promise<AgentRunResult<ToolShapes, unknown>>;
+    stop(params?: {
+        reason?: string;
+    }): void;
+    private replay;
+    private notify;
+}
+//# sourceMappingURL=stubAgentRun.d.ts.map

package/dist/ai/store/stubAgentRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubAgentRun.d.ts","sourceRoot":"","sources":["../../../ai/store/stubAgentRun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,YAAW,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,OAAO,UAAS;IAChB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4EAA4E;IAC5E,aAAa,SAAK;IAElB,OAAO,CAAC,MAAM,CAA0B;IACxC;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAyB;IACrC;oBACgB;IAChB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAoD;IACnE,OAAO,CAAC,MAAM,CAAwE;IACtF,OAAO,CAAC,OAAO,CAA+C;gBAElD,KAAK,SAAa;IAO9B,4EAA4E;IAC5E,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB;IAO/C,4EAA4E;IAC5E,MAAM,CAAC,MAAM,GAAE,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAM,GAAG,IAAI;IAavE,MAAM,CAAC,IAAI,SAAI,GAAG,aAAa,CAAC,gBAAgB,CAAC;IAK1C,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,gBAAgB,EAAE,IAAI,EAAE,IAAI,CAAC;IAM7E,UAAU,CAAC,MAAM,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,QAAQ;IAWpD,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAItD,IAAI,CAAC,MAAM,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;YAK7B,MAAM;IAmBrB,OAAO,CAAC,MAAM;CAQf"}