@a-dray/aglib 0.1.0

package/dist/session/entry.d.ts

@@ -0,0 +1,196 @@
+import type { Content } from "../content.js";
+import type { Failure } from "../result.js";
+import type { JsonValue } from "../json.js";
+/** A model's request to invoke a tool. `arguments` is unparsed JSON as the provider sent it. */
+export interface ToolCall {
+    callId: string;
+    name: string;
+    arguments: string;
+}
+export interface ToolResult {
+    content: Content;
+    /** Structured channel for the application and the UI. Never reaches the model. */
+    details?: JsonValue;
+    isError?: boolean;
+}
+/**
+ * What a generation consumed.
+ *
+ * Absent stays absent — a count nobody reported is not a zero. This package
+ * holds no rates and computes no money from tokens. Where an adapter does
+ * arithmetic it is reconciling its wire's encoding to the meanings below:
+ * normalization, which is an adapter's job, and never a new fact.
+ *
+ * That is why `costUsd` belongs here and a rate table does not. A cost the
+ * provider *states* is an observation like the counts beside it, and dropping
+ * it was the same mistake as dropping the model that served the request: an
+ * application was left reconstructing, from a table it maintains by hand, a
+ * number the wire had already given it. For a router that is not even possible
+ * — it picks an upstream provider per request and adds its own margin, so no
+ * static table can say what was charged.
+ */
+export interface Usage {
+    /**
+     * Input tokens that were neither read from nor written to a cache.
+     *
+     * **The three input counts are disjoint.** The prompt's total size is
+     * `inputTokens + cacheReadTokens + cacheWriteTokens`; no field here is a
+     * subset of another, so a caller sums and never subtracts.
+     *
+     * The wires disagree about this and one of them has to be converted. What
+     * Anthropic calls `input_tokens` is already this — "tokens which were not
+     * read from or used to create a cache". What OpenAI calls `prompt_tokens` is
+     * the whole prompt, with `cached_tokens` counted inside it, so that adapter
+     * subtracts once and callers stop having to know which wire answered.
+     *
+     * Disjoint is the choice that survives absence, which is the rule the rest of
+     * this type runs on. Summing the fields you were given is right whichever
+     * ones are missing; subtracting a field you were not given is not. Under the
+     * other convention a heavily cached Anthropic turn priced its fresh tokens at
+     * zero — quietly, because the subtraction was clamped at zero rather than
+     * being allowed to go negative where somebody would have seen it.
+     */
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Input tokens served from a cache. Disjoint from `inputTokens`. */
+    cacheReadTokens?: number;
+    /** Input tokens written to a cache. Disjoint from `inputTokens`. */
+    cacheWriteTokens?: number;
+    /**
+     * What the provider said this generation cost, in US dollars. Reported,
+     * never derived: no adapter computes this from a rate, and one whose wire
+     * does not carry a cost leaves it absent rather than estimating.
+     */
+    costUsd?: number;
+}
+/**
+ * Who sent an arrival: what sort of sender, and which one.
+ *
+ * aglib mints exactly one kind — `"session"`, a delivery from another session —
+ * and interprets no other. Every other kind is the application's word for one of
+ * its own senders: a person, a channel, a schedule, a webhook. The vocabulary
+ * belongs to whoever can close it, and that is never this package.
+ *
+ * Two fields because absence was carrying four facts. This used to be the
+ * sending session's id alone, so an operator, a channel and a timer all said the
+ * same thing by saying nothing, and a recipient could not tell a person typing
+ * from a routine firing. Packing both into one string instead — `"routine:x"` —
+ * would put the vocabulary in a convention nothing closes, which is how such a
+ * field ends up with values that exist only by grep and a different reading on
+ * every surface that renders it.
+ */
+export interface From {
+    kind: string;
+    id: string;
+}
+/**
+ * The canonical vocabulary. This is the session's state, not a record of it:
+ * the loop reads its context by projecting these and appends back to them, so
+ * there is no second transcript that could disagree.
+ *
+ * `tool.started` carries only the call id — the assistant entry above it
+ * already holds the call, and duplicating name and arguments would be a second
+ * field for a value another field determines.
+ */
+export type Entry = {
+    type: "run.started";
+    runId: string;
+    input: Content;
+    from?: From;
+} | {
+    type: "assistant";
+    runId: string;
+    content: Content;
+    calls?: readonly ToolCall[];
+    usage?: Usage;
+    /**
+     * What produced this turn, when a model did: which model answered and the
+     * span it took. `Stored.at` is when the entry was committed, which is a
+     * different fact and not a substitute — anything projecting a generation
+     * needs both ends of the call, and the commit is neither of them.
+     */
+    generation?: {
+        model?: string;
+        startedAt: string;
+        endedAt: string;
+    };
+} | {
+    type: "tool.started";
+    runId: string;
+    callId: string;
+} | {
+    type: "tool.finished";
+    runId: string;
+    callId: string;
+    result: ToolResult;
+}
+/** Compaction output. `replaces` is the seq up to which entries are folded; nothing is deleted. */
+ | {
+    type: "summary";
+    runId: string;
+    content: string;
+    replaces: number;
+} | {
+    type: "run.finished";
+    runId: string;
+    outcome: "completed" | "failed" | "cancelled";
+    error?: Failure;
+};
+export type EntryType = Entry["type"];
+/** An entry once the log has given it a position. */
+export type Stored<T extends Entry = Entry> = T & {
+    seq: number;
+    at: string;
+};
+/**
+ * Input delivered to a session, committed with the sender's own entries.
+ * Spawning a child, replying to a parent and messaging a peer are all this.
+ */
+export interface Delivery {
+    /** The session it is delivered to. */
+    sessionId: string;
+    input: Content;
+    /**
+     * Who sent it. Absent means the application did not say — not that nobody
+     * did. Recorded on the receiving `run.started`, so a recipient can tell a
+     * peer's message from its user's, and can see that it already answered one
+     * that arrives twice.
+     */
+    from?: From;
+    /**
+     * Where in the recipient's loop this lands. Defaults to "next".
+     *
+     * Three places, and each is an outcome a sender can reason about rather than
+     * a level of urgency a harness interprets:
+     *
+     *   "interrupt" — the running activation ends, so the next one begins with
+     *                 this. Its uncommitted work is lost; everything it had
+     *                 already committed stays.
+     *   "turn"      — folded into the activation already running, before its next
+     *                 model call. Nothing in flight is lost. Immediately, if
+     *                 nothing is running.
+     *   "next"      — at the start of the recipient's next activation.
+     *
+     * This used to be `now | next | later`, and `now` meant either of the first
+     * two depending on the harness — fold if it had a safe point, end the
+     * activation if it did not. One word for "your message arrives and the work
+     * continues" and "your message arrives and a turn's work is destroyed". The
+     * doctrine was that a priority names the requirement and not the mechanism,
+     * but those are not two mechanisms for one requirement: they are two
+     * different things happening to somebody's work, and a runtime answer saying
+     * which one you got was invented to paper over it. `later` named a fourth
+     * thing that nothing implemented.
+     *
+     * **A harness that cannot honour one falls back to a later place, never an
+     * earlier one.** A loop with no safe point cannot do "turn", so it does
+     * "next" — the message waits. It does not end the activation instead, which
+     * is what falling back through an ordered scale used to do: ask for the
+     * gentlest useful thing and get the most destructive one.
+     */
+    priority?: "interrupt" | "turn" | "next";
+    /**
+     * The sender's key for this delivery. Two deliveries with the same id are the
+     * same delivery, so a retried send does not arrive twice.
+     */
+    id?: string;
+}

package/dist/session/entry.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entry.js.map

package/dist/session/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/session/entry.ts"],"names":[],"mappings":"","sourcesContent":["import type { Content } from \"../content.js\";\nimport type { Failure } from \"../result.js\";\nimport type { JsonValue } from \"../json.js\";\n\n/** A model's request to invoke a tool. `arguments` is unparsed JSON as the provider sent it. */\nexport interface ToolCall {\n  callId: string;\n  name: string;\n  arguments: string;\n}\n\nexport interface ToolResult {\n  content: Content;\n  /** Structured channel for the application and the UI. Never reaches the model. */\n  details?: JsonValue;\n  isError?: boolean;\n}\n\n/**\n * What a generation consumed.\n *\n * Absent stays absent — a count nobody reported is not a zero. This package\n * holds no rates and computes no money from tokens. Where an adapter does\n * arithmetic it is reconciling its wire's encoding to the meanings below:\n * normalization, which is an adapter's job, and never a new fact.\n *\n * That is why `costUsd` belongs here and a rate table does not. A cost the\n * provider *states* is an observation like the counts beside it, and dropping\n * it was the same mistake as dropping the model that served the request: an\n * application was left reconstructing, from a table it maintains by hand, a\n * number the wire had already given it. For a router that is not even possible\n * — it picks an upstream provider per request and adds its own margin, so no\n * static table can say what was charged.\n */\nexport interface Usage {\n  /**\n   * Input tokens that were neither read from nor written to a cache.\n   *\n   * **The three input counts are disjoint.** The prompt's total size is\n   * `inputTokens + cacheReadTokens + cacheWriteTokens`; no field here is a\n   * subset of another, so a caller sums and never subtracts.\n   *\n   * The wires disagree about this and one of them has to be converted. What\n   * Anthropic calls `input_tokens` is already this — \"tokens which were not\n   * read from or used to create a cache\". What OpenAI calls `prompt_tokens` is\n   * the whole prompt, with `cached_tokens` counted inside it, so that adapter\n   * subtracts once and callers stop having to know which wire answered.\n   *\n   * Disjoint is the choice that survives absence, which is the rule the rest of\n   * this type runs on. Summing the fields you were given is right whichever\n   * ones are missing; subtracting a field you were not given is not. Under the\n   * other convention a heavily cached Anthropic turn priced its fresh tokens at\n   * zero — quietly, because the subtraction was clamped at zero rather than\n   * being allowed to go negative where somebody would have seen it.\n   */\n  inputTokens?: number;\n  outputTokens?: number;\n  /** Input tokens served from a cache. Disjoint from `inputTokens`. */\n  cacheReadTokens?: number;\n  /** Input tokens written to a cache. Disjoint from `inputTokens`. */\n  cacheWriteTokens?: number;\n  /**\n   * What the provider said this generation cost, in US dollars. Reported,\n   * never derived: no adapter computes this from a rate, and one whose wire\n   * does not carry a cost leaves it absent rather than estimating.\n   */\n  costUsd?: number;\n}\n\n/**\n * Who sent an arrival: what sort of sender, and which one.\n *\n * aglib mints exactly one kind — `\"session\"`, a delivery from another session —\n * and interprets no other. Every other kind is the application's word for one of\n * its own senders: a person, a channel, a schedule, a webhook. The vocabulary\n * belongs to whoever can close it, and that is never this package.\n *\n * Two fields because absence was carrying four facts. This used to be the\n * sending session's id alone, so an operator, a channel and a timer all said the\n * same thing by saying nothing, and a recipient could not tell a person typing\n * from a routine firing. Packing both into one string instead — `\"routine:x\"` —\n * would put the vocabulary in a convention nothing closes, which is how such a\n * field ends up with values that exist only by grep and a different reading on\n * every surface that renders it.\n */\nexport interface From {\n  kind: string;\n  id: string;\n}\n\n/**\n * The canonical vocabulary. This is the session's state, not a record of it:\n * the loop reads its context by projecting these and appends back to them, so\n * there is no second transcript that could disagree.\n *\n * `tool.started` carries only the call id — the assistant entry above it\n * already holds the call, and duplicating name and arguments would be a second\n * field for a value another field determines.\n */\nexport type Entry =\n  | { type: \"run.started\"; runId: string; input: Content; from?: From }\n  | {\n      type: \"assistant\"; runId: string; content: Content;\n      calls?: readonly ToolCall[]; usage?: Usage;\n      /**\n       * What produced this turn, when a model did: which model answered and the\n       * span it took. `Stored.at` is when the entry was committed, which is a\n       * different fact and not a substitute — anything projecting a generation\n       * needs both ends of the call, and the commit is neither of them.\n       */\n      generation?: { model?: string; startedAt: string; endedAt: string };\n    }\n  | { type: \"tool.started\"; runId: string; callId: string }\n  | { type: \"tool.finished\"; runId: string; callId: string; result: ToolResult }\n  /** Compaction output. `replaces` is the seq up to which entries are folded; nothing is deleted. */\n  | { type: \"summary\"; runId: string; content: string; replaces: number }\n  | { type: \"run.finished\"; runId: string; outcome: \"completed\" | \"failed\" | \"cancelled\"; error?: Failure };\n\nexport type EntryType = Entry[\"type\"];\n\n/** An entry once the log has given it a position. */\nexport type Stored<T extends Entry = Entry> = T & { seq: number; at: string };\n\n/**\n * Input delivered to a session, committed with the sender's own entries.\n * Spawning a child, replying to a parent and messaging a peer are all this.\n */\nexport interface Delivery {\n  /** The session it is delivered to. */\n  sessionId: string;\n  input: Content;\n  /**\n   * Who sent it. Absent means the application did not say — not that nobody\n   * did. Recorded on the receiving `run.started`, so a recipient can tell a\n   * peer's message from its user's, and can see that it already answered one\n   * that arrives twice.\n   */\n  from?: From;\n  /**\n   * Where in the recipient's loop this lands. Defaults to \"next\".\n   *\n   * Three places, and each is an outcome a sender can reason about rather than\n   * a level of urgency a harness interprets:\n   *\n   *   \"interrupt\" — the running activation ends, so the next one begins with\n   *                 this. Its uncommitted work is lost; everything it had\n   *                 already committed stays.\n   *   \"turn\"      — folded into the activation already running, before its next\n   *                 model call. Nothing in flight is lost. Immediately, if\n   *                 nothing is running.\n   *   \"next\"      — at the start of the recipient's next activation.\n   *\n   * This used to be `now | next | later`, and `now` meant either of the first\n   * two depending on the harness — fold if it had a safe point, end the\n   * activation if it did not. One word for \"your message arrives and the work\n   * continues\" and \"your message arrives and a turn's work is destroyed\". The\n   * doctrine was that a priority names the requirement and not the mechanism,\n   * but those are not two mechanisms for one requirement: they are two\n   * different things happening to somebody's work, and a runtime answer saying\n   * which one you got was invented to paper over it. `later` named a fourth\n   * thing that nothing implemented.\n   *\n   * **A harness that cannot honour one falls back to a later place, never an\n   * earlier one.** A loop with no safe point cannot do \"turn\", so it does\n   * \"next\" — the message waits. It does not end the activation instead, which\n   * is what falling back through an ordered scale used to do: ask for the\n   * gentlest useful thing and get the most destructive one.\n   */\n  priority?: \"interrupt\" | \"turn\" | \"next\";\n  /**\n   * The sender's key for this delivery. Two deliveries with the same id are the\n   * same delivery, so a retried send does not arrive twice.\n   */\n  id?: string;\n}\n"]}

package/dist/session/index.d.ts

@@ -0,0 +1,2 @@
+export type { Delivery, Entry, EntryType, From, Stored, ToolCall, ToolResult, Usage } from "./entry.js";
+export type { Message } from "./messages.js";

package/dist/session/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"","sourcesContent":["export type { Delivery, Entry, EntryType, From, Stored, ToolCall, ToolResult, Usage } from \"./entry.js\";\nexport type { Message } from \"./messages.js\";\n"]}

package/dist/session/log.d.ts

@@ -0,0 +1,20 @@
+import type { Entry, Stored } from "./entry.js";
+/**
+ * The session's state: ordered entries and the position of the last one.
+ *
+ * Not a record of state kept somewhere else — this is what the loop reads to
+ * build its next request and what it appends its results to. A store persists
+ * it; without one it lives here and the session is ephemeral.
+ */
+export interface Log {
+    readonly seq: number;
+    readonly entries: readonly Stored[];
+    /** Stamps and appends, returning what was added. */
+    append(entries: readonly Entry[]): readonly Stored[];
+}
+/**
+ * `at` is the session's real position, which is the store's to say. Deriving it
+ * from the last entry is a second answer to the same question, and the two
+ * agree only while nothing has ever been read from a cursor.
+ */
+export declare function createLog(initial?: readonly Stored[], at?: number): Log;

package/dist/session/log.js

@@ -0,0 +1,24 @@
+/**
+ * `at` is the session's real position, which is the store's to say. Deriving it
+ * from the last entry is a second answer to the same question, and the two
+ * agree only while nothing has ever been read from a cursor.
+ */
+export function createLog(initial = [], at = initial.at(-1)?.seq ?? 0) {
+    const entries = [...initial];
+    let seq = at;
+    return {
+        get seq() { return seq; },
+        // A copy. `entries()` on a harness context is documented beside `history()`,
+        // which is rebuilt every call precisely so a harness cannot hold something
+        // that drifts from the log; handing out the live array made one of the pair
+        // a lie.
+        get entries() { return [...entries]; },
+        append(added) {
+            const at = new Date().toISOString();
+            const stamped = added.map((entry) => ({ ...entry, seq: (seq += 1), at }));
+            entries.push(...stamped);
+            return stamped;
+        },
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/session/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/session/log.ts"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,UAA6B,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC;IACtF,MAAM,OAAO,GAAa,CAAC,GAAG,OAAO,CAAC,CAAC;IACvC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,OAAO;QACL,IAAI,GAAG,KAAK,OAAO,GAAG,CAAC,CAAC,CAAC;QACzB,6EAA6E;QAC7E,2EAA2E;QAC3E,4EAA4E;QAC5E,SAAS;QACT,IAAI,OAAO,KAAwB,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,CAAC,KAAK;YACV,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAU,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAClF,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;YACzB,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { Entry, Stored } from \"./entry.js\";\n\n/**\n * The session's state: ordered entries and the position of the last one.\n *\n * Not a record of state kept somewhere else — this is what the loop reads to\n * build its next request and what it appends its results to. A store persists\n * it; without one it lives here and the session is ephemeral.\n */\nexport interface Log {\n  readonly seq: number;\n  readonly entries: readonly Stored[];\n  /** Stamps and appends, returning what was added. */\n  append(entries: readonly Entry[]): readonly Stored[];\n}\n\n/**\n * `at` is the session's real position, which is the store's to say. Deriving it\n * from the last entry is a second answer to the same question, and the two\n * agree only while nothing has ever been read from a cursor.\n */\nexport function createLog(initial: readonly Stored[] = [], at = initial.at(-1)?.seq ?? 0): Log {\n  const entries: Stored[] = [...initial];\n  let seq = at;\n  return {\n    get seq() { return seq; },\n    // A copy. `entries()` on a harness context is documented beside `history()`,\n    // which is rebuilt every call precisely so a harness cannot hold something\n    // that drifts from the log; handing out the live array made one of the pair\n    // a lie.\n    get entries(): readonly Stored[] { return [...entries]; },\n    append(added) {\n      const at = new Date().toISOString();\n      const stamped = added.map((entry): Stored => ({ ...entry, seq: (seq += 1), at }));\n      entries.push(...stamped);\n      return stamped;\n    },\n  };\n}\n"]}

package/dist/session/messages.d.ts

@@ -0,0 +1,42 @@
+import type { Content } from "../content.js";
+import type { Stored, ToolCall } from "./entry.js";
+/** A message as a provider takes it: built per turn from the log, never held. */
+export type Message = {
+    role: "system";
+    content: Content;
+} | {
+    role: "user";
+    content: Content;
+} | {
+    role: "assistant";
+    content: Content;
+    calls?: readonly ToolCall[];
+} | {
+    role: "tool";
+    callId: string;
+    content: Content;
+    isError?: boolean;
+};
+/**
+ * The position everything up to has been folded into a summary.
+ *
+ * One answer, because two callers need it: the projection skips what is folded,
+ * and the loop refuses to cut at or behind it. They were the same reduce written
+ * out twice.
+ */
+export declare function foldedThrough(entries: readonly Stored[]): number;
+/**
+ * The log projected into what a provider takes.
+ *
+ * Built fresh for every request and never held. That is the whole reason there
+ * is no second transcript to drift from the log, and why nothing needs a test
+ * proving two representations agree.
+ */
+export declare function toMessages(input: {
+    instructions: Content;
+    entries: readonly Stored[];
+    context?: {
+        run?: string;
+        turn?: string;
+    };
+}): readonly Message[];

package/dist/session/messages.js

