@astralform/js 7.4.1 → 7.5.1

package/dist/index.d.cts

@@ -566,7 +566,7 @@ interface Conversation {
     /**
      * The project this task belongs to (`owner/repo`), or `null` for an ordinary
      * conversation. Set on the first turn and immutable after. Absent (rather than
-     * null) from an Astralform older than 0.70.0.
+     * null) from an Astralform older than 0.69.46.
      */
     repository?: string | null;
 }
@@ -619,15 +619,30 @@ interface AgentInfo {
     isEnabled: boolean;
     avatarUrl?: string;
     /**
-     * What the agent is for. A client shows Projects and Tasks only for `"code"`.
-     * Absent on Astralform older than 0.70.0 — treat that as `"chat"`, which is
-     * also the server's default.
+     * Whether this agent's tasks can name a repository — the workspace has GitHub
+     * connected and enabled here. A client shows Projects and Tasks on it.
+     *
+     * Derived by the server from the connector, so it cannot go stale the way the
+     * retired `mode` toggle could. It gates a SURFACE, not an ability: naming a
+     * repository is optional on every task, and a task that names none is an
+     * ordinary chat. Absent on Astralform older than 0.69.50 — fall back to `mode`
+     * there.
      *
      * It is a property of the WORKSPACE, not of a persona: `GET /v1/agents` selects
-     * the workspace row itself and returns exactly one entry, so the mode is
-     * `agents[0].mode` rather than something that varies across the list. The
-     * workspace picker (`listAgents`) does not carry it, so a client learns an
-     * agent's mode after opening it.
+     * the workspace row itself and returns exactly one entry, so read
+     * `agents[0].codeProjectsEnabled`. The workspace picker (`listAgents`) does not
+     * carry it, so a client learns this after opening an agent.
+     */
+    codeProjectsEnabled?: boolean;
+    /**
+     * @deprecated Removed in the next Astralform release. There is no agent mode —
+     * a repository belongs to the TASK, so one agent answers general questions and
+     * works in repositories from the same list. Read {@link codeProjectsEnabled}.
+     *
+     * Still reported for one release, as the STORED value of the retired column, so
+     * clients built before the change keep behaving exactly as they did. Do not
+     * treat it as an alias for `codeProjectsEnabled`: an agent that never had the
+     * toggle set still reports `"chat"` while its tasks can bind perfectly well.
      */
     mode?: "chat" | "code";
 }
