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

package/index.d.cts

@@ -1,11 +1,14 @@
 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';
 import { ChatCompletionCreateParamsStreaming, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletion, EmbeddingCreateParams, CreateEmbeddingResponse, ChatCompletionMessageParam } from 'openai/resources';
 import { Stream } from 'openai/streaming';
+import { A as AgentName } from './workflow-scheduler-DXCNKDOS.cjs';
+export { b as AgentRegistry, S as ScheduledWorkflow, c as WorkflowScheduler, a as WorkflowStartHandle, d as WorkflowStarter, W as WorkflowTriggerOptions, g as getWorkflowScheduler, e as getWorkflowStarter, s as setWorkflowScheduler, f as setWorkflowStarter } from './workflow-scheduler-DXCNKDOS.cjs';
+import { a as ConnectionAccessor } from './call-connector-CYDw_yG5.cjs';
 import { S3Client } from '@aws-sdk/client-s3';
 import { z } from 'zod';
 export { z } from 'zod';
@@ -77,7 +80,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?: {
         /**
@@ -268,7 +271,9 @@ declare const SDK_ERROR_CODE_PREFIXES: {
      */
     readonly queues: readonly ["forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
     /**
-     * `client.connections` — the agent → control plane connectors proxy. Both
+     * `client.legacyConnections` — the agent → control plane connectors proxy
+     * (legacy connector model). The `connections_*` code prefix stays stable (it
+     * names the wire domain, not the client accessor). Both
      * methods (`list`, `invoke`) hit the `/api/v1/agent/connections/*` endpoints
      * over `HttpClient`, so the full status→domain remap (`connections_unauthorized`,
      * `connections_not_found`, `connections_unavailable`, …) is in play. The agent
@@ -483,6 +488,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
@@ -603,6 +645,23 @@ interface ApprovalRequestOptions<T = unknown> {
     /** Same `(topic, idempotencyKey)` returns the same `approvalId` instead of creating a new one. */
     idempotencyKey?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * The PROJECTED `runs.id` this approval belongs to, joined into the inbox so
+     * the pause appears against its run. Used by the workflow-HITL helper
+     * (`requestApproval`), which reads it from the invocation context (F5). Stays
+     * `NULL` for the legacy fire-and-forget agent-approval path. The column is a
+     * FK to `stackbone_platform.runs(id)` (`ON DELETE SET NULL`).
+     */
+    runId?: string;
+    /**
+     * The projected `run_steps.id` of the workflow step that requested this
+     * approval, anchoring the pause to the exact step (`requested_by_step_id`,
+     * A6). The workflow-HITL helper (`requestApproval`) reads it from the
+     * invocation context (F5); stays `NULL` when no step id is available (the
+     * common case today — see `InvocationContext.requestedByStepId`). The column
+     * is a FK to `stackbone_platform.run_steps(id)` (`ON DELETE SET NULL`).
+     */
+    requestedByStepId?: string;
 }
 interface ApprovalRequest {
     approvalId: string;
@@ -640,11 +699,13 @@ interface ApprovalListResult<T = unknown> {
  * `verify()` (local crypto — see `verify.ts`).
  *
  * The write populates only the columns the cloud `create()` used to set
- * (topic/payload/callback_url/idempotency_key/fallback/metadata/timeout_at;
- * `schema` was sourced from a DTO field the SDK options object does not carry,
- * so it stays NULL). `workspace_id`/`agent_id`/`run_id` stay NULL exactly as
- * they were on the control-plane path — the idempotency `ON CONFLICT` relies on
- * `workspace_id` being NULL with `NULLS NOT DISTINCT` (migration 0008).
+ * (topic/payload/callback_url/idempotency_key/fallback/metadata/timeout_at),
+ * plus `run_id` / `requested_by_step_id` when the workflow-HITL helper supplies
+ * them from the invocation context (F5/A6). `schema` was sourced from a DTO
+ * field the SDK options object does not carry, so it stays NULL.
+ * `workspace_id`/`agent_id` stay NULL exactly as they were on the control-plane
+ * path — the idempotency `ON CONFLICT` relies on `workspace_id` being NULL with
+ * `NULLS NOT DISTINCT` (migration 0008).
  */
 declare class ApprovalFacade {
     private readonly _resolved;
@@ -671,6 +732,38 @@ declare class ApprovalFacade {
     private sql;
 }
 
+/**
+ * Augmentable registry of the agent's typed config keys. By default it is
+ * empty, so `client.config` reads stay a loose `Record<string, unknown>`
+ * (today's behavior). Creators augment it from the generated ambient types
+ * (`.stackbone/config.d.ts`, derived from their `config.schema.ts`) so reads
+ * become strict:
+ *
+ *   declare module '@stackbone/sdk' {
+ *     interface ConfigRegistry {
+ *       reply_tone: 'formal' | 'casual';
+ *       max_retries: number;
+ *     }
+ *   }
+ *
+ * Once augmented, `client.config.get('reply_tone')` is typed `'formal' |
+ * 'casual'` and `get('unknownKey')` is a compile error. Mirrors the
+ * `QueueJobs` augmentable-interface pattern.
+ */
+interface ConfigRegistry {
+}
+
+/**
+ * The effective shape of the agent's config, derived from the augmentable
+ * `ConfigRegistry`. The tuple wrap (`[X] extends [never]`) defeats the
+ * conditional-type distributivity that a bare `keyof ConfigRegistry extends
+ * never` would trigger:
+ *
+ * - empty registry  -> `Record<string, unknown>` (today's loose behavior:
+ *   any key, value `unknown`);
+ * - augmented registry -> `ConfigRegistry` itself (strict keys + value types).
+ */
+type ConfigShape = [keyof ConfigRegistry] extends [never] ? Record<string, unknown> : ConfigRegistry;
 declare class ConfigFacade {
     private readonly _resolved;
     /** Lazy accessor for `client.database` — see `SecretsFacade`. */
@@ -678,14 +771,21 @@ declare class ConfigFacade {
     constructor(_resolved: ResolvedConfig, 
     /** Lazy accessor for `client.database` — see `SecretsFacade`. */
     _getDatabase: () => DatabaseModule);
-    get<T = unknown>(key: string): Promise<Result<T>>;
+    get<K extends keyof ConfigShape>(key: K): Promise<Result<ConfigShape[K]>>;
     /**
      * Keys absent from the agent's config come back as omissions in the
      * response — the returned map only contains entries the agent DB actually
      * has, so callers must access fields with `?.` (the return type is
      * `Partial<T>`).
      */
-    getMany<T extends Record<string, unknown> = Record<string, unknown>>(keys: string[]): Promise<Result<Partial<T>>>;
+    getMany<K extends keyof ConfigShape>(keys: K[]): Promise<Result<Partial<Pick<ConfigShape, K>>>>;
+    /**
+     * Returns the agent's entire config payload as one typed object. An
+     * absent/null `agent_config` row resolves to `ok({})` — an empty config is
+     * "no config set", consistent with the facade reading the singleton row.
+     * Reads stay an unvalidated SELECT (no AJV on the read path).
+     */
+    getAll(): Promise<Result<ConfigShape>>;
     private loadPayload;
     private sql;
 }
@@ -949,7 +1049,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
@@ -1098,6 +1198,109 @@ declare class SecretsFacade {
     private sql;
 }
 
+/**
+ * eve's serialized session cursor. Mirrors eve's nominal `SessionState`
+ * interface (`{ continuationToken?, sessionId?, streamIndex }`) so a value the
+ * creator reads from a real eve session is assignable to the lazy
+ * `session(state)` resume parameter. NOT a loose `Record` — eve's `SessionState`
+ * has a required `streamIndex`, and a `Record<string, unknown>` mirror would
+ * reject it (the nominal interface lacks the record's index signature).
+ */
+interface EveSessionState {
+    readonly continuationToken?: string;
+    readonly sessionId?: string;
+    readonly streamIndex: number;
+}
+/**
+ * One streamed turn event from an eve session's NDJSON stream. A peer-free
+ * structural mirror of the slice of eve's `HandleMessageStreamEvent` a workflow
+ * reads when it FORWARDS frames to its own output (`getWritable()`): the
+ * discriminant `type` and the per-frame `data`. Eve's real union is far richer
+ * (dozens of frame variants), but a workflow that drains the stream only narrows
+ * on `type` and reads `data` off the matched frame — so this loose, open shape is
+ * what the forward loop needs while keeping the optional `eve` peer out of the
+ * main barrel's type graph. A creator who wants the full eve union types the
+ * `getWritable<...>()` sink with eve's own `HandleMessageStreamEvent`.
+ */
+interface EveStreamEvent {
+    readonly type: string;
+    readonly data?: unknown;
+    readonly [key: string]: unknown;
+}
+/**
+ * The turn payload eve's `session.send(...)` accepts. A bare string is shorthand
+ * for `{ message }`; the object form carries follow-up text, HITL results, client
+ * context, output schema, signal, and headers. Kept loose on purpose — the lazy
+ * member forwards it verbatim to the real eve session.
+ */
+type SendTurnInput<_TOutput = unknown> = string | Readonly<Record<string, unknown>>;
+/**
+ * The aggregated result of one turn, returned by `EveMessageResponse.result()`.
+ * Mirrors the slice of eve's `MessageResult<TOutput>` the workflow→agent hop
+ * reads: the typed structured `data` (from the turn's `outputSchema`) plus the
+ * terminal `status`. Eve's real `MessageResult` is richer and takes precedence
+ * when the creator has `eve` installed.
+ */
+interface EveMessageResult<TOutput = unknown> {
+    readonly data: TOutput | undefined;
+    readonly status: 'completed' | 'failed' | 'waiting';
+}
+/**
+ * The response eve's `session.send(...)` returns. Mirrors the slice of eve's
+ * `MessageResponse<TOutput>` the hop drives: collect the turn via `result()` OR
+ * iterate the event stream with `for await...of` (the response is
+ * `AsyncIterable`). Both consume the SAME single-use stream.
+ */
+interface EveMessageResponse<TOutput = unknown> extends AsyncIterable<EveStreamEvent> {
+    result(): Promise<EveMessageResult<TOutput>>;
+}
+
+/**
+ * The eve `Client` surface a lazy agent handle exposes. Narrowed to the
+ * `session(...)` factory the workflow→agent path uses; the returned session is the
+ * lazy `LazyAgentSession` below (structurally compatible with eve's `ClientSession`).
+ */
+interface LazyAgentClient {
+    session(state?: EveSessionState | string): LazyAgentSession;
+}
+/**
+ * The eve `ClientSession` surface a lazy agent session exposes — a DROP-IN twin of
+ * eve's native `ClientSession`, so a workflow written against the eager `eveAgent`
+ * path keeps compiling verbatim when it swaps to `stackbone.agent`. `send` /
+ * `stream` are the async leaves that resolve the `eve` peer on first use;
+ * everything above them (selecting the agent, opening the session) stays
+ * synchronous and peer-free. `send` returns eve's `MessageResponse<TOutput>` (so
+ * `.result()` and `for await...of` both work), and `state` exposes the advanced
+ * cursor a workflow persists between turns — readable once a turn has built the
+ * real session.
+ */
+interface LazyAgentSession {
+    /**
+     * Current session cursor (continuation token, session id, stream cursor), read
+     * to persist + resume across turns. A DROP-IN twin of eve's `ClientSession.state`,
+     * which is readable from construction: before the first `send` / `stream` it
+     * echoes the seed passed to `session(state)` (a bare continuation-token string
+     * normalizes to `{ continuationToken, streamIndex: 0 }`, an absent seed to the
+     * initial `{ streamIndex: 0 }`), and after a turn it exposes the advanced cursor
+     * off the real eve session. Never throws.
+     */
+    readonly state: EveSessionState;
+    send<TOutput = unknown>(input: SendTurnInput<TOutput>): Promise<EveMessageResponse<TOutput>>;
+    stream(options?: {
+        startIndex?: number;
+    }): AsyncIterable<EveStreamEvent>;
+}
+/**
+ * `stackbone.agent` — select a sibling eve agent by its verbatim id and get a lazy
+ * eve `Client`. A declared name (a key of the augmented `AgentRegistry`)
+ * autocompletes and a typo is a compile error; with no generated registry the name
+ * is a loose `string` (checked at runtime against `AGENT_URLS`). Same id-keyed
+ * selection style — and same `AgentName` type — as the deprecated `eveAgent(...)`.
+ */
+interface AgentAccessor {
+    (name: AgentName): LazyAgentClient;
+}
+
 interface StorageObject {
     key: string;
     size: number;
@@ -1337,8 +1540,9 @@ interface InvokeOptions {
     connection?: string;
 }
 /**
- * `client.connections` — the agent's handle on the workspace's connector
- * connections. The credentials never enter the agent container: each method
+ * `client.legacyConnections` — the agent's handle on the workspace's connector
+ * connections under the legacy connector model. The credentials never enter the
+ * agent container: each method
  * makes an authenticated call to the control plane (the connector executor owns
  * the resolved credential, in a platform process).
  *
@@ -1546,6 +1750,15 @@ interface UnscheduleRequest {
  * Contract gating: every method awaits the `queues.jobs` module gate before
  * touching the network, so a stale datapath / missing capability surfaces as
  * a gating error rather than a failed POST.
+ *
+ * @deprecated CLASSIC v2 ONLY. This enqueues a job that wakes a `defineAgent`
+ * handler over the scale-to-zero agent-jobs dispatcher — the path being retired
+ * with `/invoke`. In runtime v3 (eve + workflows) a background job IS "start a
+ * workflow": from a workflow use `startWorkflow(name, input)` /
+ * `startWorkflowAndWait(name, input)` and `scheduleWorkflow(name, input, cron)`
+ * from `@stackbone/sdk/workflow`, which run on the World's `flows` queue with
+ * their own observable runs. `client.queues.*` keeps working while cloud +
+ * self-host remain on classic v2; it disappears when v3 reaches production.
  */
 declare class QueuesModule {
     private readonly _http;
@@ -1553,9 +1766,17 @@ declare class QueuesModule {
     constructor(resolved: ResolvedConfig, _http: HttpClient, 
     /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
     gate?: ModuleGate);
+    /** @deprecated Classic v2 only. Prefer `startWorkflow(name, input)` from
+     *  `@stackbone/sdk/workflow` (a job → a workflow run on the World). */
     publish(request: PublishRequest): Promise<Result<PublishJobResponse>>;
+    /** @deprecated Classic v2 only. Prefer `scheduleWorkflow(name, input, cron)`
+     *  from `@stackbone/sdk/workflow` (a cron → a workflow run on the World). */
     schedule(request: ScheduleRequest): Promise<Result<ScheduleJobResponse>>;
+    /** @deprecated Classic v2 only. Prefer `unschedule(name)` from
+     *  `@stackbone/sdk/workflow`. */
     unschedule(request: UnscheduleRequest): Promise<Result<UnscheduleJobResponse>>;
+    /** @deprecated Classic v2 only. Prefer `listSchedules()` from
+     *  `@stackbone/sdk/workflow`. */
     listSchedules(): Promise<Result<ListSchedulesResponse>>;
 }
 
@@ -1605,7 +1826,7 @@ declare class StackboneClient {
     private _secrets?;
     private _config?;
     private _queues?;
-    private _connections?;
+    private _legacyConnections?;
     private _memory?;
     private _prompts?;
     private _httpClient?;
@@ -1629,14 +1850,53 @@ declare class StackboneClient {
      */
     get queues(): QueuesModule;
     /**
-     * Live surface — the agent's handle on the workspace's connector connections.
-     * `list` / `invoke` make authenticated calls to the control-plane connectors
-     * proxy (`/api/v1/agent/connections/*`); the credentials never enter the agent
+     * Legacy surface — the agent's handle on the workspace's connector connections
+     * under the OLD connector model. `list` / `invoke(connector, action, args)` make
+     * authenticated calls to the control-plane connectors proxy
+     * (`/api/v1/agent/connections/*`); the credentials never enter the agent
      * container. Gated against `connections.actions` so the handshake-blocked /
      * capability-missing paths are exercised the same way as the other gated
      * surfaces.
+     *
+     * Named `legacyConnections` (not `connections`) so it no longer sits one letter
+     * from the new peer-free `connection(id)` entrypoint above — the two connector
+     * entrypoints are now unambiguous. Behaviour is unchanged from the old
+     * `connections` member.
+     */
+    get legacyConnections(): ConnectionsModule;
+    /**
+     * Peer-free connector entrypoint — `stackbone.connection(id)` selects a Stackbone
+     * Connect connector by its verbatim id and returns a typed handle whose generated
+     * operations (`.sendMail({ ... })`, typed via the `StackboneConnections` registry)
+     * and dynamic `.call(operation, args)` escape hatch both resolve to the same broker
+     * call (`POST /api/connect/execute`, HMAC scheme A). It is a plain HMAC fetch — it
+     * imports NO `eve` peer — so it is wired directly onto the client with no lazy
+     * loading and pulls no new peer into the main barrel.
+     *
+     * This is the namespaced form of the top-level `connection(...)` export (now
+     * `@deprecated`); both delegate to the same implementation. Distinct from the
+     * plural `connections` surface above, which is the control-plane connectors proxy
+     * (`list` / `invoke`).
+     */
+    get connection(): ConnectionAccessor;
+    /**
+     * Namespaced sibling-agent entrypoint — `stackbone.agent(id)` selects a sibling
+     * eve agent by its verbatim name and returns a lazy eve `Client`, so a workflow
+     * step delegates with `stackbone.agent('support').session().send({ ... })`. The
+     * name is typed against the augmentable `AgentRegistry` (declared names
+     * autocomplete, a typo is a compile error).
+     *
+     * Peer isolation is load-bearing: selecting the agent and opening a session are
+     * synchronous and import NO `eve` peer — only the session's already-async leaves
+     * (`send` / `stream`) resolve `eve/client` via dynamic import on first use. So a
+     * tool-only agent that imports `@stackbone/sdk` and never calls `agent(...)` never
+     * eager-loads the optional `eve` peer and cannot crash-loop on a missing dep.
+     *
+     * This is the namespaced form of the top-level `eveAgent(...)` export (now
+     * `@deprecated`) on the `@stackbone/sdk/workflow` subpath; both produce the same
+     * signed workflow→agent call and the same eve `Client` API.
      */
-    get connections(): ConnectionsModule;
+    get agent(): AgentAccessor;
     /**
      * Pending surface — runtime not built. Every method returns
      * `not_implemented`. Mem0 is a third-party integration, not a Stackbone
@@ -1738,6 +1998,13 @@ 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.
  */
 interface InvokeContext<I extends z.ZodType> {
     input: z.infer<I>;
@@ -1746,6 +2013,19 @@ interface InvokeContext<I extends z.ZodType> {
     runId: string;
     client: StackboneClient;
     logger: Logger;
+    stream?: InvokeStream;
+}
+/**
+ * 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 synchronous `invoke` capability. Mirrors the wrapper's three HTTP verbs
@@ -1885,6 +2165,54 @@ declare function defineAgent<T extends Record<string, z.ZodType>>(spec: AgentSpe
     [K in keyof T]: HandlerBlock<T[K]>;
 };
 
+/**
+ * The minimal Standard Schema surface a workflow contract exposes. Kept
+ * structural so the SDK needs no `@standard-schema/spec` dependency: a Zod,
+ * Valibot or ArkType schema all satisfy it (each carries a `~standard` brand).
+ * The build reads the real `~standard.validate` / `z.toJSONSchema` off the live
+ * object; this type only marks "a Standard Schema goes here".
+ */
+interface WorkspaceStandardSchema {
+    readonly '~standard': unknown;
+}
+/** One agent declared in the workspace. */
+interface WorkspaceAgent {
+    /** Name = the agent's package.json name and its folder under `agents/`. */
+    name: string;
+    dir: string;
+}
+/** One workflow declared in the workspace. */
+interface WorkspaceWorkflow {
+    /** Name used to address/trigger the workflow from Studio + the CLI. */
+    name: string;
+    /** Path (relative to the workspace root) of the `*.workflow.ts` module. */
+    module: string;
+    /** Exported workflow function name inside that module. */
+    export: string;
+    /**
+     * RESERVED inline-contract variant (forward-looking). The contract a workflow
+     * declares is harvested by the build ONLY from sibling exports next to the
+     * function (`export const inputSchema`/`outputSchema`) or a `<name>.contract.ts`
+     * sibling — NOT from these config fields yet. They are typed so a creator may
+     * co-locate the contract here ahead of the build learning to read it, but in
+     * the current dev build they are inert (no schema is extracted from them).
+     * Wiring the inline variant into extraction is a follow-up.
+     */
+    inputSchema?: WorkspaceStandardSchema;
+    outputSchema?: WorkspaceStandardSchema;
+}
+/** The default export of `stackbone.config.ts`. */
+interface StackboneWorkspace {
+    agents: WorkspaceAgent[];
+    workflows: WorkspaceWorkflow[];
+}
+/**
+ * Type + return a workspace registry. Identity at runtime — its only job is to
+ * give the creator a typed `stackbone.config.ts` default export and to own the
+ * convention in one place.
+ */
+declare const defineWorkspace: (workspace: StackboneWorkspace) => StackboneWorkspace;
+
 interface InvocationContext {
     /** The envelope's `invocationId` — surfaced on log lines as `trace_id`. */
     readonly invocationId: string;
@@ -1898,6 +2226,22 @@ interface InvocationContext {
      * without routing info (older tests, lifecycle hooks) still type-checks.
      */
     readonly handler?: string;
+    /**
+     * The projected `run_steps.id` of the workflow step currently executing, when
+     * the runtime can attribute the active async tree to one step. The
+     * workflow-HITL helper reads it so an approval row can be anchored to the
+     * exact step that requested it (`approvals.requested_by_step_id`, A6).
+     *
+     * GAP (2026-06-20): no caller populates this yet. The emulator binds the
+     * invocation context once per WHOLE flow dispatch (see the runtime-mount
+     * `flowPost` wrap), not per step, and the Workflow World runs as a FLAT tree
+     * whose events carry `writer: null` / `executionContext: null`, so the
+     * per-step World id is not visible at the point a `"use step"` runs. The seam
+     * is threaded end-to-end (context → ambient approval client → INSERT) so the
+     * column is stamped the moment a step id becomes available, without another
+     * surface change. Until then it stays `undefined` and the column stays NULL.
+     */
+    readonly requestedByStepId?: string;
 }
 /**
  * Runs `fn` with `context` bound as the active invocation. The context stays
@@ -1910,6 +2254,44 @@ declare function runWithInvocationContext<T>(context: InvocationContext, fn: ()
  * invoke (process boot, lifecycle events, tests that don't set one up).
  */
 declare function getInvocationContext(): InvocationContext | undefined;
+/**
+ * Ergonomic wrapper for callers that already hold a single correlation id and
+ * want to bind it as the active run/trace for `fn` — the durable workflow step
+ * call-site is the first such caller (F5): it knows the projected `run_id` and
+ * the World run id, and wraps a step's execution so the step's logs and SDK
+ * operations correlate to its run.
+ *
+ * It does NOT generate ids — that stays a caller concern, exactly like
+ * `runWithInvocationContext`. `runId` and `invocationId` default to the single
+ * `id` you pass, so `runWithCallerId(runId, fn)` binds a context where the run
+ * and trace share that id; pass distinct values (e.g. the World run id as the
+ * trace) via the options form.
+ */
+declare function runWithCallerId<T>(id: string, fn: () => T, options?: {
+    readonly invocationId?: string;
+    readonly handler?: string;
+}): T;
+
+/**
+ * The ambient, lazily-resolved Stackbone client. A `Proxy` over the cached
+ * `StackboneClient`: every property access (the surface accessors
+ * `storage` / `rag` / `queues` / `database` / `secrets` / `config` / `ai` /
+ * `approval` / `legacyConnections` / `memory` / `prompts` / `contract`, the
+ * peer-free connector entrypoint `connection(id)`, plus the sibling-agent
+ * entrypoint `agent(id)`) is forwarded to the singleton, which is created on the
+ * first such access. Because each `StackboneClient` accessor is itself lazy +
+ * cached, repeated access returns the same surface instance (one client, one
+ * pool, per process). `connection` and `agent` are plain function members (no
+ * lazy surface build) — the Proxy binds them to the real client and forwards them
+ * like any other member. `agent` is special only in that the eve peer it needs is
+ * resolved lazily on the first async turn, NOT at member access.
+ *
+ * No surface is constructed and no env var is read at import time. A surface op
+ * that needs a genuinely-absent required env var (e.g. `STACKBONE_POSTGRES_URL`
+ * for an agent-local op) fails with the surface's actionable, coded error
+ * (`database_not_configured` etc.), never a silent `undefined`.
+ */
+declare const stackbone: StackboneClient;
 
 /** The subset of the global `console` this bridge replaces. */
 interface ConsoleLike {
@@ -2120,4 +2502,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 AgentAccessor, 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 ConfigRegistry, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type EveMessageResponse, type EveMessageResult, type EveSessionState, type EveStreamEvent, 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 InvokeStream, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type LazyAgentClient, type LazyAgentSession, 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 SendTurnInput, type SignedUrl, type SignedUrlOptions, StackboneClient, type StackboneWorkspace, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, type WorkspaceAgent, type WorkspaceStandardSchema, type WorkspaceWorkflow, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, defineWorkspace, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithCallerId, runWithInvocationContext, stackbone };