@vellumai/plugin-api 0.10.11-dev.202607221445.f732ea2 → 0.10.11-dev.202607221520.024d846

package/index.d.ts

@@ -687,6 +687,9 @@ declare const AssistantConfigSchema: z.ZodObject<{
     rateLimit: z.ZodDefault<z.ZodObject<{
         maxRequestsPerMinute: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    apiRateLimit: z.ZodDefault<z.ZodObject<{
+        authenticatedMaxRequestsPerMinute: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     secretDetection: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         blockIngress: z.ZodDefault<z.ZodBoolean>;
@@ -1521,26 +1524,34 @@ declare const AvatarUpdatedEventSchema: z.ZodObject<{
     avatarPath: z.ZodString;
 }, z.core.$strip>;
 
-declare interface BackgroundToolCompleted {
-    type: "background_tool_completed";
-    id: string;
-    conversationId: string;
-    status: "completed" | "failed" | "cancelled";
-    exitCode?: number | null;
-    output?: string;
-    completedAt: number;
-}
+declare type BackgroundToolCompletedEvent = z.infer<typeof BackgroundToolCompletedEventSchema>;
 
-declare type _BackgroundToolsServerMessages = BackgroundToolStarted | BackgroundToolCompleted;
+declare const BackgroundToolCompletedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"background_tool_completed">;
+    id: z.ZodString;
+    conversationId: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        failed: "failed";
+        completed: "completed";
+    }>;
+    exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    output: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodNumber;
+}, z.core.$strip>;
 
-declare interface BackgroundToolStarted {
-    type: "background_tool_started";
-    id: string;
-    toolName: string;
-    conversationId: string;
-    command: string;
-    startedAt: number;
-}
+declare type _BackgroundToolsServerMessages = BackgroundToolStartedEvent | BackgroundToolCompletedEvent;
+
+declare type BackgroundToolStartedEvent = z.infer<typeof BackgroundToolStartedEventSchema>;
+
+declare const BackgroundToolStartedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"background_tool_started">;
+    id: z.ZodString;
+    toolName: z.ZodString;
+    conversationId: z.ZodString;
+    command: z.ZodString;
+    startedAt: z.ZodNumber;
+}, z.core.$strip>;
 
 /**
  * Media payload for an image or file content block. One unified type covers
@@ -4437,6 +4448,17 @@ declare const OpenPanelEventSchema: z.ZodObject<{
     surfaceId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 
+/**
+ * Open a streaming transcription session against the configured STT provider
+ * (`services.stt.provider`).
+ *
+ * Returns a live {@link StreamingTranscriber} the caller drives with
+ * `start` / `sendAudio` / `stop`, or `null` when no streaming session can be
+ * opened — the provider is unknown, has no streaming adapter, or is missing
+ * credentials.
+ */
+export declare function openTranscriptionSession(): Promise<StreamingTranscriber | null>;
+
 declare type OpenUrlEvent = z.infer<typeof OpenUrlEventSchema>;
 
 declare const OpenUrlEventSchema: z.ZodObject<{
@@ -5914,6 +5936,61 @@ declare interface StopInputContext {
     readonly exitReason: AgentLoopExitReason;
 }
 
+/**
+ * Daemon-hosted streaming transcriber contract.
+ *
+ * Implementations manage a persistent session that accepts audio chunks
+ * and emits partial/final transcript events. The runtime session
+ * orchestrator (PR 5) drives this interface from the gateway WebSocket
+ * path.
+ *
+ * Lifecycle:
+ * 1. Call {@link start} to open the provider session.
+ * 2. Feed audio chunks via {@link sendAudio}.
+ * 3. Optionally call {@link finalizeUtterance} between utterances to
+ *    flush buffered audio into finals while keeping the stream open.
+ * 4. Call {@link stop} when the client finishes recording.
+ * 5. The `onEvent` callback receives server events until `closed`.
+ */
+export declare interface StreamingTranscriber {
+    /** Which provider backs this transcriber. */
+    readonly providerId: SttProviderId;
+    /** Which runtime boundary this transcriber operates in. */
+    readonly boundaryId: "daemon-streaming";
+    /**
+     * Open the streaming session with the provider.
+     *
+     * Must be called once before {@link sendAudio}. Rejects if the
+     * provider session cannot be established.
+     */
+    start(onEvent: (event: SttStreamServerEvent) => void): Promise<void>;
+    /**
+     * Feed a chunk of audio into the streaming session.
+     *
+     * Callers must not call this before {@link start} resolves or after
+     * {@link stop} has been called.
+     */
+    sendAudio(audio: Buffer, mimeType: string): void;
+    /**
+     * Flush all buffered audio into final transcript(s) without closing
+     * the stream.
+     *
+     * Emits `final` event(s) for pending audio followed by one `finalized`
+     * event; the stream stays open for more audio. Optional — callers must
+     * feature-detect this method and fall back to {@link stop} (full
+     * teardown) when the provider does not support it.
+     */
+    finalizeUtterance?(): void;
+    /**
+     * Signal that the client has finished sending audio.
+     *
+     * The provider may emit additional final events after stop is called.
+     * The session is fully closed when the `onEvent` callback receives a
+     * `closed` event.
+     */
+    stop(): void;
+}
+
 /**
  * Coerce stored message content into a single human-readable text string,
  * dropping non-text blocks (images, tool calls, tool results, thinking,
@@ -5931,6 +6008,112 @@ declare interface StopInputContext {
  */
 export declare function stringifyMessageContent(stored: string | ContentBlock[]): string;
 
+/**
+ * Normalized error categories that callers can branch on without coupling to
+ * provider-specific error shapes or HTTP status codes.
+ */
+export declare type SttErrorCategory = 
+/** The provider rejected the request due to invalid or missing credentials. */
+"auth"
+/** The provider rate-limited the request. */
+| "rate-limit"
+/** The request or response timed out. */
+| "timeout"
+/** The audio payload was rejected (unsupported format, too large, etc.). */
+| "invalid-audio"
+/** Any other provider-side or network failure. */
+| "provider-error";
+
+/**
+ * Provider-agnostic speech-to-text domain types for daemon transcription.
+ *
+ * These types define the boundary between callers that need audio transcription
+ * and the concrete STT provider implementations. The goal is to let daemon
+ * callsites program against a single typed interface so that provider swaps are
+ * localized to the adapter layer.
+ *
+ * Two execution modes are supported:
+ * - **Batch** — a single audio buffer is sent and a final transcript returned.
+ * - **Streaming** — audio chunks are sent over a persistent session, and the
+ *   provider emits partial/final transcript events in real time.
+ */
+/**
+ * Canonical provider identifiers for daemon-hosted STT backends.
+ * Extend this union as new providers are integrated.
+ */
+export declare type SttProviderId = "openai-whisper" | "deepgram" | "google-gemini" | "xai" | "vellum";
+
+/** The streaming session has closed (no more events will be emitted). */
+export declare interface SttStreamServerClosedEvent {
+    readonly type: "closed";
+}
+
+/** An error occurred during streaming transcription. */
+export declare interface SttStreamServerErrorEvent {
+    readonly type: "error";
+    /** Normalized error category for caller branching. */
+    readonly category: SttErrorCategory;
+    /** Human-readable error description. */
+    readonly message: string;
+}
+
+/**
+ * Events that the daemon streaming session emits to the client.
+ *
+ * The discriminated `type` field allows clients to handle partial
+ * and final transcripts, errors, and session lifecycle signals in a
+ * type-safe manner.
+ */
+export declare type SttStreamServerEvent = SttStreamServerPartialEvent | SttStreamServerFinalEvent | SttStreamServerFinalizedEvent | SttStreamServerErrorEvent | SttStreamServerClosedEvent;
+
+/**
+ * A final (committed) transcript — this segment will not be revised.
+ */
+export declare interface SttStreamServerFinalEvent {
+    readonly type: "final";
+    /** Committed transcript text for a completed speech segment. */
+    readonly text: string;
+    readonly speakerLabel?: string;
+    /**
+     * Provider-emitted confidence score in [0, 1]. Undefined when the
+     * provider does not surface confidence on this chunk.
+     */
+    readonly confidence?: number;
+    /**
+     * True when this final is the flush response to
+     * {@link StreamingTranscriber.finalizeUtterance} — i.e. it commits audio
+     * that was buffered before the finalize request, not new speech.
+     * Undefined on ordinary finals and on providers without finalize.
+     */
+    readonly fromFinalize?: boolean;
+}
+
+/**
+ * All provider-buffered audio has been flushed into `final` event(s) in
+ * response to {@link StreamingTranscriber.finalizeUtterance}. Emitted
+ * exactly once per finalize request, after the flushed `final` event(s).
+ * The stream stays open and continues to accept audio.
+ */
+export declare interface SttStreamServerFinalizedEvent {
+    readonly type: "finalized";
+}
+
+/**
+ * A partial (interim) transcript — may be revised by subsequent
+ * partial or final events.
+ */
+export declare interface SttStreamServerPartialEvent {
+    readonly type: "partial";
+    /** Interim transcript text. May change with subsequent events. */
+    readonly text: string;
+    readonly speakerLabel?: string;
+    /**
+     * Provider-emitted confidence score in [0, 1]. Undefined when the
+     * provider does not surface confidence on interim chunks.
+     */
+    readonly confidence?: number;
+}
+
 declare interface SubagentDetailResponse {
     type: "subagent_detail_response";
     subagentId: string;
@@ -7180,136 +7363,78 @@ export declare interface WebSearchToolResultContent {
     content: unknown;
 }
 
-/**
- * Terminal push for a workflow run. Carries the final status, counts, token
- * usage, and a human-readable result/error summary the originating
- * conversation also receives via an agent wake.
- */
-declare interface WorkflowCompleted {
-    type: "workflow_completed";
-    runId: string;
-    /**
-     * Originating conversation id, when launched from one; lets `broadcastMessage`
-     * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
-     * for a conversationless run (e.g. a scheduled workflow), which broadcasts
-     * unscoped for raw SSE listeners and the DB record.
-     */
-    conversationId?: string;
-    status: WorkflowRunStatus;
-    agentsSpawned: number;
-    inputTokens: number;
-    outputTokens: number;
-    /** Human-readable result-or-error summary. */
-    summary?: string;
-}
+declare type WorkflowCompletedEvent = z.infer<typeof WorkflowCompletedEventSchema>;
 
-/**
- * A leaf agent within a workflow run has finished. `seq` matches the
- * corresponding `workflow_leaf_started` event.
- */
-declare interface WorkflowLeafFinished {
-    type: "workflow_leaf_finished";
-    runId: string;
-    /**
-     * Originating conversation id; lets `broadcastMessage` auto-scope +
-     * seq-stamp the event to the conversation's SSE stream.
-     */
-    conversationId: string;
-    seq: number;
-    status: "completed" | "failed";
-    /** Leaf label, for client display. */
-    label?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    /** Short summary of the leaf's result, for client display. */
-    resultSummary?: string;
-}
+declare const WorkflowCompletedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"workflow_completed">;
+    runId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        aborted: "aborted";
+        completed: "completed";
+        running: "running";
+        interrupted: "interrupted";
+        cap_exceeded: "cap_exceeded";
+    }>;
+    agentsSpawned: z.ZodNumber;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 
-/**
- * A leaf agent within a workflow run has started. `seq` orders leaves within
- * the run for stable client-side tree placement.
- */
-declare interface WorkflowLeafStarted {
-    type: "workflow_leaf_started";
-    runId: string;
-    /**
-     * Originating conversation id; lets `broadcastMessage` auto-scope +
-     * seq-stamp the event to the conversation's SSE stream.
-     */
-    conversationId: string;
-    seq: number;
-    /** Leaf label, for client display. */
-    label?: string;
-    /** Phase the leaf belongs to, when the workflow declares phases. */
-    phase?: string;
-    /** Short summary of the leaf's prompt, for client display. */
-    promptSummary?: string;
-}
+declare type WorkflowLeafFinishedEvent = z.infer<typeof WorkflowLeafFinishedEventSchema>;
 
-/**
- * Progress push for an in-flight workflow run. Maps the engine's
- * `onProgress` (`phase`/`log`) callback plus the current usage snapshot into a
- * single wire event. `phase` carries the latest `phase(title)`; `message`
- * carries the latest `log(msg)`; only one is set per emission.
- */
-declare interface WorkflowProgress {
-    type: "workflow_progress";
-    runId: string;
-    /**
-     * Originating conversation id, when launched from one; lets `broadcastMessage`
-     * auto-scope + seq-stamp the event to that conversation's SSE stream. Omitted
-     * for a conversationless run (e.g. a scheduled workflow), which broadcasts
-     * unscoped for raw SSE listeners and the DB record.
-     */
-    conversationId?: string;
-    /** Latest phase title, when this emission came from a `phase(...)` call. */
-    phase?: string;
-    /** Run label (the workflow's `meta.name`), for client display. */
-    label?: string;
-    /** Live agent count at emission time. */
-    agentsSpawned: number;
-    /** Latest log line, when this emission came from a `log(...)` call. */
-    message?: string;
-}
+declare const WorkflowLeafFinishedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"workflow_leaf_finished">;
+    runId: z.ZodString;
+    conversationId: z.ZodString;
+    seq: z.ZodNumber;
+    status: z.ZodEnum<{
+        failed: "failed";
+        completed: "completed";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    resultSummary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 
-/**
- * Typed persistence for the workflow orchestration engine.
- *
- * Two tables (created by migration 282):
- *
- * - `workflow_runs` — one row per orchestration run (a sandboxed script that
- *   spawns parallel leaf agents), tracking lifecycle status and token usage.
- * - `workflow_journal` — append-only `(run_id, seq)` log of every leaf call
- *   (agent / host function / nested workflow). On resume after a daemon
- *   restart, the engine replays cached results for the unchanged call prefix
- *   instead of re-spawning agents.
- *
- * This module is pure persistence — no `workflows` feature-flag logic. Callers
- * (the engine, a later PR) own gating.
- */
-declare type WorkflowRunStatus = "running" | "completed" | "failed" | "aborted" | "cap_exceeded" | "interrupted";
+declare type WorkflowLeafStartedEvent = z.infer<typeof WorkflowLeafStartedEventSchema>;
 
-declare type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted | WorkflowStarted | WorkflowLeafStarted | WorkflowLeafFinished;
+declare const WorkflowLeafStartedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"workflow_leaf_started">;
+    runId: z.ZodString;
+    conversationId: z.ZodString;
+    seq: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodString>;
+    promptSummary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 
-/**
- * A workflow run has started. Emitted once at launch, before any leaf events.
- */
-declare interface WorkflowStarted {
-    type: "workflow_started";
-    runId: string;
-    /**
-     * Originating conversation id; lets `broadcastMessage` auto-scope +
-     * seq-stamp the event to the conversation's SSE stream.
-     */
-    conversationId: string;
-    /**
-     * Tool-use id of the `skill_execute` block that launched this run, for
-     * anchoring the inline workflow card to the exact spawn tool call.
-     */
-    toolUseId?: string;
-    /** Run label (the workflow's `meta.name`), for client display. */
-    label?: string;
-}
+declare type WorkflowProgressEvent = z.infer<typeof WorkflowProgressEventSchema>;
+
+declare const WorkflowProgressEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"workflow_progress">;
+    runId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    agentsSpawned: z.ZodNumber;
+    phase: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+declare type _WorkflowsServerMessages = WorkflowProgressEvent | WorkflowCompletedEvent | WorkflowStartedEvent | WorkflowLeafStartedEvent | WorkflowLeafFinishedEvent;
+
+declare type WorkflowStartedEvent = z.infer<typeof WorkflowStartedEventSchema>;
+
+declare const WorkflowStartedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"workflow_started">;
+    runId: z.ZodString;
+    conversationId: z.ZodString;
+    toolUseId: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 
 declare interface WorkResultDiff {
     label?: string;

package/index.js

@@ -31,6 +31,7 @@ export const lastToolResultUserMessageIndex = api.lastToolResultUserMessageIndex
 export const listCatalogSkills = api.listCatalogSkills;
 export const listConversations = api.listConversations;
 export const listInstalledSkills = api.listInstalledSkills;
+export const openTranscriptionSession = api.openTranscriptionSession;
 export const parseMessageMetadata = api.parseMessageMetadata;
 export const quarantineRefusedExchanges = api.quarantineRefusedExchanges;
 export const resolveCredential = api.resolveCredential;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.11-dev.202607221445.f732ea2",
+  "version": "0.10.11-dev.202607221520.024d846",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",