@astralform/js 7.2.0 → 7.4.0

package/dist/index.d.ts

@@ -563,6 +563,12 @@ interface Conversation {
     messageCount: number;
     createdAt: string;
     updatedAt: string;
+    /**
+     * The project this task belongs to (`owner/repo`), or `null` for an ordinary
+     * conversation. Set on the first turn and immutable after. Absent (rather than
+     * null) from an Astralform older than 0.70.0.
+     */
+    repository?: string | null;
 }
 interface Message {
     id: string;
@@ -612,6 +618,18 @@ interface AgentInfo {
     isOrchestrator: boolean;
     isEnabled: boolean;
     avatarUrl?: string;
+    /**
+     * What the agent is for. A client shows Projects and Tasks only for `"code"`.
+     * Absent on Astralform older than 0.70.0 — treat that as `"chat"`, which is
+     * also the server's default.
+     *
+     * It is a property of the WORKSPACE, not of a persona: `GET /v1/agents` selects
+     * the workspace row itself and returns exactly one entry, so the mode is
+     * `agents[0].mode` rather than something that varies across the list. The
+     * workspace picker (`listAgents`) does not carry it, so a client learns an
+     * agent's mode after opening it.
+     */
+    mode?: "chat" | "code";
 }
 interface TeamSummary {
     id: string;
@@ -738,6 +756,15 @@ interface ModelChoiceOptions {
 interface ChatStreamRequest {
     message?: string;
     conversation_id?: string;
+    /**
+     * Which project (GitHub repository, `owner/repo`) this task belongs to.
+     *
+     * Required on the FIRST turn of a conversation on a code-mode agent and
+     * ignored afterwards — a task is bound to one repository for life, so a
+     * different repository means a new task. Chat-mode agents ignore it entirely.
+     * Astralform >= 0.70.0.
+     */
+    repository?: string;
     mcp_manifest?: ToolDefinition[];
     enabled_mcp?: string[];
     continue_from_message?: string;
@@ -762,6 +789,37 @@ interface ChatStreamRequest {
     reasoning_effort?: ReasoningEffort;
     temperature?: number;
 }
+/** One repository an app user works with on a code-mode agent. */
+interface CodeProject {
+    repoFullName: string;
+    addedAt: string;
+}
+/** A repository the workspace's GitHub installations cover. */
+interface AvailableRepository {
+    fullName: string;
+    private: boolean;
+}
+/**
+ * What an app user may add, and why the list might be empty.
+ *
+ * `state` separates the three empty cases a picker must not conflate:
+ * `ok` (connected, covers nothing new), `not_installed` (no installation to ask)
+ * and `unavailable` (GitHub could not be reached — try again, do not tell the
+ * user they have no repositories). `totalCount` is the installations' raw total
+ * BEFORE already-added projects are subtracted, so it is not the list's length.
+ */
+interface AvailableRepositories {
+    state: "ok" | "unavailable" | "not_installed";
+    repositories: AvailableRepository[];
+    totalCount: number;
+    /**
+     * At least one of the workspace's GitHub installations could not be
+     * enumerated, so the list is missing whatever that one covers. It is NOT
+     * pagination — there is no next page to ask for. A picker should say some
+     * repositories may be missing rather than present the list as complete.
+     */
+    partial: boolean;
+}
 interface ToolResultRequest {
     conversation_id: string;
     message_id: string;
@@ -822,7 +880,118 @@ interface StreamJobSSEOptions {
     headers: Record<string, string>;
     signal?: AbortSignal;
     fetchFn: typeof globalThis.fetch;
+    /** Request method; defaults to GET (the job event stream). */
+    method?: "GET" | "POST";
+    /** A JSON-serialised body for POST streams (the voice polish stream). */
+    body?: string;
 }
+/**
+ * The styles a transcript can be shaped into, as the server names them.
+ * `raw` never calls the model — the transcript is used as recognized.
+ */
+declare const VOICE_POLISH_MODES: readonly ["raw", "light", "structured", "formal"];
+type VoicePolishMode = (typeof VOICE_POLISH_MODES)[number];
+/** A mode that calls the polish model — every mode except `raw`. */
+type VoiceLLMMode = Exclude<VoicePolishMode, "raw">;
+/** Whether `value` is one of the four modes this SDK version knows. */
+declare function isVoicePolishMode(value: unknown): value is VoicePolishMode;
+/**
+ * Whether `mode` may be passed to `streamVoicePolish` — the check to make on
+ * `VoiceConfig.defaultMode`, which can be `raw`.
+ */
+declare function isVoiceLLMMode(mode: VoicePolishMode): mode is VoiceLLMMode;
+/**
+ * What a client needs to run the microphone for an agent, from
+ * `GET /v1/voice/config`. Deliberately carries no provider or model names.
+ */
+interface VoiceConfig {
+    enabled: boolean;
+    /**
+     * The styles the client may request, as the server names them. Kept as
+     * plain strings so a mode this SDK version does not know still reaches a
+     * picker; `isVoicePolishMode` narrows one.
+     */
+    modes: string[];
+    /**
+     * The style to use when the user has not picked one. Falls back to
+     * `structured` when the server names a mode this SDK does not know. Can be
+     * `raw`, which `streamVoicePolish` refuses — check it with `isVoiceLLMMode`
+     * (or compare against `"raw"`) before polishing.
+     */
+    defaultMode: VoicePolishMode;
+    /** In tap-to-talk mode, the pause that ends a recording. */
+    silenceAutoStopSeconds: number;
+    /** Send the message as soon as the result is ready. */
+    autoSend: boolean;
+    maxRecordingSeconds: number;
+    /**
+     * Whether the configured recognizer emits live partial transcripts. Batch
+     * (Whisper-style) providers do not; they transcribe on stop.
+     */
+    supportsStreaming: boolean;
+    /**
+     * The project vocabulary, for display. The server applies it to every
+     * transcription and polish itself; `transcribeVoice({ hotwords })` and
+     * `VoicePolishRequest.hotwords` carry only the user's own words, which the
+     * server merges after these.
+     */
+    hotwords: string[];
+}
+/** One recording turned into text, from `POST /v1/voice/transcriptions`. */
+interface VoiceTranscript {
+    text: string;
+    language: string | null;
+    /** Length of the submitted audio, when the WAV header said so. */
+    durationMs: number | null;
+    /** Time the provider took. */
+    asrMs: number;
+}
+interface VoiceTranscribeOptions {
+    /** File name sent with the recording; defaults to `recording.wav`. */
+    filename?: string;
+    /**
+     * The user's own vocabulary — not the project's, which the server already
+     * holds and merges in first. Sent comma-separated, so a word cannot itself
+     * contain a comma.
+     */
+    hotwords?: string[];
+    /** ISO 639-1 hint; omit for auto-detection. */
+    language?: string;
+    /**
+     * Abort the upload. No client-side deadline applies to this call (a
+     * recording can run to `maxRecordingSeconds` and the upload with it), so
+     * this is the only way to give up on a stalled one; the promise rejects
+     * with the abort reason (the runtime's `AbortError`, or what was passed to
+     * `abort(reason)`).
+     */
+    signal?: AbortSignal;
+}
+interface VoicePolishRequest {
+    text: string;
+    /** One of the LLM modes; `raw` is refused by the server. */
+    mode: VoiceLLMMode;
+    /** The user's own vocabulary; the server merges it after the project's. */
+    hotwords?: string[];
+}
+/**
+ * One frame of the polish stream. `delta` text arrives in order; `done.text`
+ * is authoritative (the cleaned full output, which can differ from the
+ * concatenated deltas). On `error` keep the raw transcript; `partial` is what
+ * was streamed before the failure.
+ */
+type VoicePolishEvent = {
+    type: "delta";
+    text: string;
+} | {
+    type: "done";
+    text: string;
+    polishMs: number;
+} | {
+    type: "error";
+    reason: string;
+    partial: string;
+    detail?: string;
+};
 interface ChatStreamEvent {
     event: string;
     data: string;
@@ -892,6 +1061,15 @@ interface SendOptions$1 extends ModelChoiceOptions {
      * it's complete. Omit for a normal turn.
      */
     goal?: string;
+    /**
+     * The project this task belongs to (`owner/repo`), on a code-mode agent.
+     *
+     * Send it on the turn that STARTS a task; the binding is write-once, so later
+     * turns can omit it (sending a different one is refused). A first turn without
+     * it on a code-mode agent is refused too — the run needs a repository before it
+     * can hold a credential scoped to one. Astralform >= 0.70.0.
+     */
+    repository?: string;
 }
 /**
  * A selectable model for one of the team's connected providers, from
@@ -1039,7 +1217,16 @@ declare class AstralformClient {
         ollama_connected: boolean;
     }>;
     getAgentStatus(): Promise<AgentStatus>;
-    getConversations(limit?: number, offset?: number): Promise<Conversation[]>;
+    /**
+     * 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.
+     */
+    getConversations(limit?: number, offset?: number, options?: {
+        repository?: string;
+    }): Promise<Conversation[]>;
     getMessages(conversationId: string): Promise<Message[]>;
     /**
      * Replace the title the server generated from the conversation's first turn.
@@ -1087,6 +1274,34 @@ declare class AstralformClient {
     revokeToolPermission(id: string): Promise<void>;
     private mapAsset;
     uploadFile(conversationId: string, file: Blob, filename?: string): Promise<ConversationAsset>;
+    /** The agent's voice-input defaults (`GET /v1/voice/config`). */
+    getVoiceConfig(): Promise<VoiceConfig>;
+    /**
+     * 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)`.
+     */
+    transcribeVoice(audio: Blob, options?: VoiceTranscribeOptions): Promise<VoiceTranscript>;
+    /**
+     * 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.
+     */
+    streamVoicePolish(request: VoicePolishRequest, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<VoicePolishEvent>;
     listUploads(conversationId: string): Promise<ConversationAsset[]>;
     listOutputs(conversationId: string): Promise<ConversationAsset[]>;
     listTeams(): Promise<TeamSummary[]>;
@@ -1096,6 +1311,39 @@ declare class AstralformClient {
      * `getAgents()`, which lists the AI personas inside the active agent.
      */
     listAgents(teamId: string): Promise<TeamAgentSummary[]>;
+    /**
+     * 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.
+     */
+    readonly code: {
+        projects: {
+            /** This user's projects on the active agent, oldest first. */
+            list: () => Promise<CodeProject[]>;
+            /**
+             * 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: () => Promise<AvailableRepositories>;
+            /**
+             * 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: (repoFullName: string) => Promise<CodeProject>;
+            /**
+             * Remove a project. Tasks already bound to that repository keep their
+             * binding — they simply stop grouping under it.
+             */
+            remove: (owner: string, repo: string) => Promise<void>;
+        };
+    };
     createJob(request: ChatStreamRequest): Promise<JobCreateResponse>;
     streamJobEvents(jobId: string, afterSeq?: number, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
     cancelJob(jobId: string): Promise<void>;
@@ -1104,6 +1352,14 @@ declare class AstralformClient {
     getActiveJob(conversationId: string): Promise<ActiveJob>;
     listJobs(conversationId: string): Promise<JobSummary[]>;
 }
+/**
+ * Decode one SSE frame of `POST /v1/voice/polish`; null for frames the
+ * client does not act on (pings, unknown events).
+ */
+declare function parseVoicePolishFrame(frame: {
+    event: string;
+    data: string;
+}): VoicePolishEvent | null;
 
 /**
  * Minimal adapter contract. Frontends extend this with a `render()`
@@ -1532,7 +1788,8 @@ declare class StreamAbortedError extends AstralformError {
 declare function generateId(): string;
 
 /**
- * GET-based SSE stream for job events.
+ * SSE stream reader. GET for the job event stream (the default); POST with a
+ * JSON body for the voice polish stream. The frame parser is the same.
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
@@ -1855,4 +2112,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-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 EffortRung, 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 NoteUpdatePayload, type PlanUpdatePayload, 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 ThinkingDescriptor, type ThinkingRungOption, 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 AvailableRepositories, type AvailableRepository, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, type CodeProject, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EffortRung, 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 NoteUpdatePayload, type PlanUpdatePayload, 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 ThinkingDescriptor, type ThinkingRungOption, 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, VOICE_POLISH_MODES, type VoiceConfig, type VoiceLLMMode, type VoicePolishEvent, type VoicePolishMode, type VoicePolishRequest, type VoiceTranscribeOptions, type VoiceTranscript, 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, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };