@astralform/js 3.2.0 → 4.1.0

package/dist/index.d.cts

@@ -637,8 +637,13 @@ interface ChatStreamRequest {
     resend_from?: string;
     upload_ids?: string[];
     agent_name?: string;
-    enable_search?: boolean;
     plan_mode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The backend mints
+     * an agent_goal from this text and drives the run under a budget until the
+     * objective is genuinely complete. A blank/omitted value runs a normal turn.
+     */
+    goal?: string;
     /**
      * Per-request model choice (client-side model selection), wire shape.
      * `provider` and `model` are paired; omit to reuse the thread's last model.
@@ -723,8 +728,13 @@ interface SendOptions$1 extends ModelChoiceOptions {
     enabledClientTools?: string[];
     uploadIds?: string[];
     agentName?: string;
-    enableSearch?: boolean;
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The text becomes
+     * the goal's objective; the backend keeps the agent working under a budget until
+     * it's complete. Omit for a normal turn.
+     */
+    goal?: string;
 }
 /**
  * A selectable model for one of the team's connected providers, from
@@ -750,6 +760,13 @@ interface ConversationAsset {
     workspacePath?: string;
     sourceMessageId?: string;
     agentName?: string;
+    /**
+     * Freshly-signed download/preview URL. Minted per response by the backend
+     * (private `workspaces` bucket), so it reflects the current signature rather
+     * than a link baked in when the asset was created. May be absent if signing
+     * failed or the asset has no stored object.
+     */
+    url?: string;
     createdAt: string;
 }
 
@@ -969,9 +986,7 @@ declare class ChatSession {
     private emit;
     connect(): Promise<void>;
     send(content: string, options?: SendOptions$1): Promise<void>;
-    resendFromCheckpoint(messageId: string, newContent: string, options?: {
-        enableSearch?: boolean;
-    }): Promise<void>;
+    resendFromCheckpoint(messageId: string, newContent: string): Promise<void>;
     private resetStreamingState;
     private processStream;
     /** Last received sequence number for resumable reconnection */
@@ -1002,6 +1017,14 @@ declare class ChatSession {
     /** POST a client-tool result, retrying transient failures a few times. */
     private submitToolResultWithRetry;
     private dispatchWireEvent;
+    /**
+     * Synchronous replay of a single stored wire event — the side-effect +
+     * translate + emit core of ``dispatchWireEvent`` without the (live-only)
+     * client-tool round-trip. Called in a tight synchronous loop during history
+     * restore so the consumer's per-event store writes batch into ONE render
+     * instead of re-typing the whole conversation event by event.
+     */
+    private replayWireEvent;
     /**
      * State mutations driven by wire events. Kept separate from translation so
      * the pure wire → ChatEvent mapping can live in translate.ts and be reused
@@ -1028,16 +1051,33 @@ declare class ChatSession {
     /** Stop the job and disconnect (explicit user action). */
     disconnect(): void;
     createNewConversation(): Promise<string>;
-    switchConversation(id: string, jobId?: string, 
     /**
-     * User prompt that triggered this job, if known. Emitted as a
-     * synthetic ``user_message`` ChatEvent at the START of the replay —
-     * a completed job maps to exactly one user turn, so every event in it
-     * belongs beneath that prompt. User messages aren't persisted in
-     * ``job_events``, so without this the restored conversation would show
-     * the agent response with no visible prompt above it.
+     * Replay one completed turn's already-fetched events, synchronously.
+     *
+     * Fetching is the caller's job (``StreamManager.restore`` loads every turn's
+     * events in parallel and the message list once), so this is pure replay: no
+     * awaits, so the whole restore runs in a single synchronous pass and the
+     * consumer batches it into one render.
+     *
+     * ``userMessageContent`` is the prompt that triggered this turn. It's emitted
+     * as a synthetic ``user_message`` BEFORE any of the turn's events: user
+     * prompts aren't persisted in ``job_events``, and some events precede
+     * ``message_start`` in the stream (e.g. ``memory_recall`` from prompt prep),
+     * so leading with the prompt keeps the turn in order.
+     */
+    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string): void;
+    /**
+     * Load a conversation's messages and replay its persisted history.
+     *
+     * Convenience for plain-``ChatSession`` consumers (the documented
+     * conversation-management API). ``StreamManager`` drives restore itself —
+     * loading messages once and replaying each turn in parallel — and does NOT
+     * call this; it's kept so direct-Session usage doesn't break.
+     *
+     * Without ``jobId`` it replays the whole conversation; with one, just that
+     * job's events.
      */
-    userMessageContent?: string): Promise<void>;
+    switchConversation(id: string, jobId?: string): Promise<void>;
     deleteConversation(id: string): Promise<void>;
     toggleClientTool(name: string): boolean;
 }
