@stackbone/sdk 0.1.0-alpha.5 → 0.1.0-alpha.6

package/index.d.cts

@@ -1,6 +1,6 @@
 import { AgentConnectionListResponse, InvokeConnectorActionResponse, PublishJobResponse, ScheduleJobResponse, UnscheduleJobResponse, ListSchedulesResponse, ContractResponse } from '@stackbone/validators';
-import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { Sql } from 'postgres';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { IngestJobWriter, IngestRequest, IngestResponse, RagIngestProgress, DeleteOptions, DeleteResponse, RetrieveRequest, RetrieveHit, ChunkOptions, ParseInput, ParseOptions } from '@stackbone/rag-core';
 export { ChunkOptions, ChunkStrategy, DeleteOptions, DeleteResponse, IngestChunk, IngestRequest, IngestRequestAutoEmbed, IngestRequestPrecomputed, IngestResponse, ParseInput, ParseOptions, RagIngestProgress, RetrieveHit, RetrieveRequest, RetrieveRequestAutoEmbed, RetrieveRequestPrecomputed } from '@stackbone/rag-core';
 import OpenAI from 'openai';
@@ -77,7 +77,7 @@ interface ClientConfig {
      * RAG-related defaults parsed from `agent.yaml.rag` by the CLI/orchestrator
      * and forwarded here. The SDK never reads `agent.yaml` itself — keeping
      * filesystem ownership in the CLI. Defaults follow ADR
-     * `2026-05-10-rag-consolidation-on-client-database` (D2/D6).
+     * `2026-06-05-rag` (D2/D6).
      */
     rag?: {
         /**
@@ -483,6 +483,43 @@ declare class DatabaseModule {
     delete: DrizzleClient['delete'];
     execute: DrizzleClient['execute'];
     transaction: DrizzleClient['transaction'];
+    /**
+     * Cross-surface raw-SQL runner carrying the SAME cold-start resilience the
+     * query-builder verbs above get. Sibling agent-local surfaces (`approval`,
+     * `config`, `secrets`, `prompts`) that issue tagged-template queries over the
+     * shared postgres-js `Sql` MUST execute them through this instead of caching
+     * `shared().$client` once and calling it directly. Otherwise a dead pooled
+     * socket — Fly Machines suspending the Machine between invokes, or a
+     * WSL2/Docker localhost relay dropping an idle connection during a long LLM
+     * step — surfaces as an unretried `CONNECTION_ENDED`/`ECONNRESET`. That is
+     * exactly the asymmetry that let `client.approval.request` fail while the
+     * `client.database.insert` right before it recovered.
+     *
+     * `fn` receives a FRESH `$client` on each attempt, so the single retry runs
+     * against the rebuilt pool. Whole-operation granularity is replayed as a
+     * unit — pass a multi-statement `sql.begin(...)` transaction or a helper that
+     * fires several queries and the replay re-runs all of it; postgres-js never
+     * commits a half-applied tx, so that is safe. SQLSTATE application errors
+     * pass straight through without a retry. Like `shared()`/`raw()`, the
+     * contract gate is intentionally NOT consulted here — gating surfaces gate at
+     * their own call sites.
+     */
+    runShared<T>(fn: (sql: Sql) => Promise<T> | T): Promise<T>;
+    /**
+     * `Result`-shaped sibling of `runShared` for surfaces whose driver swallows
+     * the dead-socket error into a returned `Result.err.cause` instead of
+     * throwing it — today only `client.rag`, whose `RagPipeline` returns a
+     * `Result` rather than throwing. `attempt` runs once; if it comes back with a
+     * pool-terminated `cause`, the pool is rebuilt and `attempt` replays exactly
+     * once, then its result (success or the fresh error) is returned verbatim.
+     * The `Result` contract is preserved end to end: a still-dead socket on the
+     * replay surfaces as the surface's own `Result.err`, never as a raw throw.
+     */
+    runSharedResult<T extends {
+        error?: {
+            cause?: unknown;
+        } | null;
+    }>(attempt: () => Promise<T>): Promise<T>;
     /**
      * Canonical accessor for the **shared-handles pattern**. Returns the
      * process-wide Drizzle handle backing `client.database`. Cross-surface
@@ -949,7 +986,7 @@ interface IngestAsyncHandle {
  * Implementation note: `RagModule` is a thin facade over `RagPipeline`. The
  * pipeline owns parse → chunk → embed → persist; the facade resolves the
  * shared `client.database` pool, builds an `Embedder` on demand, and maps
- * configuration errors. See ADR `2026-05-10-rag-consolidation-on-client-database`.
+ * configuration errors. See ADR `2026-06-05-rag`.
  *
  * Connection ownership: this module never opens its own postgres pool. It
  * reaches the underlying `postgres-js` `Sql` through the **shared-handles
@@ -1738,6 +1775,22 @@ declare const createStructuredLogger: (opts?: StructuredLoggerOptions) => Logger
  *   - `logger` is a child of the wrapper's structured logger already
  *     bound to `invocationId` and `runId`, so the handler does not have to
  *     pass them on every line. The actual JSON format lands in F6.
+ *   - `stream` is present **only** when the caller requested a streamed reply
+ *     (an SSE `/invoke`). The handler pushes incremental output through it —
+ *     `delta(text)` for token-by-token text and `event(name, data?)` for a
+ *     named structured event — and the wrapper relays each onto the open
+ *     socket as it is produced. On a plain (buffered) invoke `stream` is
+ *     `undefined`, so a handler that wants to stream guards on it and falls
+ *     back to returning its `output` normally.
+ *   - `progress` / `step` are the **live run progress** helpers (distinct from
+ *     token streaming): they record `run_steps` rows on the run so the Studio
+ *     runs timeline fills in as the handler works. `progress(message, data?)` is
+ *     a coarse, point-in-time note; `step({ type, name })` opens a span and
+ *     returns a handle whose `.finish()` closes it with a duration. Both are
+ *     runtime-injected and fire-and-forget — they are wired to the install's
+ *     Postgres by the wrapper, are absent (no-op) when no run writer is mounted
+ *     (e.g. plain unit tests), and the wrapper throttles `progress` so a hot
+ *     loop cannot flood the run with notes.
  */
 interface InvokeContext<I extends z.ZodType> {
     input: z.infer<I>;
@@ -1746,7 +1799,76 @@ interface InvokeContext<I extends z.ZodType> {
     runId: string;
     client: StackboneClient;
     logger: Logger;
+    stream?: InvokeStream;
+    progress?: InvokeProgress;
+    step?: InvokeStepFn;
+}
+/**
+ * The streaming sink handed to a handler as `ctx.stream` when the caller asked
+ * for a streamed `/invoke`. Both methods are fire-and-forget — the handler
+ * emits, the wrapper relays — so neither returns a promise the handler must
+ * await.
+ */
+interface InvokeStream {
+    /** Emit an incremental chunk of text (e.g. a model token). */
+    delta(text: string): void;
+    /** Emit a named structured event with an optional JSON-serialisable payload. */
+    event(name: string, data?: unknown): void;
+}
+/**
+ * The closed set of step types `ctx.step` / `ctx.progress` may record. It
+ * mirrors the CHECK constraint on `stackbone_platform.run_steps.type`; an
+ * unknown type would be rejected by Postgres, so the contract enumerates the
+ * allowed values at the type layer too. `agent` is the catch-all a coarse
+ * `progress` note records under.
+ */
+type RunStepType = 'agent' | 'llm_call' | 'db_query' | 'http_fetch' | 'queue_publish' | 'hitl_pause' | 'tool_call' | 'rag_query' | 'storage_op';
+/**
+ * `ctx.progress` — a coarse, point-in-time note on the run, distinct from the
+ * token-level `ctx.stream`. The wrapper writes one `run_steps` row (type
+ * `agent`) per call, opened and closed in place, so it shows up immediately on
+ * the Studio timeline. Fire-and-forget: it returns nothing the handler must
+ * await, and the wrapper throttles calls to ~1/s so a hot loop cannot flood the
+ * run. `data` is an optional JSON-serialisable payload stored on the row.
+ */
+type InvokeProgress = (message: string, data?: unknown) => void;
+/** Opening descriptor for `ctx.step`. */
+interface StepOptions {
+    /** One of the canonical `run_steps` types; defaults to `agent` when omitted. */
+    type?: RunStepType;
+    /** Human-readable label for the step (the `run_steps.name` column). */
+    name: string;
+    /** Optional JSON-serialisable payload stored on the opened row. */
+    data?: unknown;
+}
+/** Closing descriptor for a `StepHandle.finish`. */
+interface StepFinishOptions {
+    /** Terminal status; defaults to `ok`. */
+    status?: 'ok' | 'error';
+    /** Failure detail recorded on the row when the step errored. */
+    error?: string;
+    /** Optional JSON-serialisable payload merged onto the row at finish. */
+    data?: unknown;
 }
+/**
+ * Handle returned by `ctx.step`. The handler calls `.finish()` when the work the
+ * step represents completes, which closes the open `run_steps` row with a
+ * duration and terminal status. Calling `.finish()` more than once is a no-op —
+ * the first close wins.
+ */
+interface StepHandle {
+    /** The id of the opened `run_steps` row (useful for nesting / correlation). */
+    readonly id: string;
+    /** Close the step. Idempotent: only the first call writes a terminal row. */
+    finish(options?: StepFinishOptions): void;
+}
+/**
+ * `ctx.step` — opens a span on the run and returns a handle to close it. The
+ * wrapper writes a `run_steps` row in the `running` state on open and updates it
+ * to `ok`/`error` with a duration on `.finish()`. Fire-and-forget like
+ * `ctx.progress`; absent (no-op handle) when no run writer is mounted.
+ */
+type InvokeStepFn = (options: StepOptions) => StepHandle;
 /**
  * The synchronous `invoke` capability. Mirrors the wrapper's three HTTP verbs
  * (`/invoke`, `/health`, `/schema`): `invoke` is the only request path, its
@@ -2120,4 +2242,4 @@ interface JsonSchemaDocument {
  */
 declare const analyzeAgentSchemas: (pair: AgentSchemaPair) => SchemaIntrospectionResult;
 
-export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type AnyCapability, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ClientConfig, type CompilePromptResult, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type InstallConsoleCaptureOptions, type InvocationContext, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeOptions, type InvokeRequest, type InvokeResponse, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LoadSystemSecretsArgs, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RESERVED_HANDLER_NAMES, RUN_ID_HEADER, type ReservedErrorCode, type Result, STORED_TO_SDK_ENV, type ScheduleRequest, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithInvocationContext };
+export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type AnyCapability, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ClientConfig, type CompilePromptResult, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type InstallConsoleCaptureOptions, type InvocationContext, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeOptions, type InvokeProgress, type InvokeRequest, type InvokeResponse, type InvokeStepFn, type InvokeStream, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LoadSystemSecretsArgs, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RESERVED_HANDLER_NAMES, RUN_ID_HEADER, type ReservedErrorCode, type Result, type RunStepType, STORED_TO_SDK_ENV, type ScheduleRequest, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StepFinishOptions, type StepHandle, type StepOptions, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithInvocationContext };

package/index.d.ts

@@ -1,6 +1,6 @@
 import { AgentConnectionListResponse, InvokeConnectorActionResponse, PublishJobResponse, ScheduleJobResponse, UnscheduleJobResponse, ListSchedulesResponse, ContractResponse } from '@stackbone/validators';
-import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { Sql } from 'postgres';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { IngestJobWriter, IngestRequest, IngestResponse, RagIngestProgress, DeleteOptions, DeleteResponse, RetrieveRequest, RetrieveHit, ChunkOptions, ParseInput, ParseOptions } from '@stackbone/rag-core';
 export { ChunkOptions, ChunkStrategy, DeleteOptions, DeleteResponse, IngestChunk, IngestRequest, IngestRequestAutoEmbed, IngestRequestPrecomputed, IngestResponse, ParseInput, ParseOptions, RagIngestProgress, RetrieveHit, RetrieveRequest, RetrieveRequestAutoEmbed, RetrieveRequestPrecomputed } from '@stackbone/rag-core';
 import OpenAI from 'openai';
@@ -77,7 +77,7 @@ interface ClientConfig {
      * RAG-related defaults parsed from `agent.yaml.rag` by the CLI/orchestrator
      * and forwarded here. The SDK never reads `agent.yaml` itself — keeping
      * filesystem ownership in the CLI. Defaults follow ADR
-     * `2026-05-10-rag-consolidation-on-client-database` (D2/D6).
+     * `2026-06-05-rag` (D2/D6).
      */
     rag?: {
         /**
@@ -483,6 +483,43 @@ declare class DatabaseModule {
     delete: DrizzleClient['delete'];
     execute: DrizzleClient['execute'];
     transaction: DrizzleClient['transaction'];
+    /**
+     * Cross-surface raw-SQL runner carrying the SAME cold-start resilience the
+     * query-builder verbs above get. Sibling agent-local surfaces (`approval`,
+     * `config`, `secrets`, `prompts`) that issue tagged-template queries over the
+     * shared postgres-js `Sql` MUST execute them through this instead of caching
+     * `shared().$client` once and calling it directly. Otherwise a dead pooled
+     * socket — Fly Machines suspending the Machine between invokes, or a
+     * WSL2/Docker localhost relay dropping an idle connection during a long LLM
+     * step — surfaces as an unretried `CONNECTION_ENDED`/`ECONNRESET`. That is
+     * exactly the asymmetry that let `client.approval.request` fail while the
+     * `client.database.insert` right before it recovered.
+     *
+     * `fn` receives a FRESH `$client` on each attempt, so the single retry runs
+     * against the rebuilt pool. Whole-operation granularity is replayed as a
+     * unit — pass a multi-statement `sql.begin(...)` transaction or a helper that
+     * fires several queries and the replay re-runs all of it; postgres-js never
+     * commits a half-applied tx, so that is safe. SQLSTATE application errors
+     * pass straight through without a retry. Like `shared()`/`raw()`, the
+     * contract gate is intentionally NOT consulted here — gating surfaces gate at
+     * their own call sites.
+     */
+    runShared<T>(fn: (sql: Sql) => Promise<T> | T): Promise<T>;
+    /**
+     * `Result`-shaped sibling of `runShared` for surfaces whose driver swallows
+     * the dead-socket error into a returned `Result.err.cause` instead of
+     * throwing it — today only `client.rag`, whose `RagPipeline` returns a
+     * `Result` rather than throwing. `attempt` runs once; if it comes back with a
+     * pool-terminated `cause`, the pool is rebuilt and `attempt` replays exactly
+     * once, then its result (success or the fresh error) is returned verbatim.
+     * The `Result` contract is preserved end to end: a still-dead socket on the
+     * replay surfaces as the surface's own `Result.err`, never as a raw throw.
+     */
+    runSharedResult<T extends {
+        error?: {
+            cause?: unknown;
+        } | null;
+    }>(attempt: () => Promise<T>): Promise<T>;
     /**
      * Canonical accessor for the **shared-handles pattern**. Returns the
      * process-wide Drizzle handle backing `client.database`. Cross-surface
@@ -949,7 +986,7 @@ interface IngestAsyncHandle {
  * Implementation note: `RagModule` is a thin facade over `RagPipeline`. The
  * pipeline owns parse → chunk → embed → persist; the facade resolves the
  * shared `client.database` pool, builds an `Embedder` on demand, and maps
- * configuration errors. See ADR `2026-05-10-rag-consolidation-on-client-database`.
+ * configuration errors. See ADR `2026-06-05-rag`.
  *
  * Connection ownership: this module never opens its own postgres pool. It
  * reaches the underlying `postgres-js` `Sql` through the **shared-handles
@@ -1738,6 +1775,22 @@ declare const createStructuredLogger: (opts?: StructuredLoggerOptions) => Logger
  *   - `logger` is a child of the wrapper's structured logger already
  *     bound to `invocationId` and `runId`, so the handler does not have to
  *     pass them on every line. The actual JSON format lands in F6.
+ *   - `stream` is present **only** when the caller requested a streamed reply
+ *     (an SSE `/invoke`). The handler pushes incremental output through it —
+ *     `delta(text)` for token-by-token text and `event(name, data?)` for a
+ *     named structured event — and the wrapper relays each onto the open
+ *     socket as it is produced. On a plain (buffered) invoke `stream` is
+ *     `undefined`, so a handler that wants to stream guards on it and falls
+ *     back to returning its `output` normally.
+ *   - `progress` / `step` are the **live run progress** helpers (distinct from
+ *     token streaming): they record `run_steps` rows on the run so the Studio
+ *     runs timeline fills in as the handler works. `progress(message, data?)` is
+ *     a coarse, point-in-time note; `step({ type, name })` opens a span and
+ *     returns a handle whose `.finish()` closes it with a duration. Both are
+ *     runtime-injected and fire-and-forget — they are wired to the install's
+ *     Postgres by the wrapper, are absent (no-op) when no run writer is mounted
+ *     (e.g. plain unit tests), and the wrapper throttles `progress` so a hot
+ *     loop cannot flood the run with notes.
  */
 interface InvokeContext<I extends z.ZodType> {
     input: z.infer<I>;
@@ -1746,7 +1799,76 @@ interface InvokeContext<I extends z.ZodType> {
     runId: string;
     client: StackboneClient;
     logger: Logger;
+    stream?: InvokeStream;
+    progress?: InvokeProgress;
+    step?: InvokeStepFn;
+}
+/**
+ * The streaming sink handed to a handler as `ctx.stream` when the caller asked
+ * for a streamed `/invoke`. Both methods are fire-and-forget — the handler
+ * emits, the wrapper relays — so neither returns a promise the handler must
+ * await.
+ */
+interface InvokeStream {
+    /** Emit an incremental chunk of text (e.g. a model token). */
+    delta(text: string): void;
+    /** Emit a named structured event with an optional JSON-serialisable payload. */
+    event(name: string, data?: unknown): void;
+}
+/**
+ * The closed set of step types `ctx.step` / `ctx.progress` may record. It
+ * mirrors the CHECK constraint on `stackbone_platform.run_steps.type`; an
+ * unknown type would be rejected by Postgres, so the contract enumerates the
+ * allowed values at the type layer too. `agent` is the catch-all a coarse
+ * `progress` note records under.
+ */
+type RunStepType = 'agent' | 'llm_call' | 'db_query' | 'http_fetch' | 'queue_publish' | 'hitl_pause' | 'tool_call' | 'rag_query' | 'storage_op';
+/**
+ * `ctx.progress` — a coarse, point-in-time note on the run, distinct from the
+ * token-level `ctx.stream`. The wrapper writes one `run_steps` row (type
+ * `agent`) per call, opened and closed in place, so it shows up immediately on
+ * the Studio timeline. Fire-and-forget: it returns nothing the handler must
+ * await, and the wrapper throttles calls to ~1/s so a hot loop cannot flood the
+ * run. `data` is an optional JSON-serialisable payload stored on the row.
+ */
+type InvokeProgress = (message: string, data?: unknown) => void;
+/** Opening descriptor for `ctx.step`. */
+interface StepOptions {
+    /** One of the canonical `run_steps` types; defaults to `agent` when omitted. */
+    type?: RunStepType;
+    /** Human-readable label for the step (the `run_steps.name` column). */
+    name: string;
+    /** Optional JSON-serialisable payload stored on the opened row. */
+    data?: unknown;
+}
+/** Closing descriptor for a `StepHandle.finish`. */
+interface StepFinishOptions {
+    /** Terminal status; defaults to `ok`. */
+    status?: 'ok' | 'error';
+    /** Failure detail recorded on the row when the step errored. */
+    error?: string;
+    /** Optional JSON-serialisable payload merged onto the row at finish. */
+    data?: unknown;
 }
+/**
+ * Handle returned by `ctx.step`. The handler calls `.finish()` when the work the
+ * step represents completes, which closes the open `run_steps` row with a
+ * duration and terminal status. Calling `.finish()` more than once is a no-op —
+ * the first close wins.
+ */
+interface StepHandle {
+    /** The id of the opened `run_steps` row (useful for nesting / correlation). */
+    readonly id: string;
+    /** Close the step. Idempotent: only the first call writes a terminal row. */
+    finish(options?: StepFinishOptions): void;
+}
+/**
+ * `ctx.step` — opens a span on the run and returns a handle to close it. The
+ * wrapper writes a `run_steps` row in the `running` state on open and updates it
+ * to `ok`/`error` with a duration on `.finish()`. Fire-and-forget like
+ * `ctx.progress`; absent (no-op handle) when no run writer is mounted.
+ */
+type InvokeStepFn = (options: StepOptions) => StepHandle;
 /**
  * The synchronous `invoke` capability. Mirrors the wrapper's three HTTP verbs
  * (`/invoke`, `/health`, `/schema`): `invoke` is the only request path, its
@@ -2120,4 +2242,4 @@ interface JsonSchemaDocument {
  */
 declare const analyzeAgentSchemas: (pair: AgentSchemaPair) => SchemaIntrospectionResult;
 
-export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type AnyCapability, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ClientConfig, type CompilePromptResult, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type InstallConsoleCaptureOptions, type InvocationContext, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeOptions, type InvokeRequest, type InvokeResponse, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LoadSystemSecretsArgs, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RESERVED_HANDLER_NAMES, RUN_ID_HEADER, type ReservedErrorCode, type Result, STORED_TO_SDK_ENV, type ScheduleRequest, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithInvocationContext };
+export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type AnyCapability, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ClientConfig, type CompilePromptResult, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type InstallConsoleCaptureOptions, type InvocationContext, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeOptions, type InvokeProgress, type InvokeRequest, type InvokeResponse, type InvokeStepFn, type InvokeStream, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LoadSystemSecretsArgs, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RESERVED_HANDLER_NAMES, RUN_ID_HEADER, type ReservedErrorCode, type Result, type RunStepType, STORED_TO_SDK_ENV, type ScheduleRequest, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StepFinishOptions, type StepHandle, type StepOptions, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithInvocationContext };