agency-lang 0.19.1 → 0.19.2

package/dist/lib/runtime/callbackForwarding.d.ts

@@ -39,7 +39,10 @@ export declare const CALLBACK_PAYLOAD_LIMIT: number;
  * excluded by non-existence rather than listed here. See the plan's
  * "Scope & design tradeoffs" section. Exported so the parent-side handler
  * (ipc.ts) rejects the same names — the guard should match its intent even under
- * parent/child version skew. */
+ * parent/child version skew. onCheckpoint is JSON-safe but must stay local: a
+ * child run inherits the parent's run id, so a forwarded child checkpoint would
+ * look to the parent's host like the parent's own latest state, and resuming
+ * the parent from it would restore the child program's stack. */
 export declare const NON_FORWARDABLE_CALLBACKS: readonly CallbackName[];
 /** Forward one lifecycle event to the parent. No-op unless this process is a
  * forked Agency subprocess with a live IPC channel. `maxBytes` is overridable

package/dist/lib/runtime/callbackForwarding.js

@@ -34,8 +34,15 @@ export const CALLBACK_PAYLOAD_LIMIT = 1024 * 1024 * 1024; // 1gb
  * excluded by non-existence rather than listed here. See the plan's
  * "Scope & design tradeoffs" section. Exported so the parent-side handler
  * (ipc.ts) rejects the same names — the guard should match its intent even under
- * parent/child version skew. */
-export const NON_FORWARDABLE_CALLBACKS = ["onStream", "onOAuthRequired"];
+ * parent/child version skew. onCheckpoint is JSON-safe but must stay local: a
+ * child run inherits the parent's run id, so a forwarded child checkpoint would
+ * look to the parent's host like the parent's own latest state, and resuming
+ * the parent from it would restore the child program's stack. */
+export const NON_FORWARDABLE_CALLBACKS = [
+    "onStream",
+    "onOAuthRequired",
+    "onCheckpoint",
+];
 /** Forward one lifecycle event to the parent. No-op unless this process is a
  * forked Agency subprocess with a live IPC channel. `maxBytes` is overridable
  * only so tests can exercise the oversize-skip without a gigabyte payload. */

package/dist/lib/runtime/debugger.d.ts

@@ -1,8 +1,9 @@
 import type { Interrupt } from "./interrupts.js";
 import type { RuntimeContext } from "./state/context.js";
 import type { SourceLocation } from "./state/sourceLocation.js";
+import type { StateStack } from "./state/stateStack.js";
 export declare function debugStep(ctx: RuntimeContext<any>, info: Omit<SourceLocation, "nodeId"> & {
     label: string | null;
     nodeContext: boolean;
     isUserAdded: boolean;
-}): Promise<Interrupt[] | undefined>;
+}, stack?: StateStack): Promise<Interrupt[] | undefined>;

package/dist/lib/runtime/debugger.js

@@ -1,6 +1,8 @@
 import { createDebugInterrupt } from "./interrupts.js";
+import { callHook, hasCallbackConsumer } from "./hooks.js";
+import { nativeTypeReplacer } from "./revivers/index.js";
 import { Checkpoint } from "./state/checkpointStore.js";
