@genesislcap/ai-assistant 15.61.0 → 15.62.0

package/dist/chat-driver.cjs

@@ -60,6 +60,7 @@ __export(chat_driver_node_exports, {
   buildTimelineEntries: () => buildTimelineEntries,
   clearSession: () => clearSession,
   defineAgent: () => defineAgent,
+  defineAutopilot: () => defineAutopilot,
   defineStatefulAgent: () => defineStatefulAgent,
   emptyUsage: () => emptyUsage,
   friendlyFallbackAgent: () => friendlyFallbackAgent,
@@ -3961,6 +3962,7 @@ var AgenticActivityBus = class {
     const inBrowser = typeof window !== "undefined" && typeof BroadcastChannel !== "undefined";
     if (this.crossTabEvents.size === 0 || !this.channelNameFactory || !inBrowser) return;
     this.channel = new BroadcastChannel(this.channelNameFactory());
+    this.channel.unref?.();
     this.channel.onmessage = (ev) => {
       const { type, detail } = ev.data ?? {};
       if (type) this.notifyLocal(type, detail);
@@ -4037,10 +4039,10 @@ var agenticActivityBus = new AgenticActivityBus({
 });
 
 // src/config/validate-providers.ts
-function resolveChatProvider(registry2, providerName, agentName) {
-  const provider = registry2.get(providerName);
+function resolveChatProvider(registry3, providerName, agentName) {
+  const provider = registry3.get(providerName);
   if (!provider) {
-    const available = registry2.names().join(", ") || "(none)";
+    const available = registry3.names().join(", ") || "(none)";
     throw new Error(
       `Agent "${agentName}" references unknown provider "${providerName}". Registered: ${available}`
     );
@@ -4052,13 +4054,13 @@ function resolveChatProvider(registry2, providerName, agentName) {
   }
   return provider;
 }
-function validateStaticAgentProviders(agents, registry2) {
+function validateStaticAgentProviders(agents, registry3) {
   const visited = /* @__PURE__ */ new Set();
   const walk = (agent) => {
     if (visited.has(agent)) return;
     visited.add(agent);
     if (typeof agent.provider === "string") {
-      resolveChatProvider(registry2, agent.provider, agent.name);
+      resolveChatProvider(registry3, agent.provider, agent.name);
     }
     for (const sub of agent.subAgents ?? []) walk(sub);
   };
@@ -4109,10 +4111,36 @@ var META_EVENT_IMPORTANCE = {
   "interaction.outcome": "normal",
   // An outcome that could not be recorded: the widget goes on showing only the answer.
   "interaction.outcome-dropped": "high",
+  // A long action's step starting, finishing, or skipped on resume because it was already done.
+  "interaction.step": "low",
+  // A cut checkpoint taken over after a reload, refused (by sameWork, or as malformed), or dropped
+  // at flow end.
+  "interaction.checkpoint": "normal",
   // A claimant handing a pending interaction to the person, or taking it back.
   "interaction.held": "normal",
   // A claim on a `userOnly` interaction, refused. Expected when an interceptor claims broadly.
   "interaction.claim-refused": "low",
+  // A claimant ran one of the surface's actions: what it did, and whether that settled it.
+  "interaction.invoked": "normal",
+  "autopilot.claimed": "normal",
+  // One per interaction the autopilot does not take, so frequent and mostly expected.
+  "autopilot.declined": "low",
+  "autopilot.decision-sent": "low",
+  "autopilot.acted": "normal",
+  "autopilot.handed-back": "normal",
+  "autopilot.paused": "normal",
+  "autopilot.resumed": "normal",
+  // The wrapper itself failed: the journey stops being automatic without anyone choosing that.
+  "autopilot.error": "high",
+  // A written answer counted against the step's limit; reaching it withdraws `reply`.
+  "autopilot.refinement": "normal",
+  // The autopilot showed its own widget because a working turn ended needing the person.
+  "autopilot.handback-presented": "normal",
+  // The autopilot was given the whole visible transcript: its first decision, a rebuild, or after
+  // a compaction removed the last message it saw.
+  "autopilot.catch-up": "normal",
+  // Autopilot spend that reached no message, so it is missing from the session total.
+  "autopilot.cost-dropped": "high",
   "external-diagnostics.folded": "normal",
   "session.cleared": "normal",
   "session.switched": "low",
@@ -4191,6 +4219,45 @@ function clearSession(key) {
   registry.delete(key);
 }
 
+// src/utils/delegated-message.ts
+var DEFAULT_DELEGATE_FRAMING = "Sent on the user's behalf.";
+function delegatedFields(options) {
+  if (!options?.delegate) return {};
+  const cost = options.externalCostUsd;
+  return {
+    delegate: options.delegate,
+    delegateFraming: options.delegateFraming ?? DEFAULT_DELEGATE_FRAMING,
+    ...typeof cost === "number" && Number.isFinite(cost) && cost > 0 ? { externalCostUsd: cost } : {}
+  };
+}
+function frameDelegatedContent(content, framing) {
+  return `(${framing ?? DEFAULT_DELEGATE_FRAMING})
+
+${content}`;
+}
+
+// src/utils/preserved-user-messages.ts
+function freshUserMessages(toCompact) {
+  return toCompact.flatMap(
+    (m) => m.role === "user" && m.content?.trim() ? [
+      {
+        content: m.content,
+        ...m.timestamp ? { timestamp: m.timestamp } : {},
+        ...m.delegate ? { delegate: m.delegate, delegateFraming: m.delegateFraming } : {}
+      }
+    ] : []
+  );
+}
+var preservedUserLine = (u) => `User: ${u.delegate ? frameDelegatedContent(u.content, u.delegateFraming) : u.content}`;
+function verbatimUserMessagesBlock(preserved) {
+  if (!preserved?.length) return "";
+  return `
+
+<user_messages_verbatim>
+${preserved.map(preservedUserLine).join("\n")}
+</user_messages_verbatim>`;
+}
+
 // src/utils/context-tokens.ts
 var APPROX_CHARS_PER_TOKEN = 4;
 var IMAGE_TOKEN_ESTIMATE = 1600;
@@ -4224,7 +4291,7 @@ function imageCount(m) {
 }
 var TEXT_ATTACHMENT_FRAMING_CHARS = 9;
 function wireChars(m) {
-  let chars = m.content?.length ?? 0;
+  let chars = (m.content?.length ?? 0) + verbatimUserMessagesBlock(m.compaction?.preservedUserMessages).length;
   for (const attachment of m.attachments ?? []) {
     if (attachment.kind === "image") continue;
     chars += TEXT_ATTACHMENT_FRAMING_CHARS + attachment.name.length + (attachment.content?.length ?? 0);
@@ -4313,8 +4380,11 @@ function projectCompaction(history, cut, summaryTokens = COMPACTION_SUMMARY_TOKE
   const { estimates, overhead, total } = calibrate(history, preambleTokens);
   let tail = 0;
   for (let i = cut; i < estimates.length; i += 1) tail += estimates[i];
+  const kept = Math.ceil(
+    verbatimUserMessagesBlock(freshUserMessages(history.slice(0, cut))).length / APPROX_CHARS_PER_TOKEN
+  );
   const tokensBefore = total;
-  const tokensAfter = overhead + summaryTokens + tail;
+  const tokensAfter = overhead + summaryTokens + kept + tail;
   return {
     cut,
     compactedCount: cut,
@@ -4324,14 +4394,6 @@ function projectCompaction(history, cut, summaryTokens = COMPACTION_SUMMARY_TOKE
   };
 }
 
-// src/utils/delegated-message.ts
-var DEFAULT_DELEGATE_FRAMING = "Sent on the user's behalf.";
-function frameDelegatedContent(content, framing) {
-  return `(${framing ?? DEFAULT_DELEGATE_FRAMING})
-
-${content}`;
-}
-
 // src/utils/logger.ts
 var logger2 = createLogger("ai-assistant");
 
@@ -4773,7 +4835,12 @@ function planCompaction(history, options = {}) {
 function renderMessageForSummary(m) {
   switch (m.role) {
     case "compacted-summary":
-      return `[Earlier summary] ${m.content}`;
+      return [
+        `[Earlier summary] ${m.content}`,
+        ...(m.compaction?.preservedUserMessages ?? []).map(
+          (u) => `[Kept word for word with it] ${preservedUserLine(u)}`
+        )
+      ].join("\n");
     case "user":
       if (!m.content) return "";
       return `User: ${m.delegate ? frameDelegatedContent(m.content, m.delegateFraming) : m.content}`;
@@ -4812,14 +4879,16 @@ function normalizeForProvider(history) {
       return { ...m, content: frameDelegatedContent(m.content ?? "", m.delegateFraming) };
     }
     if (m.role !== "compacted-summary") return m;
+    const preserved = m.compaction?.preservedUserMessages ?? [];
+    const verbatim = verbatimUserMessagesBlock(preserved);
     return {
       ...m,
       role: "user",
       content: `<conversation_summary>
 ${m.content}
-</conversation_summary>
+</conversation_summary>${verbatim}
 
-The above summarizes earlier parts of this conversation that were compacted. Continue naturally from it.`,
+The above summarizes earlier parts of this conversation that were compacted` + (preserved.length ? ", with the user's own messages from them kept word for word" : "") + ". Continue naturally from it.",
       compaction: void 0
     };
   });
@@ -5280,19 +5349,222 @@ var FoldController = class {
   }
 };
 
+// src/state/decision-surface.ts
+var SELECT_ACTION = "select";
+var REPLY_ACTION = "reply";
+var normalise = (option) => typeof option === "string" ? { id: option, label: option } : { id: option.id ?? option.label, label: option.label, enabledWhen: option.enabledWhen };
+var isEnabled = (option) => {
+  try {
+    return option.enabledWhen?.() ?? true;
+  } catch {
+    return false;
+  }
+};
+function buildDecisionSurface(spec) {
+  const options = spec.options.map(normalise);
+  const ids = /* @__PURE__ */ new Set();
+  for (const { id } of options) {
+    if (ids.has(id)) throw new Error(`exposeDecision: two options share the id "${id}".`);
+    if (spec.multi && id === SELECT_ACTION || spec.freeText && id === REPLY_ACTION) {
+      throw new Error(`exposeDecision: an option cannot use the reserved id "${id}".`);
+    }
+    ids.add(id);
+  }
+  const byIdOrLabel = (key) => typeof key === "string" ? options.find((o) => o.id === key || o.label === key) : void 0;
+  const actions = () => {
+    const enabled = options.filter(isEnabled);
+    return [
+      ...options.map((o) => ({
+        name: o.id,
+        label: o.label,
+        finishes: true,
+        enabled: isEnabled(o)
+      })),
+      ...spec.multi ? [
+        {
+          name: SELECT_ACTION,
+          finishes: true,
+          enabled: enabled.length > 0,
+          args: "options"
+        }
+      ] : [],
+      ...spec.freeText ? [{ name: REPLY_ACTION, finishes: true, enabled: true, args: "text" }] : []
+    ];
+  };
+  const answer = (a) => () => spec.choose(a);
+  return {
+    prompt: spec.prompt,
+    facts: () => spec.facts?.() ?? {},
+    actions,
+    isReady: () => actions().some((a) => a.finishes && a.enabled),
+    prepare(name, args) {
+      if (spec.multi && name === SELECT_ACTION) {
+        const picked = args?.options;
+        if (!Array.isArray(picked) || picked.length === 0) {
+          return {
+            error: "invalid-args",
+            message: "`select` takes { options: string[] }, not empty."
+          };
+        }
+        const chosen = picked.map(byIdOrLabel);
+        const unknown = picked.filter((_, i) => !chosen[i]);
+        if (unknown.length) {
+          return { error: "invalid-args", message: `Not options here: ${unknown.join(", ")}.` };
+        }
+        const disabled = chosen.filter((o) => !isEnabled(o));
+        if (disabled.length) {
+          return {
+            error: "disabled",
+            message: `Not available right now: ${disabled.map((o) => o.label).join(", ")}.`
+          };
+        }
+        const picks = chosen;
+        return {
+          choice: picks.map((o) => o.label).join(", "),
+          finishes: true,
+          run: answer({ kind: "options", options: picks.map((o) => o.id) })
+        };
+      }
+      if (spec.freeText && name === REPLY_ACTION) {
+        const text = args?.text;
+        if (typeof text !== "string" || !text.trim()) {
+          return { error: "invalid-args", message: "`reply` takes { text: string }, not empty." };
+        }
+        return { choice: text, finishes: true, run: answer({ kind: "text", text }) };
+      }
+      const option = options.find((o) => o.id === name);
+      if (!option) {
+        return { error: "unknown-action", message: `No action "${name}" here.` };
+      }
+      if (!isEnabled(option)) {
+        return { error: "disabled", message: `"${option.label}" is not available right now.` };
+      }
+      return {
+        choice: option.label,
+        finishes: true,
+        run: answer({ kind: "option", option: option.id })
+      };
+    }
+  };
+}
+var CHOICE_CHARS = 300;
+var matchesType = (value, type) => {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+    case "integer":
+      return typeof value === "number" && (type === "number" || Number.isInteger(value));
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return !!value && typeof value === "object" && !Array.isArray(value);
+    default:
+      return true;
+  }
+};
+function checkArgs(args, schema) {
+  if (!schema) return void 0;
+  if (!matchesType(args, "object")) return "its arguments must be an object.";
+  const record = args;
+  const required = schema.required ?? [];
+  const missing = required.filter((key) => record[key] === void 0);
+  if (missing.length) return `missing: ${missing.join(", ")}.`;
+  const properties = schema.properties ?? {};
+  const wrong = Object.entries(properties).filter(([key, prop]) => record[key] !== void 0 && !matchesType(record[key], prop?.type)).map(([key, prop]) => `${key} should be ${String(prop?.type)}`);
+  return wrong.length ? `${wrong.join("; ")}.` : void 0;
+}
+function buildFullSurface(spec) {
+  const guard = (enabledWhen) => {
+    try {
+      return enabledWhen?.() ?? true;
+    } catch {
+      return false;
+    }
+  };
+  const actions = () => Object.entries(spec.actions).map(([name, a]) => ({
+    name,
+    finishes: !!a.finishes,
+    enabled: guard(a.enabledWhen),
+    description: a.description,
+    ...a.argsSchema ? { args: "fields", argsSchema: a.argsSchema } : {}
+  }));
+  return {
+    prompt: spec.prompt,
+    facts: () => ({}),
+    describe: () => spec.describe(),
+    views: spec.views,
+    read: (view) => spec.read(view),
+    actions,
+    isReady: () => actions().some((a) => a.enabled),
+    prepare(name, args) {
+      const action = Object.prototype.hasOwnProperty.call(spec.actions, name) ? spec.actions[name] : void 0;
+      if (!action) return { error: "unknown-action", message: `No action "${name}" here.` };
+      if (!guard(action.enabledWhen)) {
+        return { error: "disabled", message: `"${name}" is not available right now.` };
+      }
+      const problem = checkArgs(args ?? {}, action.argsSchema);
+      if (problem) return { error: "invalid-args", message: `"${name}": ${problem}` };
+      const shown = args && Object.keys(args).length ? ` ${JSON.stringify(args)}` : "";
+      return {
+        choice: `${name}${shown}`.slice(0, CHOICE_CHARS),
+        finishes: !!action.finishes,
+        run: () => action.run(args ?? {})
+      };
+    }
+  };
+}
+
 // src/state/interaction-context.ts
-function createInteractionContext(interactionId) {
+function createInteractionContext(interactionId, deps = {}) {
   const state = {};
   const onceCache = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   const disposers = /* @__PURE__ */ new Set();
+  const readyListeners = /* @__PURE__ */ new Set();
   let disposed = false;
+  let settled = false;
   let heldBy = "user";
+  let controller;
+  let surface;
+  let lastActivityAt = Date.now();
+  let checkpoint = deps.checkpoint;
+  const checkReady = () => {
+    if (disposed || !surface || readyListeners.size === 0 || !surface.isReady()) return;
+    const waiting = [...readyListeners];
+    readyListeners.clear();
+    for (const fn of waiting) {
+      try {
+        fn();
+      } catch (e) {
+        logger2.error("InteractionContext onSurfaceReady callback threw", e);
+      }
+    }
+  };
   const context = {
     interactionId,
     get heldBy() {
       return heldBy;
     },
+    get controller() {
+      return controller;
+    },
+    get surface() {
+      return surface;
+    },
+    get lastActivityAt() {
+      return lastActivityAt;
+    },
+    get checkpoint() {
+      return checkpoint;
+    },
+    saveCheckpoint(next) {
+      if (disposed) return;
+      checkpoint = next;
+      deps.saveCheckpoint?.(next);
+    },
     state,
     once(key, factory) {
       if (onceCache.has(key)) return onceCache.get(key);
@@ -5307,6 +5579,7 @@ function createInteractionContext(interactionId) {
       return value;
     },
     notify() {
+      lastActivityAt = Date.now();
       for (const listener of listeners) {
         try {
           listener();
@@ -5314,6 +5587,7 @@ function createInteractionContext(interactionId) {
           logger2.error("InteractionContext subscriber threw during notify()", e);
         }
       }
+      checkReady();
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -5327,6 +5601,36 @@ function createInteractionContext(interactionId) {
         return;
       }
       disposers.add(fn);
+    },
+    resolve(result) {
+      if (settled || disposed) return;
+      settled = true;
+      deps.resolve?.(result);
+    },
+    exposeDecision(decision) {
+      if (disposed) return;
+      surface = buildDecisionSurface(decision);
+      context.notify();
+    },
+    exposeSurface(spec) {
+      if (disposed) return;
+      surface = buildFullSurface(spec);
+      context.notify();
+    },
+    onSurfaceReady(fn) {
+      if (disposed) return () => void 0;
+      if (surface?.isReady()) {
+        fn();
+        return () => void 0;
+      }
+      readyListeners.add(fn);
+      return () => {
+        readyListeners.delete(fn);
+      };
+    },
+    claimantOwns(action) {
+      if (heldBy === "user" || !surface) return false;
+      return surface.actions().some((a) => a.name === action && a.enabled);
     }
   };
   return {
@@ -5343,6 +5647,7 @@ function createInteractionContext(interactionId) {
       }
       disposers.clear();
       listeners.clear();
+      readyListeners.clear();
       onceCache.clear();
     },
     setHeldBy(holder) {
@@ -5350,12 +5655,70 @@ function createInteractionContext(interactionId) {
       heldBy = holder;
       context.notify();
       return true;
+    },
+    setController(value) {
+      controller = value;
+    },
+    get surface() {
+      return surface;
     }
   };
 }
 
+// src/state/interaction-registry.ts
+var registry2 = /* @__PURE__ */ new Map();
+function getInteractionRegistration(name) {
+  return registry2.get(name);
+}
+
+// src/state/run-steps.ts
+var recorders = /* @__PURE__ */ new WeakMap();
+function bindStepRecorder(ctx, record, refused) {
+  recorders.set(ctx, { step: record, refused });
+}
+
 // src/components/chat-driver/interaction-controller.ts
 var DEFAULT_DECISION_FRAMING = "Decided on the user's behalf";
+var DEFAULT_EDIT_FRAMING = "Changed on the user's behalf before the user answered; the user then finished it, confirming the changes";
+var BUSY = {
+  error: "busy",
+  message: "Another action on this interaction is still running, so this one was not run. Once that one has returned, try this again if it still applies."
+};
+var isThenable = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+function editOf(by, action, choice, args) {
+  const copy = jsonCopy(args);
+  return { by, action, choice, ...copy !== void 0 && { args: copy } };
+}
+function jsonCopy(args) {
+  if (args === void 0 || args === null) return void 0;
+  try {
+    const copy = JSON.parse(JSON.stringify(args));
+    const empty = copy === "" || Array.isArray(copy) && copy.length === 0 || copy !== null && typeof copy === "object" && Object.keys(copy).length === 0;
+    return empty ? void 0 : copy;
+  } catch {
+    return void 0;
+  }
+}
+function doneOnUsersBehalf(interaction, answeredBy) {
+  const edits = interaction.edits?.length ? interaction.edits.map((edit) => edit.choice) : void 0;
+  if (answeredBy && answeredBy !== "user") {
+    const recorded = interaction.decision;
+    return {
+      decision: {
+        framing: interaction.claimant?.decisionFraming ?? DEFAULT_DECISION_FRAMING,
+        ...edits && { edits },
+        ...recorded?.choice !== void 0 && { choice: recorded.choice },
+        ...recorded?.shownToUser !== void 0 && { shownToUser: recorded.shownToUser }
+      }
+    };
+  }
+  if (answeredBy === "user" && edits) {
+    return {
+      edited: { framing: interaction.claimant?.editFraming ?? DEFAULT_EDIT_FRAMING, edits }
+    };
+  }
+  return {};
+}
 var STOPPED = {
   status: "timeout",
   message: "The turn was stopped before this was answered."
@@ -5379,6 +5742,72 @@ var InteractionController = class {
      */
     this.interceptors = [];
   }
+  /** See `ChatDriver.getInteractionCheckpoint`. */
+  getCheckpoint() {
+    const cp = this.checkpoint;
+    return cp ? { componentName: cp.componentName, value: cp.value } : void 0;
+  }
+  /** See `ChatDriver.restoreInteractionCheckpoint`. Restored means cut: its interaction is gone. */
+  restoreCheckpoint(saved) {
+    this.checkpoint = saved ? { componentName: saved.componentName, value: saved.value, cut: true } : void 0;
+  }
+  /** Drop the checkpoint, used or not, when its flow ends. */
+  clearCheckpoint(why) {
+    const cp = this.checkpoint;
+    if (!cp) return;
+    this.checkpoint = void 0;
+    recordMetaEvent(this.deps.sessionKey, "interaction.checkpoint", {
+      action: "cleared",
+      component: cp.componentName,
+      why,
+      ...cp.interactionId ? { interactionId: cp.interactionId } : {}
+    });
+  }
+  /**
+   * Hand a cut checkpoint to a new request of the same widget type, if its registration's
+   * `sameWork` agrees. Only the first such request is asked: a refused checkpoint is dropped, and
+   * the work starts fresh as it would have without one.
+   */
+  takeOverCheckpoint(componentName, data, interactionId) {
+    const cut = this.checkpoint;
+    if (!cut?.cut || cut.componentName !== componentName) return void 0;
+    this.checkpoint = void 0;
+    const sameWork = getInteractionRegistration(componentName)?.sameWork;
+    let agrees = true;
+    if (sameWork) {
+      try {
+        agrees = sameWork(cut.value, data);
+      } catch (e) {
+        logger2.warn(`InteractionController: "${componentName}" sameWork threw; starting fresh:`, e);
+        agrees = false;
+      }
+    }
+    recordMetaEvent(this.deps.sessionKey, "interaction.checkpoint", {
+      action: agrees ? "resumed" : "refused",
+      component: componentName,
+      interactionId,
+      ...agrees ? {} : { saved: cut.value }
+    });
+    if (!agrees) return void 0;
+    this.checkpoint = { componentName, value: cut.value, interactionId };
+    return cut.value;
+  }
+  /** A controller's `ctx.saveCheckpoint`: kept as JSON, the form it is persisted in. */
+  saveCheckpoint(interactionId, componentName, value) {
+    if (!this.pending.has(interactionId)) return;
+    let copy;
+    try {
+      copy = JSON.parse(JSON.stringify(value) ?? "null");
+    } catch (e) {
+      logger2.warn(
+        `InteractionController: a "${componentName}" checkpoint is not storable as JSON:`,
+        e
+      );
+      return;
+    }
+    this.checkpoint = { componentName, value: copy, interactionId };
+    this.deps.emit(new CustomEvent("checkpoint-saved", { detail: { interactionId } }));
+  }
   /** See `ChatDriver.addInteractionInterceptor`. Returns a remover. */
   addInterceptor(interceptor) {
     if (!interceptor.id || interceptor.id === "user") {
@@ -5438,6 +5867,10 @@ var InteractionController = class {
         if (!isClaimant()) return false;
         const next = holder === "user" ? "user" : interceptor.id;
         if (!handle.setHeldBy(next)) return false;
+        if (next === "user") {
+          const pending = this.pending.get(handle.context.interactionId);
+          if (pending && !pending.running?.finishes) pending.settledBy = void 0;
+        }
         recordMetaEvent(this.deps.sessionKey, "interaction.held", {
           interactionId: handle.context.interactionId,
           heldBy: next,
@@ -5459,9 +5892,87 @@ var InteractionController = class {
         if (!pending) return false;
         pending.decision = { choice: decision.choice, shownToUser: decision.shownToUser };
         return true;
+      },
+      invoke: async (action, args, options) => {
+        const { interactionId } = handle.context;
+        const pending = this.pending.get(interactionId);
+        if (!isClaimant() || !pending || handle.context.heldBy !== interceptor.id) {
+          return {
+            ok: false,
+            error: "not-held",
+            message: pending ? "This interaction is with the person now, so it cannot be acted on." : "This interaction has already ended."
+          };
+        }
+        const { surface } = handle;
+        if (!surface) {
+          return { ok: false, error: "no-surface", message: "Nothing has been exposed here yet." };
+        }
+        if (pending.running) {
+          return { ok: false, ...BUSY, actions: surface.actions() };
+        }
+        const prepared = surface.prepare(action, args);
+        if ("error" in prepared) {
+          return { ok: false, ...prepared, actions: surface.actions() };
+        }
+        const previous = { decision: pending.decision, settledBy: pending.settledBy };
+        const restore = () => {
+          if (!prepared.finishes) return;
+          pending.decision = previous.decision;
+          pending.settledBy = handle.context.heldBy === interceptor.id ? previous.settledBy : void 0;
+        };
+        if (prepared.finishes) {
+          pending.decision = { choice: prepared.choice, shownToUser: options?.note };
+          pending.settledBy = interceptor.id;
+        }
+        const content = options?.note?.trim();
+        const note = content ? { content, delegate: interceptor.id } : void 0;
+        const token = {};
+        pending.running = { token, finishes: prepared.finishes, note };
+        let output;
+        try {
+          const ran = prepared.run();
+          output = isThenable(ran) ? await ran : ran;
+        } catch (e) {
+          logger2.warn(`InteractionController: action "${action}" threw:`, e);
+          if (pending.settledInRun !== token) restore();
+          return {
+            ok: false,
+            error: "threw",
+            message: e instanceof Error ? e.message : String(e)
+          };
+        } finally {
+          if (pending.running?.token === token) pending.running = void 0;
+        }
+        const finished = pending.settledInRun === token;
+        if (!finished) {
+          restore();
+          if (note && this.pending.has(interactionId)) this.appendNote(note);
+          (pending.edits ??= []).push(editOf(interceptor.id, action, prepared.choice, args));
+        }
+        recordMetaEvent(this.deps.sessionKey, "interaction.invoked", {
+          interactionId,
+          claimant: interceptor.id,
+          action,
+          finished
+        });
+        return {
+          ok: true,
+          finished,
+          actions: finished ? [] : surface.actions(),
+          ...output !== void 0 && !finished ? { output } : {}
+        };
       }
     };
   }
+  /** A claimant's note about its choice: a delegated, display-only message in the assistant's voice. */
+  appendNote(note) {
+    this.deps.appendToHistory({
+      role: "assistant",
+      content: note.content,
+      delegate: note.delegate,
+      excludeFromProvider: true
+    });
+  }
   /** See `ChatDriver.setHostInteractionRequester`. */
   setHostRequester(fn, recordOutcome) {
     this.hostRequester = fn;
@@ -5506,8 +6017,36 @@ var InteractionController = class {
           });
         }, timeoutMs) : void 0
       });
-      const handle = createInteractionContext(interactionId);
+      const handle = createInteractionContext(interactionId, {
+        resolve: (result) => this.resolve(interactionId, result),
+        checkpoint: this.takeOverCheckpoint(componentName, data, interactionId),
+        saveCheckpoint: (value) => this.saveCheckpoint(interactionId, componentName, value)
+      });
       this.contexts.set(interactionId, handle);
+      bindStepRecorder(
+        handle.context,
+        (step, outcome) => recordMetaEvent(this.deps.sessionKey, "interaction.step", {
+          interactionId,
+          component: componentName,
+          step,
+          outcome
+        }),
+        (reason, saved) => recordMetaEvent(this.deps.sessionKey, "interaction.checkpoint", {
+          action: "refused",
+          component: componentName,
+          interactionId,
+          reason,
+          saved
+        })
+      );
+      const registration = getInteractionRegistration(componentName);
+      if (registration?.controller) {
+        try {
+          handle.setController(registration.controller(data, handle.context));
+        } catch (e) {
+          logger2.error(`InteractionController: the "${componentName}" controller threw:`, e);
+        }
+      }
       const heldBy = this.offer(handle, {
         interactionId,
         componentName,
@@ -5584,21 +6123,20 @@ var InteractionController = class {
     const costUsd = typeof result?.costUsd === "number" && Number.isFinite(result.costUsd) && result.costUsd > 0 ? result.costUsd : void 0;
     const unanswered = result?.status === "timeout";
     const answeredBy = unanswered ? void 0 : interaction.settledBy ?? "user";
-    const decision = answeredBy && answeredBy !== "user" ? {
-      framing: interaction.claimant?.decisionFraming ?? DEFAULT_DECISION_FRAMING,
-      ...interaction.decision?.choice !== void 0 && {
-        choice: interaction.decision.choice
-      },
-      ...interaction.decision?.shownToUser !== void 0 && {
-        shownToUser: interaction.decision.shownToUser
-      }
-    } : void 0;
+    const run = answeredBy && answeredBy !== "user" ? interaction.running : void 0;
+    if (run) {
+      interaction.settledInRun = run.token;
+      if (run.note) this.appendNote(run.note);
+    }
+    const edits = interaction.edits?.length ? interaction.edits : void 0;
+    const { decision, edited } = doneOnUsersBehalf(interaction, answeredBy);
     const patched = this.deps.patchInteractionMessage(interactionId, (message) => ({
       ...message,
       interaction: {
         ...message.interaction,
         resolved: result,
-        ...answeredBy ? { answeredBy } : {}
+        ...answeredBy ? { answeredBy } : {},
+        ...edits ? { edits } : {}
       },
       ...costUsd != null ? { externalCostUsd: (message.externalCostUsd ?? 0) + costUsd } : {}
     }));
@@ -5618,16 +6156,23 @@ var InteractionController = class {
     }
     recordMetaEvent(this.deps.sessionKey, "interaction.resolved", {
       interactionId,
-      ...answeredBy ? { answeredBy } : {}
+      ...answeredBy ? { answeredBy } : {},
+      ...edits ? { edits: edits.length } : {}
     });
     this.deps.activityBus.publish("interaction-resolved", void 0);
     try {
-      interaction.onSettled?.({ answeredBy, decision });
+      interaction.onSettled?.({ answeredBy, decision, ...edited ? { edited } : {} });
     } catch (e) {
       logger2.warn("InteractionController: onSettled threw:", e);
     }
+    this.deps.emit(
+      new CustomEvent("interaction-settled", {
+        detail: { interactionId, ...answeredBy ? { answeredBy } : {} }
+      })
+    );
     interaction.resolve(result);
     this.pending.delete(interactionId);
+    if (this.checkpoint?.interactionId === interactionId) this.checkpoint = void 0;
     this.contexts.get(interactionId)?.dispose();
     this.contexts.delete(interactionId);
   }
@@ -6024,17 +6569,30 @@ var budgetDetailOf = (e) => {
     ...e.otherVendorAvailable != null ? { otherVendorAvailable: e.otherVendorAvailable } : {}
   };
 };
-function withDelegatedDecisions(result, content, decisions, hasImages) {
-  if (decisions.length === 0) return content;
+function withDelegatedDecisions(result, content, done, hasImages) {
+  const { decided, edited } = done;
+  if (decided.length === 0 && edited.length === 0) return content;
   if (!hasImages && result !== null && typeof result === "object" && !Array.isArray(result)) {
-    return JSON.stringify({ ...result, decidedOnUsersBehalf: decisions });
+    return JSON.stringify({
+      ...result,
+      ...decided.length ? { decidedOnUsersBehalf: decided } : {},
+      ...edited.length ? { editedOnUsersBehalf: edited } : {}
+    });
   }
-  return [content, ...decisions.map(describeDelegatedDecision)].join("\n\n");
+  return [
+    content,
+    ...decided.map(describeDelegatedDecision),
+    ...edited.map(describeDelegatedEdits)
+  ].join("\n\n");
+}
+function describeDelegatedEdits(edited) {
+  return `${edited.framing}: ${edited.edits.map((edit) => `"${edit}"`).join(", ")}.`;
 }
 function describeDelegatedDecision(decision) {
   const choice = decision.choice !== void 0 ? `: "${decision.choice}"` : "";
   const shown = decision.shownToUser ? ` What the user was shown, as your words: "${decision.shownToUser}"` : " Nothing was shown to the user about it.";
-  return `${decision.framing}${choice}.${shown}`;
+  const edited = decision.edits?.length ? ` Before deciding it changed the widget: ${decision.edits.map((edit) => `"${edit}"`).join(", ")}.` : "";
+  return `${decision.framing}${choice}.${shown}${edited}`;
 }
 function inFlightToolCallsAt(history) {
   for (let i = history.length - 1; i >= 0; i -= 1) {
@@ -6781,6 +7339,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * release, then the active agent.
    */
   dispatchAgentTransition(t) {
+    if (t.flowOwnerChangedTo === null) this.interactions.clearCheckpoint("flow-ended");
     if (t.flowOwnerChangedTo !== void 0) {
       this.dispatchEvent(new CustomEvent("flow-owner-changed", { detail: t.flowOwnerChangedTo }));
     }
@@ -7365,7 +7924,11 @@ var ChatDriver = class _ChatDriver extends EventTarget {
         // below, taking its per-message cost/token fields with it — so a host total
         // re-derived from the transcript would otherwise fall by exactly this much
         // on every compaction. Summarising a turn does not refund what it cost.
-        rolledUpUsage: sumUsage(toCompact)
+        rolledUpUsage: sumUsage(toCompact),
+        // The user's own words survive word for word, beside the paraphrase (GENC-1660, C2): this
+        // range's own only. An earlier summary's kept messages are not carried forward; the
+        // summariser read them with it and folded them into this paraphrase.
+        preservedUserMessages: freshUserMessages(toCompact)
       }
     };
     this.loadHistory([summaryMessage, ...tail]);
@@ -7537,6 +8100,14 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   getInteractionContext(interactionId) {
     return this.interactions.context(interactionId);
   }
+  /** {@inheritDoc AiDriver.getInteractionCheckpoint} */
+  getInteractionCheckpoint() {
+    return this.interactions.getCheckpoint();
+  }
+  /** {@inheritDoc AiDriver.restoreInteractionCheckpoint} */
+  restoreInteractionCheckpoint(saved) {
+    this.interactions.restoreCheckpoint(saved);
+  }
   /**
    * Replace the history message owning `interactionId`. `false` when it is no longer in history.
    * Does not announce the change — the interaction paths differ on whether they should.
@@ -7579,7 +8150,8 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       role: "user",
       content: userInput,
       attachments,
-      ...delegate ? { delegate, delegateFraming } : {}
+      // Who sent it, and what writing it cost when that was not the working agent's own spend.
+      ...delegatedFields(options)
     });
     this.turnStartedAt = Date.now();
     recordMetaEvent(this.sessionKey, "turn.start", {
@@ -7645,7 +8217,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    *   kept on a seven-way fan-out, reporting ~2.3x under the real cost, with the
    *   error growing as the fan-out widens.
    */
-  buildHandlerContext(activeToolCallId, traceCapture, decisions) {
+  buildHandlerContext(activeToolCallId, traceCapture, done) {
     let opened;
     let recorded = false;
     const capabilities2 = this.buildCapabilities();
@@ -7659,9 +8231,11 @@ var ChatDriver = class _ChatDriver extends EventTarget {
           opened = interactionId;
         },
         void 0,
-        // An interaction an interceptor answered is reported in THIS call's result (GENC-1660).
+        // What an interceptor did to an interaction is reported in THIS call's result
+        // (GENC-1660): its answer, or the edits it made before the person answered.
         (settled) => {
-          if (settled.decision) decisions?.push(settled.decision);
+          if (settled.decision) done?.decided.push(settled.decision);
+          if (settled.edited) done?.edited.push(settled.edited);
         }
       ),
       recordInteractionOutcome: (outcome) => {
@@ -8498,17 +9072,17 @@ ${tailBody}
             }
             const traceCapture = { traces: [] };
             const capturedTrace = () => traceCapture.traces.length ? traceCapture.traces.flat() : void 0;
-            const decisions = [];
+            const done = { decided: [], edited: [] };
             try {
               const result = await handler(
                 tc.args,
-                this.buildHandlerContext(tc.id, traceCapture, decisions)
+                this.buildHandlerContext(tc.id, traceCapture, done)
               );
               const resultImages = toolResultImages(result);
               const content = withDelegatedDecisions(
                 result,
                 resultImages ? typeof result.content === "string" ? result.content : JSON.stringify({ ...result, attachments: void 0 }) : typeof result === "string" ? result : JSON.stringify(result),
-                decisions,
+                done,
                 !!resultImages
               );
               executedById.set(tc.id, {
@@ -8718,8 +9292,10 @@ var AI_DRIVER_EVENT_TYPES = Object.keys({
   "sub-agent-stop": true,
   "interaction-start": true,
   "interaction-stop": true,
+  "interaction-settled": true,
   "provider-changed": true,
   "external-cost-recorded": true,
+  "checkpoint-saved": true,
   "agent-changed": true,
   "agent-released": true,
   "flow-owner-changed": true,
@@ -8815,6 +9391,12 @@ var BaseDriverDecorator = class _BaseDriverDecorator extends EventTarget {
   getFlowOwner() {
     return this.inner.getFlowOwner?.() ?? null;
   }
+  getInteractionCheckpoint() {
+    return this.inner.getInteractionCheckpoint?.();
+  }
+  restoreInteractionCheckpoint(saved) {
+    this.inner.restoreInteractionCheckpoint?.(saved);
+  }
   /**
    * Forwarded, so an interceptor installed on any layer lands on the driver that opens the
    * interactions. A decorator that answers interactions installs its own on `this.inner`.
@@ -9049,10 +9631,7 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
     return this.chatDriver.getSuggestions(history, prompt2, count, agentInfo);
   }
   async sendMessage(input, attachments, options) {
-    const delegated = options?.delegate ? {
-      delegate: options.delegate,
-      delegateFraming: options.delegateFraming ?? DEFAULT_DELEGATE_FRAMING
-    } : {};
+    const delegated = delegatedFields(options);
     try {
       return await this.runOrchestratedTurn(input, attachments, options, delegated);
     } catch (e) {
@@ -9185,7 +9764,25 @@ var OrchestratingDriver = class _OrchestratingDriver extends BaseDriverDecorator
     this.cancelled = false;
     await this.installAgent(agent);
     if (!resumeNote || agent.resumeOnRestore === false || this.cancelled) return void 0;
-    return this.chatDriver.continueFromHistory(void 0, { tailNote: resumeNote });
+    const result = await this.chatDriver.continueFromHistory(void 0, { tailNote: resumeNote });
+    await this.releaseIfRequested();
+    return result;
+  }
+  /**
+   * A continuation outside a routed turn — a decorator carrying the agent on, say — can finish the
+   * flow as surely as a turn can, so a release it requests is acted on here too. Before
+   * (GENC-1660), only `sendMessage` checked, and a flow finished by a continuation stayed locked.
+   */
+  async continueFromHistory(transientPrimer, options) {
+    const result = await this.chatDriver.continueFromHistory(transientPrimer, options);
+    await this.releaseIfRequested();
+    return result;
+  }
+  /** Release the flow if the turn that just ended asked to, and an agent is still active to release. */
+  async releaseIfRequested() {
+    if (this.chatDriver.getAgentReleaseRequested() && this.agentSession.getActive()) {
+      await this.releaseActiveAgent();
+    }
   }
   /**
    * {@inheritDoc AiDriver.getContextReserve}
@@ -9648,6 +10245,13 @@ function defineStatefulAgent(opts) {
     notResumableMessage: opts.notResumableMessage,
     resumeOnRestore: opts.resumeOnRestore,
     contextReserve: opts.contextReserve,
+    // Bound to the live state, so the autopilot's resolvers see what this agent's do (GENC-1660).
+    ...opts.autopilot && {
+      autopilot: {
+        config: opts.autopilot,
+        state: () => state
+      }
+    },
     onActivate: async (ctx) => {
       state = await opts.init(ctx);
       if (opts.toolHandlers) {
@@ -9688,6 +10292,9 @@ function defineStatefulAgent(opts) {
     excludeFromClassifier: opts.excludeFromClassifier
   };
 }
+function defineAutopilot(config) {
+  return config;
+}
 
 // src/config/fallback-agents.ts
 var friendlyFallbackAgent = {
@@ -9905,6 +10512,7 @@ function withFreshMetaSnapshot(stored, fresh) {
   buildTimelineEntries,
   clearSession,
   defineAgent,
+  defineAutopilot,
   defineStatefulAgent,
   emptyUsage,
   friendlyFallbackAgent,