@astralform/js 1.1.0 → 2.0.0

package/README.md

@@ -57,7 +57,7 @@ session.disconnect();
 import { ChatSession } from "@astralform/js";
 
 const session = new ChatSession({
-  apiKey: "your-api-key",   // Required — Astralform project API key
+  apiKey: "your-api-key",   // Required — Astralform agent API key
   userId: "user-123",       // Required — identifies the end user
   baseURL: "http://localhost:8000", // Optional — defaults to https://api.astralform.ai
   fetch: customFetch,       // Optional — custom fetch implementation
@@ -72,7 +72,7 @@ Subscribe to events with `.on()`, which returns an unsubscribe function. The SDK
 const unsubscribe = session.on((event) => {
   switch (event.type) {
     case "connected":
-      // Session connected, project status and tools loaded
+      // Session connected, agent status and tools loaded
       break;
 
     // --- Turn lifecycle ---
@@ -212,10 +212,10 @@ import { ChatSession, parseEmbeddedResource } from "@astralform/js";
 
 await session.connect();
 
-// Gate registration on the project's configured protocol.
-if (session.projectStatus?.uiComponents.enabled) {
+// Gate registration on the agent's configured protocol.
+if (session.agentStatus?.uiComponents.enabled) {
   session.protocols.register({
-    mimeType: session.projectStatus.uiComponents.mimeType!,
+    mimeType: session.agentStatus.uiComponents.mimeType!,
     render: (payload) => {
       /* framework-specific render */
     },
@@ -305,7 +305,7 @@ const client = new AstralformClient({
 });
 
 // REST endpoints
-const status = await client.getProjectStatus();
+const status = await client.getAgentStatus();
 const conversations = await client.getConversations();
 const messages = await client.getMessages("conversation-id");
 const agents = await client.getAgents();

package/dist/index.cjs

@@ -66,7 +66,7 @@ var RateLimitError = class extends AstralformError {
   }
 };
 var LLMNotConfiguredError = class extends AstralformError {
-  constructor(message = "LLM provider not configured for this project") {
+  constructor(message = "LLM provider not configured for this agent") {
     super(message, "llm_not_configured");
     this.name = "LLMNotConfiguredError";
   }
@@ -338,11 +338,11 @@ var AstralformClient = class {
           "accessToken is required and must be a non-empty string in user-token mode"
         );
       }
-      const projectId = typeof config.projectId === "string" && config.projectId.length > 0 ? config.projectId : null;
+      const agentId = typeof config.agentId === "string" && config.agentId.length > 0 ? config.agentId : null;
       this.auth = {
         kind: "user_token",
         accessToken: config.accessToken,
-        projectId,
+        agentId,
         endUserId: typeof config.endUserId === "string" && config.endUserId.length > 0 ? config.endUserId : null
       };
     }
@@ -364,17 +364,17 @@ var AstralformClient = class {
     this.auth = { ...this.auth, accessToken };
   }
   /**
-   * Swap the active project for a user-token client. The backend verifies the
-   * current developer has access to the new project; a 403 comes back if not.
+   * Swap the active agent for a user-token client. The backend verifies the
+   * current developer has access to the new agent; a 403 comes back if not.
    */
-  updateProjectId(projectId) {
+  updateAgentId(agentId) {
     if (this.auth.kind !== "user_token") {
-      throw new Error("updateProjectId is only valid in user-token mode");
+      throw new Error("updateAgentId is only valid in user-token mode");
     }
-    if (!projectId || typeof projectId !== "string") {
-      throw new Error("projectId must be a non-empty string");
+    if (!agentId || typeof agentId !== "string") {
+      throw new Error("agentId must be a non-empty string");
     }
-    this.auth = { ...this.auth, projectId };
+    this.auth = { ...this.auth, agentId };
   }
   /**
    * Set (or clear) the end-user override for user-token mode.
@@ -396,13 +396,13 @@ var AstralformClient = class {
     return this.auth.kind === "user_token" ? this.auth.endUserId : null;
   }
   /**
-   * Active project for user-token mode, or `null` if pre-pick (client
-   * was constructed without one). For API-key mode the project is baked
+   * Active agent for user-token mode, or `null` if pre-pick (client
+   * was constructed without one). For API-key mode the agent is baked
    * into the key, so this getter returns `null` there too — use
    * `authMode` to disambiguate.
    */
-  get projectId() {
-    return this.auth.kind === "user_token" ? this.auth.projectId : null;
+  get agentId() {
+    return this.auth.kind === "user_token" ? this.auth.agentId : null;
   }
   /** Which auth mode this client was constructed with. */
   get authMode() {
@@ -424,8 +424,8 @@ var AstralformClient = class {
     const headers = {
       Authorization: `Bearer ${this.auth.accessToken}`
     };
-    if (this.auth.projectId) {
-      headers["X-Project-ID"] = this.auth.projectId;
+    if (this.auth.agentId) {
+      headers["X-Project-ID"] = this.auth.agentId;
     }
     if (this.auth.endUserId) {
       headers["X-End-User-ID"] = this.auth.endUserId;
@@ -480,7 +480,9 @@ var AstralformClient = class {
   async getHealth() {
     return this.get("/v1/health");
   }
-  async getProjectStatus() {
+  // Agent readiness check. The path is a legacy wire name (shared with the
+  // iOS SDK) — it scopes to the client's active agent via X-Project-ID.
+  async getAgentStatus() {
     const raw = await this.get("/v1/project/status");
     const ui = raw.ui_components ?? {};
     return {
@@ -523,6 +525,12 @@ var AstralformClient = class {
   async deleteConversation(id) {
     await this.del(`/v1/conversations/${encodeURIComponent(id)}`);
   }
+  /**
+   * List the AI personas (sub-agents) available INSIDE the client's active
+   * agent workspace — orchestrator + specialists, addressed per message via
+   * `ChatStreamRequest.agent_name`. Not to be confused with `listAgents()`,
+   * which enumerates the team-level agents a signed-in user can open.
+   */
   async getAgents() {
     const raw = await this.get("/v1/agents");
     return raw.map((a) => ({
@@ -644,7 +652,7 @@ var AstralformClient = class {
   }
   // --- Account-scoped discovery (user-token mode) ---
   //
-  // Lets a signed-in user pick which team/project they want to act on.
+  // Lets a signed-in user pick which team/agent they want to act on.
   // Backend gates these on OIDC user context (no X-Project-ID required) —
   // sending them in API-key mode yields 401.
   async listTeams() {
@@ -657,14 +665,19 @@ var AstralformClient = class {
       role: t.role
     }));
   }
-  async listProjects(teamId) {
-    const raw = await this.get(`/v1/teams/${encodeURIComponent(teamId)}/projects`);
-    return raw.map((p) => ({
-      id: p.id,
-      name: p.name,
-      teamId: p.team_id,
-      createdAt: p.created_at,
-      updatedAt: p.updated_at
+  /**
+   * List the team-level agents (formerly "projects") the signed-in user can
+   * open — the pickable workspaces under a team. Not to be confused with
+   * `getAgents()`, which lists the AI personas inside the active agent.
+   */
+  async listAgents(teamId) {
+    const raw = await this.get(`/v1/teams/${encodeURIComponent(teamId)}/agents`);
+    return raw.map((a) => ({
+      id: a.id,
+      name: a.name,
+      teamId: a.team_id,
+      createdAt: a.created_at,
+      updatedAt: a.updated_at
     }));
   }
   // --- Jobs API ---
@@ -1190,6 +1203,11 @@ function translateWireEvent(wire) {
 }
 
 // src/session.ts
+var SSE_MAX_RECONNECTS = 6;
+var TOOL_RESULT_MAX_RETRIES = 3;
+function sseReconnectDelayMs(attempt) {
+  return Math.min(500 * 2 ** (attempt - 1), 5e3);
+}
 function pathEquals(a, b) {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) {
@@ -1202,7 +1220,7 @@ var ChatSession = class {
     /**
      * Pluggable UI protocol adapters. Consumers register a framework-
      * specific adapter (e.g. React) for each MIME type they can render,
-     * typically gated on ``session.projectStatus.uiComponents.protocol``.
+     * typically gated on ``session.agentStatus.uiComponents.protocol``.
      * ``ToolBlock``-style consumers look up the adapter for an incoming
      * embedded resource and hand off rendering.
      */
@@ -1212,7 +1230,7 @@ var ChatSession = class {
     this.conversations = [];
     this.messages = [];
     this.isStreaming = false;
-    this.projectStatus = null;
+    this.agentStatus = null;
     this.agents = [];
     this.skills = [];
     this.enabledClientTools = /* @__PURE__ */ new Set();
@@ -1226,6 +1244,13 @@ var ChatSession = class {
     this.abortController = null;
     /** Last received sequence number for resumable reconnection */
     this.lastSeq = -1;
+    /**
+     * Client-tool call_ids whose result was already submitted this turn. On a
+     * reconnect the resumed stream can replay a tool request we already handled;
+     * this dedups so each is executed + submitted at most once (but a request we
+     * never submitted still runs). Cleared at the start of each turn.
+     */
+    this.submittedToolCallIds = /* @__PURE__ */ new Set();
     /** Current job ID for cancellation */
     this.currentJobId = null;
     this.client = new AstralformClient(config);
@@ -1248,13 +1273,13 @@ var ChatSession = class {
   }
   async connect() {
     const [status, conversations, agents, skills] = await Promise.allSettled([
-      this.client.getProjectStatus(),
+      this.client.getAgentStatus(),
       this.client.getConversations(),
       this.client.getAgents().catch(() => []),
       this.client.getSkills().catch(() => [])
     ]);
     if (status.status === "fulfilled") {
-      this.projectStatus = status.value;
+      this.agentStatus = status.value;
     }
     if (conversations.status === "fulfilled") {
       this.conversations = conversations.value;
@@ -1360,13 +1385,9 @@ var ChatSession = class {
     }
     const messageId = job.message_id;
     this.lastSeq = -1;
-    const stream = this.client.streamJobEvents(
-      job.job_id,
-      this.lastSeq,
-      this.abortController?.signal
-    );
+    this.submittedToolCallIds.clear();
     await this.consumeEventStream(
-      stream,
+      job.job_id,
       conversationId,
       messageId,
       true
@@ -1377,7 +1398,41 @@ var ChatSession = class {
    * Shared event consumption loop. Parses each wire event, updates
    * minimal session state, and emits typed ChatEvents to consumers.
    */
-  async consumeEventStream(stream, conversationId, messageId, executeClientTools) {
+  async consumeEventStream(jobId, conversationId, messageId, executeClientTools) {
+    const signal = this.abortController?.signal;
+    for (let attempt = 0; ; attempt++) {
+      const stream = this.client.streamJobEvents(jobId, this.lastSeq, signal);
+      let sawTerminal;
+      try {
+        sawTerminal = await this.pumpStream(
+          stream,
+          conversationId,
+          messageId,
+          executeClientTools
+        );
+      } catch (err) {
+        if (signal?.aborted) return;
+        if (err instanceof AuthenticationError || err instanceof RateLimitError) {
+          throw err;
+        }
+        if (attempt >= SSE_MAX_RECONNECTS) throw err;
+        await this.sleepUnlessAborted(sseReconnectDelayMs(attempt + 1), signal);
+        continue;
+      }
+      if (sawTerminal || signal?.aborted) return;
+      if (attempt >= SSE_MAX_RECONNECTS) {
+        throw new ConnectionError("Lost connection to the response stream.");
+      }
+      await this.sleepUnlessAborted(sseReconnectDelayMs(attempt + 1), signal);
+    }
+  }
+  /**
+   * Consume a single SSE stream to exhaustion. Returns whether a terminal
+   * event (``message_stop`` / ``error``) was seen, so the caller can decide
+   * whether an ended stream means "turn done" vs "dropped, reconnect".
+   */
+  async pumpStream(stream, conversationId, messageId, executeClientTools) {
+    let sawTerminal = false;
     for await (const raw of stream) {
       let parsed;
       try {
@@ -1395,6 +1450,9 @@ var ChatSession = class {
       } catch {
         continue;
       }
+      if (parsed.type === "message_stop" || parsed.type === "error") {
+        sawTerminal = true;
+      }
       await this.dispatchWireEvent(
         parsed,
         conversationId,
@@ -1402,6 +1460,39 @@ var ChatSession = class {
         executeClientTools
       );
     }
+    return sawTerminal;
+  }
+  /** Sleep for ``ms``, resolving early if the turn is aborted mid-backoff. */
+  sleepUnlessAborted(ms, signal) {
+    return new Promise((resolve) => {
+      if (signal?.aborted) return resolve();
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, ms);
+      const onAbort = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  /** POST a client-tool result, retrying transient failures a few times. */
+  async submitToolResultWithRetry(payload) {
+    const signal = this.abortController?.signal;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await this.client.submitToolResult(payload);
+        return;
+      } catch (err) {
+        if (signal?.aborted) throw err;
+        if (err instanceof AuthenticationError || err instanceof RateLimitError) {
+          throw err;
+        }
+        if (attempt >= TOOL_RESULT_MAX_RETRIES) throw err;
+        await this.sleepUnlessAborted(sseReconnectDelayMs(attempt + 1), signal);
+      }
+    }
   }
   async dispatchWireEvent(wire, conversationId, messageId, executeClientTools) {
     this.applyWireSideEffects(wire, conversationId, messageId);
@@ -1411,18 +1502,22 @@ var ChatSession = class {
     }
     if (executeClientTools && wire.type === "block_stop" && wire.status === "awaiting_client_result" && wire.final?.call_id) {
       const f = wire.final;
-      const request = {
-        callId: f.call_id ?? "",
-        toolName: f.tool_name ?? "",
-        arguments: f.input ?? {},
-        isClientTool: true
-      };
-      const results = await this.executeClientTools([request]);
-      await this.client.submitToolResult({
-        conversation_id: conversationId,
-        message_id: messageId,
-        tool_results: results
-      });
+      const callId = f.call_id ?? "";
+      if (callId && !this.submittedToolCallIds.has(callId)) {
+        const request = {
+          callId,
+          toolName: f.tool_name ?? "",
+          arguments: f.input ?? {},
+          isClientTool: true
+        };
+        const results = await this.executeClientTools([request]);
+        await this.submitToolResultWithRetry({
+          conversation_id: conversationId,
+          message_id: messageId,
+          tool_results: results
+        });
+        this.submittedToolCallIds.add(callId);
+      }
     }
   }
   /**
@@ -1519,16 +1614,12 @@ var ChatSession = class {
     this.isStreaming = true;
     this.currentJobId = jobId;
     this.lastSeq = -1;
+    this.submittedToolCallIds.clear();
     this.resetStreamingState();
     this.abortController = new AbortController();
     try {
-      const stream = this.client.streamJobEvents(
-        jobId,
-        this.lastSeq,
-        this.abortController?.signal
-      );
       await this.consumeEventStream(
-        stream,
+        jobId,
         this.conversationId ?? "",
         "",
         false