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

package/index.d.cts

@@ -1,13 +1,15 @@
-import { ContractResponse } from '@stackbone/validators';
+import { AgentConnectionListResponse, InvokeConnectorActionResponse, PublishJobResponse, ScheduleJobResponse, UnscheduleJobResponse, ListSchedulesResponse, ContractResponse } from '@stackbone/validators';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { Sql } from 'postgres';
+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 { RunStepsSpanProcessorOptions, RunStepsSpanProcessor, PlatformLoggerOptions, PlatformLogger, AggregateRunCostResult } from './observability/index.cjs';
 import { S3Client } from '@aws-sdk/client-s3';
 import { z } from 'zod';
 export { z } from 'zod';
+import { SecretCipher } from '@stackbone/crypto';
 
 /**
  * Optional overrides accepted by `createClient`. All fields are optional;
@@ -29,11 +31,17 @@ interface ClientConfig {
      * every SDK consumer that talks to the agent's Postgres.
      */
     databaseUrl?: string;
+    /**
+     * Per-agent encryption key (base64, 32 bytes) used to decrypt the agent's
+     * own application secrets read directly from `stackbone_platform.secrets`.
+     * Falls back to `STACKBONE_SECRET_KEY` — the per-agent key the saga/harness
+     * inject into the runtime env. This is the ONLY new env channel the
+     * agent-owned-secrets split adds; the deliberate no-generic-env-channel
+     * stance is preserved.
+     */
+    secretKey?: string;
     openrouterKey?: string;
     openrouterBaseUrl?: string;
-    qstashToken?: string;
-    qstashCurrentSigningKey?: string;
-    qstashNextSigningKey?: string;
     llamaParseApiKey?: string;
     /** mem0 API key for the long-term memory backend (`client.memory`). Falls back to `MEM0_API_KEY`. */
     mem0ApiKey?: string;