-export async function debugStep(ctx, info) {
+export async function debugStep(ctx, info, stack) {
     // Global initialization runs outside any graph node, so there's no node
     // context to create checkpoints against. Skip debugging entirely.
     if (!ctx.stateStack.currentNodeId()) {
@@ -13,6 +15,23 @@ export async function debugStep(ctx, info) {
     if (!skipCheckpoint && ctx.stateStack.currentNodeId()) {
         const cp = Checkpoint.fromContext(ctx, info);
         await ctx.writeCheckpointToTraceWriter(cp);
+        // Only a checkpoint on the top-level stack is reported: a branch (fork,
+        // parallel block, tool call) cannot be re-entered from outside, the same
+        // rule a pause follows. The payload goes through nativeTypeReplacer so
+        // a scoped Agency callback becomes a function ref the host can store
+        // and the resume path can revive.
+        if (stack !== undefined &&
+            stack === ctx.stateStack &&
+            hasCallbackConsumer(ctx, "onCheckpoint", stack)) {
+            await callHook({
+                ctx,
+                name: "onCheckpoint",
+                data: {
+                    runId: ctx.getRunId(),
+                    checkpoint: JSON.parse(JSON.stringify(cp.toJSON(), nativeTypeReplacer)),
+                },
+            });
+        }
     }
     const dbg = ctx.debuggerState;
     if (!dbg) {

package/dist/lib/runtime/handoff.d.ts

@@ -1,29 +1,45 @@
 import type { MessageThread } from "./state/messageThread.js";
 /** The refusal for a handoff call that shares a round with another call. */
 export declare function handoffNotAloneMessage(toolName: string): string;
-export declare function handoffMarkerText(toolName: string, args: Record<string, unknown>): string;
+/** The scope key one dispatch tags its body's system messages with. The
+ *  nesting depth is part of it because a provider that sends no call ids
+ *  (Gemini) leaves a handoff nested inside itself with the same name and
+ *  the same empty id. Compute it before entering the scope and again after
+ *  leaving it; the depth is the same at both points. */
+export declare function handoffScopeKey(thread: MessageThread, toolName: string, toolCallId: string): string;
 export declare function handoffResumeText(toolName: string, body: string): string;
 /** The resume message for a handoff that failed or was aborted partway. */
 export declare function handoffStoppedText(toolName: string, reason: string): string;
 /**
- * Rewrite the assistant message that carried the handoff tool call: keep
- * its text, drop the tool call, append the marker.
+ * Drop the tool call from the assistant message that carried the handoff
+ * call. Its text stays; a message that was only the call is removed, so
+ * the thread reads as the user's request followed by the body's work.
+ * Nothing is added in its place: a model that sees dispatch narration in
+ * its history learns to write it instead of calling the tool.
  */
-export declare function applyHandoffMarker(thread: MessageThread, toolName: string, args: Record<string, unknown>): void;
+export declare function dropHandoffToolCall(thread: MessageThread): void;
 /**
- * Remove the system messages the body pushed: every system message after
- * this dispatch's marker. Anchored on the marker rather than on a recorded
- * position because memory compaction rewrites the thread and shifts every
- * index. A marker that compaction summarized away took the body's earlier
- * system messages with it, so there is nothing left to remove.
+ * Remove the system messages the body pushed: every message tagged with
+ * this dispatch's scope key. Tags survive checkpoints and compaction, and
+ * a message compaction summarized away is simply not there to remove.
  */
-export declare function stripHandoffSystemMessages(thread: MessageThread, toolName: string, args: Record<string, unknown>): void;
+export declare function stripHandoffSystemMessages(thread: MessageThread, scopeKey: string): void;
 /**
  * Close a handoff: remove the body's system messages (its persona is not
  * useful to the caller afterwards and would grow the context on every
  * dispatch), then hand control back with a user-role message that carries
  * the body's result.
  */
-export declare function finishHandoff(thread: MessageThread, toolName: string, args: Record<string, unknown>, body: string): void;
+export declare function finishHandoff(args: {
+    thread: MessageThread;
+    scopeKey: string;
+    toolName: string;
+    body: string;
+}): void;
 /** Close a handoff that failed or was aborted. */
-export declare function finishStoppedHandoff(thread: MessageThread, toolName: string, args: Record<string, unknown>, reason: string): void;
+export declare function finishStoppedHandoff(args: {
+    thread: MessageThread;
+    scopeKey: string;
+    toolName: string;
+    reason: string;
+}): void;

package/dist/lib/runtime/handoff.js

@@ -1,11 +1,13 @@
 /**
  * Message plumbing for handoff functions (`handoff def`). When a model
  * calls one as a tool, the tool loop keeps the body on the caller's
- * thread and replaces the tool-call bookkeeping with two plain messages:
- * an assistant-role marker where the tool call was, and a user-role
- * resume message when the body returns. These helpers only touch a
- * MessageThread; prompt.ts decides when to call them. See
- * docs/dev/language/handoff-functions.md.
+ * thread: the tool call is dropped from the assistant message that
+ * carried it (providers demand a tool result right after a tool call,
+ * and the body's messages land there instead), the body's system
+ * messages are tagged with the dispatch's scope key while it runs, and a
+ * user-role resume message hands control back when the body returns.
+ * These helpers only touch a MessageThread; prompt.ts decides when to
+ * call them. See docs/dev/language/handoff-functions.md.
  */
 import * as smoltalk from "smoltalk";
 /** The refusal for a handoff call that shares a round with another call. */
@@ -13,8 +15,13 @@ export function handoffNotAloneMessage(toolName) {
     return (`Error: ${toolName} continues this conversation, so it must be the only tool call in its round. ` +
         `It was not run. Call it again by itself, with no other tool calls in the same response.`);
 }
-export function handoffMarkerText(toolName, args) {
-    return `[dispatching ${toolName}: ${JSON.stringify(args)}]`;
+/** The scope key one dispatch tags its body's system messages with. The
+ *  nesting depth is part of it because a provider that sends no call ids
+ *  (Gemini) leaves a handoff nested inside itself with the same name and
+ *  the same empty id. Compute it before entering the scope and again after
+ *  leaving it; the depth is the same at both points. */
+export function handoffScopeKey(thread, toolName, toolCallId) {
+    return `${toolName}:${toolCallId}:${thread.handoffDepth()}`;
 }
 export function handoffResumeText(toolName, body) {
     return `[${toolName} finished. ${body}]\nContinue with the user's request.`;
@@ -25,10 +32,13 @@ export function handoffStoppedText(toolName, reason) {
         `Its work so far is in the messages above. Continue with the user's request using that work.`);
 }
 /**
- * Rewrite the assistant message that carried the handoff tool call: keep
- * its text, drop the tool call, append the marker.
+ * Drop the tool call from the assistant message that carried the handoff
+ * call. Its text stays; a message that was only the call is removed, so
+ * the thread reads as the user's request followed by the body's work.
+ * Nothing is added in its place: a model that sees dispatch narration in
+ * its history learns to write it instead of calling the tool.
  */
-export function applyHandoffMarker(thread, toolName, args) {
+export function dropHandoffToolCall(thread) {
     const messages = thread.getMessages();
     const index = messages.length - 1;
     const last = messages[index];
@@ -36,39 +46,19 @@ export function applyHandoffMarker(thread, toolName, args) {
         throw new Error(`handoff: expected the thread to end with the assistant message carrying the tool call, found ${last?.role ?? "an empty thread"}`);
     }
     const text = typeof last.content === "string" ? last.content.trim() : "";
-    const marker = handoffMarkerText(toolName, args);
-    const content = text === "" ? marker : `${text}\n\n${marker}`;
-    thread.replaceAt(index, smoltalk.assistantMessage(content));
-}
-/** The index of this dispatch's marker, searching from the end so the
- *  newest dispatch of a tool wins. -1 when memory compaction has
- *  summarized the marker away. */
-function markerIndex(thread, toolName, args) {
-    const marker = handoffMarkerText(toolName, args);
-    const messages = thread.getMessages();
-    for (let index = messages.length - 1; index >= 0; index--) {
-        const message = messages[index];
-        if (message.role === "assistant" &&
-            typeof message.content === "string" &&
-            message.content.endsWith(marker)) {
-            return index;
-        }
+    if (text === "") {
+        thread.removeAt(index);
+        return;
     }
-    return -1;
+    thread.replaceAt(index, smoltalk.assistantMessage(text));
 }
 /**
- * Remove the system messages the body pushed: every system message after
- * this dispatch's marker. Anchored on the marker rather than on a recorded
- * position because memory compaction rewrites the thread and shifts every
- * index. A marker that compaction summarized away took the body's earlier
- * system messages with it, so there is nothing left to remove.
+ * Remove the system messages the body pushed: every message tagged with
+ * this dispatch's scope key. Tags survive checkpoints and compaction, and
+ * a message compaction summarized away is simply not there to remove.
  */
-export function stripHandoffSystemMessages(thread, toolName, args) {
-    const index = markerIndex(thread, toolName, args);
-    if (index === -1) {
-        return;
-    }
-    thread.removeMatching(index + 1, (message) => message.role === "system");
+export function stripHandoffSystemMessages(thread, scopeKey) {
+    thread.removeHandoffScoped(scopeKey);
 }
 /**
  * Close a handoff: remove the body's system messages (its persona is not
@@ -76,12 +66,12 @@ export function stripHandoffSystemMessages(thread, toolName, args) {
  * dispatch), then hand control back with a user-role message that carries
  * the body's result.
  */
-export function finishHandoff(thread, toolName, args, body) {
-    stripHandoffSystemMessages(thread, toolName, args);
-    thread.push(smoltalk.userMessage(handoffResumeText(toolName, body)));
+export function finishHandoff(args) {
+    stripHandoffSystemMessages(args.thread, args.scopeKey);
+    args.thread.push(smoltalk.userMessage(handoffResumeText(args.toolName, args.body)));
 }
 /** Close a handoff that failed or was aborted. */
-export function finishStoppedHandoff(thread, toolName, args, reason) {
-    stripHandoffSystemMessages(thread, toolName, args);
-    thread.push(smoltalk.userMessage(handoffStoppedText(toolName, reason)));
+export function finishStoppedHandoff(args) {
+    stripHandoffSystemMessages(args.thread, args.scopeKey);
+    args.thread.push(smoltalk.userMessage(handoffStoppedText(args.toolName, args.reason)));
 }

package/dist/lib/runtime/hooks.d.ts

@@ -2,7 +2,7 @@ import type { CostEstimate, MessageJSON, ModelName, PromptResult, TokenUsage, To
 import type { LLMRetryReason } from "./llmRetry.js";
 import type { RuntimeContext } from "./state/context.js";
 import type { StateStack } from "./state/stateStack.js";
-import type { TraceEvent } from "./trace/types.js";
+import type { CheckpointJSON, TraceEvent } from "./trace/types.js";
 import type { RunNodeResult } from "./types.js";
 export type CallbackMap = {
     onAgentStart: {
@@ -83,6 +83,15 @@ export type CallbackMap = {
         error: any;
     };
     onTrace: TraceEvent;
+    /** One statement checkpoint on the top-level stack, fired from `debugStep`
+     *  whenever a consumer is registered. `checkpoint` is plain JSON (function
+     *  refs encoded, as in a pause result); `{ type: "paused", checkpoint,
+     *  runId }` resumes through `resumeFromCheckpoint`. Never forwarded from
+     *  a subprocess. */
+    onCheckpoint: {
+        runId: string;
+        checkpoint: CheckpointJSON;
+    };
     onOAuthRequired: {
         serverName: string;
         authUrl: string;

package/dist/lib/runtime/prompt.js

@@ -24,7 +24,7 @@ import { warnOnOversizedToolSchemas } from "./toolSchemaSize.js";
 import { DEFAULT_MAX_REPEATED_TOOL_CALLS, freshRepeatStreak, markupArgument, markupArgumentMessage, noteRepeat, repeatedCallMessage, repeatKey, repeatsBefore, resetRepeat, } from "./toolLoopGuards.js";
 import { GuardTripRetry, raiseGuardTripsUntilClear } from "./guardTripInterrupt.js";
 import { failure, isFailure, isSuccess, markDestructiveWork, runtimeFailure } from "./result.js";
-import { applyHandoffMarker, finishHandoff, finishStoppedHandoff, handoffNotAloneMessage, stripHandoffSystemMessages, } from "./handoff.js";
+import { dropHandoffToolCall, finishHandoff, finishStoppedHandoff, handoffNotAloneMessage, handoffScopeKey, stripHandoffSystemMessages, } from "./handoff.js";
 import { isAborted } from "./abortedResult.js";
 import { MessageThread } from "./state/messageThread.js";
 import { claimFrameForScope } from "./state/stateStack.js";
@@ -164,13 +164,22 @@ async function invokeOnFreshThreadStore(ctx, invoke) {
  * active stack, so two prompts running at once (two `async llm()` calls,
  * say) cannot interleave pushes and pops on a shared one.
  */
-async function invokeOnThread(thread, invoke) {
-    const parentFrame = agencyStore.getStore();
-    if (!parentFrame) {
-        return invoke();
+async function invokeOnThread(thread, scopeKey, invoke) {
+    // The body's system messages are tagged with the dispatch's scope key
+    // while it runs, so the hand-back can remove them without a marker on
+    // the thread. Re-entered when a resume re-runs the dispatch.
+    thread.enterHandoffScope(scopeKey);
+    try {
+        const parentFrame = agencyStore.getStore();
+        if (!parentFrame) {
+            return await invoke();
+        }
+        const view = parentFrame.threads.viewWithActive(thread);
+        return await agencyStore.run({ ...parentFrame, threads: view }, invoke);
+    }
+    finally {
+        thread.exitHandoffScope();
     }
-    const view = parentFrame.threads.viewWithActive(thread);
-    return agencyStore.run({ ...parentFrame, threads: view }, invoke);
 }
 /** Classify a tool failure. Most-specific fact wins: a started destructive
  *  operation, then a proved-nothing-ran, then the tool's own idempotent
@@ -350,10 +359,16 @@ async function runPostTurnMemory(ctx, targetStack, messages) {
             // Reassemble the thread from the ORIGINAL smoltalk Message
             // instances so tool_call metadata, ids, and other class-level
             // fields survive untouched.
+            // Labels and handoff scopes ride along with the kept messages; the
+            // summary has neither.
+            const kept = [...plan.systemPrefixIndices, ...plan.tailIndices];
             const head = plan.systemPrefixIndices.map((i) => original[i]);
             const tail = plan.tailIndices.map((i) => original[i]);
             const summary = smoltalk.systemMessage(plan.summaryMessageContent);
-            messages.setMessages([...head, summary, ...tail]);
+            const labels = kept.map((i) => messages.labelAt(i));
+            const scopes = kept.map((i) => messages.scopeAt(i));
+            const splitAt = head.length;
+            messages.setMessages([...head, summary, ...tail], [...labels.slice(0, splitAt), null, ...labels.slice(splitAt)], [...scopes.slice(0, splitAt), null, ...scopes.slice(splitAt)]);
         }
     }
     catch (err) {
@@ -866,7 +881,7 @@ export async function runPrompt(args) {
                 // Every other tool gets a fresh store.
                 const continuesCallerThread = !!handler.markers?.handoff;
                 if (continuesCallerThread) {
-                    toolResult = await invokeOnThread(messages, invokeAsTool);
+                    toolResult = await invokeOnThread(messages, handoffScopeKey(messages, handler.name, toolCall.id), invokeAsTool);
                 }
                 else {
                     toolResult = await invokeOnFreshThreadStore(ctx, invokeAsTool);
@@ -880,11 +895,10 @@ export async function runPrompt(args) {
                 // "Tool call X crashed" for every tool on the stack and corrupt
                 // the thread. Mirrors the function/node catch re-throws. A
                 // cancelled handoff never reaches finishHandoff, so its body's
-                // system messages are removed here; the marker stays as the
-                // record of what was attempted.
+                // system messages are removed here.
                 if (isAbortError(error)) {
                     if (handler.markers?.handoff) {
-                        stripHandoffSystemMessages(messages, handler.name, namedArgs);
+                        stripHandoffSystemMessages(messages, handoffScopeKey(messages, handler.name, toolCall.id));
                     }
                     stack.deleteBranch(branchKey);
                     throw error;
@@ -1044,7 +1058,7 @@ export async function runPrompt(args) {
         // Push a plain notice ToolMessage for one call — the refusal gates
         // (unhandled, round cap, removed, markup, repeat, prior rejection,
         // handoff not alone) all answer the model this way. A refusal happens
-        // before the .handoffMarker step, so the assistant message is intact
+        // before the .handoffDropCall step, so the assistant message is intact
         // and the notice pairs with its tool_use even for a handoff.
         const pushToolMessage = (content, toolCall) => {
             messages.push(smoltalk.toolMessage(content, { tool_call_id: toolCall.id, name: toolCall.name }));
@@ -1054,20 +1068,31 @@ export async function runPrompt(args) {
         };
         // Answer the model for one invoked call. An ordinary tool gets a
         // tool message paired with its tool_use. A handoff has no tool_use
-        // (the .handoffMarker step rewrote it), so it gets the user-role
+        // (the .handoffDropCall step removed it), so it gets the user-role
         // resume message instead, after the body's system messages are
         // stripped. `content` may be structured; the resume message needs
         // text. `stoppedReason` is set when the call failed or was aborted;
         // a handoff's resume message then points at the work already on this
         // thread instead of carrying the error text an ordinary tool gets.
         const pushToolReply = (args) => {
-            const { content, toolCall, handler, namedArgs, stoppedReason } = args;
+            const { content, toolCall, handler, stoppedReason } = args;
             if (handler.markers?.handoff) {
+                const scopeKey = handoffScopeKey(messages, handler.name, toolCall.id);
                 if (stoppedReason !== undefined) {
-                    finishStoppedHandoff(messages, handler.name, namedArgs, stoppedReason);
+                    finishStoppedHandoff({
+                        thread: messages,
+                        scopeKey,
+                        toolName: handler.name,
+                        reason: stoppedReason,
+                    });
                     return;
                 }
-                finishHandoff(messages, handler.name, namedArgs, stringifyToolResult(content));
+                finishHandoff({
+                    thread: messages,
+                    scopeKey,
+                    toolName: handler.name,
+                    body: stringifyToolResult(content),
+                });
                 return;
             }
             pushToolMessage(content, toolCall);
@@ -1315,15 +1340,15 @@ export async function runPrompt(args) {
                             // Unreachable: a missing handler yields the "unhandled" verdict.
                             return;
                         }
-                        // A handoff replaces the assistant message that carried
-                        // its tool call with a marker. The rewritten thread is in
-                        // the checkpoint, so a resumed pass does not rewrite again.
-                        // The thread ends on that assistant message here because
-                        // the handoff is the round's only call and the round
-                        // boundary runs after the tools.
+                        // A handoff drops the tool call from the assistant message
+                        // that carried it, so the body's messages can follow. The
+                        // rewritten thread is in the checkpoint, so a resumed pass
+                        // does not rewrite again. The thread ends on that assistant
+                        // message here because the handoff is the round's only call
+                        // and the round boundary runs after the tools.
                         if (handler.markers?.handoff) {
-                            await b.step(`${invocationKey}.handoffMarker`, async () => {
-                                applyHandoffMarker(messages, handler.name, namedArgs);
+                            await b.step(`${invocationKey}.handoffDropCall`, async () => {
+                                dropHandoffToolCall(messages);
                             });
                         }
                         const branchKey = `tool_${callSlug}`;

package/dist/lib/runtime/runner.d.ts

@@ -184,6 +184,12 @@ export declare class Runner {
     private maybeDebugHook;
     /** Clean up the debug flag for a step after it completes without halting. */
     private clearDebugFlag;
+    /** Whether this step should build a checkpoint: the debugger wants one, a
+     *  trace sink wants one, or a host or Agency callback registered for
+     *  `onCheckpoint` wants one. `debugHook` and `clearDebugFlag` must agree,
+     *  so both read this. The `onCheckpoint` reason applies only on the
+     *  top-level stack, because a branch checkpoint is not reported. */
+    private recordsStepCheckpoints;
     private stepPath;
     private debugFlagKey;
     /** Seed branch.stack.localCost / localTokens from the parent stack

package/dist/lib/runtime/runner.js

@@ -5,7 +5,7 @@ import { raiseGuardTripsAtStep } from "./guardTripInterrupt.js";
 import { debugStep } from "./debugger.js";
 import { RunControlSignal, readCause } from "./errors.js";
 import { HaltSignal } from "./haltSignal.js";
-import { invokeCallbacks, isInsideCallback } from "./hooks.js";
+import { hasCallbackConsumer, invokeCallbacks, isInsideCallback } from "./hooks.js";
 import { hasInterrupts } from "./interrupts.js";
 import { pauseAtStep } from "./pause.js";
 import { __pipeBind } from "./result.js";
@@ -368,7 +368,7 @@ export class Runner {
      * that pauses) — the flag stays set so the next resume skips the hook.
      */
     async maybeDebugHook(id, label = null, isUserAdded = false) {
-        if (!this.ctx.hasDebugger() && !this.ctx.hasTraceWriter())
+        if (!this.recordsStepCheckpoints())
             return false;
         if (this.ctx.isInsideToolCall())
             return false;
@@ -390,7 +390,7 @@ export class Runner {
             label,
             nodeContext: this.nodeContext,
             isUserAdded,
-        });
+        }, this.stack);
         if (dbg) {
             if (this.nodeContext) {
                 // Wrap in { messages, data } to match node return format.
@@ -411,11 +411,23 @@ export class Runner {
     }
     /** Clean up the debug flag for a step after it completes without halting. */
     clearDebugFlag(id) {
-        if (!this.ctx.hasDebugger() && !this.ctx.hasTraceWriter()) {
+        if (!this.recordsStepCheckpoints()) {
             return;
         }
         delete this.frame.locals[this.debugFlagKey(id)];
     }
+    /** Whether this step should build a checkpoint: the debugger wants one, a
+     *  trace sink wants one, or a host or Agency callback registered for
+     *  `onCheckpoint` wants one. `debugHook` and `clearDebugFlag` must agree,
+     *  so both read this. The `onCheckpoint` reason applies only on the
+     *  top-level stack, because a branch checkpoint is not reported. */
+    recordsStepCheckpoints() {
+        if (this.ctx.hasDebugger() || this.ctx.hasTraceWriter())
+            return true;
+        return (this.stack !== undefined &&
+            this.stack === this.ctx.stateStack &&
+            hasCallbackConsumer(this.ctx, "onCheckpoint", this.stack));
+    }
     stepPath(id) {
         return this.path.length === 0 ? `${id}` : `${this.key()}.${id}`;
     }

package/dist/lib/runtime/state/messageThread.d.ts

@@ -2,6 +2,7 @@ import * as smoltalk from "smoltalk";
 export type MessageThreadJSON = {
     messages: smoltalk.MessageJSON[];
     messageLabels?: (string | null)[];
+    messageScopes?: (string | null)[];
     parentId?: string | null;
     hidden?: boolean;
     label?: string | null;
@@ -84,10 +85,22 @@ export declare class MessageThread {
      *
      *  Nothing else touches `this.messages`. A desync does not degrade
      *  gracefully — it shifts every later label onto the wrong message — so
-     *  keep it that way. A rewrite via `setMessages` with no labels
-     *  (summarization) drops them; that is intended. (Thread repair
-     *  appends via `push`, so it keeps them.) */
+     *  keep it that way. A rewrite via `setMessages` with no labels drops
+     *  them; summarization passes the labels of the messages it keeps.
+     *  (Thread repair appends via `push`, so it keeps them.) */
     messageLabels: (string | null)[];
+    /** Which handoff dispatch a system message belongs to, aligned with
+     *  `messages` by index like `messageLabels`, null for every other
+     *  message. Stamped by `push` from `handoffScopes` while a dispatch's
+     *  body is running on this thread, so the body's persona can be
+     *  removed when the body returns without leaving a marker in the
+     *  conversation. Serialized with the thread, kept through compaction,
+     *  never sent to the provider. */
+    messageScopes: (string | null)[];
+    /** The dispatches whose bodies are running on this thread right now,
+     *  innermost last. Transient: the prompt loop re-enters a scope when it
+     *  re-runs a dispatch after a resume, so nothing here is serialized. */
+    private handoffScopes;
     /** Messages queued by `queueMessage`, waiting for the thread's next
      *  request-turn. Drained by the turn-boundary machinery in the tool
      *  loop; never sent to the provider directly from here. Serialized
@@ -108,7 +121,7 @@ export declare class MessageThread {
      *  outright rather than padded or sliced: the lengths disagreeing means
      *  the source is already wrong, and guessing an alignment would put
      *  real labels on the wrong messages. Unlabeled beats mislabeled. */
-    setMessages(messages: smoltalk.Message[], labels?: (string | null)[]): void;
+    setMessages(messages: smoltalk.Message[], labels?: (string | null)[], scopes?: (string | null)[]): void;
     /** Remove the message at `index`, taking its label with it. For the
      *  callers that edit one message out of the thread and would otherwise
      *  reach for `setMessages` and drop every label as collateral. */
@@ -137,6 +150,21 @@ export declare class MessageThread {
     push(message: smoltalk.Message, label?: string | null): void;
     /** The label of the message at `index`, or null when unlabeled. */
     labelAt(index: number): string | null;
+    /** The handoff dispatch the system message at `index` belongs to, or
+     *  null for a message outside any dispatch. */
+    scopeAt(index: number): string | null;
+    /** Mark the start of a handoff body on this thread: every system message
+     *  pushed until the matching `exitHandoffScope` belongs to `key`. Scopes
+     *  nest, innermost winning, for a handoff dispatched inside a handoff. */
+    enterHandoffScope(key: string): void;
+    exitHandoffScope(): void;
+    /** How many handoff bodies are running on this thread right now. */
+    handoffDepth(): number;
+    private currentHandoffScope;
+    /** Remove every message that belongs to the dispatch `key`: the
+     *  persona and any other system message its body pushed. Walks
+     *  backwards so each removal leaves the indexes still to visit intact. */
+    removeHandoffScoped(key: string): void;
     /** Queue a message for delivery at this thread's next request-turn:
      *  the start of the thread's next `llm()` call, or after a tool round
      *  within a running call. The mid-turn-safe counterpart to an immediate