@astralform/js 7.2.0 → 7.4.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;
@@ -333,6 +389,69 @@ function isApiKeyConfig(config) {
 }
 var AstralformClient = class {
   constructor(config) {
+    // --- Code mode: the app user's projects ---
+    /**
+     * 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.
+     */
+    this.code = {
+      projects: {
+        /** This user's projects on the active agent, oldest first. */
+        list: async () => {
+          const raw = await this.get(
+            "/v1/code/projects"
+          );
+          return raw.map((p) => camelizeKeys(p));
+        },
+        /**
+         * What the workspace's GitHub installations cover, minus what this user
+         * has already added. Read `state` before the list: an empty `repositories`
+         * means something different in each of its three values.
+         */
+        available: async () => {
+          const raw = await this.get("/v1/code/projects/available");
+          return {
+            state: raw.state,
+            repositories: (raw.repositories ?? []).map((r) => ({
+              fullName: r.full_name,
+              private: r.private
+            })),
+            // Defaulted like its neighbours: the `unavailable` branch has nothing
+            // to count, and an absent field behind a `number` type prints
+            // "undefined" in a picker rather than a number.
+            totalCount: raw.total_count ?? 0,
+            partial: raw.partial ?? false
+          };
+        },
+        /**
+         * Add a repository. The server checks it against the workspace's own
+         * installations and answers a repository it cannot reach the same way it
+         * answers one owned by someone else — deliberately, so this call cannot be
+         * used to discover which organisations use Astralform.
+         */
+        add: async (repoFullName) => {
+          const raw = await this.post(
+            "/v1/code/projects",
+            { repo_full_name: repoFullName }
+          );
+          return camelizeKeys(raw);
+        },
+        /**
+         * Remove a project. Tasks already bound to that repository keep their
+         * binding — they simply stop grouping under it.
+         */
+        remove: async (owner, repo) => {
+          await this.del(
+            `/v1/code/projects/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`
+          );
+        }
+      }
+    };
     if (isApiKeyConfig(config)) {
       if (!config.apiKey || typeof config.apiKey !== "string") {
         throw new Error("apiKey is required and must be a non-empty string");
@@ -573,10 +692,18 @@ var AstralformClient = class {
       }
     };
   }
-  async getConversations(limit = 50, offset = 0) {
+  /**
+   * 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.
+   */
+  async getConversations(limit = 50, offset = 0, options) {
     const safeLimit = Math.max(1, Math.min(200, Math.floor(Number(limit))));
     const safeOffset = Math.max(0, Math.floor(Number(offset)));
-    const raw = await this.get(`/v1/conversations?limit=${safeLimit}&offset=${safeOffset}`);
+    const filter = options?.repository ? `&repository=${encodeURIComponent(options.repository)}` : "";
+    const raw = await this.get(`/v1/conversations?limit=${safeLimit}&offset=${safeOffset}${filter}`);
     return raw.map((c) => camelizeKeys(c));
   }
   async getMessages(conversationId) {
@@ -736,6 +863,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 +1037,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 {
@@ -1554,6 +1798,9 @@ 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
+      // server-side: sent on every turn, honoured on the first.
+      repository: options?.repository,
       // Per-request model choice (client-side model selection).
       provider: options?.provider,
       model: options?.model,
@@ -2306,50 +2553,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) {
@@ -3004,10 +3207,14 @@ function parseEmbeddedResource(value) {
   StreamAbortedError,
   StreamManager,
   ToolRegistry,
+  VOICE_POLISH_MODES,
   generateId,
   isEmbeddedResource,
+  isVoiceLLMMode,
+  isVoicePolishMode,
   mapSseToChat,
   parseEmbeddedResource,
+  parseVoicePolishFrame,
   replayEvents,
   streamJobSSE,
   translateDelta