@astralform/js 7.4.1 → 7.5.0

package/dist/index.d.cts

@@ -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.71.0 — 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,11 +774,12 @@ 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.
+     * 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.71.0 there is no agent mode that requires
+     * one.
      * Astralform >= 0.70.0.
      */
     repository?: string;
@@ -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.71.0 no agent requires one, and a first
+     * turn without it is no longer a 400. Astralform >= 0.70.0.
      */
     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.71.0 there is no agent mode that requires one, so a first turn
+     * without it is no longer a 400. Astralform >= 0.70.0.
      */
     repository?: string;
 }

package/dist/index.d.ts

@@ -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.71.0 — 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,11 +774,12 @@ 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.
+     * 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.71.0 there is no agent mode that requires
+     * one.
      * Astralform >= 0.70.0.
      */
     repository?: string;
@@ -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.71.0 no agent requires one, and a first
+     * turn without it is no longer a 400. Astralform >= 0.70.0.
      */
     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.71.0 there is no agent mode that requires one, so a first turn
+     * without it is no longer a 400. Astralform >= 0.70.0.
      */
     repository?: string;
 }

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).