@@ -759,12 +774,13 @@ interface ChatStreamRequest {
     /**
      * Which project (GitHub repository, `owner/repo`) this task belongs to.
      *
-     * Required on the FIRST turn of a conversation on a code-mode agent, which
-     * binds it. A later turn may omit it or repeat the same value; a DIFFERENT
-     * value is refused (409), not ignored — a task is bound to one repository for
-     * life, so a different repository means a new task. Chat-mode agents ignore
-     * it entirely.
-     * Astralform >= 0.70.0.
+     * Optional on every agent. The first turn that names one binds the task, and a
+     * later turn may omit it or repeat the same value; a DIFFERENT value is refused
+     * (409), not ignored — a task is bound to one repository for life, so a
+     * different repository means a new task. A task that never names one is an
+     * ordinary chat; since Astralform 0.69.50 there is no agent mode that requires
+     * one.
+     * Astralform >= 0.69.46.
      */
     repository?: string;
     mcp_manifest?: ToolDefinition[];
@@ -791,7 +807,7 @@ interface ChatStreamRequest {
     reasoning_effort?: ReasoningEffort;
     temperature?: number;
 }
-/** One repository an app user works with on a code-mode agent. */
+/** One repository an app user works with on an agent. */
 interface CodeProject {
     repoFullName: string;
     addedAt: string;
@@ -1064,13 +1080,13 @@ interface SendOptions$1 extends ModelChoiceOptions {
      */
     goal?: string;
     /**
-     * The project this task belongs to (`owner/repo`), on a code-mode agent.
+     * The project this task belongs to (`owner/repo`), when it has one.
      *
      * Send it on the turn that STARTS a task; the binding is write-once, so a
      * later turn may omit it or repeat the same value, and a DIFFERENT value is
-     * refused (409) rather than ignored. A first turn without it on a code-mode
-     * agent is refused too (400) — the run needs a repository before it can hold a
-     * credential scoped to one. Astralform >= 0.70.0.
+     * refused (409) rather than ignored. Omit it entirely and the task is an
+     * ordinary chat — since Astralform 0.69.50 no agent requires one, and a first
+     * turn without it is no longer a 400. Astralform >= 0.69.46.
      */
     repository?: string;
 }
@@ -1223,9 +1239,10 @@ declare class AstralformClient {
     /**
      * A page of conversations, newest-updated first.
      *
-     * `options.repository` narrows to one project's tasks (`owner/repo`) on a
-     * code-mode agent — the same paging applies within the filter, so a client
-     * showing tasks per project pages each project separately.
+     * `options.repository` narrows to one project's tasks (`owner/repo`) — the same
+     * paging applies within the filter, so a client showing tasks per project pages
+     * each project separately. Tasks that named no repository fall outside every
+     * such filter; list them with no filter at all.
      */
     getConversations(limit?: number, offset?: number, options?: {
         repository?: string;
@@ -1318,10 +1335,11 @@ declare class AstralformClient {
      * The projects (GitHub repositories) this app user works with, and what they
      * may add.
      *
-     * A project list is per app user within a code-mode agent: the developer
-     * connects the workspace's GitHub account, and each user curates their own
-     * list from what that connection covers. Every method 404s on a chat-mode
-     * agent, so the surface is invisible rather than empty there.
+     * A project list is per app user: the developer connects the workspace's GitHub
+     * account, and each user curates their own list from what that connection
+     * covers. There is no agent-level gate — an agent with no GitHub lists nothing,
+     * reports `not_installed` from `available()`, and refuses `add()`. Read
+     * {@link AgentInfo.codeProjectsEnabled} to decide whether to show the surface.
      */
     readonly code: {
         projects: {
@@ -1820,14 +1838,15 @@ interface SendOptions extends ModelChoiceOptions {
      */
     goal?: string;
     /**
-     * The project this task belongs to (`owner/repo`), on a code-mode agent.
+     * The project this task belongs to (`owner/repo`), when it has one.
      *
      * Write-once server-side, and the refusal is the part that matters: the FIRST
-     * turn binds the task, a later turn may omit it or repeat the same value, and
-     * a DIFFERENT value is refused (409) rather than ignored — silently acting on
-     * the wrong repository is the failure that rule exists to prevent. A first
-     * turn without it on a code-mode agent is refused too (400). Astralform
-     * >= 0.70.0.
+     * turn that names a repository binds the task, a later turn may omit it or
+     * repeat the same value, and a DIFFERENT value is refused (409) rather than
+     * ignored — silently acting on the wrong repository is the failure that rule
+     * exists to prevent. Omit it entirely and the task is an ordinary chat: since
+     * Astralform 0.69.50 there is no agent mode that requires one, so a first turn
+     * without it is no longer a 400. Astralform >= 0.69.46.
      */
     repository?: string;
 }
@@ -1999,6 +2018,14 @@ declare class StreamManager {
      */
     private settleIdle;
     private finalizeStream;
+    /**
+     * A conversation's turns, oldest first.
+     *
+     * Its own method so ``restore`` can put the request on the wire beside the
+     * probe and the message list while ``replayHistory``, which consumes it,
+     * keeps owning the shape it reads.
+     */
+    private jobList;
     private restore;
     /**
      * Has a live turn taken the block view over?
@@ -2037,6 +2064,12 @@ declare class StreamManager {
      * that started it, which is emitted as a bubble with no events — the whole
      * reason a conversation reopened mid-turn now shows the message that started
      * that turn.
+     *
+     * ``jobsRequest`` is the job list already IN FLIGHT — issued by ``restore``
+     * alongside the probe and the message list rather than fetched here, so the
+     * three round trips overlap. It is awaited inside the try below, which is
+     * what keeps a failed job list non-blocking exactly as it was when the fetch
+     * lived here.
      */
     private replayHistory;
     private setActiveConversation;

package/dist/index.d.ts

@@ -566,7 +566,7 @@ interface Conversation {
     /**
      * The project this task belongs to (`owner/repo`), or `null` for an ordinary
      * conversation. Set on the first turn and immutable after. Absent (rather than
-     * null) from an Astralform older than 0.70.0.
+     * null) from an Astralform older than 0.69.46.
      */
     repository?: string | null;
 }
@@ -619,15 +619,30 @@ interface AgentInfo {
     isEnabled: boolean;
     avatarUrl?: string;
     /**
-     * What the agent is for. A client shows Projects and Tasks only for `"code"`.
-     * Absent on Astralform older than 0.70.0 — treat that as `"chat"`, which is
-     * also the server's default.
+     * Whether this agent's tasks can name a repository — the workspace has GitHub
+     * connected and enabled here. A client shows Projects and Tasks on it.
+     *
+     * Derived by the server from the connector, so it cannot go stale the way the
+     * retired `mode` toggle could. It gates a SURFACE, not an ability: naming a
+     * repository is optional on every task, and a task that names none is an
+     * ordinary chat. Absent on Astralform older than 0.69.50 — fall back to `mode`
+     * there.
      *
      * It is a property of the WORKSPACE, not of a persona: `GET /v1/agents` selects
-     * the workspace row itself and returns exactly one entry, so the mode is
-     * `agents[0].mode` rather than something that varies across the list. The
-     * workspace picker (`listAgents`) does not carry it, so a client learns an
-     * agent's mode after opening it.
+     * the workspace row itself and returns exactly one entry, so read
+     * `agents[0].codeProjectsEnabled`. The workspace picker (`listAgents`) does not
+     * carry it, so a client learns this after opening an agent.
+     */
+    codeProjectsEnabled?: boolean;
+    /**
+     * @deprecated Removed in the next Astralform release. There is no agent mode —
+     * a repository belongs to the TASK, so one agent answers general questions and
+     * works in repositories from the same list. Read {@link codeProjectsEnabled}.
+     *
+     * Still reported for one release, as the STORED value of the retired column, so
+     * clients built before the change keep behaving exactly as they did. Do not
+     * treat it as an alias for `codeProjectsEnabled`: an agent that never had the
+     * toggle set still reports `"chat"` while its tasks can bind perfectly well.
      */
     mode?: "chat" | "code";
 }
@@ -759,12 +774,13 @@ interface ChatStreamRequest {
     /**
      * Which project (GitHub repository, `owner/repo`) this task belongs to.
      *
-     * Required on the FIRST turn of a conversation on a code-mode agent, which
-     * binds it. A later turn may omit it or repeat the same value; a DIFFERENT
-     * value is refused (409), not ignored — a task is bound to one repository for
-     * life, so a different repository means a new task. Chat-mode agents ignore
-     * it entirely.
-     * Astralform >= 0.70.0.
+     * Optional on every agent. The first turn that names one binds the task, and a
+     * later turn may omit it or repeat the same value; a DIFFERENT value is refused
+     * (409), not ignored — a task is bound to one repository for life, so a
+     * different repository means a new task. A task that never names one is an
+     * ordinary chat; since Astralform 0.69.50 there is no agent mode that requires
+     * one.
+     * Astralform >= 0.69.46.
      */
     repository?: string;
     mcp_manifest?: ToolDefinition[];
@@ -791,7 +807,7 @@ interface ChatStreamRequest {
     reasoning_effort?: ReasoningEffort;
     temperature?: number;
 }
-/** One repository an app user works with on a code-mode agent. */
+/** One repository an app user works with on an agent. */
 interface CodeProject {
     repoFullName: string;
     addedAt: string;
@@ -1064,13 +1080,13 @@ interface SendOptions$1 extends ModelChoiceOptions {
      */
     goal?: string;
     /**
-     * The project this task belongs to (`owner/repo`), on a code-mode agent.
+     * The project this task belongs to (`owner/repo`), when it has one.
      *
      * Send it on the turn that STARTS a task; the binding is write-once, so a
      * later turn may omit it or repeat the same value, and a DIFFERENT value is
-     * refused (409) rather than ignored. A first turn without it on a code-mode
-     * agent is refused too (400) — the run needs a repository before it can hold a
-     * credential scoped to one. Astralform >= 0.70.0.
+     * refused (409) rather than ignored. Omit it entirely and the task is an
+     * ordinary chat — since Astralform 0.69.50 no agent requires one, and a first
+     * turn without it is no longer a 400. Astralform >= 0.69.46.
      */
     repository?: string;
 }
@@ -1223,9 +1239,10 @@ declare class AstralformClient {
     /**
      * A page of conversations, newest-updated first.
      *
-     * `options.repository` narrows to one project's tasks (`owner/repo`) on a
-     * code-mode agent — the same paging applies within the filter, so a client
-     * showing tasks per project pages each project separately.
+     * `options.repository` narrows to one project's tasks (`owner/repo`) — the same
+     * paging applies within the filter, so a client showing tasks per project pages
+     * each project separately. Tasks that named no repository fall outside every
+     * such filter; list them with no filter at all.
      */
     getConversations(limit?: number, offset?: number, options?: {
         repository?: string;
@@ -1318,10 +1335,11 @@ declare class AstralformClient {
      * The projects (GitHub repositories) this app user works with, and what they
      * may add.
      *
-     * A project list is per app user within a code-mode agent: the developer
-     * connects the workspace's GitHub account, and each user curates their own
-     * list from what that connection covers. Every method 404s on a chat-mode
-     * agent, so the surface is invisible rather than empty there.
+     * A project list is per app user: the developer connects the workspace's GitHub
+     * account, and each user curates their own list from what that connection
+     * covers. There is no agent-level gate — an agent with no GitHub lists nothing,
+     * reports `not_installed` from `available()`, and refuses `add()`. Read
+     * {@link AgentInfo.codeProjectsEnabled} to decide whether to show the surface.
      */
     readonly code: {
         projects: {
@@ -1820,14 +1838,15 @@ interface SendOptions extends ModelChoiceOptions {
      */
     goal?: string;
     /**
-     * The project this task belongs to (`owner/repo`), on a code-mode agent.
+     * The project this task belongs to (`owner/repo`), when it has one.
      *
      * Write-once server-side, and the refusal is the part that matters: the FIRST
-     * turn binds the task, a later turn may omit it or repeat the same value, and
-     * a DIFFERENT value is refused (409) rather than ignored — silently acting on
-     * the wrong repository is the failure that rule exists to prevent. A first
-     * turn without it on a code-mode agent is refused too (400). Astralform
-     * >= 0.70.0.
+     * turn that names a repository binds the task, a later turn may omit it or
+     * repeat the same value, and a DIFFERENT value is refused (409) rather than
+     * ignored — silently acting on the wrong repository is the failure that rule
+     * exists to prevent. Omit it entirely and the task is an ordinary chat: since
+     * Astralform 0.69.50 there is no agent mode that requires one, so a first turn
+     * without it is no longer a 400. Astralform >= 0.69.46.
      */
     repository?: string;
 }
@@ -1999,6 +2018,14 @@ declare class StreamManager {
      */
     private settleIdle;
     private finalizeStream;
+    /**
+     * A conversation's turns, oldest first.
+     *
+     * Its own method so ``restore`` can put the request on the wire beside the
+     * probe and the message list while ``replayHistory``, which consumes it,
+     * keeps owning the shape it reads.
+     */
+    private jobList;
     private restore;
     /**
      * Has a live turn taken the block view over?
@@ -2037,6 +2064,12 @@ declare class StreamManager {
      * that started it, which is emitted as a bubble with no events — the whole
      * reason a conversation reopened mid-turn now shows the message that started
      * that turn.
+     *
+     * ``jobsRequest`` is the job list already IN FLIGHT — issued by ``restore``
+     * alongside the probe and the message list rather than fetched here, so the
+     * three round trips overlap. It is awaited inside the try below, which is
+     * what keeps a failed job list non-blocking exactly as it was when the fetch
+     * lived here.
      */
     private replayHistory;
     private setActiveConversation;

package/dist/index.js

@@ -338,15 +338,16 @@ function isApiKeyConfig(config) {
 }
 var AstralformClient = class {
   constructor(config) {
-    // --- Code mode: the app user's projects ---
+    // --- Projects: the repositories this app user works with ---
     /**
      * The projects (GitHub repositories) this app user works with, and what they
      * may add.
      *
-     * A project list is per app user within a code-mode agent: the developer
-     * connects the workspace's GitHub account, and each user curates their own
-     * list from what that connection covers. Every method 404s on a chat-mode
-     * agent, so the surface is invisible rather than empty there.
+     * A project list is per app user: the developer connects the workspace's GitHub
+     * account, and each user curates their own list from what that connection
+     * covers. There is no agent-level gate — an agent with no GitHub lists nothing,
+     * reports `not_installed` from `available()`, and refuses `add()`. Read
+     * {@link AgentInfo.codeProjectsEnabled} to decide whether to show the surface.
      */
     this.code = {
       projects: {
@@ -644,9 +645,10 @@ var AstralformClient = class {
   /**
    * A page of conversations, newest-updated first.
    *
-   * `options.repository` narrows to one project's tasks (`owner/repo`) on a
-   * code-mode agent — the same paging applies within the filter, so a client
-   * showing tasks per project pages each project separately.
+   * `options.repository` narrows to one project's tasks (`owner/repo`) — the same
+   * paging applies within the filter, so a client showing tasks per project pages
+   * each project separately. Tasks that named no repository fall outside every
+   * such filter; list them with no filter at all.
    */
   async getConversations(limit = 50, offset = 0, options) {
     const safeLimit = Math.max(1, Math.min(200, Math.floor(Number(limit))));
@@ -1747,7 +1749,7 @@ var ChatSession = class {
       image_mode: options?.imageMode,
       video_mode: options?.videoMode,
       goal: options?.goal,
-      // The project this task belongs to, on a code-mode agent. Write-once
+      // The project this task belongs to, when it has one. Write-once
       // server-side: sent on every turn, honoured on the first.
       repository: options?.repository,
       // Per-request model choice (client-side model selection).
@@ -2885,23 +2887,41 @@ var StreamManager = class {
     }
   }
   // ── Internal: restore ─────────────────────────────────────────
+  /**
+   * A conversation's turns, oldest first.
+   *
+   * Its own method so ``restore`` can put the request on the wire beside the
+   * probe and the message list while ``replayHistory``, which consumes it,
+   * keeps owning the shape it reads.
+   */
+  jobList(conversationId) {
+    return this.session.client.get(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/jobs`
+    );
+  }
   async restore(conversationId, gen) {
     const superseded = () => gen !== this.generation;
     if (superseded()) return;
     const turn = this.turnCounter;
     const announcedRestoring = !this.session.isStreaming;
     if (announcedRestoring) this.setState("restoring");
-    let activeJobId = null;
-    try {
-      const res = await this.session.client.getActiveJob(conversationId);
-      activeJobId = res.jobId;
-    } catch {
-    }
     if (superseded()) return;
-    await this.session.loadConversation(conversationId);
+    const probeRequest = this.session.client.getActiveJob(conversationId).catch(() => null);
+    const loadRequest = this.session.loadConversation(conversationId);
+    const jobsRequest = announcedRestoring ? this.jobList(conversationId) : null;
+    void jobsRequest?.catch(() => {
+    });
+    const [probe] = await Promise.all([probeRequest, loadRequest]);
+    const activeJobId = probe?.jobId ?? null;
     if (superseded()) return;
     if (announcedRestoring && this.viewTakenOverByLiveTurn()) return;
-    if (announcedRestoring && !await this.replayHistory(conversationId, gen, activeJobId, turn))
+    if (jobsRequest && !await this.replayHistory(
+      conversationId,
+      gen,
+      activeJobId,
+      turn,
+      jobsRequest
+    ))
       return;
     if (activeJobId) {
       this.setState("streaming");
@@ -2959,11 +2979,17 @@ var StreamManager = class {
    * that started it, which is emitted as a bubble with no events — the whole
    * reason a conversation reopened mid-turn now shows the message that started
    * that turn.
+   *
+   * ``jobsRequest`` is the job list already IN FLIGHT — issued by ``restore``
+   * alongside the probe and the message list rather than fetched here, so the
+   * three round trips overlap. It is awaited inside the try below, which is
+   * what keeps a failed job list non-blocking exactly as it was when the fetch
+   * lived here.
    */
-  async replayHistory(conversationId, gen, activeJobId, turn) {
+  async replayHistory(conversationId, gen, activeJobId, turn, jobsRequest) {
     const stopReplay = () => gen !== this.generation || this.viewTakenOverByLiveTurn() || this.turnStarted(turn);
     try {
-      const jobs = await this.session.client.get(`/v1/conversations/${encodeURIComponent(conversationId)}/jobs`);
+      const jobs = await jobsRequest;
       if (stopReplay()) return false;
       const replayableJobs = jobs.filter(
         (j) => j.job_id !== activeJobId