@genesislcap/ai-assistant 15.55.0 → 15.57.0

package/dist/ai-assistant.d.ts

@@ -449,6 +449,8 @@ export declare class AgentSession {
      * activation, then deleted so a later re-activation starts fresh.
      */
     private restoredStates;
+    /** The tail of the activation queue — see {@link AgentSession.activate}. */
+    private activation;
     constructor(deps: AgentSessionDeps);
     /** The active agent, or `undefined` before the first activation and after a release. */
     getActive(): AgentConfig | undefined;
@@ -481,8 +483,15 @@ export declare class AgentSession {
      *
      * Re-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no
      * handoff is recorded. That guard matters because a per-turn re-resolve calls through here.
+     *
+     * Single-flight (GENC-1662): calls run one after another, never interleaved. `active` is only
+     * set once the hooks have finished, so two overlapping calls for the same agent would otherwise
+     * both see a switch and run `onActivate` twice — and a restored `init` would be overwritten by a
+     * fresh one that finished later. That overlap became possible when a restore started activating
+     * the flow owner outside a turn, where a send can land mid-activation.
      */
     activate(agent: AgentConfig): Promise<AgentTransition>;
+    private activateNow;
     /**
      * Release the active agent: fire `onDeactivate` and drop the flow lock.
      *
@@ -767,7 +776,7 @@ export declare interface AiDriver extends EventTarget {
      * `turnSignal`. A continuation after the user stopped that message is not
      * part of it, and gets a fresh one.
      */
-    continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+    continueFromHistory(transientPrimer?: ChatMessage[], options?: ContinueFromHistoryOptions): Promise<ChatDriverResult>;
     /**
      * Resolve a pending blocking interaction with the given result.
      */
@@ -803,6 +812,35 @@ export declare interface AiDriver extends EventTarget {
      * shipped drivers implement it and a host no longer has to feature-detect before restoring.
      */
     primeRestoredAgentState(snapshots: Record<string, unknown>): void;
+    /**
+     * Whether a restore can bring back the flow `agentName` owns (GENC-1662): the agent is configured
+     * here. Pure — no activation. A restore re-activates only an owner this answers `true` for.
+     *
+     * Optional: a driver without it never re-activates or resumes.
+     *
+     * @beta
+     */
+    canRestoreFlowOwner?(agentName: string): boolean;
+    /**
+     * Whether a restored flow owned by `agentName` should also RESUME — run a turn on its own — when
+     * the reload interrupted one (GENC-1662): the agent is configured here and has not opted out with
+     * `resumeOnRestore: false`. Pure. Lets the restore pick its divider wording.
+     *
+     * @beta
+     */
+    canResumeRestoredFlow?(agentName: string): boolean;
+    /**
+     * Bring a restored session's flow back to life (GENC-1662). Activates the flow owner — a
+     * stateful agent, the only kind that holds a flow — so its `init({ restored })` runs now rather
+     * than on the next message, then, when `resumeNote` is given and the agent has not opted out,
+     * runs one turn from the restored history with the note in the tail of its first model call.
+     *
+     * Returns the turn's result when one ran, `undefined` otherwise (no flow owner, the owner is not
+     * configured, or no note). Never throws for those cases.
+     *
+     * @beta
+     */
+    resumeRestoredFlow?(resumeNote?: string): Promise<ChatDriverResult | undefined>;
     /**
      * Return the full, unredacted conversation history.
      */
@@ -1434,6 +1472,27 @@ declare interface BaseAgentConfig {
      * @beta
      */
     notResumableMessage?: string;
+    /**
+     * Whether a restored session whose flow this agent owns continues on its own after a page reload
+     * (GENC-1662). Defaults to `true`; set `false` to keep the old behaviour of waiting for the user.
+     *
+     * Only meaningful on a STATEFUL agent (one with `onActivate`/`onDeactivate`, e.g. built with
+     * `defineStatefulAgent`) — only those own a flow, so on any other agent this is a no-op.
+     *
+     * Applies when the reload interrupted a turn: an unanswered tool call (often one waiting on a
+     * widget, which is a promise inside a running handler and cannot be persisted, so the restore
+     * trims it), tool results the model had not yet answered, or a user message with no reply yet.
+     * With this on, the restore runs one turn from the restored history, with a note in the tail of
+     * its first model call saying what was cut. That turn is a fresh model decision — it usually asks
+     * the same question again, but may word it differently or pick another valid action.
+     *
+     * A restored flow owner is re-activated either way, so its `init({ restored })` runs straight
+     * after the reload rather than on the next message. Never consulted for a session restored as
+     * interrupted ({@link BaseAgentConfig.resumable} returned `false`).
+     *
+     * @beta
+     */
+    resumeOnRestore?: boolean;
     /**
      * Tokens this agent wants kept free for one of its turns (GENC-1567).
      * Overrides `chatConfig.context.reserveTokens` while this agent is active;
@@ -2559,9 +2618,13 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private invokeSubAgent;
     /**
      * Continue the tool loop from current history without appending a new user message.
-     * Used by OrchestratingDriver after an agent handoff.
+     * Used by OrchestratingDriver after an agent handoff, and to resume a restored flow (GENC-1662).
+     *
+     * `options.tailNote` rides the framed tail of the FIRST model call only — after the history, where
+     * a note about the conversation belongs — and is dropped once the model has answered, so it
+     * cannot go stale over the rest of the loop. Contrast `transientPrimer`, which leads the request.
      */
-    continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+    continueFromHistory(transientPrimer?: ChatMessage[], options?: ContinueFromHistoryOptions): Promise<ChatDriverResult>;
     private runToolLoop;
     /**
      * Append prose the DRIVER wrote rather than the model — a failure notice, a limit explanation,
@@ -2879,6 +2942,19 @@ declare interface ContextReserveResolution {
     basis: 'locked' | 'reachable-max';
 }
 
+/**
+ * Options for `continueFromHistory` (GENC-1662).
+ *
+ * @beta
+ */
+export declare interface ContinueFromHistoryOptions {
+    /**
+     * A note for the model, placed in the framed tail of the first model call only — after the
+     * history it describes — and dropped once the model has answered.
+     */
+    tailNote?: string;
+}
+
 /** A model used during a recorded cost session. */
 export declare interface CostSessionModelEntry {
     model: string;
@@ -4945,6 +5021,22 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * persistence is (now) on.
      */
     private initPersistenceForNewStore;
+    /**
+     * Whether the session restored for `key` is no longer the one on screen (GENC-1662): switched in
+     * place, or the element disconnected, while the load was in flight.
+     */
+    private isRestoredSessionStale;
+    /**
+     * Re-activate a restored flow owner (GENC-1662), so a stateful agent's `init({ restored })` — and
+     * anything the host hangs off it, like a progress stepper — runs straight after the reload
+     * instead of on the next message.
+     */
+    private reactivateRestoredFlow;
+    /**
+     * Run the turn a reload interrupted (GENC-1662), shown as busy exactly as a send is — or, when it
+     * cannot run, withdraw the resume the restore divider promised.
+     */
+    private resumeInterruptedTurn;
     triggerFileInput(): void;
     handleFileSelect(e: Event): void;
     removeAttachment(attachment: ChatAttachment): void;
@@ -4991,6 +5083,11 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     private _pendingSendPrompt?;
     private send;
+    /**
+     * The post-turn settle shared by `send()` and a resumed restore turn: back to idle through
+     * the session ref captured at turn start, then the cleanup the state setter would have done.
+     */
+    private settleAfterTurn;
     onChatHeaderMouseDown(e: MouseEvent): void;
     handleInteractionCompleted(e: Event): void;
     /**
@@ -5490,9 +5587,22 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
     private runOrchestratedTurn;
-    continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+    continueFromHistory(transientPrimer?: ChatMessage[], options?: ContinueFromHistoryOptions): Promise<ChatDriverResult>;
     /** {@inheritDoc AiDriver.primeRestoredAgentState} */
     primeRestoredAgentState(snapshots: Record<string, unknown>): void;
+    /** {@inheritDoc AiDriver.canRestoreFlowOwner} */
+    canRestoreFlowOwner(agentName: string): boolean;
+    /** {@inheritDoc AiDriver.canResumeRestoredFlow} */
+    canResumeRestoredFlow(agentName: string): boolean;
+    /**
+     * {@inheritDoc AiDriver.resumeRestoredFlow}
+     *
+     * Installs the flow owner directly rather than through `handleTurn`: there is no user message
+     * to classify, and a restored lock already says which agent owns the flow. `continueFromHistory`
+     * on its own would not do — it neither routes nor installs, so it would run on whatever agent
+     * happened to be installed (none, straight after a reload).
+     */
+    resumeRestoredFlow(resumeNote?: string): Promise<ChatDriverResult | undefined>;
     /**
      * {@inheritDoc AiDriver.getContextReserve}
      *
@@ -6400,6 +6510,12 @@ export declare interface StatefulAgentInit<S> {
      * `false`. Falls back to a built-in default when omitted.
      */
     notResumableMessage?: string;
+    /**
+     * Whether this agent's flow continues on its own when a page reload interrupted one of its turns
+     * — see `AgentConfig.resumeOnRestore`, which this is passed straight through to. Defaults to
+     * `true`. A stateful agent is the only kind this applies to, since only it owns a flow.
+     */
+    resumeOnRestore?: boolean;
 }
 
 /**

package/dist/chat-driver.cjs

@@ -4114,6 +4114,10 @@ var META_EVENT_IMPORTANCE = {
   "session.switched": "low",
   "session.switch-deferred": "low",
   "persistence.restored": "normal",
+  // Whether a restored flow will be re-activated and resumed (GENC-1662), and how much the trim cut.
+  "persistence.resume-planned": "normal",
+  // A planned resume that did not run, and why (GENC-1662) — the divider was put back to plain.
+  "persistence.resume-withdrawn": "normal",
   "persistence.suppressed": "normal",
   "persistence.not-resumable": "normal",
   "driver.wired": "low",
@@ -4907,6 +4911,8 @@ var AgentSession = class {
      * activation, then deleted so a later re-activation starts fresh.
      */
     this.restoredStates = {};
+    /** The tail of the activation queue — see {@link AgentSession.activate}. */
+    this.activation = Promise.resolve();
   }
   /** The active agent, or `undefined` before the first activation and after a release. */
   getActive() {
@@ -4955,8 +4961,19 @@ var AgentSession = class {
    *
    * Re-activating the same agent by name is not a switch: no hooks fire, no lock moves, and no
    * handoff is recorded. That guard matters because a per-turn re-resolve calls through here.
-   */
-  async activate(agent) {
+   *
+   * Single-flight (GENC-1662): calls run one after another, never interleaved. `active` is only
+   * set once the hooks have finished, so two overlapping calls for the same agent would otherwise
+   * both see a switch and run `onActivate` twice — and a restored `init` would be overwritten by a
+   * fresh one that finished later. That overlap became possible when a restore started activating
+   * the flow owner outside a turn, where a send can land mid-activation.
+   */
+  activate(agent) {
+    const run = this.activation.then(() => this.activateNow(agent));
+    this.activation = run.catch(() => void 0);
+    return run;
+  }
+  async activateNow(agent) {
     const previousAgent = this.active;
     const switched = !previousAgent || previousAgent.name !== agent.name;
     const transition = { previousAgent, switched };
@@ -7517,9 +7534,13 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   }
   /**
    * Continue the tool loop from current history without appending a new user message.
-   * Used by OrchestratingDriver after an agent handoff.
+   * Used by OrchestratingDriver after an agent handoff, and to resume a restored flow (GENC-1662).
+   *
+   * `options.tailNote` rides the framed tail of the FIRST model call only — after the history, where
+   * a note about the conversation belongs — and is dropped once the model has answered, so it
+   * cannot go stale over the rest of the loop. Contrast `transientPrimer`, which leads the request.
    */
-  async continueFromHistory(transientPrimer) {
+  async continueFromHistory(transientPrimer, options) {
     if (this.busy) return { reason: "done" };
     this.busy = true;
     if (this.messageController.signal.aborted) this.beginMessage();
@@ -7541,7 +7562,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.activityBus.publish("tool-loop-start", void 0);
     let result = { reason: "done" };
     try {
-      result = await this.runToolLoop("", void 0, transientPrimer);
+      result = await this.runToolLoop("", void 0, transientPrimer, options?.tailNote);
       return result;
     } catch (e) {
       logger2.error("ChatDriver error:", e);
@@ -7578,7 +7599,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   // splitting threads that state through signatures rather than removing it. `turn-setup.ts`
   // (docs/code-health.md §11.3) is the intended carve-up.
   // oxlint-disable-next-line complexity, max-lines-per-function
-  async runToolLoop(userInput, attachments, transientPrimer) {
+  async runToolLoop(userInput, attachments, transientPrimer, tailNote) {
     if (!this.systemPrompt) {
       logger2.warn(
         "ChatDriver: no systemPrompt set. The assistant will have no instructions \u2014 provide a systemPrompt via agents config or the foundation-ai-assistant property."
@@ -7639,7 +7660,10 @@ var ChatDriver = class _ChatDriver extends EventTarget {
 ${MALFORMED_CALL_NUDGE}` : emptyResponseAttempts > 0 ? `
 
 ${EMPTY_RESPONSE_NUDGE}` : "";
-      const frameworkSystemSuffix = `${foldSuffix}${retryNudge}`;
+      const firstCallNote = tailNote && iterations === 1 ? `
+
+${tailNote}` : "";
+      const frameworkSystemSuffix = `${foldSuffix}${firstCallNote}${retryNudge}`;
       const primer = normalizeForProvider([
         ...this.primerHistory ?? [],
         ...transientPrimer ?? []
@@ -8698,13 +8722,39 @@ var OrchestratingDriver = class extends EventTarget {
     }
     return lastResult?.reason === "done" ? lastResult : { reason: "done" };
   }
-  async continueFromHistory(transientPrimer) {
-    return this.chatDriver.continueFromHistory(transientPrimer);
+  async continueFromHistory(transientPrimer, options) {
+    return this.chatDriver.continueFromHistory(transientPrimer, options);
   }
   /** {@inheritDoc AiDriver.primeRestoredAgentState} */
   primeRestoredAgentState(snapshots) {
     this.agentSession.primeRestoredStates(snapshots);
   }
+  /** {@inheritDoc AiDriver.canRestoreFlowOwner} */
+  canRestoreFlowOwner(agentName) {
+    return this.agents.some((a) => a.name === agentName);
+  }
+  /** {@inheritDoc AiDriver.canResumeRestoredFlow} */
+  canResumeRestoredFlow(agentName) {
+    const agent = this.agents.find((a) => a.name === agentName);
+    return !!agent && agent.resumeOnRestore !== false;
+  }
+  /**
+   * {@inheritDoc AiDriver.resumeRestoredFlow}
+   *
+   * Installs the flow owner directly rather than through `handleTurn`: there is no user message
+   * to classify, and a restored lock already says which agent owns the flow. `continueFromHistory`
+   * on its own would not do — it neither routes nor installs, so it would run on whatever agent
+   * happened to be installed (none, straight after a reload).
+   */
+  async resumeRestoredFlow(resumeNote) {
+    const owner = this.agentSession.getFlowOwner();
+    const agent = owner ? this.agents.find((a) => a.name === owner) : void 0;
+    if (!agent) return void 0;
+    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 });
+  }
   /**
    * {@inheritDoc AiDriver.getContextReserve}
    *
@@ -9179,6 +9229,7 @@ function defineStatefulAgent(opts) {
     onUnresolvedTool: wrappedOnUnresolvedTool,
     resumable: wrappedResumable,
     notResumableMessage: opts.notResumableMessage,
+    resumeOnRestore: opts.resumeOnRestore,
     contextReserve: opts.contextReserve,
     onActivate: async (ctx) => {
       state = await opts.init(ctx);