@@ -0,0 +1,99 @@
+/**
+ * The position everything up to has been folded into a summary.
+ *
+ * One answer, because two callers need it: the projection skips what is folded,
+ * and the loop refuses to cut at or behind it. They were the same reduce written
+ * out twice.
+ */
+export function foldedThrough(entries) {
+    return entries.reduce((at, entry) => entry.type === "summary" ? Math.max(at, entry.replaces) : at, 0);
+}
+/** Names the sender in the turn itself, since only text reaches the model. */
+function sent(input, from) {
+    if (!from)
+        return input;
+    const label = `[from ${from.kind} ${from.id}]`;
+    return typeof input === "string"
+        ? `${label}\n${input}`
+        : [{ type: "text", text: label }, ...input];
+}
+/**
+ * The log projected into what a provider takes.
+ *
+ * Built fresh for every request and never held. That is the whole reason there
+ * is no second transcript to drift from the log, and why nothing needs a test
+ * proving two representations agree.
+ */
+export function toMessages(input) {
+    const messages = [{ role: "system", content: input.instructions }];
+    // Run-scoped context sits immediately after the instructions, inside the
+    // cacheable prefix, because it does not change for the life of the run.
+    if (input.context?.run)
+        messages.push({ role: "system", content: input.context.run });
+    // A summary folds everything up to `replaces`. The source entries stay in the
+    // log — compaction changes what the model sees, never what happened.
+    const cut = foldedThrough(input.entries);
+    // A call whose result never committed. It happens when an activation ends
+    // between asking and answering — cancelled, interrupted, or beaten to the
+    // commit by another worker. The projection has to close it: a provider
+    // rejects an assistant turn holding a call with no result, so leaving the gap
+    // would make the session permanently unusable. What is said is what is known
+    // — the call did not report back — and never an invented result.
+    const answered = new Set(input.entries.filter((entry) => entry.type === "tool.finished").map((entry) => entry.callId));
+    for (const entry of input.entries) {
+        // A summary folds like anything else it covers. Exempting the whole type
+        // kept every summary ever written, so a long session carried a chain of
+        // them whose content was already inside the newest — duplicated, and
+        // rewriting the cached prefix each time one was added.
+        if (entry.seq <= cut)
+            continue;
+        switch (entry.type) {
+            case "run.started":
+                // Provenance the model can see. `from` was recorded and then dropped
+                // here, so the documents claimed a recipient could tell a peer's
+                // message from its user's while the only actor that had to could not.
+                messages.push({ role: "user", content: sent(entry.input, entry.from) });
+                break;
+            case "assistant": {
+                messages.push({
+                    role: "assistant",
+                    content: entry.content,
+                    ...(entry.calls?.length ? { calls: entry.calls } : {}),
+                });
+                for (const call of entry.calls ?? []) {
+                    if (answered.has(call.callId))
+                        continue;
+                    messages.push({
+                        role: "tool", callId: call.callId, isError: true,
+                        content: "This call did not report back: the activation ended before its result was committed.",
+                    });
+                }
+                break;
+            }
+            case "tool.finished":
+                messages.push({
+                    role: "tool",
+                    callId: entry.callId,
+                    content: entry.result.content,
+                    ...(entry.result.isError ? { isError: true } : {}),
+                });
+                break;
+            case "summary":
+                // Delimited user context rather than an assistant turn: attributing a
+                // summary to the assistant puts words in the model's mouth it never said.
+                messages.push({ role: "user", content: `<summary>\n${entry.content}\n</summary>` });
+                break;
+            // Not model-visible: tool.started is bookkeeping and run.finished is a
+            // boundary.
+            case "tool.started":
+            case "run.finished":
+                break;
+        }
+    }
+    // Turn-scoped context sits last, after the cache boundary, because it is for
+    // this request only and must not be written into the cached prefix.
+    if (input.context?.turn)
+        messages.push({ role: "system", content: input.context.turn });
+    return messages;
+}
+//# sourceMappingURL=messages.js.map