@@ -125,8 +133,14 @@ interface ResolvedConfig {
     readonly approvalSigningKey: string | undefined;
     /** Resolved from `config.agentId` ?? `STACKBONE_AGENT_ID`. */
     readonly agentId: string | undefined;
-    /** Resolved from `config.databaseUrl` ?? `STACKBONE_POSTGRES_URL`. Shared by `client.database`, `client.rag` and `client.observability`. */
+    /** Resolved from `config.databaseUrl` ?? `STACKBONE_POSTGRES_URL`. Shared by `client.database`, `client.rag`, and the platform observability hooks in `@stackbone/sdk/observability`. */
     readonly databaseUrl: string | undefined;
+    /**
+     * Resolved from `config.secretKey` ?? `STACKBONE_SECRET_KEY`. The per-agent
+     * base64 encryption key `client.secrets` uses to decrypt rows read straight
+     * out of `stackbone_platform.secrets`.
+     */
+    readonly secretKey: string | undefined;
     /** Resolved from `config.openrouterKey` ?? `OPENROUTER_API_KEY`. */
     readonly openrouterKey: string | undefined;
     /** Resolved from `config.openrouterBaseUrl` ?? `OPENROUTER_BASE_URL`. `undefined` means use the OpenRouter default. */
@@ -223,22 +237,59 @@ declare const SDK_ERROR_CODE_PREFIXES: {
      */
     readonly rag: readonly ["dim_mismatch", "embedding_failed", "embedding_model_unsupported", "error", "ingest_cancelled", "invalid_request", "job_insert_failed", "jobs_error", "schema_missing"];
     /**
-     * `client.approval` — control-plane facade plus the HMAC verify helper.
-     * The transport-driven codes (`unauthorized`, `forbidden`, ...) come from
-     * `HttpClient`'s status→domain remap with `prefix: 'approval'`; the
-     * verify-specific codes (`invalid_signature`, etc.) are emitted locally.
+     * `client.approval` — AGENT-LOCAL DB facade plus the HMAC verify helper.
+     * The request/cancel/get/list codes (`persist_failed`, `cancel_failed`,
+     * `unavailable`) come from the direct write/read against
+     * `stackbone_platform.approvals`; the verify-specific codes
+     * (`invalid_signature`, etc.) are emitted locally.
      */
-    readonly approval: readonly ["forbidden", "invalid_payload", "invalid_request", "invalid_response", "invalid_signature", "not_found", "rate_limited", "signature_expired", "signing_key_missing", "timeout", "tool_execute_failed", "unauthorized", "unavailable"];
+    readonly approval: readonly ["cancel_failed", "forbidden", "invalid_payload", "invalid_request", "invalid_response", "invalid_signature", "not_found", "persist_failed", "rate_limited", "signature_expired", "signing_key_missing", "timeout", "tool_execute_failed", "unauthorized", "unavailable"];
     /**
-     * `client.secrets` — control-plane facade. Almost entirely transport-
-     * driven (HttpClient remap with `prefix: 'secrets'`); the local codes are
-     * the request-shape rail.
+     * `client.secrets` — AGENT-LOCAL facade. Reads `stackbone_platform.secrets`
+     * over the shared `client.database` pool and decrypts with the per-agent
+     * key. `not_configured` covers a missing `STACKBONE_SECRET_KEY`;
+     * `decrypt_failed` covers a key/envelope mismatch; `unavailable` covers a
+     * failed DB read.
      */
-    readonly secrets: readonly ["already_exists", "forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    readonly secrets: readonly ["already_exists", "decrypt_failed", "forbidden", "invalid_request", "invalid_response", "not_configured", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
     /**
-     * `client.config` — symmetric to `secrets`, points at `/api/config`.
+     * `client.config` — AGENT-LOCAL facade, reads the singleton
+     * `stackbone_platform.agent_config` row over the shared `client.database`
+     * pool.
      */
     readonly config: readonly ["forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.queues` — the agent → control plane job-enqueue surface. Every
+     * method (`publish`, `schedule`, `unschedule`, `listSchedules`) POSTs/GETs
+     * the BullMQ dispatcher endpoints over `HttpClient`, so the full
+     * status→domain remap (`queues_unauthorized`, `queues_not_found`,
+     * `queues_unavailable`, …) is in play. The agent never touches Redis — it
+     * only calls these endpoints.
+     */
+    readonly queues: readonly ["forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.connections` — the agent → control plane connectors proxy. 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
+     * never holds a credential — it only calls these endpoints; the control plane
+     * resolves the workspace connection and runs the connector action. `ambiguous`
+     * is the 409 the proxy returns when the workspace holds several connections of
+     * the same connector and `invoke` carried no `{ connection }` selector to pick
+     * one — the error message lists the candidate names/ids so the author can.
+     */
+    readonly connections: readonly ["ambiguous", "forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.prompts` — AGENT-LOCAL facade. Reads
+     * `stackbone_platform.prompts` / `prompt_versions` over the shared
+     * `client.database` pool and compiles templates with the local
+     * `@stackbone/prompt-compiler` (Mustache subset). `not_configured` covers a
+     * missing prompts schema (the `42P01` "run `stackbone db migrate up`" hint);
+     * `not_found` covers an absent / soft-deleted key; `missing_var` is the
+     * compile-time diagnostic when a `{{var}}` has no value; `unavailable`
+     * covers a failed DB read; `already_exists` covers a duplicate `create`.
+     */
+    readonly prompts: readonly ["already_exists", "invalid_request", "missing_var", "not_configured", "not_found", "unavailable"];
     /**
      * `client.memory` — reserved. The README documents the prefix; today the
      * pending surface returns `not_implemented` for every method so no
@@ -260,9 +311,10 @@ declare const SDK_ERROR_CODE_PREFIXES: {
      */
     readonly database: readonly ["not_configured"];
     /**
-     * `client.observability` — only the run-cost rollup emits a domain code
-     * today; everything else either returns ok or surfaces through the
-     * `database_*` family above.
+     * Observability — the run-cost rollup hook in `@stackbone/sdk/observability`
+     * (wired by the runtime, not a creator surface) emits this when its post-run
+     * Postgres write fails; everything else either returns ok or surfaces through
+     * the `database_*` family above.
      */
     readonly observability: readonly ["close_run_failed"];
     /**
@@ -467,6 +519,265 @@ declare class DatabaseModule {
     raw(): DrizzleClient;
 }
 
+interface ApprovalToolSpec<I, O> {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    needsApproval?: boolean | ((input: I) => boolean | Promise<boolean>);
+    /**
+     * Maps the LLM input to the approval request fields. `topic` and `payload`
+     * default to the tool name and the raw input respectively when omitted;
+     * `onDecide` must always be supplied so the control plane knows where to
+     * deliver the eventual decision.
+     */
+    toRequest: (input: I) => Omit<ApprovalRequestOptions<I>, 'payload' | 'topic'> & Partial<Pick<ApprovalRequestOptions<I>, 'payload' | 'topic'>>;
+    execute: (input: I) => Promise<O> | O;
+}
+interface OpenAIToolSpec {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+type ToolInvokeResult<O> = {
+    status: 'pending';
+    approvalId: string;
+    expiresAt: string;
+} | {
+    status: 'ok';
+    result: O;
+};
+interface ApprovalTool<I, O> {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    openaiSpec(): OpenAIToolSpec;
+    invoke(input: I): Promise<Result<ToolInvokeResult<O>>>;
+}
+
+interface VerifyOptions {
+    /** Override the signing key resolved from `STACKBONE_APPROVAL_SIGNING_KEY` / `approvalSigningKey`. */
+    signingKey?: string;
+    /** Reject signatures whose timestamp is older than this (seconds). Default 300. */
+    toleranceSeconds?: number;
+    /** Inject a clock for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+
+type ApprovalTopic = string;
+declare const DECISION_STATUSES: readonly ["approved", "rejected", "timed_out", "cancelled"];
+type DecisionStatus = (typeof DECISION_STATUSES)[number];
+type ApprovalStatus = 'pending' | DecisionStatus;
+type Decision<T = unknown> = {
+    status: 'approved' | 'rejected';
+    payload: T;
+    approver: ApproverInfo;
+    decidedAt: string;
+    reason?: string;
+} | {
+    status: 'timed_out';
+    decidedAt: string;
+} | {
+    status: 'cancelled';
+    decidedAt: string;
+    reason?: string;
+};
+interface ApproverInfo {
+    id: string;
+    email: string;
+    name?: string;
+}
+interface ApprovalRequestOptions<T = unknown> {
+    topic: ApprovalTopic;
+    payload: T;
+    title?: string;
+    description?: string;
+    /** Path on the agent the control plane will POST the decision to (resolved against the agent's public URL server-side). */
+    onDecide: string;
+    /** ISO 8601 duration (`'24h'`) or milliseconds. Default 24h. */
+    timeout?: string | number;
+    onTimeout?: 'reject' | 'approve' | 'ignore';
+    approver?: string;
+    /** Same `(topic, idempotencyKey)` returns the same `approvalId` instead of creating a new one. */
+    idempotencyKey?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ApprovalRequest {
+    approvalId: string;
+    status: 'pending';
+    callbackUrl: string;
+    expiresAt: string;
+}
+interface ApprovalRecord<T = unknown> {
+    approvalId: string;
+    topic: ApprovalTopic;
+    status: ApprovalStatus;
+    payload: T;
+    decision?: Decision<T>;
+    createdAt: string;
+    expiresAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface ApprovalListOptions {
+    status?: ApprovalStatus;
+    topic?: ApprovalTopic;
+    cursor?: string;
+    /** 1..100. Default 50. */
+    limit?: number;
+}
+interface ApprovalListResult<T = unknown> {
+    items: ApprovalRecord<T>[];
+    nextCursor?: string;
+}
+/**
+ * `client.approval` — AGENT-LOCAL. The HITL pause is recorded directly in the
+ * agent's own `stackbone_platform.approvals` table over the shared
+ * `client.database` pool; there is no control-plane POST anymore. The RESUME
+ * half stays Studio-driven: a human decides in Studio, the control plane signs
+ * an HMAC callback to `callbackUrl`, and the agent reconciles it with
+ * `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).
+ */
+declare class ApprovalFacade {
+    private readonly _resolved;
+    /** Lazy accessor for `client.database` — reaches the shared `Sql` via `.shared().$client`. */
+    private readonly _getDatabase;
+    constructor(_resolved: ResolvedConfig, 
+    /** Lazy accessor for `client.database` — reaches the shared `Sql` via `.shared().$client`. */
+    _getDatabase: () => DatabaseModule);
+    request<T = unknown>(options: ApprovalRequestOptions<T>): Promise<Result<ApprovalRequest>>;
+    cancel(approvalId: string, reason?: string): Promise<Result<void>>;
+    get<T = unknown>(approvalId: string): Promise<Result<ApprovalRecord<T>>>;
+    list<T = unknown>(options?: ApprovalListOptions): Promise<Result<ApprovalListResult<T>>>;
+    /**
+     * Local crypto verification — does not touch the database, so it has the same
+     * shape it had on the control-plane surface. Auditing rule: a method gates
+     * iff it issues a datapath call; this one never does.
+     */
+    verify<T = unknown>(request: Request, options?: VerifyOptions): Promise<Result<Decision<T>>>;
+    /**
+     * Pure factory — returns an `ApprovalTool` whose `invoke()` ultimately calls
+     * back into `ApprovalFacade.request`.
+     */
+    tool<I, O>(spec: ApprovalToolSpec<I, O>): ApprovalTool<I, O>;
+    private sql;
+}
+
+declare class ConfigFacade {
+    private readonly _resolved;
+    /** Lazy accessor for `client.database` — see `SecretsFacade`. */
+    private readonly _getDatabase;
+    constructor(_resolved: ResolvedConfig, 
+    /** Lazy accessor for `client.database` — see `SecretsFacade`. */
+    _getDatabase: () => DatabaseModule);
+    get<T = unknown>(key: string): Promise<Result<T>>;
+    /**
+     * 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>>>;
+    private loadPayload;
+    private sql;
+}
+
+/**
+ * A prompt's current/active state. Key-based (workspace-unique). `template` is
+ * the current version's content; `version` is the live version number.
+ */
+interface Prompt {
+    key: string;
+    name: string;
+    description: string | null;
+    /** The current version's content. */
+    template: string;
+    /** The live version number. The first `create` produces version `1`. */
+    version: number;
+    /** `{{var}}` names referenced by the current version. */
+    variables: readonly string[];
+    metadata: Record<string, unknown> | null;
+    /** ISO 8601 UTC timestamp. */
+    createdAt: string;
+    updatedAt: string;
+}
+interface GetPromptOptions {
+    /** Pin a specific version. Omitted -> current/latest. */
+    version?: number;
+}
+interface ListPromptsOptions {
+    /** 1..100. Default 50. */
+    limit?: number;
+}
+interface ListPromptsResult {
+    /** Current version of each (non-deleted) prompt. */
+    items: readonly Prompt[];
+}
+interface CreatePromptRequest {
+    key: string;
+    name: string;
+    /** The version-1 content. */
+    template: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdatePromptOptions {
+    /** New content. Appends a new immutable version. */
+    template?: string;
+    name?: string;
+    description?: string | null;
+    /** Replaces the prompt-head metadata. */
+    metadata?: Record<string, unknown>;
+}
+interface DeletePromptOptions {
+    /** Reserved for future per-version deletes; ignored today (soft-deletes the key). */
+    version?: number;
+}
+interface DeletePromptResult {
+    key: string;
+    /** Number of prompt heads soft-deleted (0 or 1). */
+    deleted: number;
+}
+interface CompilePromptResult {
+    /** The rendered string. */
+    output: string;
+    /** The version the compile ran against. */
+    version: number;
+}
+declare class PromptsFacade {
+    private readonly _resolved;
+    /**
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
+     */
+    private readonly _getDatabase;
+    constructor(_resolved: ResolvedConfig, 
+    /**
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
+     */
+    _getDatabase: () => DatabaseModule);
+    get(key: string, options?: GetPromptOptions): Promise<Result<Prompt>>;
+    compile(key: string, variables: Record<string, unknown>, options?: GetPromptOptions): Promise<Result<CompilePromptResult>>;
+    list(options?: ListPromptsOptions): Promise<Result<ListPromptsResult>>;
+    create(request: CreatePromptRequest): Promise<Result<Prompt>>;
+    update(key: string, options: UpdatePromptOptions): Promise<Result<Prompt>>;
+    delete(key: string, _options?: DeletePromptOptions): Promise<Result<DeletePromptResult>>;
+    private sql;
+    private mapReadError;
+    private mapWriteError;
+}
+
 /**
  * Public surface behind `client.ai`. Wraps the official `openai` SDK with a
  * `baseURL` override pointing to OpenRouter, so 300+ models are reachable
@@ -618,206 +929,47 @@ interface RequestOptions$1 {
     signal?: AbortSignal;
 }
 
-type ChunkStrategy = 'recursive' | 'sentence';
-interface ChunkOptions {
-    /** Splitter algorithm. Default `recursive`. */
-    strategy?: ChunkStrategy;
-    /** Target characters per chunk. Default 512. */
-    size?: number;
-    /** Characters of overlap between consecutive chunks. Default 64. */
-    overlap?: number;
-}
-
-type RagIngestProgress = {
-    type: 'started';
-    jobId: string;
-    totalChunks: number;
-} | {
-    type: 'progress';
-    jobId: string;
-    processedChunks: number;
-    totalChunks: number;
-    currentDocument?: {
-        source: string;
-        ordinal: number;
-    };
-} | {
-    type: 'completed';
-    jobId: string;
-    totalChunks: number;
-} | {
-    type: 'failed';
-    jobId: string;
-    error: string;
-};
-interface IngestJobStartArgs {
-    collection: string;
-    source: string;
-    totalChunks: number;
-}
-interface IngestJobProgressArgs {
-    jobId: string;
-    processedChunks: number;
-    totalChunks: number;
-    currentDocument?: {
-        source: string;
-        ordinal: number;
-    };
-}
-interface IngestJobCompleteArgs {
-    jobId: string;
-    totalChunks: number;
-}
-interface IngestJobFailArgs {
+/**
+ * Handle returned by `client.rag.ingestAsync`. The job id is allocated
+ * synchronously against `stackbone_rag_jobs` so the caller can track / cancel
+ * the work via the `/api/rag/jobs/:jobId/*` surface; `events` is a streaming
+ * channel of progress events (ADR §D9 shape); `result` settles when the
+ * pipeline finishes (or fails / is cancelled).
+ */
+interface IngestAsyncHandle {
     jobId: string;
-    error: string;
+    events: AsyncIterable<RagIngestProgress>;
+    result: Promise<Result<IngestResponse>>;
 }
-interface IngestJobWriter {
-    /**
-     * Allocates a `stackbone_rag_jobs` row in `running` state and returns its
-     * id. Caller is expected to surface this id to the user before any
-     * progress event fires so a `client.rag.ingestAsync` consumer can
-     * immediately address the job (e.g. `POST /api/rag/jobs/:jobId/cancel`).
-     */
-    start(args: IngestJobStartArgs): Promise<Result<{
-        jobId: string;
-    }>>;
-    /** Idempotent — last write wins on `progress` jsonb. */
-    progress(args: IngestJobProgressArgs): Promise<void>;
-    /** Marks the row terminal (status='succeeded'). */
-    complete(args: IngestJobCompleteArgs): Promise<void>;
-    /** Marks the row terminal (status='failed') and stores the error message. */
-    fail(args: IngestJobFailArgs): Promise<void>;
-    /**
-     * Polled between chunk batches. Returning `true` makes the pipeline abort
-     * with `rag_ingest_cancelled`, leaving the row in whatever terminal state
-     * the writer transitions it to next (typically `cancelled`).
-     */
-    isCancelled(args: {
-        jobId: string;
-    }): Promise<boolean>;
-}
-
-interface ParseOptions {
-    /** MIME type override. If omitted, the parser sniffs the input (Blob.type or PDF magic bytes). */
-    mime?: string;
-}
-type ParseInput = Blob | string | Uint8Array | ArrayBuffer;
-
-interface IngestChunk {
-    content: string;
-    embedding: number[];
-}
-interface IngestRequestBase {
-    /** Document identifier — re-ingesting with the same `id` replaces all its chunks atomically. */
-    id: string;
-    metadata?: Record<string, unknown>;
-    /** Logical namespace for separation. Default `'default'`. */
-    namespace?: string;
-    /**
-     * Canonical collection name used by the `stackbone_rag_jobs` writer (F07)
-     * to bind the row to a `stackbone_rag_collections` parent. Optional for
-     * back-compat with pre-F07 callers — when absent, no job row is written
-     * and progress is delivered only via `onProgress` (if any).
-     */
-    collection?: string;
-    /**
-     * Optional sink for streaming progress events. Fired in addition to (and
-     * before) the matching `IngestJobWriter` call so synchronous `ingest`
-     * consumers can observe progress without paying the SQL writer cost.
-     */
-    onProgress?: (event: RagIngestProgress) => void | Promise<void>;
-}
-interface IngestRequestPrecomputed extends IngestRequestBase {
-    chunks: IngestChunk[];
-}
-interface IngestRequestAutoEmbed extends IngestRequestBase {
-    chunks: string[];
-    /** Embedding model id. When set, the pipeline calls the configured Embedder. */
-    model: string;
-    /**
-     * Items per embeddings request. Consumed by the facade when it builds the
-     * `Embedder`; ignored by the pipeline itself (the embedder is fully
-     * configured at construction time).
-     */
-    batchSize?: number;
-}
-type IngestRequest = IngestRequestPrecomputed | IngestRequestAutoEmbed;
-interface IngestResponse {
-    id: string;
-    chunks: number;
-}
-interface DeleteOptions {
-    namespace?: string;
-}
-interface DeleteResponse {
-    deleted: number;
-}
-interface RetrieveRequestBase {
-    topK?: number;
-    filter?: Record<string, unknown>;
-    namespace?: string;
-    includeContent?: boolean;
-    includeMetadata?: boolean;
-}
-interface RetrieveRequestPrecomputed extends RetrieveRequestBase {
-    embedding: number[];
-}
-interface RetrieveRequestAutoEmbed extends RetrieveRequestBase {
-    text: string;
-    /** Must match the model used at ingest time. */
-    model: string;
-}
-type RetrieveRequest = RetrieveRequestPrecomputed | RetrieveRequestAutoEmbed;
-interface RetrieveHit {
-    id: string;
-    chunkIdx: number;
-    content?: string;
-    metadata?: Record<string, unknown>;
-    score: number;
-}
-
-/**
- * Handle returned by `client.rag.ingestAsync`. The job id is allocated
- * synchronously against `stackbone_rag_jobs` so the caller can track / cancel
- * the work via the `/api/rag/jobs/:jobId/*` surface; `events` is a streaming
- * channel of progress events (ADR §D9 shape); `result` settles when the
- * pipeline finishes (or fails / is cancelled).
- */
-interface IngestAsyncHandle {
-    jobId: string;
-    events: AsyncIterable<RagIngestProgress>;
-    result: Promise<Result<IngestResponse>>;
-}
-/**
- * `client.rag` — `pgvector`-backed retrieval. Two shapes per write/read:
- * pass `model` to let the SDK embed for you; pass embeddings precomputed for
- * provider/dimension/batching control.
- *
- * 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`.
- *
- * Connection ownership: this module never opens its own postgres pool. It
- * reaches the underlying `postgres-js` `Sql` through the **shared-handles
- * pattern** — `client.database.shared().$client` — so an agent that
- * touches both surfaces still opens exactly one connection pool against
- * `STACKBONE_POSTGRES_URL`. RAG is the canonical first cross-surface
- * consumer; memory and queues will adopt the same accessor when they
- * land.
- *
- * Schema readiness: starting with feature 30, the canonical schema is
- * installed by the CLI (`stackbone db migrate add-rag` + `migrate up`). When
- * an operation hits `42P01 relation does not exist`, the pipeline returns
- * `SdkError('rag_schema_missing')` with an actionable hint.
- */
-/**
- * Test-only seams accepted by `RagModule`. Production callers leave these
- * unset — they are injected by `ingest-async.spec.ts` to substitute the
- * shared-pool lookup and the SQL-backed job writer.
- */
-interface RagModuleTestDeps {
+/**
+ * `client.rag` — `pgvector`-backed retrieval. Two shapes per write/read:
+ * pass `model` to let the SDK embed for you; pass embeddings precomputed for
+ * provider/dimension/batching control.
+ *
+ * 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`.
+ *
+ * Connection ownership: this module never opens its own postgres pool. It
+ * reaches the underlying `postgres-js` `Sql` through the **shared-handles
+ * pattern** — `client.database.shared().$client` — so an agent that
+ * touches both surfaces still opens exactly one connection pool against
+ * `STACKBONE_POSTGRES_URL`. RAG is the canonical first cross-surface
+ * consumer; memory and queues will adopt the same accessor when they
+ * land.
+ *
+ * Schema readiness: the canonical schema (`stackbone_platform.rag_*`) is
+ * provisioned by the platform migrator, present on every install. When an
+ * operation still hits `42P01 relation does not exist`, the pipeline returns
+ * `SdkError('rag_schema_missing')` with an actionable hint.
+ */
+/**
+ * Test-only seams accepted by `RagModule`. Production callers leave these
+ * unset — they are injected by `ingest-async.spec.ts` to substitute the
+ * shared-pool lookup and the SQL-backed job writer.
+ */
+interface RagModuleTestDeps {
     /**
      * Replaces the `client.database.shared().$client` lookup used by
      * `ingestAsync`. Tests can plug a fake `Sql` here without standing up
@@ -884,10 +1036,11 @@ declare class RagModule {
     deleteWhere(filter: Record<string, unknown>, options?: DeleteOptions): Promise<Result<DeleteResponse>>;
     retrieve(request: RetrieveRequest): Promise<Result<RetrieveHit[]>>;
     /**
-     * Drops the legacy ad-hoc RAG schema. Kept for backwards compatibility with
-     * pre-feature-30 agents whose tables were provisioned by `ensureSchema` on
-     * first call. The canonical RAG schema (feature 30) is owned by the CLI and
-     * removed via `stackbone db migrate` flows, not by this method.
+     * Drops the legacy ad-hoc RAG tables (`rag_chunks` / `_rag_meta`) that
+     * pre-feature-30 agents provisioned on first ingest. Kept for backwards
+     * compatibility so an old agent can clean those up after upgrading. The
+     * canonical RAG schema (`stackbone_platform.rag_*`) is owned by the platform
+     * migrator — this method never touches it.
      */
     reset(): Promise<Result<void>>;
     /**
@@ -917,356 +1070,32 @@ declare class RagModule {
     private sql;
     private withPipeline;
 }
-
-/** Subset of `RequestInit['body']` we serialize without modification. */
-type SerializedBody = NonNullable<RequestInit['body']>;
-/**
- * Per-status overrides facades attach when an HTTP status carries a
- * non-canonical meaning for the endpoint — e.g. a `POST` whose `409` means
- * "already exists" instead of the default "conflict". Keys are HTTP statuses,
- * values are domain codes the transport should surface verbatim (no prefix
- * concatenation — the override is the final code).
- *
- * The value is typed against the catalog (`SdkErrorCode`) so an endpoint
- * cannot smuggle a wire code that isn't in the documented inventory.
- */
-type ErrorOverrides = Record<number, SdkErrorCode>;
-/**
- * Tells the transport how to remap HTTP status codes onto the surface's
- * domain code prefix. `404 → '<prefix>_not_found'`, `401 → '<prefix>_unauthorized'`,
- * etc. Endpoint-specific overrides win over the canonical mapping.
- *
- * `prefix` is constrained to `SdkErrorPrefix` (the catalog's prefix tuple) so
- * an unknown surface name doesn't compile — keeps the wire codes the
- * transport emits inside the typed inventory.
- */
-interface ErrorMapping {
-    /** Prefix concatenated with `_not_found`, `_unauthorized`, …. Required for any domain remap. */
-    prefix: SdkErrorPrefix;
-    /** Per-status final code that overrides the canonical mapping. */
-    overrides?: ErrorOverrides;
-}
-interface RequestOptions extends Omit<RequestInit, 'body' | 'signal'> {
-    /** Scalar query params. `undefined` values are dropped, others get coerced via `String()`. */
-    params?: Record<string, string | number | boolean | undefined>;
-    /**
-     * Repeated string-array params validated and serialised by the transport.
-     * Empty arrays / blank elements reject upstream with `<prefix>_invalid_request`
-     * (falls back to `http_invalid_request` when no `errorMapping` is set). Each
-     * array is joined with `,` to match the canonical control-plane shape.
-     */
-    arrayParams?: Record<string, readonly string[]>;
-    body?: SerializedBody | Record<string, unknown> | unknown[] | null;
-    signal?: AbortSignal;
-    /** Allow retrying non-idempotent requests (POST, PATCH). Off by default to prevent duplicate writes. */
-    idempotent?: boolean;
-}
-/**
- * Shape every facade method ideally collapses into: "POST to /path with this
- * body, validate against this schema, surface errors as `<prefix>_*`". The
- * transport handles validation, HTTP→domain remapping, querystring assembly
- * and the `Result` envelope so facades stay tiny orchestrators.
- *
- * `arrayParams` keys default to `errorMapping.prefix` for the validation
- * error code (e.g. an empty `names: []` becomes `secrets_invalid_request`).
- */
-interface TransportRequest<T> extends RequestOptions {
-    method: string;
-    path: string;
-    /**
-     * Zod schema (or any object with a `.safeParse()` method) the parsed body
-     * must validate against. On failure the transport surfaces
-     * `<prefix>_invalid_response` (or `http_invalid_response` if no prefix is
-     * configured) with the schema issues attached to `meta.issues`.
-     */
-    responseSchema?: ResponseSchema<T>;
-    /** HTTP→domain remapping. Omit to let `http_*` codes flow through unchanged. */
-    errorMapping?: ErrorMapping;
-}
-/**
- * Minimal contract the transport needs from a schema — `safeParse`. Compatible
- * with Zod (`z.object(…).safeParse(value)`) and any hand-rolled validator that
- * follows the same shape. Avoids leaking Zod's full surface into the transport
- * signature.
- */
-interface ResponseSchema<T> {
-    safeParse(input: unknown): {
-        success: true;
-        data: T;
-    } | {
-        success: false;
-        error: {
-            issues: unknown;
-        };
-    };
-}
-interface HttpClientOptions {
-    /** Default 30_000. Set to 0 to disable. */
-    timeout?: number;
-    /** Default 3. Set to 0 to disable. */
-    retryCount?: number;
-    /** Initial backoff in ms; doubles each attempt with ±15% jitter. Default 500. */
-    retryDelay?: number;
-    /** Override the global fetch (useful for tests). */
-    fetch?: typeof fetch;
-}
-/**
- * Shared HTTP client used by every facade that talks to the Stackbone
- * control plane. Wraps `fetch` with timeout, exponential backoff with jitter,
- * idempotent-only retries, response validation (Zod-compatible schemas) and
- * a uniform `Result` envelope so facades never throw at the SDK boundary.
- *
- * Each facade tells the transport its error prefix (`'secrets'`, `'config'`,
- * `'approval'`) so 404/401/403/429/5xx remap to surface-specific codes —
- * `secrets_not_found`, `approval_unauthorized`, etc. Endpoint-specific
- * remaps (e.g. `409 → 'secrets_already_exists'`) flow through
- * `errorMapping.overrides`. Transport-level failures (network, timeout,
- * parse) keep the `http_*` prefix the README contract documents.
- *
- * Reads `STACKBONE_API_URL` and `STACKBONE_AGENT_JWT` lazily on every request so
- * env-var rotation is picked up without restarting the client.
- */
-declare class HttpClient {
-    private readonly resolved;
-    private readonly timeout;
-    private readonly retryCount;
-    private readonly retryDelay;
-    private readonly fetchImpl;
-    constructor(resolved: ResolvedConfig, options?: HttpClientOptions);
-    /**
-     * Convenience for `request({ method: 'GET', path, ... })`. Kept so legacy
-     * callers (tests, pending facades) keep compiling — the deep work happens
-     * in `request()`.
-     */
-    get<T>(path: string, options?: RequestOptions): Promise<Result<T>>;
-    post<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
-    put<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
-    patch<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
-    delete<T>(path: string, options?: RequestOptions): Promise<Result<T>>;
-    /**
-     * The transport entry point every facade should target. Handles base-URL
-     * resolution, header injection, body/querystring serialisation, retry +
-     * timeout, response validation and HTTP→domain error remapping.
-     */
-    request<T>(req: TransportRequest<T>): Promise<Result<T>>;
-    private computeBackoff;
-}
-
-interface ApprovalToolSpec<I, O> {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    needsApproval?: boolean | ((input: I) => boolean | Promise<boolean>);
-    /**
-     * Maps the LLM input to the approval request fields. `topic` and `payload`
-     * default to the tool name and the raw input respectively when omitted;
-     * `onDecide` must always be supplied so the control plane knows where to
-     * deliver the eventual decision.
-     */
-    toRequest: (input: I) => Omit<ApprovalRequestOptions<I>, 'payload' | 'topic'> & Partial<Pick<ApprovalRequestOptions<I>, 'payload' | 'topic'>>;
-    execute: (input: I) => Promise<O> | O;
-}
-interface OpenAIToolSpec {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        parameters: Record<string, unknown>;
-    };
-}
-type ToolInvokeResult<O> = {
-    status: 'pending';
-    approvalId: string;
-    expiresAt: string;
-} | {
-    status: 'ok';
-    result: O;
-};
-interface ApprovalTool<I, O> {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    openaiSpec(): OpenAIToolSpec;
-    invoke(input: I): Promise<Result<ToolInvokeResult<O>>>;
-}
-
-interface VerifyOptions {
-    /** Override the signing key resolved from `STACKBONE_APPROVAL_SIGNING_KEY` / `approvalSigningKey`. */
-    signingKey?: string;
-    /** Reject signatures whose timestamp is older than this (seconds). Default 300. */
-    toleranceSeconds?: number;
-    /** Inject a clock for tests. Defaults to `Date.now`. */
-    now?: () => number;
-}
-
-type ApprovalTopic = string;
-declare const DECISION_STATUSES: readonly ["approved", "rejected", "timed_out", "cancelled"];
-type DecisionStatus = (typeof DECISION_STATUSES)[number];
-type ApprovalStatus = 'pending' | DecisionStatus;
-type Decision<T = unknown> = {
-    status: 'approved' | 'rejected';
-    payload: T;
-    approver: ApproverInfo;
-    decidedAt: string;
-    reason?: string;
-} | {
-    status: 'timed_out';
-    decidedAt: string;
-} | {
-    status: 'cancelled';
-    decidedAt: string;
-    reason?: string;
-};
-interface ApproverInfo {
-    id: string;
-    email: string;
-    name?: string;
-}
-interface ApprovalRequestOptions<T = unknown> {
-    topic: ApprovalTopic;
-    payload: T;
-    title?: string;
-    description?: string;
-    /** Path on the agent the control plane will POST the decision to (resolved against the agent's public URL server-side). */
-    onDecide: string;
-    /** ISO 8601 duration (`'24h'`) or milliseconds. Default 24h. */
-    timeout?: string | number;
-    onTimeout?: 'reject' | 'approve' | 'ignore';
-    approver?: string;
-    /** Same `(topic, idempotencyKey)` returns the same `approvalId` instead of creating a new one. */
-    idempotencyKey?: string;
-    metadata?: Record<string, unknown>;
-}
-interface ApprovalRequest {
-    approvalId: string;
-    status: 'pending';
-    callbackUrl: string;
-    expiresAt: string;
-}
-interface ApprovalRecord<T = unknown> {
-    approvalId: string;
-    topic: ApprovalTopic;
-    status: ApprovalStatus;
-    payload: T;
-    decision?: Decision<T>;
-    createdAt: string;
-    expiresAt: string;
-    metadata?: Record<string, unknown>;
-}
-interface ApprovalListOptions {
-    status?: ApprovalStatus;
-    topic?: ApprovalTopic;
-    cursor?: string;
-    /** 1..100. Default 50. */
-    limit?: number;
-}
-interface ApprovalListResult<T = unknown> {
-    items: ApprovalRecord<T>[];
-    nextCursor?: string;
-}
-declare class ApprovalFacade {
-    private readonly _resolved;
-    private readonly _http;
-    private readonly _gate;
-    constructor(_resolved: ResolvedConfig, _http: HttpClient, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    request<T = unknown>(options: ApprovalRequestOptions<T>): Promise<Result<ApprovalRequest>>;
-    cancel(approvalId: string, reason?: string): Promise<Result<void>>;
-    get<T = unknown>(approvalId: string): Promise<Result<ApprovalRecord<T>>>;
-    list<T = unknown>(options?: ApprovalListOptions): Promise<Result<ApprovalListResult<T>>>;
-    /**
-     * Local crypto verification — does not touch the datapath, so it is NOT
-     * gated by the contract handshake. Auditing rule: a method gates iff it
-     * issues an HTTP request to the configured baseUrl.
-     */
-    verify<T = unknown>(request: Request, options?: VerifyOptions): Promise<Result<Decision<T>>>;
-    /**
-     * Pure factory — returns an `ApprovalTool` whose `invoke()` ultimately
-     * calls back into `ApprovalFacade.request`, so the gate fires there. Not
-     * gated here.
-     */
-    tool<I, O>(spec: ApprovalToolSpec<I, O>): ApprovalTool<I, O>;
-}
-
-declare class ConfigFacade {
-    private readonly _http;
-    private readonly _gate;
-    constructor(resolved: ResolvedConfig, _http: HttpClient, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    get<T = unknown>(key: string): Promise<Result<T>>;
-    /**
-     * Keys absent from the agent's config come back as omissions in the
-     * response — the returned map only contains entries the control plane
-     * 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>>>;
-}
-
-declare class SecretsFacade {
-    private readonly _http;
-    private readonly _gate;
-    constructor(resolved: ResolvedConfig, _http: HttpClient, 
-    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
-    gate?: ModuleGate);
-    get(name: string): Promise<Result<string>>;
-    /**
-     * Names absent from the organization come back as omissions in the response —
-     * the returned map only contains entries the control plane actually has.
-     * Callers that need "all-or-nothing" semantics should diff the keys.
-     */
-    getMany(names: string[]): Promise<Result<Record<string, string>>>;
-}
-
-/**
- * `client.observability` — span processor + per-run JSONL/OTLP logger +
- * run-cost rollup. Local mode writes JSONL to `~/.stackbone/dev/runs/`; cloud
- * mode forwards OTLP/HTTP to the collector.
- *
- * Contract gating: not gated. Local writes touch the filesystem (no
- * Stackbone wire surface) and cloud writes go to OpenTelemetry, not the
- * Stackbone Agent Protocol — so there is no `Capability` to assert against.
- * No entry in `MODULE_CAPABILITIES` per the rule documented in
- * `contract/capability-registry.ts`.
- */
-declare class ObservabilityModule {
+
+declare class SecretsFacade {
     private readonly _resolved;
-    private _processor?;
-    private readonly _loggers;
-    private _sql;
-    private _sqlResolved;
-    constructor(_resolved: ResolvedConfig);
     /**
-     * Singleton SpanProcessor that the agent registers in its OTel
-     * TracerProvider. Coexists with the OTLP exporter — cloud builds wire
-     * both so Postgres feeds Studio (paridad con local) and Tempo feeds
-     * Platform Ops.
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
      */
-    spanProcessor(options?: RunStepsSpanProcessorOptions): RunStepsSpanProcessor;
-    flush(): Promise<Result<void>>;
+    private readonly _getDatabase;
+    private _cipher?;
+    constructor(_resolved: ResolvedConfig, 
     /**
-     * Per-run structured logger. In local mode (no `OTEL_EXPORTER_OTLP_ENDPOINT`)
-     * appends JSONL to `~/.stackbone/dev/runs/<runId>.jsonl`; in cloud mode batches
-     * OTLP/HTTP/JSON log records to the collector. Cached by `runId` so the
-     * file handle / buffered timer stays stable across repeated calls inside
-     * the same run.
+     * Lazy accessor for `client.database`. The facade pulls the shared
+     * `postgres-js` `Sql` via `getDatabase().shared().$client` — never
+     * reaching into a sibling module's implementation file.
      */
-    logger(options: {
-        runId: string;
-    } & Partial<PlatformLoggerOptions>): PlatformLogger;
-    /** Closes the per-run logger (flushes the JSONL file or the OTLP buffer). */
-    closeLogger(runId: string): Promise<void>;
+    _getDatabase: () => DatabaseModule);
+    get(name: string): Promise<Result<string>>;
     /**
-     * Hook the agent calls when a run finishes. Sums `cost_usd` from every
-     * `llm_call` span of the run and writes the total to
-     * `stackbone_platform.runs.cost_estimated_usd`. Errors are folded into the
-     * Result envelope so the agent's run cleanup never aborts on a flaky
-     * Postgres call — the cost is decorative metadata, not load-bearing.
+     * Names absent from the agent come back as omissions in the response — the
+     * returned map only contains entries the agent DB actually has. Callers that
+     * need "all-or-nothing" semantics should diff the keys.
      */
-    closeRun(runId: string): Promise<Result<AggregateRunCostResult>>;
-    private resolveSql;
+    getMany(names: string[]): Promise<Result<Record<string, string>>>;
+    private cipher;
+    private sql;
 }
 
 interface StorageObject {
@@ -1363,28 +1192,190 @@ declare class StorageBucket {
     private resolve;
 }
 
+/** Subset of `RequestInit['body']` we serialize without modification. */
+type SerializedBody = NonNullable<RequestInit['body']>;
+/**
+ * Per-status overrides facades attach when an HTTP status carries a
+ * non-canonical meaning for the endpoint — e.g. a `POST` whose `409` means
+ * "already exists" instead of the default "conflict". Keys are HTTP statuses,
+ * values are domain codes the transport should surface verbatim (no prefix
+ * concatenation — the override is the final code).
+ *
+ * The value is typed against the catalog (`SdkErrorCode`) so an endpoint
+ * cannot smuggle a wire code that isn't in the documented inventory.
+ */
+type ErrorOverrides = Record<number, SdkErrorCode>;
+/**
+ * Tells the transport how to remap HTTP status codes onto the surface's
+ * domain code prefix. `404 → '<prefix>_not_found'`, `401 → '<prefix>_unauthorized'`,
+ * etc. Endpoint-specific overrides win over the canonical mapping.
+ *
+ * `prefix` is constrained to `SdkErrorPrefix` (the catalog's prefix tuple) so
+ * an unknown surface name doesn't compile — keeps the wire codes the
+ * transport emits inside the typed inventory.
+ */
+interface ErrorMapping {
+    /** Prefix concatenated with `_not_found`, `_unauthorized`, …. Required for any domain remap. */
+    prefix: SdkErrorPrefix;
+    /** Per-status final code that overrides the canonical mapping. */
+    overrides?: ErrorOverrides;
+}
+interface RequestOptions extends Omit<RequestInit, 'body' | 'signal'> {
+    /** Scalar query params. `undefined` values are dropped, others get coerced via `String()`. */
+    params?: Record<string, string | number | boolean | undefined>;
+    /**
+     * Repeated string-array params validated and serialised by the transport.
+     * Empty arrays / blank elements reject upstream with `<prefix>_invalid_request`
+     * (falls back to `http_invalid_request` when no `errorMapping` is set). Each
+     * array is joined with `,` to match the canonical control-plane shape.
+     */
+    arrayParams?: Record<string, readonly string[]>;
+    body?: SerializedBody | Record<string, unknown> | unknown[] | null;
+    signal?: AbortSignal;
+    /** Allow retrying non-idempotent requests (POST, PATCH). Off by default to prevent duplicate writes. */
+    idempotent?: boolean;
+}
+/**
+ * Shape every facade method ideally collapses into: "POST to /path with this
+ * body, validate against this schema, surface errors as `<prefix>_*`". The
+ * transport handles validation, HTTP→domain remapping, querystring assembly
+ * and the `Result` envelope so facades stay tiny orchestrators.
+ *
+ * `arrayParams` keys default to `errorMapping.prefix` for the validation
+ * error code (e.g. an empty `names: []` becomes `secrets_invalid_request`).
+ */
+interface TransportRequest<T> extends RequestOptions {
+    method: string;
+    path: string;
+    /**
+     * Zod schema (or any object with a `.safeParse()` method) the parsed body
+     * must validate against. On failure the transport surfaces
+     * `<prefix>_invalid_response` (or `http_invalid_response` if no prefix is
+     * configured) with the schema issues attached to `meta.issues`.
+     */
+    responseSchema?: ResponseSchema<T>;
+    /** HTTP→domain remapping. Omit to let `http_*` codes flow through unchanged. */
+    errorMapping?: ErrorMapping;
+}
+/**
+ * Minimal contract the transport needs from a schema — `safeParse`. Compatible
+ * with Zod (`z.object(…).safeParse(value)`) and any hand-rolled validator that
+ * follows the same shape. Avoids leaking Zod's full surface into the transport
+ * signature.
+ */
+interface ResponseSchema<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: unknown;
+        };
+    };
+}
+interface HttpClientOptions {
+    /** Default 30_000. Set to 0 to disable. */
+    timeout?: number;
+    /** Default 3. Set to 0 to disable. */
+    retryCount?: number;
+    /** Initial backoff in ms; doubles each attempt with ±15% jitter. Default 500. */
+    retryDelay?: number;
+    /** Override the global fetch (useful for tests). */
+    fetch?: typeof fetch;
+}
 /**
- * OAuth connections (Notion, GDrive, Slack…).
+ * Shared HTTP client used by every facade that talks to the Stackbone
+ * control plane. Wraps `fetch` with timeout, exponential backoff with jitter,
+ * idempotent-only retries, response validation (Zod-compatible schemas) and
+ * a uniform `Result` envelope so facades never throw at the SDK boundary.
  *
- * Contract gating: not gated. The OAuth surface targets third-party
- * providers, not the Stackbone Agent Protocol, so there is no entry in
- * `MODULE_CAPABILITIES` (see `contract/capability-registry.ts`). When the
- * runtime lands and a Stackbone-mediated capability shows up (e.g. control
- * plane OAuth broker), we add the row and wire the gate.
+ * Each facade tells the transport its error prefix (`'secrets'`, `'config'`,
+ * `'approval'`) so 404/401/403/429/5xx remap to surface-specific codes —
+ * `secrets_not_found`, `approval_unauthorized`, etc. Endpoint-specific
+ * remaps (e.g. `409 → 'secrets_already_exists'`) flow through
+ * `errorMapping.overrides`. Transport-level failures (network, timeout,
+ * parse) keep the `http_*` prefix the README contract documents.
+ *
+ * Reads `STACKBONE_API_URL` and `STACKBONE_AGENT_JWT` lazily on every request so
+ * env-var rotation is picked up without restarting the client.
  */
-declare class ConnectionsFacade {
-    constructor(_resolved: ResolvedConfig, _http: HttpClient);
-    list(): Promise<Result<readonly never[]>>;
+declare class HttpClient {
+    private readonly resolved;
+    private readonly timeout;
+    private readonly retryCount;
+    private readonly retryDelay;
+    private readonly fetchImpl;
+    constructor(resolved: ResolvedConfig, options?: HttpClientOptions);
+    /**
+     * Convenience for `request({ method: 'GET', path, ... })`. Kept so legacy
+     * callers (tests, pending facades) keep compiling — the deep work happens
+     * in `request()`.
+     */
+    get<T>(path: string, options?: RequestOptions): Promise<Result<T>>;
+    post<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
+    put<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
+    patch<T>(path: string, body?: RequestOptions['body'], options?: RequestOptions): Promise<Result<T>>;
+    delete<T>(path: string, options?: RequestOptions): Promise<Result<T>>;
+    /**
+     * The transport entry point every facade should target. Handles base-URL
+     * resolution, header injection, body/querystring serialisation, retry +
+     * timeout, response validation and HTTP→domain error remapping.
+     */
+    request<T>(req: TransportRequest<T>): Promise<Result<T>>;
+    private computeBackoff;
 }
 
-/** Emit events to the organization event bus. */
-declare class EventsFacade {
+/** Options for `invoke`. */
+interface InvokeOptions {
+    /**
+     * Selector to disambiguate when the workspace holds several connections of the
+     * same connector. Accepts a connection **id** or a unique **name** (both are
+     * returned by `list()`). Omitted → the proxy resolves the sole connection, or
+     * fails `connections_ambiguous` when there is more than one.
+     */
+    connection?: string;
+}
+/**
+ * `client.connections` — the agent's handle on the workspace's connector
+ * connections. 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).
+ *
+ * - `list` returns the workspace's connections (connector id, label, auth kind,
+ *   health) — never any credential material — so the agent can adapt to what the
+ *   customer has connected.
+ * - `invoke(connector, action, args)` runs a connector action imperatively. The
+ *   control plane resolves the workspace's connection for `connector`, validates
+ *   `args` against the action's input schema, executes it, and returns the
+ *   validated output verbatim. `args` is opaque — the SDK forwards it untouched.
+ *
+ * Authentication reuses the existing `STACKBONE_AGENT_JWT` channel injected at
+ * provisioning (the `HttpClient` attaches the bearer + install header), so the
+ * control plane scopes every call to the agent's own install → organization.
+ *
+ * Contract gating: every method awaits the `connections.actions` module gate
+ * before touching the network, so a stale datapath / missing capability surfaces
+ * as a gating error rather than a failed request.
+ */
+declare class ConnectionsModule {
     private readonly _http;
     private readonly _gate;
     constructor(resolved: ResolvedConfig, _http: HttpClient, 
     /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
     gate?: ModuleGate);
-    emit(_name: string, _payload: unknown): Promise<Result<void>>;
+    /** List the workspace's connections (no credentials). */
+    list(): Promise<Result<AgentConnectionListResponse>>;
+    /**
+     * Invoke a connector action against the workspace's connection for that
+     * connector. `args` is forwarded opaquely; the control plane validates it
+     * against the action's own input schema and returns the validated output.
+     *
+     * When the workspace holds several connections of the same connector, pass
+     * `{ connection }` (a connection id or unique name) to pick one; omitting it
+     * with more than one connection fails `connections_ambiguous`.
+     */
+    invoke(connector: string, action: string, args: unknown, opts?: InvokeOptions): Promise<Result<InvokeConnectorActionResponse>>;
 }
 
 /**
@@ -1506,95 +1497,66 @@ declare class MemoryModule {
 }
 
 /**
- * A prompt managed by the Stackbone control plane. Templates are plain strings
- * with Mustache-style `{{var}}` placeholders — no conditionals or loops.
+ * Enqueue a one-shot (or deferred) job. The opaque `payload` is whatever the
+ * agent's `receive` handler expects — the core never inspects it.
  */
-interface Prompt {
+interface PublishRequest {
+    /** Opaque job name (e.g. `send-email`). Surfaced in the Studio inspector. */
     name: string;
-    template: string;
-    /** Monotonically increasing per `name`. The first `create` produces version `1`. */
-    version: number;
-    /** Variable names parsed from the template. */
-    variables?: readonly string[];
-    metadata?: Record<string, unknown>;
-    /** ISO 8601 UTC timestamp. */
-    createdAt: string;
-    updatedAt: string;
-}
-interface GetPromptOptions {
-    /** Pin a specific version. Omitted -> latest. */
-    version?: number;
-}
-interface ListPromptsOptions {
-    /** 1..100. Default 50. */
-    limit?: number;
-    cursor?: string;
-}
-interface ListPromptsResult {
-    /** Latest version of each prompt. */
-    items: readonly Prompt[];
-    nextCursor?: string;
+    /** Opaque job payload — JSON-serialisable; the core forwards it untouched. */
+    payload: unknown;
+    /** Per-job override of the platform retry default. Omitted → platform default. */
+    retries?: number;
+    /** Deferred delivery in milliseconds. Omitted / 0 → immediate. */
+    delay?: number;
+    /** Idempotency hint — a duplicate publish with the same key collapses to one job. */
+    deduplicationId?: string;
 }
-interface CreatePromptRequest {
+/** Register / update a dynamic per-installation cron schedule. */
+interface ScheduleRequest {
+    /** Schedule name, unique per install. Re-scheduling the same name updates it in place. */
     name: string;
-    template: string;
-    metadata?: Record<string, unknown>;
-}
-interface UpdatePromptOptions {
-    /** New template. Bumps `version` by one. */
-    template?: string;
-    /** Shallow-merged onto the existing metadata. */
-    metadata?: Record<string, unknown>;
-}
-interface DeletePromptOptions {
-    /** Delete a specific version. Omitted -> delete every version under `name`. */
-    version?: number;
+    /** Opaque payload delivered on every fire. */
+    payload: unknown;
+    /** Cron expression evaluated by the dispatcher. */
+    cron: string;
+    /** IANA timezone the cron pattern runs in. Defaults to UTC. */
+    tz?: string;
+    /** Per-job override of the platform retry default. */
+    retries?: number;
 }
-interface DeletePromptResult {
+/** Cancel a previously registered schedule by name. */
+interface UnscheduleRequest {
     name: string;
-    /** Number of versions actually removed. */
-    deleted: number;
 }
 /**
- * `client.prompts` — managed prompts for the agent. Prompts live outside the
- * code so creators can edit, version and A/B test them without rebuilding the
- * container. The first iteration is a scaffolding placeholder: every method
- * returns `not_implemented`. The real backend will be the Stackbone control
- * plane and the public surface defined here is the contract callers can
- * already type against.
+ * `client.queues` — the agent's handle on the BullMQ-backed job system. The
+ * agent never touches Redis: each method makes an authenticated call to the
+ * control plane (the dispatcher owns the queue + the clock).
  *
- * Contract gating: not gated yet. Prompts will eventually talk to the
- * Stackbone control plane, but no `Capability` has been declared for it
- * (no entry in `MODULE_CAPABILITIES` — see `contract/capability-registry.ts`).
- * When the runtime lands we add the row (e.g. `prompts.read_write`) and
- * wire the gate the same way `secrets` / `config` do.
+ * - `publish` enqueues a one-shot job (optionally deferred via `delay`, with a
+ *   per-job `retries` override and an optional `deduplicationId`).
+ * - `schedule` / `unschedule` manage dynamic per-user cron schedules.
+ * - `listSchedules` lists the install's active schedules.
+ *
+ * Authentication reuses the existing `STACKBONE_AGENT_JWT` channel injected at
+ * provisioning (the `HttpClient` attaches the bearer + install header), so the
+ * core scopes every enqueue to the agent's own install.
+ *
+ * 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.
  */
-declare class PromptsFacade {
-    constructor(_resolved: ResolvedConfig, _http: HttpClient);
-    get(_name: string, _options?: GetPromptOptions): Promise<Result<Prompt>>;
-    compile(_name: string, _variables: Record<string, unknown>, _options?: GetPromptOptions): Promise<Result<string>>;
-    list(_options?: ListPromptsOptions): Promise<Result<ListPromptsResult>>;
-    create(_request: CreatePromptRequest): Promise<Result<Prompt>>;
-    update(_name: string, _options: UpdatePromptOptions): Promise<Result<Prompt>>;
-    delete(_name: string, _options?: DeletePromptOptions): Promise<Result<DeletePromptResult>>;
-}
-
-interface PublishRequest {
-    url: string;
-    body: unknown;
-    retries?: number;
-    delay?: number;
-    deduplicationId?: string;
-    headers?: Record<string, string>;
-}
 declare class QueuesModule {
+    private readonly _http;
     private readonly _gate;
-    constructor(resolved: ResolvedConfig, 
+    constructor(resolved: ResolvedConfig, _http: HttpClient, 
     /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
     gate?: ModuleGate);
-    publish(_request: PublishRequest): Promise<Result<{
-        messageId: string;
-    }>>;
+    publish(request: PublishRequest): Promise<Result<PublishJobResponse>>;
+    schedule(request: ScheduleRequest): Promise<Result<ScheduleJobResponse>>;
+    unschedule(request: UnscheduleRequest): Promise<Result<UnscheduleJobResponse>>;
+    listSchedules(): Promise<Result<ListSchedulesResponse>>;
 }
 
 /**
@@ -1603,18 +1565,25 @@ declare class QueuesModule {
  * groups each surface by where its state lives:
  *
  * - `surfaces/agent-local/` — Postgres branch owned by the agent
- *   (`database`, `rag`).
+ *   (`database`, `rag`, `secrets`, `config`, `approval`). `secrets`,
+ *   `config` and `approval` moved here from the control plane: the agent now
+ *   reads its secrets/config and records HITL pauses directly against its own
+ *   `stackbone_platform.*` tables (decrypting secrets with the per-agent key),
+ *   with no control-plane round-trip. The approval RESUME callback stays
+ *   Studio-signed and is reconciled locally by `approval.verify()`.
  * - `surfaces/external/` — managed partner SDKs the SDK wraps directly
- *   (`ai` / OpenRouter, `storage` / S3 + R2 / MinIO, `observability` /
- *   OpenTelemetry).
+ *   (`ai` / OpenRouter, `storage` / S3 + R2 / MinIO). Observability is not a
+ *   creator surface: agent code observes runs through the handler-scoped
+ *   `ctx.logger` (and plain `console.*`, which the wrapper captures and
+ *   correlates), while the platform primitives live in the
+ *   `@stackbone/sdk/observability` subpath the runtime wires directly.
  * - `surfaces/control-plane/` — thin HTTP calls to Stackbone's control
- *   plane (`approval`, `secrets`, `config`).
+ *   plane (none today after secrets/config/approval moved agent-local).
  * - `surfaces/pending/` — public surface is stable but the runtime is
  *   not built yet. They are wired as live `client.X` accessors so MVP
  *   agent code can be authored against the eventual contract today; each
  *   method returns `Result<{ error: { code: "not_implemented" } }>` until
- *   the backing runtime ships. Today: queues, memory, prompts,
- *   connections, events.
+ *   the backing runtime ships. Today: queues, memory.
  *
  * Each accessor builds its surface on first access and caches it — env
  * vars and partner SDK init costs are paid only when the agent actually
@@ -1632,15 +1601,13 @@ declare class StackboneClient {
     private _storage?;
     private _ai?;
     private _rag?;
-    private _observability?;
     private _approval?;
     private _secrets?;
     private _config?;
     private _queues?;
+    private _connections?;
     private _memory?;
-    private _events?;
     private _prompts?;
-    private _connections?;
     private _httpClient?;
     private readonly _contractStore;
     constructor(resolved: ResolvedConfig);
@@ -1649,18 +1616,27 @@ declare class StackboneClient {
     get storage(): StorageModule;
     get ai(): AiModule;
     get rag(): RagModule;
-    get observability(): ObservabilityModule;
     get approval(): ApprovalFacade;
     get secrets(): SecretsFacade;
     get config(): ConfigFacade;
     /**
-     * Pending surface — runtime not built. Every method returns
-     * `not_implemented` so MVP agent code can wire against the eventual
-     * contract today and switch over the day the backing runtime ships.
-     * Gated against `queues.pgmq` so the handshake-blocked / capability-
-     * missing paths are exercised the same way as the live surfaces.
+     * Live surface — the agent's handle on the BullMQ-backed job system.
+     * `publish` / `schedule` / `unschedule` / `listSchedules` make authenticated
+     * calls to the control-plane dispatcher (`/api/v1/agent/queues/*`); the
+     * agent never touches Redis. Gated against `queues.jobs` so the
+     * handshake-blocked / capability-missing paths are exercised the same way
+     * as the other gated surfaces.
      */
     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
+     * container. Gated against `connections.actions` so the handshake-blocked /
+     * capability-missing paths are exercised the same way as the other gated
+     * surfaces.
+     */
+    get connections(): ConnectionsModule;
     /**
      * Pending surface — runtime not built. Every method returns
      * `not_implemented`. Mem0 is a third-party integration, not a Stackbone
@@ -1668,23 +1644,14 @@ declare class StackboneClient {
      */
     get memory(): MemoryModule;
     /**
-     * Pending surface — runtime not built. Every method returns
-     * `not_implemented`. Gated against `events.bus` so handshake errors
-     * surface symmetrically with the other control-plane facades.
-     */
-    get events(): EventsFacade;
-    /**
-     * Pending surface — runtime not built. Every method returns
-     * `not_implemented`. Will gate once a capability row is declared in
-     * `MODULE_CAPABILITIES`; until then it is intentionally ungated.
+     * Live agent-local surface — reads prompts from `stackbone_platform.prompts`
+     * in the agent DB over the shared `client.database` pool and compiles
+     * templates with the local `@stackbone/prompt-compiler`. Constructed with
+     * the same `(resolved, () => this.database)` shape as `secrets`/`config`;
+     * like them it is NOT wired to the control-plane handshake gate (it talks to
+     * the agent's own tables, not a control-plane datapath).
      */
     get prompts(): PromptsFacade;
-    /**
-     * Pending surface — runtime not built. Returns an empty list today.
-     * Connections target third-party OAuth providers, not the Stackbone
-     * Agent Protocol, so this surface is intentionally not gated.
-     */
-    get connections(): ConnectionsFacade;
     /**
      * Read-only view of the most recently resolved Stackbone Agent Protocol
      * contract for this client's `stackboneApiUrl`. Returns `null` until a
@@ -1781,13 +1748,13 @@ interface InvokeContext<I extends z.ZodType> {
     logger: Logger;
 }
 /**
- * The single `invoke` capability the creator exposes. Mirrors the wrapper's
- * three HTTP verbs (`/invoke`, `/health`, `/schema`) — F1 lands only the
- * invoke half; `/health` and `/schema` land in later slices.
+ * The synchronous `invoke` capability. Mirrors the wrapper's three HTTP verbs
+ * (`/invoke`, `/health`, `/schema`): `invoke` is the only request path, its
+ * `output` is the `/invoke` response body, and its schemas drive `/schema`.
  *
  * The fields are deliberately enumerated (no `[k: string]: unknown` escape
- * hatch) so the parent `AgentSpec` can reject unknown keys at the type level
- * via `keyof` checks downstream.
+ * hatch) so the precise type the creator gets from `defineAgent` rejects
+ * unknown keys on the block at compile time.
  */
 interface InvokeCapability<I extends z.ZodType, O extends z.ZodType> {
     /** Zod schema for the parsed `/invoke` request body. */
@@ -1796,47 +1763,232 @@ interface InvokeCapability<I extends z.ZodType, O extends z.ZodType> {
     output: O;
     /** Creator-supplied handler. Returns either the parsed output or a promise of it. */
     run: (ctx: InvokeContext<I>) => z.infer<O> | Promise<z.infer<O>>;
-    /** Optional per-invocation timeout in milliseconds. Wired by a later slice. */
+    /** Optional per-invocation timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * A named **job handler** — a sibling of `invoke` at the top level of the spec,
+ * reached asynchronously via `client.queues.publish({ name })` (the BullMQ
+ * dispatcher pushes the job back to `/invoke` with that name; the wrapper routes
+ * it here instead of to `invoke.run`).
+ *
+ * Same shape as `invoke` with one difference: `output` is **optional**. A job is
+ * fire-and-forget — the dispatcher only checks the 2xx, the return value is
+ * journalled, not delivered to a caller. Declaring `output` self-validates the
+ * job's result; omitting it lets `run` return anything (or nothing).
+ */
+interface JobCapability<I extends z.ZodType, O extends z.ZodType = z.ZodType> {
+    /** Zod schema for the job payload (`publish`'s `payload`, revalidated here). */
+    input: I;
+    /** Optional Zod schema for the job's return value. Validated + journalled, never returned. */
+    output?: O;
+    /** Creator-supplied job handler. May return nothing — the result is not delivered. */
+    run: (ctx: InvokeContext<I>) => z.infer<O> | void | Promise<z.infer<O> | void>;
+    /** Optional per-job timeout in milliseconds. */
     timeoutMs?: number;
 }
 /**
- * The declarative shape every Stackbone agent returns from `src/index.ts`.
+ * Loose, non-generic view of a single capability (invoke or a job handler).
+ * The wrapper / `loadSpec` read the spec through this — the precise per-handler
+ * typing lives on the value `defineAgent` returns to the creator, not here.
  *
- * `AgentSpec` is a closed object: the keys are listed explicitly so adding
- * `{ invoke, anyOtherKey }` at the call site fails `tsc`. The corresponding
- * runtime guard in `defineAgent` enforces the same invariant against callers
- * that bypass the type system through `as any`.
+ * `run` is a method signature (not an arrow property) on purpose: it makes the
+ * parameter bivariant so every concrete `InvokeCapability` / `JobCapability`
+ * (whose `run` is typed against its own narrow input) is assignable to it, which
+ * is what lets `AgentSpec` carry a string index signature of capabilities.
+ */
+interface AnyCapability {
+    input: z.ZodType;
+    output?: z.ZodType | undefined;
+    run(ctx: InvokeContext<z.ZodType>): unknown;
+    timeoutMs?: number | undefined;
+}
+/**
+ * The declarative shape every Stackbone agent returns from `src/index.ts`, as
+ * the wrapper / `loadSpec` consume it: the **loose runtime view**. Every
+ * capability — `invoke` and each named job handler — is an `AnyCapability`
+ * (`output` optional, `run` loose). `invoke` is required; the string index
+ * carries the job handlers, reached by name through the BullMQ dispatcher.
  *
- * `health` and other capabilities will join `invoke` as they land — every
- * addition is an explicit, reviewable edit to this type.
+ * The precise per-handler typing (each `ctx.input` inferred, `invoke.output`
+ * required) lives on the value `defineAgent` returns, which is assignable to
+ * this. At runtime `invoke.output` is always present — the spec seed forces it —
+ * so the wrapper reads it behind a small guard.
  */
-interface AgentSpec<I extends z.ZodType, O extends z.ZodType> {
-    invoke: InvokeCapability<I, O>;
+interface AgentSpec {
+    /** The synchronous entry: the `/invoke` response + the `GET /schema` source. */
+    invoke: AnyCapability;
+    /** Named job handlers, reached via `client.queues.publish({ name })`. */
+    [name: string]: AnyCapability;
 }
 /**
- * Hard ceiling on `invoke.timeoutMs`. The platform saga kills the Machine
- * before the wrapper would time out at higher values, so a creator declaring
- * a 10-minute timeout would publish a contract the runtime cannot keep.
- * Surface that conflict at boot instead of as a mysterious mid-invocation
+ * Top-level keys the platform owns. A job handler may not use these names.
+ * Only `invoke` for now; the contract adds `health` / `schema` / `events` /
+ * `schedules` here if/when they become declarable capabilities (see the named
+ * job handlers ADR).
+ */
+declare const RESERVED_HANDLER_NAMES: readonly ["invoke"];
+/**
+ * Hard ceiling on any capability's `timeoutMs`. The platform saga kills the
+ * Machine before the wrapper would time out at higher values, so a creator
+ * declaring a 10-minute timeout would publish a contract the runtime cannot
+ * keep. Surface that conflict at boot instead of as a mysterious mid-invocation
  * SIGKILL in production.
  */
 declare const INVOKE_TIMEOUT_HARD_CAP_MS = 300000;
 /**
- * Identity function with two jobs:
+ * One handler block, generic **directly** on its input Zod schema `I`. `input: I`
+ * is a single-level type parameter (not a nested indexed access like
+ * `S['input']`), which is the shape TypeScript can invert when reading the spec
+ * literal back — so every handler's `ctx.input` is inferred from its own schema.
+ * `output` stays loose (`z.ZodType`) and `run`'s return is `unknown`: a handler's
+ * result is validated against `output` at runtime (the wrapper), not at the type
+ * layer, so output inference is not needed for the contract to hold.
+ */
+type HandlerBlock<I extends z.ZodType> = {
+    input: I;
+    output?: z.ZodType;
+    run: (ctx: InvokeContext<I>) => unknown | Promise<unknown>;
+    timeoutMs?: number;
+};
+/**
+ * Per-key precise shape of the spec the creator writes. `T` maps each handler
+ * name to its **input** schema; `[K in keyof T]: HandlerBlock<T[K]>` is a
+ * homomorphic mapped type whose value (`input: T[K]`) is a single-level access,
+ * so TypeScript infers `T` back from the literal and keeps the concrete key
+ * names. The `& { invoke: ... }` arm makes `invoke` required and forces its
+ * `output` to be present (a job's `output` is optional).
+ */
+type AgentSpecParam<T extends Record<string, z.ZodType>> = {
+    [K in keyof T]: HandlerBlock<T[K]>;
+} & {
+    invoke: {
+        input: z.ZodType;
+        output: z.ZodType;
+    };
+};
+/**
+ * Anchor + guard for `defineAgent`:
  *
- * 1. **Inference anchor** — pins the input/output Zod schemas so creators get
- *    a fully typed `ctx.input` and a typed return value inside `run` without
- *    repeating themselves.
- * 2. **Boot-time invariant** — throws on any unknown top-level or invoke-block
- *    key. This is the safety net for creators that force a shape through
- *    `as any`; the type system already rejects this, but the wrapper PRD's
- *    "impossible to break the contract from creator code" success criterion
- *    requires the runtime check too.
+ * 1. **Inference anchor** — each handler (`invoke` and every named job) infers
+ *    its own `ctx.input` from its `input` schema. The creator never repeats a
+ *    type.
+ * 2. **Boot-time invariant** — `invoke` is required; every other top-level key
+ *    must be a valid handler object reached via `client.queues.publish({ name })`.
+ *    The TypeScript signature already shapes this; the runtime guard is the
+ *    safety net for creators forcing a shape through `as any`.
  *
  * Returns the spec verbatim so callers can `export default defineAgent({...})`
  * and the wrapper can read the same object back through dynamic import.
  */
-declare const defineAgent: <I extends z.ZodType, O extends z.ZodType>(spec: AgentSpec<I, O>) => AgentSpec<I, O>;
+declare function defineAgent<T extends Record<string, z.ZodType>>(spec: AgentSpecParam<T>): {
+    [K in keyof T]: HandlerBlock<T[K]>;
+};
+
+interface InvocationContext {
+    /** The envelope's `invocationId` — surfaced on log lines as `trace_id`. */
+    readonly invocationId: string;
+    /** The run this invoke belongs to — surfaced on log lines as `run_id`. */
+    readonly runId: string;
+    /**
+     * The handler this invoke routed to — `invoke` for a direct entry or the
+     * named job handler (e.g. `demo-log-job`) the dispatcher delivered to.
+     * Surfaced on log lines as `handler` so the Studio logs trail can tell which
+     * entrypoint emitted each line. Optional so a caller that binds a context
+     * without routing info (older tests, lifecycle hooks) still type-checks.
+     */
+    readonly handler?: string;
+}
+/**
+ * Runs `fn` with `context` bound as the active invocation. The context stays
+ * available to every synchronous and asynchronous continuation rooted in this
+ * call (i.e. across `await`s inside `fn`). Returns whatever `fn` returns.
+ */
+declare function runWithInvocationContext<T>(context: InvocationContext, fn: () => T): T;
+/**
+ * Returns the active invocation context, or `undefined` when called outside any
+ * invoke (process boot, lifecycle events, tests that don't set one up).
+ */
+declare function getInvocationContext(): InvocationContext | undefined;
+
+/** The subset of the global `console` this bridge replaces. */
+interface ConsoleLike {
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+}
+interface InstallConsoleCaptureOptions {
+    /** Console object to patch. Defaults to the global `console`. Test seam. */
+    console?: ConsoleLike;
+    /** Sink for `log` / `info` / `debug`. Defaults to `process.stdout`. Test seam. */
+    stdout?: LogSink;
+    /** Sink for `warn` / `error`. Defaults to `process.stderr`. Test seam. */
+    stderr?: LogSink;
+    /** Clock for the `ts` field. Defaults to `() => new Date()`. Test seam. */
+    now?: () => Date;
+}
+/**
+ * Replaces `console.log/info/debug/warn/error` so that, while an invocation
+ * context is active, each call is re-emitted as a structured log line carrying
+ * `run_id` / `trace_id`. Returns a function that restores the originals.
+ * Calling it twice on the same console is a no-op (returns a no-op restore).
+ */
+declare function installInvocationConsoleCapture(options?: InstallConsoleCaptureOptions): () => void;
+
+declare const STORED_TO_SDK_ENV: Readonly<Record<string, string>>;
+/** Encrypted envelope row as stored in `stackbone_platform.secrets`. */
+interface SystemSecretRow {
+    name: string;
+    version: string;
+    nonce: Buffer | Uint8Array;
+    ciphertext: Buffer | Uint8Array;
+}
+/**
+ * Maps the `is_system` rows to the SDK env names, decrypting ONLY the rows that
+ * have a known mapping, then derives two env-only channels. Existing values are
+ * never overwritten (an explicit container/Machine override always wins). The
+ * SDK env names this call populated are returned (sorted) so the caller can log
+ * an observable, value-free "what got rehydrated" line — values are never
+ * logged. Shared by both the cloud neon reader and the postgres-js reader so
+ * they cannot drift on the mapping.
+ *
+ * Decryption is lazy on purpose: an unmapped stored row is skipped WITHOUT
+ * decrypting it, so a non-envelope row (e.g. a probe row a stubbed query
+ * returns) never throws. The two derived channels:
+ *   - `STACKBONE_POSTGRES_URL` from `databaseUrl` (the SDK's `client.database`
+ *     reads this name; the cloud harness's own Neon driver keeps `DATABASE_URL`).
+ *   - `STACKBONE_APPROVAL_SIGNING_KEY` from `HMAC_SECRET` so the SDK's approval
+ *     callback verifier reconciles with the signer (which signs with the same
+ *     boot-bundle HMAC).
+ */
+declare function rehydrateSystemSecretsRows(env: NodeJS.ProcessEnv, rows: readonly SystemSecretRow[], cipher: SecretCipher, databaseUrl: string): string[];
+/**
+ * Reads the `is_system` rows from `stackbone_platform.secrets`. Injectable so
+ * tests run against a stub without a real Postgres; production opens a
+ * short-lived `postgres-js` connection (see `loadSystemSecretsIntoEnv`).
+ */
+type SystemSecretsReader = () => Promise<SystemSecretRow[]>;
+interface LoadSystemSecretsArgs {
+    /** Connection string for the agent's Postgres (`STACKBONE_POSTGRES_URL`). */
+    readonly databaseUrl: string;
+    /** Per-agent base64 key the rows are decrypted with (`STACKBONE_SECRET_KEY`). */
+    readonly secretKey: string;
+    /** Target env to populate. Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override the row reader (tests inject a stub). */
+    readonly reader?: SystemSecretsReader;
+}
+/**
+ * Reads every `is_system` row from the agent's Postgres via `postgres-js`,
+ * decrypts each with the per-agent key, and rehydrates them into `env` under
+ * the SDK's expected names. Used by the `stackbone dev` emulator and the
+ * self-host runtime entry to give the agent the same credentials the cloud
+ * harness rehydrates — without depending on a Neon HTTP endpoint, which local
+ * dev does not have.
+ */
+declare function loadSystemSecretsIntoEnv(args: LoadSystemSecretsArgs): Promise<string[]>;
 
 /**
  * Reserved error codes. Order is intentional: keep them flat (string) so
@@ -1968,4 +2120,4 @@ interface JsonSchemaDocument {
  */
 declare const analyzeAgentSchemas: (pair: AgentSchemaPair) => SchemaIntrospectionResult;
 
-export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ChunkOptions, type ChunkStrategy, type ClientConfig, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeleteOptions, type DeletePromptOptions, type DeletePromptResult, type DeleteResponse, 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 IngestChunk, type IngestRequest, type IngestRequestAutoEmbed, type IngestRequestPrecomputed, type IngestResponse, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeRequest, type InvokeResponse, type InvokeSuccessEnvelope, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type ParseInput, type ParseOptions, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RUN_ID_HEADER, type RagIngestProgress, type ReservedErrorCode, type Result, type RetrieveHit, type RetrieveRequest, type RetrieveRequestAutoEmbed, type RetrieveRequestPrecomputed, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StorageBody, type StorageObject, type StructuredLoggerOptions, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode };
+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 };