@genesislcap/ai-assistant 15.87.0 → 15.88.0

package/dist/ai-assistant.api.json

@@ -31319,6 +31319,48 @@
                 }
               ],
               "name": "notePrompt"
+            },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!HeadlessPersistenceBinding#restore:member(1)",
+              "docComment": "/**\n * Restore the saved session for this key into the driver and the store, as the browser's element does on mount: the history, the agents' snapshots, the pin, the hand-offs. Resolves to the outcome, or `undefined` when there is nothing to restore, or it could not be (a failed load, a schema or host mismatch: the persister checks the snapshot's `host` against `window.location.host`).\n *\n * Call it after `attach` and before the first `send`. It does NOT resume the flow, and runs no turn: a cloned or imported session is saved as `interrupted`, so `flowOwnerAgentName` comes back null; a message the host then sends re-activates the flow.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "restore(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HeadlessRestoreOutcome",
+                  "canonicalReference": "@genesislcap/ai-assistant!HeadlessRestoreOutcome:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [],
+              "name": "restore"
             }
           ],
           "extendsTokenRanges": []
@@ -31613,6 +31655,105 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/ai-assistant!HeadlessRestoreOutcome:interface",
+          "docComment": "/**\n * What a restore brought back that the host may act on: the session restored, and the flow owner and resume note the browser's element would act on after its restore.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface HeadlessRestoreOutcome "
+            }
+          ],
+          "fileUrlPath": "src/headless/headless.types.ts",
+          "releaseTag": "Beta",
+          "name": "HeadlessRestoreOutcome",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!HeadlessRestoreOutcome#flowOwnerAgentName:member",
+              "docComment": "/**\n * The agent that owned the flow at save time; `null` when none was owned, the owner is not among the configured agents, or the session was saved as `interrupted` (a cloned or imported session is), which is never resumed.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly flowOwnerAgentName: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "flowOwnerAgentName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!HeadlessRestoreOutcome#resumeNote:member",
+              "docComment": "/**\n * The note for one resumed turn, set only when a turn was cut off. A headless host does not resume it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly resumeNote?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "resumeNote",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!HeadlessRestoreOutcome#sessionKey:member",
+              "docComment": "/**\n * The session key restored.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly sessionKey: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "sessionKey",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/ai-assistant!HeadlessResult:type",
@@ -32255,6 +32396,51 @@
               "isAbstract": false,
               "name": "resolve"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!HeadlessSession#restore:member(1)",