package/dist/session/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/session/messages.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Content } from \"../content.js\";\nimport type { From, Stored, ToolCall } from \"./entry.js\";\n\n/** A message as a provider takes it: built per turn from the log, never held. */\nexport type Message =\n  | { role: \"system\"; content: Content }\n  | { role: \"user\"; content: Content }\n  | { role: \"assistant\"; content: Content; calls?: readonly ToolCall[] }\n  | { role: \"tool\"; callId: string; content: Content; isError?: boolean };\n\n/**\n * The position everything up to has been folded into a summary.\n *\n * One answer, because two callers need it: the projection skips what is folded,\n * and the loop refuses to cut at or behind it. They were the same reduce written\n * out twice.\n */\nexport function foldedThrough(entries: readonly Stored[]): number {\n  return entries.reduce((at, entry) => entry.type === \"summary\" ? Math.max(at, entry.replaces) : at, 0);\n}\n\n/** Names the sender in the turn itself, since only text reaches the model. */\nfunction sent(input: Content, from: From | undefined): Content {\n  if (!from) return input;\n  const label = `[from ${from.kind} ${from.id}]`;\n  return typeof input === \"string\"\n    ? `${label}\\n${input}`\n    : [{ type: \"text\" as const, text: label }, ...input];\n}\n\n/**\n * The log projected into what a provider takes.\n *\n * Built fresh for every request and never held. That is the whole reason there\n * is no second transcript to drift from the log, and why nothing needs a test\n * proving two representations agree.\n */\nexport function toMessages(input: {\n  instructions: Content;\n  entries: readonly Stored[];\n  context?: { run?: string; turn?: string };\n}): readonly Message[] {\n  const messages: Message[] = [{ role: \"system\", content: input.instructions }];\n\n  // Run-scoped context sits immediately after the instructions, inside the\n  // cacheable prefix, because it does not change for the life of the run.\n  if (input.context?.run) messages.push({ role: \"system\", content: input.context.run });\n\n  // A summary folds everything up to `replaces`. The source entries stay in the\n  // log — compaction changes what the model sees, never what happened.\n  const cut = foldedThrough(input.entries);\n\n  // A call whose result never committed. It happens when an activation ends\n  // between asking and answering — cancelled, interrupted, or beaten to the\n  // commit by another worker. The projection has to close it: a provider\n  // rejects an assistant turn holding a call with no result, so leaving the gap\n  // would make the session permanently unusable. What is said is what is known\n  // — the call did not report back — and never an invented result.\n  const answered = new Set(\n    input.entries.filter((entry) => entry.type === \"tool.finished\").map((entry) => entry.callId),\n  );\n\n  for (const entry of input.entries) {\n    // A summary folds like anything else it covers. Exempting the whole type\n    // kept every summary ever written, so a long session carried a chain of\n    // them whose content was already inside the newest — duplicated, and\n    // rewriting the cached prefix each time one was added.\n    if (entry.seq <= cut) continue;\n    switch (entry.type) {\n      case \"run.started\":\n        // Provenance the model can see. `from` was recorded and then dropped\n        // here, so the documents claimed a recipient could tell a peer's\n        // message from its user's while the only actor that had to could not.\n        messages.push({ role: \"user\", content: sent(entry.input, entry.from) });\n        break;\n      case \"assistant\": {\n        messages.push({\n          role: \"assistant\",\n          content: entry.content,\n          ...(entry.calls?.length ? { calls: entry.calls } : {}),\n        });\n        for (const call of entry.calls ?? []) {\n          if (answered.has(call.callId)) continue;\n          messages.push({\n            role: \"tool\", callId: call.callId, isError: true,\n            content: \"This call did not report back: the activation ended before its result was committed.\",\n          });\n        }\n        break;\n      }\n      case \"tool.finished\":\n        messages.push({\n          role: \"tool\",\n          callId: entry.callId,\n          content: entry.result.content,\n          ...(entry.result.isError ? { isError: true } : {}),\n        });\n        break;\n      case \"summary\":\n        // Delimited user context rather than an assistant turn: attributing a\n        // summary to the assistant puts words in the model's mouth it never said.\n        messages.push({ role: \"user\", content: `<summary>\\n${entry.content}\\n</summary>` });\n        break;\n      // Not model-visible: tool.started is bookkeeping and run.finished is a\n      // boundary.\n      case \"tool.started\":\n      case \"run.finished\":\n        break;\n    }\n  }\n\n  // Turn-scoped context sits last, after the cache boundary, because it is for\n  // this request only and must not be written into the cached prefix.\n  if (input.context?.turn) messages.push({ role: \"system\", content: input.context.turn });\n  return messages;\n}\n\n"]}

package/dist/store/adapters/sqlite.d.ts

@@ -0,0 +1,20 @@
+import type { Store } from "../store.js";
+/**
+ * The minimum a driver must provide. Declared here rather than importing one so
+ * the same file serves `node:sqlite` and `bun:sqlite`, and so an application can
+ * hand in a database it already opened — which is what lets its own tables live
+ * beside the log and join against it.
+ */
+export interface SqliteDatabase {
+    exec(sql: string): void;
+    query(sql: string): {
+        all(...parameters: unknown[]): unknown[];
+        run(...parameters: unknown[]): unknown;
+    };
+}
+export declare function createSqliteStore(input: {
+    database: SqliteDatabase;
+    claimMs?: number;
+    /** How long a delivery id is remembered. Defaults to seven days. */
+    deliveryMemoryMs?: number;
+}): Store;