@astralform/js 1.2.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 ---
@@ -1207,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.
      */
@@ -1217,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();
@@ -1260,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;