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

package/index.d.ts

@@ -6,6 +6,9 @@ export { ChunkOptions, ChunkStrategy, DeleteOptions, DeleteResponse, IngestChunk
 import OpenAI from 'openai';
 import { ChatCompletionCreateParamsStreaming, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletion, EmbeddingCreateParams, CreateEmbeddingResponse, ChatCompletionMessageParam } from 'openai/resources';
 import { Stream } from 'openai/streaming';
+import { W as WorkflowName, c as StartWorkflowOptions, e as WorkflowStartHandle, b as StartWorkflowAndWaitOptions, S as ScheduledWorkflow, A as AgentName } from './agent-registry-BNXuj88Q.js';
+export { a as AgentRegistry, g as WorkflowScheduler, h as WorkflowStarter, i as WorkflowTriggerOptions, j as getWorkflowScheduler, k as getWorkflowStarter, l as setWorkflowScheduler, m as setWorkflowStarter } from './agent-registry-BNXuj88Q.js';
+import { a as ConnectionAccessor } from './call-connector-CYDw_yG5.js';
 import { S3Client } from '@aws-sdk/client-s3';
 import { z } from 'zod';
 export { z } from 'zod';
@@ -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
@@ -640,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;
@@ -677,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;
@@ -708,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`. */
@@ -715,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;
 }
@@ -1135,6 +1198,140 @@ declare class SecretsFacade {
     private sql;
 }
 
+/**
+ * The shape of `stackbone.workflows` — the namespaced workflow trigger + schedule
+ * surface. Every `name` is typed `WorkflowName` (a loose `string` until
+ * `stackbone dev` generates `.stackbone/workflows.d.ts`, then the closed set of
+ * declared workflow names — a typo is a compile error).
+ */
+interface WorkflowsAccessor {
+    /**
+     * Start another workflow BY NAME as its own independent run, fire-and-forget;
+     * resolves to `{ runId }` immediately. Durable `"use step"`. MUST be called from
+     * inside a running workflow. See {@link startWorkflow}.
+     */
+    start(name: WorkflowName, input: unknown, opts?: StartWorkflowOptions): Promise<WorkflowStartHandle>;
+    /**
+     * Run another workflow BY NAME as a durable sub-routine: suspend until it
+     * reaches a terminal state, then return its output validated against the
+     * target's declared output schema. See {@link startWorkflowAndWait}.
+     */
+    startAndWait<TOutput = unknown>(name: WorkflowName, input: unknown, opts?: StartWorkflowAndWaitOptions): Promise<TOutput>;
+    /**
+     * Register (or upsert) a DYNAMIC recurring trigger that starts `name` on the
+     * `cron` cadence. Idempotent by `name`. Prefer the declarative `export const
+     * schedules` for cadences that ship with the workspace. See {@link scheduleWorkflow}.
+     */
+    schedule(name: WorkflowName, input: unknown, cron: string): Promise<void>;
+    /** Cancel a dynamic scheduled trigger by `name`. See {@link unschedule}. */
+    unschedule(name: WorkflowName): Promise<void>;
+    /** List active triggers (declarative + dynamic). See {@link listSchedules}. */
+    listSchedules(): Promise<ScheduledWorkflow[]>;
+}
+
+/**
+ * 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;
@@ -1374,8 +1571,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).
  *
@@ -1583,6 +1781,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;
@@ -1590,9 +1797,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>>;
 }
 
@@ -1642,7 +1857,7 @@ declare class StackboneClient {
     private _secrets?;
     private _config?;
     private _queues?;
-    private _connections?;
+    private _legacyConnections?;
     private _memory?;
     private _prompts?;
     private _httpClient?;
@@ -1666,14 +1881,69 @@ 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 agent(): AgentAccessor;
+    /**
+     * Namespaced workflow trigger + schedule surface — `stackbone.workflows.start(...)`
+     * / `.startAndWait(...)` / `.schedule(...)` / `.unschedule(...)` / `.listSchedules()`.
+     * Start another workflow by name (fire-and-forget or durable sub-routine) and
+     * manage dynamic cron triggers, all from inside a running workflow.
+     *
+     * These are peer-free shims over the ambient `WorkflowStarter` / `WorkflowScheduler`
+     * the runtime injects on first dispatch — they import NO `workflow` / `eve` peer,
+     * so (like `connection` / `agent`) they are wired directly onto the client and
+     * pull nothing new into the main barrel. This is the namespaced form of the loose
+     * `startWorkflow(...)` / `scheduleWorkflow(...)` exports (now `@deprecated`) on the
+     * `@stackbone/sdk/workflow` subpath; both delegate to the same implementation, so
+     * `start` / `startAndWait` keep their `"use step"` durability. The peer-bound
+     * authoring API (`requestApproval` / `defineHook` / `sleep`) stays on that subpath.
      */
-    get connections(): ConnectionsModule;
+    get workflows(): WorkflowsAccessor;
     /**
      * Pending surface — runtime not built. Every method returns
      * `not_implemented`. Mem0 is a third-party integration, not a Stackbone
@@ -1782,15 +2052,6 @@ declare const createStructuredLogger: (opts?: StructuredLoggerOptions) => Logger
  *     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>;
@@ -1800,8 +2061,6 @@ interface InvokeContext<I extends z.ZodType> {
     client: StackboneClient;
     logger: Logger;
     stream?: InvokeStream;
-    progress?: InvokeProgress;
-    step?: InvokeStepFn;
 }
 /**
  * The streaming sink handed to a handler as `ctx.stream` when the caller asked
@@ -1815,60 +2074,6 @@ interface InvokeStream {
     /** 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
@@ -2007,6 +2212,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;
@@ -2020,6 +2273,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
@@ -2032,6 +2301,45 @@ 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)`, the sibling-agent entrypoint
+ * `agent(id)`, plus the peer-free `workflows` trigger/schedule surface) 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 {
@@ -2242,4 +2550,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 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 };
+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, ScheduledWorkflow, 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, WorkflowStartHandle, type WorkflowsAccessor, type WorkspaceAgent, type WorkspaceStandardSchema, type WorkspaceWorkflow, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, defineWorkspace, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithCallerId, runWithInvocationContext, stackbone };