@astralform/js 7.1.1 → 7.3.0

package/dist/index.cjs

@@ -35,10 +35,14 @@ __export(index_exports, {
   StreamAbortedError: () => StreamAbortedError,
   StreamManager: () => StreamManager,
   ToolRegistry: () => ToolRegistry,
+  VOICE_POLISH_MODES: () => VOICE_POLISH_MODES,
   generateId: () => generateId,
   isEmbeddedResource: () => isEmbeddedResource,
+  isVoiceLLMMode: () => isVoiceLLMMode,
+  isVoicePolishMode: () => isVoicePolishMode,
   mapSseToChat: () => mapSseToChat,
   parseEmbeddedResource: () => parseEmbeddedResource,
+  parseVoicePolishFrame: () => parseVoicePolishFrame,
   replayEvents: () => replayEvents,
   streamJobSSE: () => streamJobSSE,
   translateDelta: () => translateDelta
@@ -241,12 +245,13 @@ function createRateLimitErrorFromHttp(response, rawText) {
 
 // src/streaming.ts
 async function* streamJobSSE(options) {
-  const { url, headers, signal, fetchFn } = options;
+  const { url, headers, signal, fetchFn, method = "GET", body } = options;
   let response;
   try {
     response = await fetchFn(url, {
-      method: "GET",
+      method,
       headers,
+      body,
       signal
     });
   } catch (err) {
@@ -308,6 +313,57 @@ async function* streamJobSSE(options) {
   }
 }
 
+// src/types.ts
+var ChatEventType = {
+  // Connection lifecycle (SDK-local, not wire)
+  Connected: "connected",
+  Disconnected: "disconnected",
+  // Turn lifecycle
+  MessageStart: "message_start",
+  MessageStop: "message_stop",
+  // Block lifecycle
+  BlockStart: "block_start",
+  BlockDelta: "block_delta",
+  BlockStop: "block_stop",
+  // Reliability
+  Stall: "stall",
+  Retry: "retry",
+  Error: "error",
+  Keepalive: "keepalive",
+  // Conversation-level (typed custom events)
+  UserMessage: "user_message",
+  TitleGenerated: "title_generated",
+  TodoUpdate: "todo_update",
+  PlanUpdate: "plan_update",
+  NoteUpdate: "note_update",
+  ContextUpdate: "context_update",
+  SubagentStart: "subagent_start",
+  SubagentStop: "subagent_stop",
+  ContextWarning: "context_warning",
+  MemoryRecall: "memory_recall",
+  MemoryUpdate: "memory_update",
+  DesktopStream: "desktop_stream",
+  AttachmentStaged: "attachment_staged",
+  WorkspaceReady: "workspace_ready",
+  AssetCreated: "asset_created",
+  ToolApprovalRequested: "tool_approval_requested",
+  ToolApprovalGranted: "tool_approval_granted",
+  ToolPermissionDenied: "tool_permission_denied",
+  ToolHarnessWarning: "tool_harness_warning",
+  UserUnavailable: "user_unavailable",
+  PromptSuggestion: "prompt_suggestion",
+  StateChanged: "state_changed",
+  // Generic fallthrough for unknown custom events
+  Custom: "custom"
+};
+var VOICE_POLISH_MODES = ["raw", "light", "structured", "formal"];
+function isVoicePolishMode(value) {
+  return typeof value === "string" && VOICE_POLISH_MODES.includes(value);
+}
+function isVoiceLLMMode(mode) {
+  return mode !== "raw";
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.astralform.ai";
 var DEFAULT_TIMEOUT_MS = 3e4;
@@ -736,6 +792,94 @@ var AstralformClient = class {
     const raw = await response.json();
     return this.mapAsset(raw);
   }
+  // --- Voice input ---
+  /** The agent's voice-input defaults (`GET /v1/voice/config`). */
+  async getVoiceConfig() {
+    const raw = await this.get("/v1/voice/config");
+    return {
+      enabled: Boolean(raw.enabled),
+      modes: raw.modes ?? [...VOICE_POLISH_MODES],
+      // A mode this SDK does not know must not reach a `switch` typed as
+      // `VoicePolishMode`; `structured` is the server's own default.
+      defaultMode: isVoicePolishMode(raw.default_mode) ? raw.default_mode : "structured",
+      silenceAutoStopSeconds: raw.silence_auto_stop_seconds ?? 2,
+      autoSend: raw.auto_send ?? true,
+      maxRecordingSeconds: raw.max_recording_seconds ?? 300,
+      supportsStreaming: Boolean(raw.supports_streaming),
+      hotwords: raw.hotwords ?? []
+    };
+  }
+  /**
+   * Transcribe one recording with the agent's configured speech-to-text
+   * provider (`POST /v1/voice/transcriptions`). 16 kHz mono 16-bit WAV is the
+   * reference format; anything the provider accepts works.
+   *
+   * Deliberately outside `withDeadline`: a recording can run to
+   * `VoiceConfig.maxRecordingSeconds`, so the 30 s default would cut real
+   * uploads off. Pass `options.signal` to give up on a stalled one; the
+   * promise then rejects with the abort reason — the runtime's `AbortError`,
+   * or whatever was passed to `abort(reason)`.
+   */
+  async transcribeVoice(audio, options = {}) {
+    const formData = new FormData();
+    formData.append("file", audio, options.filename ?? "recording.wav");
+    if (options.hotwords?.length) {
+      formData.append("hotwords", options.hotwords.join(", "));
+    }
+    if (options.language) {
+      formData.append("language", options.language);
+    }
+    const response = await this.fetchFn(`${this.baseURL}/v1/voice/transcriptions`, {
+      method: "POST",
+      headers: this.authHeaders,
+      body: formData,
+      signal: options.signal
+    }).catch((err) => {
+      if (options.signal?.aborted) {
+        throw err;
+      }
+      throw new ConnectionError(
+        err instanceof Error ? err.message : "Failed to connect"
+      );
+    });
+    await this.handleError(response);
+    const raw = await response.json();
+    return {
+      text: raw.text ?? "",
+      language: raw.language ?? null,
+      durationMs: raw.duration_ms ?? null,
+      asrMs: raw.asr_ms ?? 0
+    };
+  }
+  /**
+   * Stream the LLM rewrite of a transcript (`POST /v1/voice/polish`) as typed
+   * frames.
+   *
+   * Failures the server reports mid-stream arrive as an `error` frame, but
+   * the iteration itself can reject: aborting `signal` closes the connection
+   * (which cancels the model call upstream) and rejects with
+   * `StreamAbortedError`; a non-2xx open rejects with `AuthenticationError`,
+   * `RateLimitError` or `ServerError`; a network failure with
+   * `ConnectionError`. Wrap the `for await` accordingly.
+   */
+  async *streamVoicePolish(request, options = {}) {
+    const frames = streamJobSSE({
+      url: `${this.baseURL}/v1/voice/polish`,
+      headers: { ...this.headers, Accept: "text/event-stream" },
+      method: "POST",
+      body: JSON.stringify({
+        text: request.text,
+        mode: request.mode,
+        hotwords: request.hotwords ?? []
+      }),
+      signal: options.signal,
+      fetchFn: this.fetchFn
+    });
+    for await (const frame of frames) {
+      const event = parseVoicePolishFrame(frame);
+      if (event) yield event;
+    }
+  }
   async listUploads(conversationId) {
     const raw = await this.get(
       `/v1/conversations/${encodeURIComponent(conversationId)}/uploads`
@@ -822,6 +966,35 @@ var AstralformClient = class {
     }));
   }
 };
+function parseVoicePolishFrame(frame) {
+  let payload;
+  try {
+    const parsed = JSON.parse(frame.data);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    payload = parsed;
+  } catch {
+    return null;
+  }
+  switch (frame.event) {
+    case "delta":
+      return typeof payload.text === "string" ? { type: "delta", text: payload.text } : null;
+    case "done":
+      return typeof payload.text === "string" ? {
+        type: "done",
+        text: payload.text,
+        polishMs: payload.polish_ms ?? 0
+      } : null;
+    case "error":
+      return {
+        type: "error",
+        reason: payload.reason ?? "unknown",
+        partial: payload.partial ?? "",
+        ...typeof payload.detail === "string" ? { detail: payload.detail } : {}
+      };
+    default:
+      return null;
+  }
+}
 
 // src/storage.ts
 var InMemoryStorage = class {
@@ -2306,50 +2479,6 @@ function planRestore(args) {
   return steps;
 }
 
-// src/types.ts
-var ChatEventType = {
-  // Connection lifecycle (SDK-local, not wire)
-  Connected: "connected",
-  Disconnected: "disconnected",
-  // Turn lifecycle
-  MessageStart: "message_start",
-  MessageStop: "message_stop",
-  // Block lifecycle
-  BlockStart: "block_start",
-  BlockDelta: "block_delta",
-  BlockStop: "block_stop",
-  // Reliability
-  Stall: "stall",
-  Retry: "retry",
-  Error: "error",
-  Keepalive: "keepalive",
-  // Conversation-level (typed custom events)
-  UserMessage: "user_message",
-  TitleGenerated: "title_generated",
-  TodoUpdate: "todo_update",
-  PlanUpdate: "plan_update",
-  NoteUpdate: "note_update",
-  ContextUpdate: "context_update",
-  SubagentStart: "subagent_start",
-  SubagentStop: "subagent_stop",
-  ContextWarning: "context_warning",
-  MemoryRecall: "memory_recall",
-  MemoryUpdate: "memory_update",
-  DesktopStream: "desktop_stream",
-  AttachmentStaged: "attachment_staged",
-  WorkspaceReady: "workspace_ready",
-  AssetCreated: "asset_created",
-  ToolApprovalRequested: "tool_approval_requested",
-  ToolApprovalGranted: "tool_approval_granted",
-  ToolPermissionDenied: "tool_permission_denied",
-  ToolHarnessWarning: "tool_harness_warning",
-  UserUnavailable: "user_unavailable",
-  PromptSuggestion: "prompt_suggestion",
-  StateChanged: "state_changed",
-  // Generic fallthrough for unknown custom events
-  Custom: "custom"
-};
-
 // src/stream-manager.ts
 var StreamManager = class {
   constructor(session) {
@@ -2371,6 +2500,13 @@ var StreamManager = class {
      * its awaits. This can.
      */
     this.turnCounter = 0;
+    /**
+     * True while a `resync` is between its probe and its restore. Visibility and
+     * focus listeners can both fire for one return, and two overlapping resyncs
+     * would each detach the other's stream mid-flight — the second call must
+     * find the flag set and leave the first to converge.
+     */
+    this._resyncing = false;
     this.session = session;
     this.attach();
   }
@@ -2555,6 +2691,73 @@ var StreamManager = class {
       }
     }
   }
+  // ── Resync after the page sat in the background ───────────────
+  /**
+   * Re-attach to whatever the server says is live for the ACTIVE conversation.
+   *
+   * The reconnect machinery inside ``consumeEventStream`` only runs while a
+   * stream is being consumed — and a page suspended in the background (locked
+   * phone, app switch, hidden tab) can outlive it: timers are throttled or
+   * suspended, so the stall watchdog may never fire while hidden; the
+   * reconnect budget (``SSE_MAX_RECONNECTS``) can burn out in fail-fast
+   * attempts; and a 401 from a rotated access token ends the loop outright as
+   * non-retryable. What is left is a manager that believes a turn is streaming
+   * (or has given up on one that is still running) with nothing attached — and
+   * no navigation will ever fix it, because ``switchTo`` early-returns on the
+   * conversation it is already on.
+   *
+   * So the consumer calls this when the user COMES BACK
+   * (``visibilitychange → visible``, window ``focus``). One ``getActiveJob``
+   * probe, then:
+   *
+   *  - attached to exactly the job the server calls live → healthy. The stall
+   *    watchdog owns zombie recovery from here, now that timers run again.
+   *    No-op.
+   *  - anything else — attached to a job the server no longer calls live,
+   *    attached to nothing while a job runs, or idle with a live job another
+   *    tab/device started — → detach and re-run ``restore``, the same path a
+   *    conversation reopen takes, with all of its supersession and takeover
+   *    guards inherited.
+   *
+   * Skipped while a restore is already in flight (it is converging on server
+   * truth by itself) and while another resync holds the flag — see
+   * ``_resyncing``.
+   */
+  async resync() {
+    const conversationId = this._activeConversationId;
+    if (!conversationId) return;
+    if (this._state === "restoring" || this._resyncing) return;
+    this._resyncing = true;
+    const gen = this.generation;
+    const turn = this.turnCounter;
+    try {
+      let activeJobId = null;
+      try {
+        activeJobId = (await this.session.client.getActiveJob(conversationId)).jobId;
+      } catch {
+        return;
+      }
+      if (gen !== this.generation || this.turnStarted(turn)) return;
+      const attached = this._state === "streaming" || this.session.isStreaming;
+      if (activeJobId === null && !attached) return;
+      if (activeJobId !== null && this.session.isStreaming && this.session.currentJobId === activeJobId) {
+        return;
+      }
+      this.session.detach();
+      this.session.currentJobId = null;
+      this._state = "idle";
+      try {
+        await this.restore(conversationId, gen);
+      } catch {
+      }
+    } finally {
+      this._resyncing = false;
+      const restoring = "restoring";
+      if (gen === this.generation && this._state === restoring) {
+        this.settleIdle();
+      }
+    }
+  }
   // ── Create / rename / delete conversation ─────────────────────
   /**
    * Create a conversation and make it active.
@@ -2930,10 +3133,14 @@ function parseEmbeddedResource(value) {
   StreamAbortedError,
   StreamManager,
   ToolRegistry,
+  VOICE_POLISH_MODES,
   generateId,
   isEmbeddedResource,
+  isVoiceLLMMode,
+  isVoicePolishMode,
   mapSseToChat,
   parseEmbeddedResource,
+  parseVoicePolishFrame,
   replayEvents,
   streamJobSSE,
   translateDelta