@astralform/js 4.3.0 → 4.5.0

package/dist/index.d.cts

@@ -420,6 +420,12 @@ type ChatEvent = {
     type: "user_message";
     content: string;
     createdAt?: number;
+    id?: string;
+    /** This message was steered into a run already in flight — it started
+     *  no turn of its own. Consumers that badge a steer (a "waiting to be
+     *  read" notice) key off this; without it a replayed steer is
+     *  indistinguishable from an ordinary prompt. */
+    steer?: boolean;
 } | {
     type: "title_generated";
     title: string;
@@ -546,6 +552,12 @@ interface UIComponentsConfig {
     /** MIME type to match against embedded resources (e.g. "application/json+a2ui"). */
     mimeType: string | null;
 }
+/** One capability the agent either has or does not, right now. */
+interface AgentCapability {
+    /** Stable key, e.g. `"image"`, `"web"`, `"skills"`. */
+    key: string;
+    enabled: boolean;
+}
 interface AgentStatus {
     isReady: boolean;
     llmConfigured: boolean;
@@ -553,6 +565,16 @@ interface AgentStatus {
     llmModel?: string;
     message: string;
     uiComponents: UIComponentsConfig;
+    /**
+     * What the agent can do right now, so a client can offer a capability only
+     * where it will actually work rather than failing on send.
+     *
+     * Empty when the backend does not report it (older servers) or when the agent
+     * is not ready — treat an ABSENT key as "not reported", never as disabled.
+     * Only capabilities with a real per-agent gate appear; always-on ones do not,
+     * because a constant tells a client nothing.
+     */
+    capabilities: AgentCapability[];
 }
 interface AgentInfo {
     name: string;
@@ -1139,7 +1161,7 @@ declare class ChatSession {
      * ``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;
+    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string, userMessageId?: string, isSteer?: boolean): void;
     /**
      * Load a conversation's messages and replay its persisted history.
      *
@@ -1236,26 +1258,6 @@ declare function generateId(): string;
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
-/**
- * StreamManager — high-level conversation lifecycle coordinator.
- *
- * Sits on top of ChatSession and manages the state machine for
- * multi-conversation SSE streaming. Framework-agnostic: emits
- * typed events to registered handlers. Block construction is NOT
- * the SDK's concern — consumers build their own block tree from
- * the forwarded ``ChatEvent`` instances.
- *
- *   import { ChatSession, StreamManager } from "@astralform/js";
- *   const session = new ChatSession({ ... });
- *   const manager = new StreamManager(session);
- *   manager.on((event) => {
- *     if (event.type === "event") {
- *       // event.event is a typed ChatEvent — dispatch to your reducer
- *     }
- *   });
- *   await manager.send("Hello");
- */
-
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
     agentName?: string;
@@ -1418,4 +1420,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-export { type ActiveJob, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };

package/dist/index.d.ts

@@ -420,6 +420,12 @@ type ChatEvent = {
     type: "user_message";
     content: string;
     createdAt?: number;
+    id?: string;
+    /** This message was steered into a run already in flight — it started
+     *  no turn of its own. Consumers that badge a steer (a "waiting to be
+     *  read" notice) key off this; without it a replayed steer is
+     *  indistinguishable from an ordinary prompt. */
+    steer?: boolean;
 } | {
     type: "title_generated";
     title: string;
@@ -546,6 +552,12 @@ interface UIComponentsConfig {
     /** MIME type to match against embedded resources (e.g. "application/json+a2ui"). */
     mimeType: string | null;
 }
+/** One capability the agent either has or does not, right now. */
+interface AgentCapability {
+    /** Stable key, e.g. `"image"`, `"web"`, `"skills"`. */
+    key: string;
+    enabled: boolean;
+}
 interface AgentStatus {
     isReady: boolean;
     llmConfigured: boolean;
@@ -553,6 +565,16 @@ interface AgentStatus {
     llmModel?: string;
     message: string;
     uiComponents: UIComponentsConfig;
+    /**
+     * What the agent can do right now, so a client can offer a capability only
+     * where it will actually work rather than failing on send.
+     *
+     * Empty when the backend does not report it (older servers) or when the agent
+     * is not ready — treat an ABSENT key as "not reported", never as disabled.
+     * Only capabilities with a real per-agent gate appear; always-on ones do not,
+     * because a constant tells a client nothing.
+     */
+    capabilities: AgentCapability[];
 }
 interface AgentInfo {
     name: string;
@@ -1139,7 +1161,7 @@ declare class ChatSession {
      * ``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;
+    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string, userMessageId?: string, isSteer?: boolean): void;
     /**
      * Load a conversation's messages and replay its persisted history.
      *
@@ -1236,26 +1258,6 @@ declare function generateId(): string;
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
-/**
- * StreamManager — high-level conversation lifecycle coordinator.
- *
- * Sits on top of ChatSession and manages the state machine for
- * multi-conversation SSE streaming. Framework-agnostic: emits
- * typed events to registered handlers. Block construction is NOT
- * the SDK's concern — consumers build their own block tree from
- * the forwarded ``ChatEvent`` instances.
- *
- *   import { ChatSession, StreamManager } from "@astralform/js";
- *   const session = new ChatSession({ ... });
- *   const manager = new StreamManager(session);
- *   manager.on((event) => {
- *     if (event.type === "event") {
- *       // event.event is a typed ChatEvent — dispatch to your reducer
- *     }
- *   });
- *   await manager.send("Hello");
- */
-
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
     agentName?: string;
@@ -1418,4 +1420,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-export { type ActiveJob, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };

package/dist/index.js

@@ -491,6 +491,14 @@ var AstralformClient = class {
       llmProvider: raw.llm_provider,
       llmModel: raw.llm_model,
       message: raw.message,
+      // Defaults to [] rather than undefined so a caller can iterate without a
+      // guard, and so a server that predates the field behaves as "reports
+      // nothing" instead of throwing. Entries missing a key are dropped: a
+      // capability with no name cannot be matched against and would render as
+      // an unlabelled row.
+      capabilities: (raw.capabilities ?? []).flatMap(
+        (c) => typeof c?.key === "string" && c.key.length > 0 ? [{ key: c.key, enabled: Boolean(c.enabled) }] : []
+      ),
       uiComponents: {
         enabled: Boolean(ui.enabled),
         protocol: ui.protocol ?? null,
@@ -1773,11 +1781,16 @@ var ChatSession = class {
    * ``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) {
+  replayTurn(id, events, userMessageContent, userMessageId, isSteer = false) {
     this.conversationId = id;
     this.resetStreamingState();
     if (userMessageContent) {
-      this.emit({ type: "user_message", content: userMessageContent });
+      this.emit({
+        type: "user_message",
+        content: userMessageContent,
+        ...userMessageId ? { id: userMessageId } : {},
+        ...isSteer ? { steer: true } : {}
+      });
     }
     for (const ev of events) {
       const type = ev.data.type || ev.event;
@@ -1890,6 +1903,64 @@ var ChatSession = class {
   }
 };
 
+// src/restore-plan.ts
+function planRestore(args) {
+  const { completedJobs, userMessages } = args;
+  const byId = /* @__PURE__ */ new Map();
+  userMessages.forEach((m, i) => {
+    if (m.id) byId.set(m.id, i);
+  });
+  const linkOf = (j) => j.message_id ? byId.get(j.message_id) : void 0;
+  const positional = (jobs, msgs) => jobs.map((job, i) => ({
+    kind: "turn",
+    jobId: job.job_id,
+    content: msgs[i]?.content,
+    messageId: msgs[i]?.id
+  }));
+  const firstLinked = completedJobs.findIndex((j) => linkOf(j) !== void 0);
+  if (firstLinked === -1) {
+    return positional(completedJobs, userMessages);
+  }
+  const cutover = linkOf(completedJobs[firstLinked]);
+  const steps = positional(
+    completedJobs.slice(0, firstLinked),
+    userMessages.slice(0, cutover)
+  );
+  let cursor = cutover;
+  const isSteer = (m) => !!m?.id && !completedJobs.some((j) => j.message_id === m.id);
+  const drainTo = (stopAt) => {
+    while (cursor < stopAt) {
+      const m = userMessages[cursor++];
+      if (isSteer(m)) {
+        steps.push({ kind: "steer", content: m.content, messageId: m.id });
+      }
+    }
+    cursor = stopAt + 1;
+  };
+  for (const job of completedJobs.slice(firstLinked)) {
+    const at = linkOf(job);
+    if (at !== void 0) {
+      drainTo(at);
+      const prompt = userMessages[at];
+      steps.push({
+        kind: "turn",
+        jobId: job.job_id,
+        content: prompt.content,
+        messageId: prompt.id
+      });
+      continue;
+    }
+    steps.push({ kind: "turn", jobId: job.job_id });
+  }
+  for (let i = cursor; i < userMessages.length; i++) {
+    const m = userMessages[i];
+    if (isSteer(m)) {
+      steps.push({ kind: "steer", content: m.content, messageId: m.id });
+    }
+  }
+  return steps;
+}
+
 // src/types.ts
 var ChatEventType = {
   // Connection lifecycle (SDK-local, not wire)
@@ -2158,16 +2229,40 @@ var StreamManager = class {
         const userMessages = this.session.messages.filter(
           (m) => m.role === "user"
         );
+        const plan = planRestore({
+          completedJobs: completedJobs.map((j) => ({
+            job_id: j.job_id,
+            message_id: j.message_id
+          })),
+          userMessages: userMessages.map((m) => ({
+            id: m.id,
+            content: m.content
+          }))
+        });
         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 eventsByJobId = new Map(
+          completedJobs.map((job, i) => [job.job_id, eventLists[i] ?? []])
+        );
+        for (const step of plan) {
+          if (step.kind === "steer") {
+            this.session.replayTurn(
+              conversationId,
+              [],
+              step.content,
+              step.messageId,
+              true
+            );
+            continue;
+          }
           this.session.replayTurn(
             conversationId,
-            eventLists[i] ?? [],
-            userMessages[i]?.content
+            eventsByJobId.get(step.jobId) ?? [],
+            step.content,
+            step.messageId
           );
         }
         if (completedJobs.length > 0) {