+              "docComment": "/**\n * Restore the saved session for this key, as the browser's element does on mount (see `HeadlessPersistenceBinding.restore`). Call it before the first `send`. The restored history is the starting point, not news: it is not reported as `message` events or as a turn, and the event log and its cursors carry on from where they are. A no-op without `persistence`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "restore(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "HeadlessRestoreOutcome",
+                  "canonicalReference": "@genesislcap/ai-assistant!HeadlessRestoreOutcome:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | undefined>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "restore"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!HeadlessSession#send:member(1)",

package/dist/ai-assistant.d.ts

@@ -7680,6 +7680,18 @@ export declare interface HeadlessPersistenceBinding {
     notePrompt(text: string): void;
     /** Save the snapshot and append the diagnostics now, rather than at the next throttled flush. */
     flush(): Promise<void>;
+    /**
+     * Restore the saved session for this key into the driver and the store, as the browser's element
+     * does on mount: the history, the agents' snapshots, the pin, the hand-offs. Resolves to the
+     * outcome, or `undefined` when there is nothing to restore, or it could not be (a failed load, a
+     * schema or host mismatch: the persister checks the snapshot's `host` against
+     * `window.location.host`).
+     *
+     * Call it after `attach` and before the first `send`. It does NOT resume the flow, and runs no
+     * turn: a cloned or imported session is saved as `interrupted`, so `flowOwnerAgentName` comes back
+     * null; a message the host then sends re-activates the flow.
+     */
+    restore(): Promise<HeadlessRestoreOutcome | undefined>;
     /** The debug log for the whole session, stitched from the stored stream (see `lifetimeDebugLog`). */
     debugLog(): Promise<DebugLog>;
     /** Stop watching the driver and cancel pending saves. The saved session is left as it is. */
@@ -7737,6 +7749,25 @@ export declare type HeadlessReadResult = {
     readonly error: string;
 };
 
+/**
+ * What a restore brought back that the host may act on: the session restored, and the flow owner
+ * and resume note the browser's element would act on after its restore.
+ *
+ * @beta
+ */
+export declare interface HeadlessRestoreOutcome {
+    /** The session key restored. */
+    readonly sessionKey: string;
+    /**
+     * The agent that owned the flow at save time; `null` when none was owned, the owner is not among
+     * the configured agents, or the session was saved as `interrupted` (a cloned or imported session
+     * is), which is never resumed.
+     */
+    readonly flowOwnerAgentName: string | null;
+    /** The note for one resumed turn, set only when a turn was cut off. A headless host does not resume it. */
+    readonly resumeNote?: string;
+}
+
 /**
  * The result of a call that may be refused: the reason, as words, in `error`.
  *
@@ -7811,6 +7842,8 @@ export declare class HeadlessSession {
     private lastProbe;
     private lastAutopilot;
     private disposed;
+    /** While a restore loads the history, which is not new activity. */
+    private restoring;
     constructor(driver: AiDriver, options?: HeadlessSessionOptions);
     /**
      * Send the person's message, and start the turn. Returns as soon as the turn has started, not
@@ -7859,6 +7892,13 @@ export declare class HeadlessSession {
      * the others open behind it), the autopilot, what it has cost, and the host's probe.
      */
     state(): HeadlessState;
+    /**
+     * Restore the saved session for this key, as the browser's element does on mount (see
+     * `HeadlessPersistenceBinding.restore`). Call it before the first `send`. The restored history is
+     * the starting point, not news: it is not reported as `message` events or as a turn, and the
+     * event log and its cursors carry on from where they are. A no-op without `persistence`.
+     */
+    restore(): Promise<HeadlessRestoreOutcome | undefined>;
     /**
      * Save the session now: the snapshot, and the diagnostics appended since the last flush, rather
      * than at the next throttled save. A no-op without `persistence`.

package/dist/chat-driver.cjs

@@ -12053,6 +12053,8 @@ var HeadlessSession = class {
     this.lastProbe = {};
     this.lastAutopilot = "";
     this.disposed = false;
+    /** While a restore loads the history, which is not new activity. */
+    this.restoring = false;
     if (typeof driver.addInteractionInterceptor !== "function") {
       throw new Error(
         "HeadlessSession needs a driver that supports interaction interceptors (addInteractionInterceptor), and this one does not."
@@ -12337,6 +12339,23 @@ var HeadlessSession = class {
       lastSeq: this.seq
     };
   }
+  /**
+   * Restore the saved session for this key, as the browser's element does on mount (see
+   * `HeadlessPersistenceBinding.restore`). Call it before the first `send`. The restored history is
+   * the starting point, not news: it is not reported as `message` events or as a turn, and the
+   * event log and its cursors carry on from where they are. A no-op without `persistence`.
+   */
+  async restore() {
+    if (!this.persistence) return void 0;
+    this.restoring = true;
+    try {
+      return await this.persistence.restore();
+    } finally {
+      this.restoring = false;
+      this.seen = this.history().length;
+      this.base = this.seen;
+    }
+  }
   /**
    * Save the session now: the snapshot, and the diagnostics appended since the last flush, rather
    * than at the next throttled save. A no-op without `persistence`.
@@ -12495,7 +12514,7 @@ var HeadlessSession = class {
   }
   /** New messages in the driver's history: report what the person would see of them. */
   onHistory() {
-    if (this.disposed) return;
+    if (this.disposed || this.restoring) return;
     this.reportMessages();
     this.observe();
   }