@earendil-works/pi-durable 0.99.1 → 0.99.2

package/dist/harness/generation.d.ts

@@ -1,36 +1,67 @@
-import { type DeferredHandle, type ModelThinkingLevel } from "@earendil-works/pi-ai";
-import type { EntryId } from "../types.ts";
-import type { ConversationStreamOptions, ModelRef } from "./types.ts";
+import { type Draft } from "@earendil-works/chord";
+import type { DeferredHandle, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { ConversationId, EntryId, SubmissionId, TaskId, Tx } from "../types.ts";
+import { type LiveState } from "./live.ts";
+import { type ToolTaskResult } from "./tool.ts";
+import type { CompactionResult, ConversationStreamOptions, GenerationHooks, ModelRef, ToolExecutionMode } from "./types.ts";
 export type GenerationInput = Record<string, never>;
 export type GenerationCheckpoint = {
     phase: "prepare";
     attempt: number;
+    /** The blocking compaction this generation waited for; it starts no other compaction (spec §8.3). */
+    compacted?: TaskId<CompactionResult>;
+    /** Error text of the overflow that started `compacted`; checked once when `prepare` resumes. */
+    overflow?: string;
 } | {
     phase: "request";
     attempt: number;
+    compacted?: TaskId<CompactionResult>;
     model: ModelRef;
     thinkingLevel: ModelThinkingLevel;
     /** Configured request options when preparation committed; a resend after recovery uses them unchanged. */
     streamOptions: ConversationStreamOptions;
+    toolExecution: ToolExecutionMode;
     /** Newest entry included in the request. */
     cutoff: EntryId;
 } | {
     phase: "retry";
     attempt: number;
+    compacted?: TaskId<CompactionResult>;
     until: number;
 } | {
     phase: "poll";
     attempt: number;
+    compacted?: TaskId<CompactionResult>;
     model: ModelRef;
+    toolExecution: ToolExecutionMode;
+    cutoff: EntryId;
     handle: DeferredHandle;
     pollAt: number;
+} | {
+    /** Waiting on the round's tool tasks, which the generation owns (spec §8.5). */
+    phase: "tools";
+    /** The tool-calling answer. */
+    assistant: EntryId;
+    /** Tool tasks created so far, in call order; grows by one per started call of a sequential round. */
+    tools: TaskId<ToolTaskResult>[];
+    /** Calls of a sequential round not started yet, in call order. */
+    pending: string[];
 };
 export type GenerationResult = {
     entryId: EntryId;
 };
 /**
- * Built-in generation task: prepares the positional system prompt, requests or polls the model, retries, and classifies
- * the response. The run's inputs live in `pi.live.run`.
+ * Built-in generation task: prepares the positional system prompt and tool loadout, requests or polls the model,
+ * retries, and classifies the response. The run's inputs live in `pi.live.run`.
+ */
+export declare const GenerationTask: import("../types.ts").Task<GenerationInput, GenerationCheckpoint, GenerationResult, GenerationHooks>;
+/**
+ * Append a committed partial left by an interrupted, aborted, faulted, or orphaned attempt as an aborted assistant
+ * entry; the caller replaces or removes `generation`.
  */
-export declare const GenerationTask: import("../types.ts").Task<GenerationInput, GenerationCheckpoint, GenerationResult, object>;
+export declare function convertPartial(tx: Tx, live: Draft<LiveState>, conversationId: ConversationId): Promise<void>;
+/** Start a run for `inputs`, placed input submissions: a new generation takes `pi.live.run`. */
+export declare function startRun(tx: Tx, conversationId: ConversationId, live: Draft<LiveState>, inputs: SubmissionId[]): Promise<void>;
+/** Hand run control from `from` to `to`; the run's inputs move with it. */
+export declare function handOver(live: Draft<LiveState>, from: TaskId, to: TaskId): void;
 //# sourceMappingURL=generation.d.ts.map

package/dist/harness/generation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../../src/harness/generation.ts"],"names":[],"mappings":"AACA,OAAO,EAGN,KAAK,cAAc,EAInB,KAAK,kBAAkB,EAGvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAkB,OAAO,EAAkC,MAAM,aAAa,CAAC;AAI3F,OAAO,KAAK,EAAE,yBAAyB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEpD,MAAM,MAAM,oBAAoB,GAC7B;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IACA,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,QAAQ,CAAC;IAChB,aAAa,EAAE,kBAAkB,CAAC;IAClC,0GAA0G;IAC1G,aAAa,EAAE,yBAAyB,CAAC;IACzC,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;CACf,GACD;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F,MAAM,MAAM,gBAAgB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAQpD;;;GAGG;AACH,eAAO,MAAM,cAAc,6FAiGzB,CAAC"}
+{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../../src/harness/generation.ts"],"names":[],"mappings":"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"}

package/dist/harness/generation.js

@@ -1,15 +1,22 @@
 import { copyJson } from "@earendil-works/chord";
-import { isRetryableAssistantError, retryDelayMs, } from "@earendil-works/pi-ai";
-import { AssistantEntry, SystemEntry } from "../entries.js";
+import { isContextOverflow } from "@earendil-works/pi-ai/utils/overflow";
+import { isRetryableAssistantError, retryDelayMs } from "@earendil-works/pi-ai/utils/retry";
+import { getCurrentTools } from "@earendil-works/pi-ai/utils/transcript";
+import { AssistantEntry, ResetEntry, SystemEntry, UserEntry } from "../entries.js";
 import { defineTask } from "../tasks.js";
-import { ConversationConfig, DEFAULT_RETRY_POLICY } from "./config.js";
+import { createCompaction, estimateContext, selectCut } from "./compaction.js";
+import { ConversationConfig, DEFAULT_COMPACTION_POLICY, DEFAULT_RETRY_POLICY } from "./config.js";
+import { applyBoundary, prepareBoundary } from "./inbox.js";
+import { assignJson } from "./json.js";
 import { endRun, LiveDoc } from "./live.js";
-import { planSystemEntries, renderSections, replaySections } from "./prompt.js";
+import { desiredTools, planSystemEntries, renderSections, replaySections } from "./prompt.js";
+import { appendToolResult, harnessError, ToolTask } from "./tool.js";
+import { recordUsage } from "./usage.js";
 const PARTIAL_THROTTLE_MS = 100;
 const DEFAULT_POLL_AFTER_MS = 5000;
 /**
- * Built-in generation task: prepares the positional system prompt, requests or polls the model, retries, and classifies
- * the response. The run's inputs live in `pi.live.run`.
+ * Built-in generation task: prepares the positional system prompt and tool loadout, requests or polls the model,
+ * retries, and classifies the response. The run's inputs live in `pi.live.run`.
  */
 export const GenerationTask = defineTask({
     name: "pi.generation",
@@ -17,24 +24,33 @@ export const GenerationTask = defineTask({
     initial: () => ({ phase: "prepare", attempt: 1 }),
     phases: {
         /**
-         * Render the system prompt and append the positional `pi.system` entries it needs, then move to `request`. Only
-         * the Harness writes to a busy conversation, so the transcript read here is still the tail at the commit.
+         * Render the system prompt and tool loadout and append the positional `pi.system` entries they need, then move to
+         * `request`. The configuration read here is fixed for this request. Only the Harness writes to a busy
+         * conversation, so the transcript read here is still the tail at the commit.
          */
         prepare: async (task, runtime, context) => {
             const { conversationId, registry } = runtime;
             for (const failure of registry.failures())
-                if (failure.kind === "section")
-                    runtime.report(failure.error);
-            const { model, thinkingLevel, streamOptions } = (await runtime.snapshot(ConversationConfig, conversationId, context)) ??
+                runtime.report(failure.error);
+            const config = (await runtime.snapshot(ConversationConfig, conversationId, context)) ??
                 ConversationConfig.definition.initial();
-            if (model === undefined || runtime.models.getModel(model.provider, model.modelId) === undefined) {
+            const { model, thinkingLevel, streamOptions } = config;
+            const resolved = model === undefined ? undefined : runtime.models.getModel(model.provider, model.modelId);
+            if (model === undefined || resolved === undefined)
                 return failNoModel(runtime, model, context);
+            const { attempt, compacted, overflow } = task.state.checkpoint;
+            if (compacted !== undefined && overflow !== undefined) {
+                const [outcome] = await runtime.outcomes([compacted], context);
+                if (outcome?.status !== "completed" || outcome.result.entryId === undefined) {
+                    return failModelError(runtime, overflow, context);
+                }
             }
             const view = await runtime.context(conversationId, context);
             const shown = replaySections(view.messages);
+            const tools = desiredTools(config.activeTools, (name) => registry.tool(name));
             const input = {
                 conversationId,
-                tools: [],
+                tools,
                 shown: Object.fromEntries(shown),
                 model,
                 thinkingLevel,
@@ -42,20 +58,43 @@ export const GenerationTask = defineTask({
             };
             const report = (error) => runtime.report(error);
             const desired = await renderSections(registry.sections(), input, shown, report, context);
-            const entries = planSystemEntries(view, desired, runtime.now());
+            const entries = planSystemEntries(view, desired, tools, runtime.now());
+            const threshold = compacted === undefined
+                ? thresholdCompaction(view, entries, resolved.contextWindow, config.compaction ?? DEFAULT_COMPACTION_POLICY)
+                : undefined;
+            if (threshold === "blocking") {
+                // Compact first and prepare again; the transcript is unchanged until the compaction appends.
+                await runtime.commit(async (tx) => {
+                    const child = await createCompaction(tx, conversationId, { reason: "threshold" }, runtime.taskId);
+                    const checkpoint = { phase: "prepare", attempt, compacted: child };
+                    return { status: "waiting", checkpoint, on: [child], policy: "allSettled" };
+                }, context);
+                return;
+            }
             await runtime.commit(async (tx) => {
                 let cutoff = (await tx.scanEntries({ conversationId }, 1)).items[0]?.id;
                 for (const entry of entries)
                     cutoff = (await tx.appendEntry(SystemEntry, conversationId, entry)).id;
                 if (cutoff === undefined)
                     throw new Error(`Conversation ${conversationId} has no entries to send`);
-                const { attempt } = task.state.checkpoint;
-                const request = { attempt, model, thinkingLevel, streamOptions: streamOptions ?? {}, cutoff };
+                // Checked in this commit, so a compaction admitted during preparation counts.
+                if (threshold === "background" && (await tx.doc(LiveDoc, conversationId)).compactions === undefined) {
+                    await createCompaction(tx, conversationId, { reason: "threshold" });
+                }
+                const request = {
+                    attempt,
+                    ...(compacted === undefined ? {} : { compacted }),
+                    model,
+                    thinkingLevel,
+                    streamOptions: streamOptions ?? {},
+                    toolExecution: config.toolExecution ?? "parallel",
+                    cutoff,
+                };
                 return { status: "running", checkpoint: { phase: "request", ...request } };
             }, context);
         },
         request: async (task, runtime, context) => {
-            const { attempt, model: ref, thinkingLevel, streamOptions, cutoff } = task.state.checkpoint;
+            const { attempt, compacted, model: ref, thinkingLevel, streamOptions, toolExecution, cutoff, } = task.state.checkpoint;
             const conversationId = runtime.conversationId;
             await runtime.commit(async (tx) => {
                 const live = await tx.doc(LiveDoc, conversationId);
@@ -67,30 +106,64 @@ export const GenerationTask = defineTask({
             if (model === undefined)
                 return failNoModel(runtime, ref, context);
             const view = await runtime.context(conversationId, context, cutoff);
+            let messages = view.messages;
+            await runtime.hooks.each("beforeRequest", async (hook) => {
+                const replaced = await hook({ messages }, runtime, context);
+                if (replaced !== undefined)
+                    messages = replaced.messages;
+            });
             const options = {
                 ...streamOptions,
                 signal: runtime.signal,
                 ...(thinkingLevel === "off" ? {} : { reasoning: thinkingLevel }),
             };
-            const message = await streamResponse(runtime, model, view.messages, options, attempt, context);
-            await classify(runtime, attempt, ref, undefined, message, context);
+            const message = await streamResponse(runtime, model, messages, options, attempt, context);
+            const request = { attempt, compacted, model: ref, toolExecution, cutoff, messages: view.messages };
+            await classify(runtime, request, message, context);
         },
         retry: async (task, runtime, context) => {
-            const { attempt, until } = task.state.checkpoint;
+            const { attempt, compacted, until } = task.state.checkpoint;
             await runtime.sleep(until, context);
             await runtime.commit(async (tx) => {
                 (await tx.doc(LiveDoc, runtime.conversationId)).generation = { attempt: attempt + 1 };
-                return { status: "running", checkpoint: { phase: "prepare", attempt: attempt + 1 } };
+                const checkpoint = {
+                    phase: "prepare",
+                    attempt: attempt + 1,
+                    ...(compacted === undefined ? {} : { compacted }),
+                };
+                return { status: "running", checkpoint };
             }, context);
         },
         poll: async (task, runtime, context) => {
-            const { attempt, model: ref, handle, pollAt } = task.state.checkpoint;
+            const { attempt, compacted, model: ref, toolExecution, cutoff, handle, pollAt } = task.state.checkpoint;
             const model = runtime.models.getModel(ref.provider, ref.modelId);
             if (model === undefined)
                 return failNoModel(runtime, ref, context);
             await runtime.sleep(pollAt, context);
             const message = await runtime.models.fetchDeferred(model, handle, { signal: runtime.signal });
-            await classify(runtime, attempt, ref, pollAt, message, context);
+            const request = { attempt, compacted, model: ref, toolExecution, cutoff, pollAt };
+            await classify(runtime, request, message, context);
+        },
+        tools: async (task, runtime, context) => {
+            const { assistant, tools, pending } = task.state.checkpoint;
+            const [next, ...rest] = pending;
+            if (next === undefined)
+                return finishToolRound(runtime, assistant, tools, context);
+            // Sequential round: start the next call and wait for it.
+            await runtime.commit(async (tx) => {
+                const live = await tx.doc(LiveDoc, runtime.conversationId);
+                const taskId = await createToolTask(tx, runtime, assistant, next);
+                const slot = live.tools?.find((slot) => slot.callId === next && slot.taskId === undefined);
+                if (slot !== undefined)
+                    slot.taskId = taskId;
+                const checkpoint = {
+                    phase: "tools",
+                    assistant,
+                    tools: [...tools, taskId],
+                    pending: rest,
+                };
+                return { status: "waiting", checkpoint, on: [taskId], policy: "allSettled" };
+            }, context);
         },
     },
     abort: async (task, runtime, context) => {
@@ -107,14 +180,59 @@ export const GenerationTask = defineTask({
             }
         }
         const conversationId = runtime.conversationId;
+        // Runs after the round's tool tasks are terminal; calls never started get `aborted` results (spec §8.5).
+        const unstarted = checkpoint.phase === "tools"
+            ? await readCalls(runtime, checkpoint.assistant, checkpoint.pending, context)
+            : [];
         await runtime.commit(async (tx) => {
             const live = await tx.doc(LiveDoc, conversationId);
             await convertPartial(tx, live, conversationId);
+            for (const call of unstarted) {
+                const result = harnessError("aborted", `Tool ${call.name} was aborted`);
+                await appendToolResult(tx, conversationId, call, result, runtime.now());
+            }
             endRun(tx, live, runtime.taskId, { status: "unanswered", reason: "aborted" });
             return { status: "terminal", outcome: { status: "aborted" } };
         }, context);
     },
 });
+/** The calls `callIds` of the assistant entry, in the given order. */
+async function readCalls(runtime, assistant, callIds, context) {
+    const message = (await runtime.entry(AssistantEntry, assistant, context))?.model?.[0];
+    const calls = message?.role === "assistant" ? message.content.filter((content) => content.type === "toolCall") : [];
+    return callIds.flatMap((id) => calls.filter((call) => call.id === id).slice(0, 1));
+}
+/** A tool task for call `callId`, owned by the generation. */
+function createToolTask(tx, runtime, assistant, callId) {
+    return tx.createTask(ToolTask, { assistant, callId }, { ownership: { kind: "task", taskId: runtime.taskId } });
+}
+/**
+ * Which threshold compaction preparation starts before its request (spec §8.3): `blocking` above
+ * `contextWindow - reserveTokens`, `background` above the background threshold, and only when range selection finds a
+ * cut. The caller starts a background one only while no compaction is listed.
+ */
+function thresholdCompaction(view, planned, contextWindow, policy) {
+    if (!policy.enabled || contextWindow <= 0)
+        return undefined;
+    const tokens = estimateContext(view, planned.flatMap((entry) => entry.model ?? []));
+    const blocking = contextWindow - policy.reserveTokens;
+    const background = blocking - policy.backgroundTokens;
+    const over = tokens > blocking ? "blocking" : policy.backgroundTokens > 0 && tokens > background ? "background" : undefined;
+    if (over === undefined || selectCut(view, policy.keepRecentTokens) === undefined)
+        return undefined;
+    return over;
+}
+/** Settle the run's inputs `unanswered` with `model_error` and fail with `text`. */
+async function failModelError(runtime, text, context) {
+    await runtime.commit(async (tx) => {
+        const live = await tx.doc(LiveDoc, runtime.conversationId);
+        endRun(tx, live, runtime.taskId, { status: "unanswered", reason: "model_error", detail: text });
+        return {
+            status: "terminal",
+            outcome: { status: "failed", error: { message: text, detail: { reason: "model_error" } } },
+        };
+    }, context);
+}
 /** Settle the run's inputs `unanswered` with `no_model` and fail. */
 async function failNoModel(runtime, ref, context) {
     const message = ref === undefined ? "No model is configured" : `Model ${ref.provider}/${ref.modelId} is not available`;
@@ -124,13 +242,16 @@ async function failNoModel(runtime, ref, context) {
         return { status: "terminal", outcome: { status: "failed", error: { message, detail: { reason: "no_model" } } } };
     }, context);
 }
-/** Append a committed partial left by an interrupted attempt as an aborted assistant entry; the caller replaces `generation`. */
-async function convertPartial(tx, live, conversationId) {
+/**
+ * Append a committed partial left by an interrupted, aborted, faulted, or orphaned attempt as an aborted assistant
+ * entry; the caller replaces or removes `generation`.
+ */
+export async function convertPartial(tx, live, conversationId) {
     const partial = live.generation?.message;
     if (partial === undefined)
         return;
     const message = copyJson(partial);
-    await tx.appendEntry(AssistantEntry, conversationId, { model: [{ ...message, stopReason: "aborted" }] });
+    await appendAssistant(tx, conversationId, { ...message, stopReason: "aborted" });
 }
 /**
  * Stream one request and return the terminal message. Partials commit as trailing writes at most every 100 ms with one
@@ -171,7 +292,9 @@ async function streamResponse(runtime, model, messages, options, attempt, contex
     try {
         const events = runtime.models.streamSimple(model, { messages: [...messages] }, options);
         for await (const event of events) {
-            if (event.type === "done" || event.type === "error")
+            // A partial without content, such as pi-ai's opening `start` event, shows nothing; a deferred response
+            // never gets past it, so it never leaves a partial.
+            if (event.type === "done" || event.type === "error" || event.partial.content.length === 0)
                 continue;
             pending = event.partial;
             if (timer === undefined && inFlight === undefined)
@@ -185,43 +308,78 @@ async function streamResponse(runtime, model, messages, options, attempt, contex
         await inFlight;
     }
 }
-/**
- * Classify a terminal provider message in one commit that also clears the partial. `previousPollAt` is set when the
- * message came from polling, so a still deferred result polls strictly later.
- */
-async function classify(runtime, attempt, ref, previousPollAt, message, context) {
+/** Classify a terminal provider message in one commit that also clears the partial. */
+async function classify(runtime, request, message, context) {
     // An abort mark or close: the abort invocation or the reopened run handles the committed state.
     runtime.signal.throwIfAborted();
     const conversationId = runtime.conversationId;
+    const { attempt, compacted, model: ref, toolExecution, cutoff } = request;
     if (message.stopReason === "deferred" && message.deferred !== undefined) {
         const handle = message.deferred;
-        const pollAt = Math.max(runtime.now() + (handle.pollAfterMs ?? DEFAULT_POLL_AFTER_MS), previousPollAt === undefined ? Number.NEGATIVE_INFINITY : previousPollAt + 1);
+        const pollAt = Math.max(runtime.now() + (handle.pollAfterMs ?? DEFAULT_POLL_AFTER_MS), request.pollAt === undefined ? Number.NEGATIVE_INFINITY : request.pollAt + 1);
         await runtime.commit(async (tx) => {
             (await tx.doc(LiveDoc, conversationId)).generation = { attempt, deferred: { pollAt } };
-            return { status: "running", checkpoint: { phase: "poll", attempt, model: ref, handle, pollAt } };
+            const checkpoint = {
+                phase: "poll",
+                attempt,
+                ...(compacted === undefined ? {} : { compacted }),
+                model: ref,
+                toolExecution,
+                cutoff,
+                handle,
+                pollAt,
+            };
+            return { status: "running", checkpoint };
         }, context);
         return;
     }
-    const policy = (await runtime.snapshot(ConversationConfig, conversationId, context))?.retry ?? DEFAULT_RETRY_POLICY;
+    await runtime.hooks.each("afterResponse", (hook) => hook(message, runtime, context));
+    const calls = message.content.filter((content) => content.type === "toolCall");
+    if (message.stopReason === "toolUse" && calls.length > 0) {
+        return startToolRound(runtime, request, message, calls, context);
+    }
+    if (message.stopReason === "stop" || message.stopReason === "length" || message.stopReason === "toolUse") {
+        return answer(runtime, message, context);
+    }
+    // The retry and compaction policies govern the next attempt, so they are read now rather than pinned at preparation.
+    const config = await runtime.snapshot(ConversationConfig, conversationId, context);
+    const overflow = message.stopReason === "error" && isContextOverflow(message);
+    if (overflow && compacted === undefined && (config?.compaction ?? DEFAULT_COMPACTION_POLICY).enabled) {
+        const policy = config?.compaction ?? DEFAULT_COMPACTION_POLICY;
+        const view = await runtime.context(conversationId, context, cutoff);
+        if (selectCut(view, policy.keepRecentTokens) !== undefined) {
+            const text = message.errorMessage ?? "Context overflow";
+            await runtime.commit(async (tx) => {
+                const live = await tx.doc(LiveDoc, conversationId);
+                await appendAssistant(tx, conversationId, message);
+                delete live.generation;
+                const child = await createCompaction(tx, conversationId, { reason: "overflow" }, runtime.taskId);
+                const checkpoint = { phase: "prepare", attempt, compacted: child, overflow: text };
+                return { status: "waiting", checkpoint, on: [child], policy: "allSettled" };
+            }, context);
+            return;
+        }
+    }
+    const policy = config?.retry ?? DEFAULT_RETRY_POLICY;
+    // An overflow is never retried: only a compaction can make the next request fit.
     const retry = message.stopReason === "error" &&
+        !overflow &&
         isRetryableAssistantError(message) &&
         policy.enabled &&
         attempt <= policy.maxRetries;
     const until = retry ? runtime.now() + retryDelayMs(policy, attempt) : 0;
     await runtime.commit(async (tx) => {
         const live = await tx.doc(LiveDoc, conversationId);
-        const entry = await tx.appendEntry(AssistantEntry, conversationId, { model: [message] });
-        switch (message.stopReason) {
-            case "stop":
-            case "length":
-            // Until the tool chain exists, a tool call settles as the answer.
-            case "toolUse":
-                endRun(tx, live, runtime.taskId, { status: "done", answer: entry.id });
-                return { status: "terminal", outcome: { status: "completed", result: { entryId: entry.id } } };
-        }
+        await appendAssistant(tx, conversationId, message);
         if (retry) {
             live.generation = { attempt, retry: { at: until, error: message.errorMessage ?? "" } };
-            return { status: "running", checkpoint: { phase: "retry", attempt, until } };
+            const checkpoint = {
+                phase: "retry",
+                attempt,
+                ...(compacted === undefined ? {} : { compacted }),
+                until,
+            };
+            return { status: "running", checkpoint };
         }
         const text = message.errorMessage ?? `Model response ended with stop reason ${message.stopReason}`;
         endRun(tx, live, runtime.taskId, { status: "unanswered", reason: "model_error", detail: text });
@@ -232,35 +390,155 @@ async function classify(runtime, attempt, ref, previousPollAt, message, context)
     }, context);
 }
 /**
- * Assign `value` at `target[key]` leaf by leaf. Chord records a container assignment as one full set and only emits an
- * append when a string leaf is reassigned with a longer string, so writing the partial whole would store and publish the
- * complete message on every flush.
+ * A final answer; the final boundary places queued items (spec §6). The first `onYield` continuation appends a user
+ * message and hands the run to a successor generation, but only when the boundary selected no user item and no reset.
+ * Otherwise the run's inputs settle `done`, and selected user items start the next run.
  */
-function assignJson(target, key, value) {
-    const slots = target;
-    const current = slots[key];
-    if (isRecord(current) && isRecord(value)) {
-        for (const name of Object.keys(current))
-            if (!Object.hasOwn(value, name))
-                delete current[name];
-        for (const [name, child] of Object.entries(value))
-            assignJson(current, name, child);
-        return;
-    }
-    if (Array.isArray(current) && Array.isArray(value) && current.length <= value.length) {
-        const items = current;
-        for (let index = 0; index < value.length; index++) {
-            if (index < items.length)
-                assignJson(items, index, value[index]);
-            else
-                items.push(value[index]);
+async function answer(runtime, message, context) {
+    let continuation;
+    await runtime.hooks.each("onYield", async (hook) => {
+        if (continuation !== undefined)
+            return;
+        continuation = (await hook(message, runtime, context))?.continue;
+    });
+    const conversationId = runtime.conversationId;
+    await runtime.commit(async (tx) => {
+        const boundary = await prepareBoundary(tx, conversationId);
+        const live = await tx.doc(LiveDoc, conversationId);
+        const entry = await appendAssistant(tx, conversationId, message);
+        const result = { status: "terminal", outcome: { status: "completed", result: { entryId: entry.id } } };
+        const { users, reset } = await applyBoundary(tx, boundary, "final", runtime.now());
+        if (continuation !== undefined && users.length === 0 && !reset) {
+            const user = { role: "user", content: continuation, timestamp: runtime.now() };
+            await tx.appendEntry(UserEntry, conversationId, { model: [user] });
+            handOver(live, runtime.taskId, await createGeneration(tx, conversationId));
+            delete live.generation;
+            return result;
         }
-        return;
-    }
-    if (current !== value)
-        slots[key] = value;
+        endRun(tx, live, runtime.taskId, { status: "done", answer: entry.id });
+        if (users.length > 0)
+            await startRun(tx, conversationId, live, users);
+        return result;
+    }, context);
+}
+/**
+ * Append the tool-calling answer and start its tool round in one commit (spec §8.3). A call to a tool the request did
+ * not offer gets its `tool_unavailable` result here; every other call gets a tool task owned by the generation, only the
+ * first one now when the round is sequential. The generation then waits for them in its `tools` phase, keeping the run.
+ */
+async function startToolRound(runtime, request, message, calls, context) {
+    const conversationId = runtime.conversationId;
+    const messages = request.messages ?? (await runtime.context(conversationId, context, request.cutoff)).messages;
+    const offered = new Set(getCurrentTools(messages).map((tool) => tool.name));
+    const sequential = request.toolExecution === "sequential" ||
+        calls.some((call) => offered.has(call.name) && runtime.registry.tool(call.name)?.executionMode === "sequential");
+    await runtime.commit(async (tx) => {
+        const live = await tx.doc(LiveDoc, conversationId);
+        const entry = await appendAssistant(tx, conversationId, message);
+        const slots = [];
+        const tools = [];
+        const pending = [];
+        for (const call of calls) {
+            if (!offered.has(call.name)) {
+                const unavailable = harnessError("tool_unavailable", `Tool ${call.name} is not available`);
+                const result = await appendToolResult(tx, conversationId, call, unavailable, runtime.now());
+                slots.push({ callId: call.id, name: call.name, status: "done", entry: result.id });
+                continue;
+            }
+            if (sequential && tools.length > 0) {
+                pending.push(call.id);
+                slots.push({ callId: call.id, name: call.name, status: "pending" });
+                continue;
+            }
+            const taskId = await createToolTask(tx, runtime, entry.id, call.id);
+            tools.push(taskId);
+            slots.push({ callId: call.id, name: call.name, taskId, status: "pending" });
+        }
+        delete live.generation;
+        live.tools = slots;
+        const checkpoint = { phase: "tools", assistant: entry.id, tools, pending };
+        return { status: "waiting", checkpoint, on: tools, policy: "allSettled" };
+    }, context);
+}
+/**
+ * The round's tools are terminal: apply their controls and either end the run at the final boundary (`terminate`,
+ * `handoff`, or a queued reset) or hand it to the next generation at the `postTools` boundary (spec §8.5).
+ */
+async function finishToolRound(runtime, assistant, tools, context) {
+    const conversationId = runtime.conversationId;
+    const controls = new Map();
+    const outcomes = await runtime.outcomes(tools, context);
+    tools.forEach((id, index) => {
+        const outcome = outcomes[index];
+        controls.set(id, outcome.status === "completed" ? outcome.result.control : undefined);
+    });
+    const slots = (await runtime.snapshot(LiveDoc, conversationId, context))?.tools ?? [];
+    const results = slots.flatMap((slot) => (slot.entry === undefined ? [] : [slot.entry]));
+    await runtime.hooks.each("afterTools", (hook) => hook(assistant, results, runtime, context));
+    // Every call of the round, including those answered without a task, must ask to terminate.
+    const terminate = slots.length > 0 &&
+        slots.every((slot) => slot.taskId !== undefined && controls.get(slot.taskId)?.terminate === true);
+    const added = [...controls.values()].flatMap((control) => control?.addTools ?? []);
+    // The last handoff in call order wins.
+    const handoff = [...controls.values()].findLast((control) => control?.handoff !== undefined)?.handoff;
+    await runtime.commit(async (tx) => {
+        const boundary = await prepareBoundary(tx, conversationId);
+        if (added.length > 0) {
+            const config = await tx.doc(ConversationConfig, conversationId);
+            for (const name of added)
+                if (!config.activeTools.includes(name))
+                    config.activeTools.push(name);
+        }
+        const live = await tx.doc(LiveDoc, conversationId);
+        const now = runtime.now();
+        if (terminate || handoff !== undefined) {
+            if (handoff !== undefined) {
+                const message = { role: "user", content: handoff, timestamp: now };
+                const entry = await tx.appendEntry(ResetEntry, conversationId, { head: "self", model: [message] });
+                boundary.head = entry.id;
+            }
+            const { users } = await applyBoundary(tx, boundary, "final", now);
+            endRun(tx, live, runtime.taskId, { status: "done", answer: assistant });
+            if (users.length > 0)
+                await startRun(tx, conversationId, live, users);
+        }
+        else {
+            const { users, reset } = await applyBoundary(tx, boundary, "postTools", now);
+            if (reset) {
+                // The queued reset cut the run's context before an answer.
+                endRun(tx, live, runtime.taskId, { status: "unanswered", reason: "reset" });
+                if (users.length > 0)
+                    await startRun(tx, conversationId, live, users);
+            }
+            else {
+                delete live.tools;
+                if (live.run?.taskId === runtime.taskId)
+                    live.run.inputs.push(...users);
+                handOver(live, runtime.taskId, await createGeneration(tx, conversationId));
+            }
+        }
+        return { status: "terminal", outcome: { status: "completed", result: { entryId: assistant } } };
+    }, context);
+}
+/**
+ * Append a provider result and add its usage to `pi.usage` in the same commit.
+ * REMINDER: every built-in writer of assistant entries goes through here, so the usage ledger stays complete.
+ */
+async function appendAssistant(tx, conversationId, message) {
+    await recordUsage(tx, conversationId, "models", `${message.provider}/${message.model}`, message.usage);
+    return tx.appendEntry(AssistantEntry, conversationId, { model: [message] });
+}
+/** Start a run for `inputs`, placed input submissions: a new generation takes `pi.live.run`. */
+export async function startRun(tx, conversationId, live, inputs) {
+    live.run = { taskId: await createGeneration(tx, conversationId), inputs };
+}
+/** A generation owned by its conversation. */
+function createGeneration(tx, conversationId) {
+    return tx.createTask(GenerationTask, {}, { ownership: { kind: "conversation" }, conversationId });
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+/** Hand run control from `from` to `to`; the run's inputs move with it. */
+export function handOver(live, from, to) {
+    if (live.run?.taskId === from)
+        live.run.taskId = to;
 }
 //# sourceMappingURL=generation.js.map