@@ -1110,10 +1150,14 @@ declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<Chat
 
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
-    enableSearch?: boolean;
     agentName?: string;
     uploadIds?: string[];
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode) — the text is the
+     * goal objective the backend drives to completion. Omit for a normal turn.
+     */
+    goal?: string;
 }
 type StreamManagerEvent = {
     type: "stateChange";
@@ -1153,7 +1197,26 @@ declare class StreamManager {
     private onSessionEvent;
     send(content: string, options?: SendOptions): Promise<void>;
     regenerate(): Promise<void>;
-    switchTo(conversationId: string): Promise<void>;
+    /**
+     * Switch the active conversation.
+     *
+     * ``opts.skipHistoryReplay`` is a fast path for consumers that CACHE a
+     * restored conversation's rendered blocks: it moves the active pointer and
+     * loads the message list (needed for send / regenerate context) but skips
+     * the expensive event fetch + replay, and never enters the ``restoring``
+     * state, so a consumer that clears its block view on ``restoring`` keeps
+     * showing the cached history with no flash of a spinner.
+     *
+     * It still confirms there is no live job before skipping: the in-memory
+     * background-job map is empty on a fresh instance (page reload) and blind to
+     * jobs started in another tab/device, so the fast path always asks the server
+     * (``getActiveJob``) and falls through to a full reconnect if one is running.
+     * That one small request is the only cost it doesn't skip, so passing the
+     * flag whenever you hold cached blocks is safe.
+     */
+    switchTo(conversationId: string, opts?: {
+        skipHistoryReplay?: boolean;
+    }): Promise<void>;
     createConversation(): Promise<string>;
     deleteConversation(id: string): Promise<void>;
     stop(): void;
@@ -1200,7 +1263,9 @@ declare function mapSseToChat(raw: RawSseEvent): ChatEvent[];
  * ``message_start`` (e.g. ``memory_recall``, emitted during prompt prep), so
  * gating the user block on ``message_start`` would replay them above the
  * user's own message. Keying off ``job_id`` injects the prompt once per job,
- * before its first event — matching ``session.ts#switchConversation``.
+ * before its first event — matching how the restore path
+ * (``stream-manager.ts#restore`` → ``session.ts#replayTurn``) leads each turn
+ * with its own prompt.
  */
 declare function replayEvents(sseEvents: RawSseEvent[], userMessages: {
     role: string;

package/dist/index.d.ts

@@ -637,8 +637,13 @@ interface ChatStreamRequest {
     resend_from?: string;
     upload_ids?: string[];
     agent_name?: string;
-    enable_search?: boolean;
     plan_mode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The backend mints
+     * an agent_goal from this text and drives the run under a budget until the
+     * objective is genuinely complete. A blank/omitted value runs a normal turn.
+     */
+    goal?: string;
     /**
      * Per-request model choice (client-side model selection), wire shape.
      * `provider` and `model` are paired; omit to reuse the thread's last model.
@@ -723,8 +728,13 @@ interface SendOptions$1 extends ModelChoiceOptions {
     enabledClientTools?: string[];
     uploadIds?: string[];
     agentName?: string;
-    enableSearch?: boolean;
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode). The text becomes
+     * the goal's objective; the backend keeps the agent working under a budget until
+     * it's complete. Omit for a normal turn.
+     */
+    goal?: string;
 }
 /**
  * A selectable model for one of the team's connected providers, from
@@ -750,6 +760,13 @@ interface ConversationAsset {
     workspacePath?: string;
     sourceMessageId?: string;
     agentName?: string;
+    /**
+     * Freshly-signed download/preview URL. Minted per response by the backend
+     * (private `workspaces` bucket), so it reflects the current signature rather
+     * than a link baked in when the asset was created. May be absent if signing
+     * failed or the asset has no stored object.
+     */
+    url?: string;
     createdAt: string;
 }
 
@@ -969,9 +986,7 @@ declare class ChatSession {
     private emit;
     connect(): Promise<void>;
     send(content: string, options?: SendOptions$1): Promise<void>;
-    resendFromCheckpoint(messageId: string, newContent: string, options?: {
-        enableSearch?: boolean;
-    }): Promise<void>;
+    resendFromCheckpoint(messageId: string, newContent: string): Promise<void>;
     private resetStreamingState;
     private processStream;
     /** Last received sequence number for resumable reconnection */
@@ -1002,6 +1017,14 @@ declare class ChatSession {
     /** POST a client-tool result, retrying transient failures a few times. */
     private submitToolResultWithRetry;
     private dispatchWireEvent;
+    /**
+     * Synchronous replay of a single stored wire event — the side-effect +
+     * translate + emit core of ``dispatchWireEvent`` without the (live-only)
+     * client-tool round-trip. Called in a tight synchronous loop during history
+     * restore so the consumer's per-event store writes batch into ONE render
+     * instead of re-typing the whole conversation event by event.
+     */
+    private replayWireEvent;
     /**
      * State mutations driven by wire events. Kept separate from translation so
      * the pure wire → ChatEvent mapping can live in translate.ts and be reused
@@ -1028,16 +1051,33 @@ declare class ChatSession {
     /** Stop the job and disconnect (explicit user action). */
     disconnect(): void;
     createNewConversation(): Promise<string>;
-    switchConversation(id: string, jobId?: string, 
     /**
-     * User prompt that triggered this job, if known. Emitted as a
-     * synthetic ``user_message`` ChatEvent at the START of the replay —
-     * a completed job maps to exactly one user turn, so every event in it
-     * belongs beneath that prompt. User messages aren't persisted in
-     * ``job_events``, so without this the restored conversation would show
-     * the agent response with no visible prompt above it.
+     * Replay one completed turn's already-fetched events, synchronously.
+     *
+     * Fetching is the caller's job (``StreamManager.restore`` loads every turn's
+     * events in parallel and the message list once), so this is pure replay: no
+     * awaits, so the whole restore runs in a single synchronous pass and the
+     * consumer batches it into one render.
+     *
+     * ``userMessageContent`` is the prompt that triggered this turn. It's emitted
+     * as a synthetic ``user_message`` BEFORE any of the turn's events: user
+     * prompts aren't persisted in ``job_events``, and some events precede
+     * ``message_start`` in the stream (e.g. ``memory_recall`` from prompt prep),
+     * so leading with the prompt keeps the turn in order.
+     */
+    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string): void;
+    /**
+     * Load a conversation's messages and replay its persisted history.
+     *
+     * Convenience for plain-``ChatSession`` consumers (the documented
+     * conversation-management API). ``StreamManager`` drives restore itself —
+     * loading messages once and replaying each turn in parallel — and does NOT
+     * call this; it's kept so direct-Session usage doesn't break.
+     *
+     * Without ``jobId`` it replays the whole conversation; with one, just that
+     * job's events.
      */
-    userMessageContent?: string): Promise<void>;
+    switchConversation(id: string, jobId?: string): Promise<void>;
     deleteConversation(id: string): Promise<void>;
     toggleClientTool(name: string): boolean;
 }
@@ -1110,10 +1150,14 @@ declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<Chat
 
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
-    enableSearch?: boolean;
     agentName?: string;
     uploadIds?: string[];
     planMode?: boolean;
+    /**
+     * Start a durable long-horizon goal for this run (goal mode) — the text is the
+     * goal objective the backend drives to completion. Omit for a normal turn.
+     */
+    goal?: string;
 }
 type StreamManagerEvent = {
     type: "stateChange";
@@ -1153,7 +1197,26 @@ declare class StreamManager {
     private onSessionEvent;
     send(content: string, options?: SendOptions): Promise<void>;
     regenerate(): Promise<void>;
-    switchTo(conversationId: string): Promise<void>;
+    /**
+     * Switch the active conversation.
+     *
+     * ``opts.skipHistoryReplay`` is a fast path for consumers that CACHE a
+     * restored conversation's rendered blocks: it moves the active pointer and
+     * loads the message list (needed for send / regenerate context) but skips
+     * the expensive event fetch + replay, and never enters the ``restoring``
+     * state, so a consumer that clears its block view on ``restoring`` keeps
+     * showing the cached history with no flash of a spinner.
+     *
+     * It still confirms there is no live job before skipping: the in-memory
+     * background-job map is empty on a fresh instance (page reload) and blind to
+     * jobs started in another tab/device, so the fast path always asks the server
+     * (``getActiveJob``) and falls through to a full reconnect if one is running.
+     * That one small request is the only cost it doesn't skip, so passing the
+     * flag whenever you hold cached blocks is safe.
+     */
+    switchTo(conversationId: string, opts?: {
+        skipHistoryReplay?: boolean;
+    }): Promise<void>;
     createConversation(): Promise<string>;
     deleteConversation(id: string): Promise<void>;
     stop(): void;
@@ -1200,7 +1263,9 @@ declare function mapSseToChat(raw: RawSseEvent): ChatEvent[];
  * ``message_start`` (e.g. ``memory_recall``, emitted during prompt prep), so
  * gating the user block on ``message_start`` would replay them above the
  * user's own message. Keying off ``job_id`` injects the prompt once per job,
- * before its first event — matching ``session.ts#switchConversation``.
+ * before its first event — matching how the restore path
+ * (``stream-manager.ts#restore`` → ``session.ts#replayTurn``) leads each turn
+ * with its own prompt.
  */
 declare function replayEvents(sseEvents: RawSseEvent[], userMessages: {
     role: string;

package/dist/index.js

@@ -592,6 +592,10 @@ var AstralformClient = class {
       workspacePath: raw.workspace_path,
       sourceMessageId: raw.source_message_id,
       agentName: raw.agent_name,
+      // The API serializes an unsigned asset as `url: null`; normalize to
+      // undefined so it matches the `url?: string` type and consumers that
+      // check `!== undefined` never receive a null.
+      url: raw.url ?? void 0,
       createdAt: raw.created_at
     };
   }
@@ -1297,8 +1301,8 @@ var ChatSession = class {
       ),
       upload_ids: options?.uploadIds,
       agent_name: options?.agentName,
-      enable_search: options?.enableSearch,
       plan_mode: options?.planMode,
+      goal: options?.goal,
       // Per-request model choice (client-side model selection).
       provider: options?.provider,
       model: options?.model,
@@ -1307,15 +1311,14 @@ var ChatSession = class {
     };
     await this.processStream(request);
   }
-  async resendFromCheckpoint(messageId, newContent, options) {
+  async resendFromCheckpoint(messageId, newContent) {
     if (this.isStreaming) return;
     const request = {
       message: newContent,
       conversation_id: this.conversationId ?? void 0,
       resend_from: messageId,
       mcp_manifest: this.toolRegistry.getManifest(),
-      enabled_mcp: Array.from(this.enabledClientTools),
-      enable_search: options?.enableSearch
+      enabled_mcp: Array.from(this.enabledClientTools)
     };
     await this.processStream(request);
   }
@@ -1506,6 +1509,20 @@ var ChatSession = class {
       }
     }
   }
+  /**
+   * Synchronous replay of a single stored wire event — the side-effect +
+   * translate + emit core of ``dispatchWireEvent`` without the (live-only)
+   * client-tool round-trip. Called in a tight synchronous loop during history
+   * restore so the consumer's per-event store writes batch into ONE render
+   * instead of re-typing the whole conversation event by event.
+   */
+  replayWireEvent(wire, conversationId) {
+    this.applyWireSideEffects(wire, conversationId, "");
+    const event = translateWireEvent(wire);
+    if (event) {
+      this.emit(event);
+    }
+  }
   /**
    * State mutations driven by wire events. Kept separate from translation so
    * the pure wire → ChatEvent mapping can live in translate.ts and be reused
@@ -1652,34 +1669,57 @@ var ChatSession = class {
     this.messages = [];
     return id;
   }
-  async switchConversation(id, jobId, userMessageContent) {
+  /**
+   * Replay one completed turn's already-fetched events, synchronously.
+   *
+   * Fetching is the caller's job (``StreamManager.restore`` loads every turn's
+   * events in parallel and the message list once), so this is pure replay: no
+   * awaits, so the whole restore runs in a single synchronous pass and the
+   * consumer batches it into one render.
+   *
+   * ``userMessageContent`` is the prompt that triggered this turn. It's emitted
+   * as a synthetic ``user_message`` BEFORE any of the turn's events: user
+   * prompts aren't persisted in ``job_events``, and some events precede
+   * ``message_start`` in the stream (e.g. ``memory_recall`` from prompt prep),
+   * so leading with the prompt keeps the turn in order.
+   */
+  replayTurn(id, events, userMessageContent) {
     this.conversationId = id;
     this.resetStreamingState();
+    if (userMessageContent) {
+      this.emit({ type: "user_message", content: userMessageContent });
+    }
+    for (const ev of events) {
+      const type = ev.data.type || ev.event;
+      if (!type || type === "done") continue;
+      const wire = { ...ev.data, type };
+      try {
+        this.replayWireEvent(wire, id);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Load a conversation's messages and replay its persisted history.
+   *
+   * Convenience for plain-``ChatSession`` consumers (the documented
+   * conversation-management API). ``StreamManager`` drives restore itself —
+   * loading messages once and replaying each turn in parallel — and does NOT
+   * call this; it's kept so direct-Session usage doesn't break.
+   *
+   * Without ``jobId`` it replays the whole conversation; with one, just that
+   * job's events.
+   */
+  async switchConversation(id, jobId) {
     const [messagesResult, eventsResult] = await Promise.allSettled([
       this.client.getMessages(id).catch(() => this.storage.fetchMessages(id)),
       this.client.getConversationEvents(id, jobId)
     ]);
     this.messages = messagesResult.status === "fulfilled" ? messagesResult.value : [];
-    if (eventsResult.status === "fulfilled") {
-      if (userMessageContent) {
-        this.emit({ type: "user_message", content: userMessageContent });
-      }
-      for (const ev of eventsResult.value) {
-        const type = ev.data.type || ev.event;
-        if (!type || type === "done") continue;
-        const wire = { ...ev.data, type };
-        try {
-          await this.dispatchWireEvent(
-            wire,
-            id,
-            "",
-            false
-            // don't execute client tools on replay
-          );
-        } catch {
-        }
-      }
-    }
+    this.replayTurn(
+      id,
+      eventsResult.status === "fulfilled" ? eventsResult.value : []
+    );
   }
   async deleteConversation(id) {
     try {
@@ -1823,10 +1863,10 @@ var StreamManager = class {
     this.setState("streaming");
     try {
       await this.session.send(content, {
-        enableSearch: options?.enableSearch,
         agentName: options?.agentName,
         uploadIds: options?.uploadIds,
         planMode: options?.planMode,
+        goal: options?.goal,
         provider: options?.provider,
         model: options?.model,
         reasoningEffort: options?.reasoningEffort,
@@ -1855,8 +1895,26 @@ var StreamManager = class {
     this.finalizeStream();
   }
   // ── Switch conversation ───────────────────────────────────────
-  async switchTo(conversationId) {
+  /**
+   * Switch the active conversation.
+   *
+   * ``opts.skipHistoryReplay`` is a fast path for consumers that CACHE a
+   * restored conversation's rendered blocks: it moves the active pointer and
+   * loads the message list (needed for send / regenerate context) but skips
+   * the expensive event fetch + replay, and never enters the ``restoring``
+   * state, so a consumer that clears its block view on ``restoring`` keeps
+   * showing the cached history with no flash of a spinner.
+   *
+   * It still confirms there is no live job before skipping: the in-memory
+   * background-job map is empty on a fresh instance (page reload) and blind to
+   * jobs started in another tab/device, so the fast path always asks the server
+   * (``getActiveJob``) and falls through to a full reconnect if one is running.
+   * That one small request is the only cost it doesn't skip, so passing the
+   * flag whenever you hold cached blocks is safe.
+   */
+  async switchTo(conversationId, opts) {
     if (conversationId === this._activeConversationId) return;
+    const targetHadBackgroundJob = this._backgroundJobs.has(conversationId);
     if (this._state === "streaming") {
       const oldConvId = this._activeConversationId;
       const jobId = this.session.currentJobId;
@@ -1877,6 +1935,18 @@ var StreamManager = class {
       });
     }
     this.setActiveConversation(conversationId);
+    if (opts?.skipHistoryReplay && !targetHadBackgroundJob) {
+      let activeJobId = null;
+      try {
+        activeJobId = (await this.session.client.getActiveJob(conversationId)).jobId;
+      } catch {
+      }
+      if (!activeJobId) {
+        await this.session.loadConversation(conversationId);
+        this.setState("idle");
+        return;
+      }
+    }
     await this.restore(conversationId);
   }
   // ── Create / delete conversation ──────────────────────────────
@@ -1941,13 +2011,16 @@ var StreamManager = class {
         const userMessages = this.session.messages.filter(
           (m) => m.role === "user"
         );
+        const eventLists = await Promise.all(
+          completedJobs.map(
+            (job) => this.session.client.getConversationEvents(conversationId, job.job_id).catch(() => [])
+          )
+        );
         for (let i = 0; i < completedJobs.length; i++) {
-          const job = completedJobs[i];
-          const userContent = userMessages[i]?.content;
-          await this.session.switchConversation(
+          this.session.replayTurn(
             conversationId,
-            job.job_id,
-            userContent
+            eventLists[i] ?? [],
+            userMessages[i]?.content
           );
         }
         if (completedJobs.length > 0) {