@stackbone/sdk 0.1.0-alpha.0

package/index.d.ts

@@ -0,0 +1,1325 @@
+import { ContractResponse } from '@stackbone/validators';
+import OpenAI from 'openai';
+import { ChatCompletionCreateParamsStreaming, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletion, EmbeddingCreateParams, CreateEmbeddingResponse, ChatCompletionMessageParam } from 'openai/resources';
+import { Stream } from 'openai/streaming';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { Sql } from 'postgres';
+import { S3Client } from '@aws-sdk/client-s3';
+
+/**
+ * Optional overrides accepted by `createClient`. All fields are optional;
+ * modules fall back to the corresponding upstream env var on first access.
+ */
+interface ClientConfig {
+    /** Ed25519 JWT signed by the control plane. Falls back to `STACKBONE_AGENT_JWT`. */
+    agentJwt?: string;
+    /** Stackbone control plane base URL used by the facade HttpClient. Falls back to `STACKBONE_API_URL`. */
+    stackboneApiUrl?: string;
+    /** Stable agent identifier injected at provisioning. Falls back to `STACKBONE_AGENT_ID`. Used as the multi-tenant key prefix in `client.storage`. */
+    agentId?: string;
+    /**
+     * Postgres connection string consumed by `client.rag` and the platform
+     * observability exporter. Falls back to `DATABASE_URL`. Note: `client.database`
+     * uses `STACKBONE_POSTGRES_URL` instead — the two env vars are intentionally
+     * different so that the SDK's own DB pool stays decoupled from the legacy
+     * `DATABASE_URL` consumers until `feature 30` consolidates them.
+     */
+    databaseUrl?: 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;
+    /** mem0 API base URL. Falls back to `MEM0_BASE_URL` (defaults to mem0 cloud when unset). */
+    mem0BaseUrl?: string;
+    /** HMAC key the control plane uses to sign approval-decision callbacks. Falls back to `STACKBONE_APPROVAL_SIGNING_KEY`. */
+    approvalSigningKey?: string;
+    /**
+     * Identifies the install the agent runs inside. Sent as the
+     * `X-Stackbone-Installation-Id` header when the SDK talks to the control
+     * plane. Falls back to `STACKBONE_INSTALLATION_ID`.
+     * TODO(studio-v1): remove once `STACKBONE_AGENT_JWT` carries the install id
+     * and `apps/api` derives it from the bearer instead of an explicit header.
+     */
+    installationId?: string;
+    s3?: {
+        /** Falls back to `AWS_ACCESS_KEY_ID`. */
+        accessKeyId?: string;
+        /** Falls back to `AWS_SECRET_ACCESS_KEY`. */
+        secretAccessKey?: string;
+        /** Falls back to `S3_ENDPOINT`. */
+        endpoint?: string;
+        /** Physical R2/S3 bucket scoped to the agent. Falls back to `S3_BUCKET`. */
+        bucket?: string;
+    };
+    otel?: {
+        exporterOtlpEndpoint?: string;
+        resourceAttributes?: string;
+    };
+    /**
+     * RAG-related defaults parsed from `agent.yaml.rag` by the CLI/orchestrator
+     * and forwarded here. The SDK never reads `agent.yaml` itself — keeping
+     * filesystem ownership in the CLI. Defaults follow ADR
+     * `2026-05-10-rag-consolidation-on-client-database` (D2/D6).
+     */
+    rag?: {
+        /**
+         * Embedding model used by `client.rag.ingest`/`retrieve` when the caller
+         * omits `model`. Defaults to `openai/text-embedding-3-small`.
+         */
+        embeddingModel?: string;
+    };
+    /**
+     * Creator-side floor on the negotiated Stackbone Agent Protocol contract
+     * version. Sourced from `agent.yaml.protocol.required` by the
+     * CLI/orchestrator (the SDK never reads `agent.yaml` itself). When set and
+     * the datapath's negotiated `contract.version` is below this value, every
+     * gated module call returns `SdkError('contract_version_unsupported',
+     * { detected, required })` — independent of per-module capability gating.
+     * When omitted, the SDK uses `MIN_SUPPORTED_CONTRACT_VERSION` as the
+     * implicit floor (i.e. behaviour matches slice F5).
+     */
+    protocolRequired?: number;
+}
+/**
+ * `env` is a live reference to `process.env` (not a snapshot) so tests that
+ * mutate the environment between `createClient()` and the first module access
+ * still observe the new values via the lazy initialisers.
+ */
+interface ResolvedConfig {
+    config: Readonly<ClientConfig>;
+    env: NodeJS.ProcessEnv;
+}
+
+/**
+ * Uniform error envelope returned by every SDK method. `cause` and `meta` are
+ * optional escape hatches so wrappers can attach upstream errors / context
+ * without breaking the public shape.
+ */
+interface SdkError {
+    code: string;
+    message: string;
+    cause?: unknown;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Discriminated result the entire SDK returns. Narrowing on `result.error`
+ * automatically refines `result.data` to `T`.
+ */
+type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: SdkError;
+};
+
+/**
+ * Async predicate every gated SDK module awaits before forwarding to its
+ * underlying implementation. Returns ok when the negotiated contract clears
+ * the module's gate (or the escape hatch suppresses a gating error); returns
+ * an error envelope otherwise — the caller propagates it back as the public
+ * `Result<T>` of the method.
+ *
+ * Test seam — every gated module exposes an optional `gate` constructor
+ * argument that defaults to `createModuleGate(<id>, resolved)`. Specs inject
+ * a stub returning a synthetic `Result<undefined>` to exercise the gating
+ * paths (ok / `contract_version_unsupported` / `capability_unavailable` /
+ * `contract_unreachable`) without driving a real handshake.
+ */
+type ModuleGate = () => Promise<Result<undefined>>;
+
+/** Subset of `RequestInit['body']` we serialize without modification. */
+type SerializedBody = NonNullable<RequestInit['body']>;
+interface RequestOptions$1 extends Omit<RequestInit, 'body' | 'signal'> {
+    params?: Record<string, 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;
+}
+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 the control-plane facades (approval, secrets,
+ * connections, config, events). Wraps `fetch` with timeout, exponential
+ * backoff with jitter, idempotent-only retries, and a uniform Result
+ * envelope so facades never throw at the SDK boundary.
+ *
+ * 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);
+    get<T>(path: string, options?: RequestOptions$1): Promise<Result<T>>;
+    post<T>(path: string, body?: RequestOptions$1['body'], options?: RequestOptions$1): Promise<Result<T>>;
+    put<T>(path: string, body?: RequestOptions$1['body'], options?: RequestOptions$1): Promise<Result<T>>;
+    patch<T>(path: string, body?: RequestOptions$1['body'], options?: RequestOptions$1): Promise<Result<T>>;
+    delete<T>(path: string, options?: RequestOptions$1): Promise<Result<T>>;
+    request<T>(method: string, path: string, options?: RequestOptions$1): 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>>>;
+}
+
+/** OAuth connections (Notion, GDrive, Slack…). */
+declare class ConnectionsFacade {
+    private readonly _resolved;
+    private readonly _http;
+    constructor(_resolved: ResolvedConfig, _http: HttpClient);
+    list(): Promise<Result<readonly never[]>>;
+}
+
+/** Emit events to the workspace event bus. */
+declare class EventsFacade {
+    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>>;
+}
+
+/**
+ * A prompt managed by the Stackbone control plane. Templates are plain strings
+ * with Mustache-style `{{var}}` placeholders — no conditionals or loops.
+ */
+interface Prompt {
+    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;
+}
+interface CreatePromptRequest {
+    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;
+}
+interface DeletePromptResult {
+    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.
+ */
+declare class PromptsFacade {
+    private readonly _http;
+    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>>;
+}
+
+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 workspace 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>>>;
+}
+
+/**
+ * Public surface behind `client.ai`. Wraps the official `openai` SDK with a
+ * `baseURL` override pointing to OpenRouter, so 300+ models are reachable
+ * with a single, OpenAI-compatible API.
+ *
+ * Lazy: the underlying `OpenAI` client is built on the first method call
+ * (or the first time a sub-namespace is touched) so env vars mutated after
+ * `createClient()` are still picked up — same pattern as `DatabaseModule`.
+ *
+ * Error model: every method returns `Result<T>`. Upstream `APIError`s are
+ * mapped to `SdkError` with stable `ai_*` codes. For streaming, the
+ * `Result` envelope only covers connection establishment; once the stream
+ * is open, mid-flight errors propagate through the iterator — callers must
+ * wrap their `for await` loop in `try/catch`. Aborts via `signal.abort()`
+ * surface as `ai_aborted` in non-streaming requests; in streaming, the
+ * iterator simply terminates (the upstream SDK swallows the abort).
+ *
+ * Test override: pass `clientOverride` to inject a pre-built `OpenAI`
+ * instance (or a stand-in) instead of letting the module build one. The
+ * override flows to all four namespaces — `models.list()` included.
+ */
+declare class AiModule {
+    private readonly _resolved;
+    private _openai;
+    private _chat;
+    private _embeddings;
+    private _images;
+    private _models;
+    private readonly _gate;
+    constructor(_resolved: ResolvedConfig, clientOverride?: OpenAI, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
+    gate?: ModuleGate);
+    get chat(): {
+        completions: ChatCompletionsNamespace;
+    };
+    get embeddings(): EmbeddingsNamespace;
+    get images(): ImagesNamespace;
+    get models(): ModelsNamespace;
+    private client;
+}
+declare class ChatCompletionsNamespace {
+    private readonly _getClient;
+    private readonly _gate;
+    constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
+    create(params: ChatCompletionCreateParamsStreaming, options?: RequestOptions): Promise<Result<Stream<ChatCompletionChunk>>>;
+    create(params: ChatCompletionCreateParamsNonStreaming, options?: RequestOptions): Promise<Result<ChatCompletion>>;
+}
+declare class EmbeddingsNamespace {
+    private readonly _getClient;
+    private readonly _gate;
+    constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
+    create(params: EmbeddingCreateParams, options?: RequestOptions): Promise<Result<CreateEmbeddingResponse>>;
+}
+interface ImageGenerateParams {
+    model: string;
+    prompt: string;
+    /** Forwarded to OpenRouter as `image_config`. Use for aspect ratio, size, etc. */
+    imageConfig?: Record<string, unknown>;
+}
+interface ImagesResponse {
+    created: number;
+    data: GeneratedImage[];
+}
+interface GeneratedImage {
+    /** Original `data:image/...;base64,...` URL as returned by OpenRouter. */
+    url: string;
+    /** Base64 payload extracted from the data URL. */
+    b64Json?: string;
+    /** MIME type parsed from the data URL prefix. */
+    mimeType?: string;
+}
+declare class ImagesNamespace {
+    private readonly _getClient;
+    private readonly _gate;
+    constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
+    /**
+     * OpenRouter does not implement the OpenAI `/v1/images/generations`
+     * endpoint. Image models are reached via `/v1/chat/completions` with
+     * `modalities: ['image']`, and the resulting image is returned as a
+     * non-standard `message.images[]` array of base64 data URLs. This method
+     * encapsulates that quirk and surfaces an OpenAI-shaped response so
+     * agent code does not need to know.
+     *
+     * If the model does not return any images (wrong model, content policy,
+     * etc.) this returns an `ai_no_image_generated` error rather than an
+     * empty success — surfacing the failure to the caller instead of
+     * silently producing zero images.
+     */
+    generate(params: ImageGenerateParams, options?: RequestOptions): Promise<Result<ImagesResponse>>;
+}
+interface OpenRouterModel {
+    id: string;
+    name?: string;
+    description?: string;
+    context_length?: number;
+    pricing?: Record<string, unknown>;
+    architecture?: Record<string, unknown>;
+    supported_parameters?: string[];
+}
+interface ModelsListResponse {
+    data: OpenRouterModel[];
+}
+declare class ModelsNamespace {
+    private readonly _getClient;
+    private readonly _gate;
+    constructor(_getClient: () => Result<OpenAI>, _gate: ModuleGate);
+    /**
+     * Calls `GET ${baseURL}/models` directly with `fetch` — the upstream
+     * `openai.models.list()` parses the response into OpenAI's `Model` type
+     * which discards OpenRouter-specific fields (`pricing`, `context_length`,
+     * `supported_parameters`, `architecture`). Going through `fetch` keeps
+     * the full payload.
+     *
+     * Reuses the cached `OpenAI` instance (built lazily by `AiModule`) so
+     * the resolved `apiKey` and `baseURL` are consistent with the rest of
+     * the namespaces — and any `clientOverride` injected for tests applies
+     * here too.
+     */
+    list(options?: RequestOptions): Promise<Result<ModelsListResponse>>;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+
+/**
+ * Public surface a creator can use through `client.database`. We pin it to the
+ * `postgres-js` Drizzle wrapper because that is the only driver `@stackbone/sdk`
+ * ships and the only one `STACKBONE_POSTGRES_URL` is contracted to point at.
+ *
+ * Re-exporting Drizzle's own type instead of inventing a structural alias keeps
+ * the surface 1:1 with what `drizzle-orm` documents and what `@stackbone/sdk/db`
+ * re-exports — so types flow end to end without translation.
+ */
+type DrizzleClient = PostgresJsDatabase<Record<string, never>> & {
+    $client: Sql;
+};
+
+/**
+ * `client.database` is a lazy wrapper over a `drizzle()` instance bound to
+ * `STACKBONE_POSTGRES_URL`. The underlying postgres-js connection and the
+ * Drizzle facade are constructed on the first method call so env vars rotated
+ * post-`createClient()` are still honoured.
+ *
+ * Native Drizzle methods (`select`, `insert`, `update`, `delete`, `transaction`,
+ * `execute`) are exposed verbatim — we explicitly avoid wrapping them in a
+ * Result envelope here. Drizzle already throws on misuse and returns typed rows
+ * on success; mirroring its API keeps the contract identical to what the
+ * `@stackbone/sdk/db` re-exports document, so creators write idiomatic Drizzle.
+ *
+ * Missing `STACKBONE_POSTGRES_URL` raises `SdkError('database_not_configured')`
+ * with an actionable hint that points to `stackbone dev`. This is a creator
+ * setup bug, not something the agent's code can recover from at runtime.
+ *
+ * Methods are declared with their full Drizzle generic signatures (rather than
+ * `(...args) => Drizzle[k](...args)` arrow properties) so the inferred row
+ * types from `pgTable(...)` flow end-to-end into the caller, which is the
+ * promise the `@stackbone/sdk/db` re-export makes.
+ *
+ * The actual `postgres()` pool and the Drizzle handle are owned by the
+ * module-internal singleton in `./internal.ts`. `client.database` and any
+ * other internal SDK module that imports `getDatabaseHandle` therefore share
+ * one pool per agent process — see `internal.spec.ts` for the invariant.
+ */
+declare class DatabaseModule {
+    private readonly _resolved;
+    private readonly _gate;
+    constructor(_resolved: ResolvedConfig, 
+    /**
+     * Test seam — see `ModuleGate`. Defaults to the lazy contract gate.
+     * The gate is awaited at the terminal `await` of every Drizzle chain
+     * (`select/insert/update/delete/execute/transaction`); when it returns
+     * an error, a tagged `GateBlockedError` is thrown so callers see the
+     * same `Error & { code, message, meta }` surface as the existing
+     * `database_not_configured` setup-bug.
+     */
+    gate?: ModuleGate);
+    /**
+     * Escape hatch — returns Drizzle's relational query builder verbatim. The
+     * contract gate does NOT fire here because the surface is a synchronous
+     * accessor; the user can still bypass the gate via `client.database.raw()`
+     * for the same reason. Audit: `query` and `raw()` are intentionally
+     * ungated escape hatches; the standard `select/insert/update/delete/
+     * execute/transaction` path is fully gated.
+     */
+    get query(): DrizzleClient['query'];
+    select: DrizzleClient['select'];
+    insert: DrizzleClient['insert'];
+    update: DrizzleClient['update'];
+    delete: DrizzleClient['delete'];
+    execute: DrizzleClient['execute'];
+    transaction: DrizzleClient['transaction'];
+    /**
+     * Escape hatch for callers that want the raw Drizzle handle (e.g. to pass
+     * it to a library that expects `PostgresJsDatabase`). Reading this property
+     * triggers the same lazy initialisation as any other method but
+     * intentionally does NOT consult the contract gate — the surface is sync
+     * and the caller is opting out of the SDK's structured surface.
+     */
+    raw(): DrizzleClient;
+}
+
+/**
+ * Where a memory lives. Default `'user'`. `'session'` is short-lived and
+ * collapsed (or dropped) by `endSession()`; `'agent'` is shared across every
+ * user of the agent.
+ */
+type MemoryScope = 'user' | 'session' | 'agent';
+/**
+ * Either raw text or an OpenAI-shaped conversation. The future mem0 backend
+ * accepts both: strings ingest verbatim, message arrays are summarised into
+ * one or more facts.
+ */
+type MemoryContent = string | ChatCompletionMessageParam[];
+interface AddMemoryRequest {
+    userId: string;
+    /** Conversation/session bucket. Required when `scope: 'session'`. */
+    sessionId?: string;
+    /** Default `'user'`. */
+    scope?: MemoryScope;
+    metadata?: Record<string, unknown>;
+}
+interface MemoryItem {
+    id: string;
+    content: string;
+    userId: string;
+    sessionId?: string;
+    scope: MemoryScope;
+    metadata?: Record<string, unknown>;
+    /** ISO 8601 UTC timestamp. */
+    createdAt: string;
+    updatedAt: string;
+}
+interface SearchMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    /** 1..100. Default 10. */
+    limit?: number;
+    /** Minimum cosine similarity in [0, 1]. Hits below this are dropped. */
+    threshold?: number;
+    /** Metadata predicates AND-ed to the semantic match. */
+    filters?: Record<string, unknown>;
+    /** Restrict the search to a subset of scopes. Default: every scope. */
+    includeScopes?: readonly MemoryScope[];
+}
+interface MemoryHit extends MemoryItem {
+    /** Cosine similarity in [0, 1]. */
+    score: number;
+}
+interface ListMemoryRequest {
+    userId: string;
+    /** 1..100. Default 50. */
+    limit?: number;
+    cursor?: string;
+}
+interface ListMemoryResult {
+    items: readonly MemoryItem[];
+    nextCursor?: string;
+}
+interface UpdateMemoryOptions {
+    content?: string;
+    /** Shallow-merged onto the existing metadata (mem0 semantics). */
+    metadata?: Record<string, unknown>;
+}
+interface DeleteAllMemoryRequest {
+    userId: string;
+}
+type MemoryHistoryEvent = 'created' | 'updated' | 'accessed' | 'deleted';
+interface MemoryHistoryEntry {
+    id: string;
+    memoryId: string;
+    event: MemoryHistoryEvent;
+    /** ISO 8601 UTC timestamp. */
+    at: string;
+    /** Identifier of who triggered the event (user id, agent id, etc.). */
+    actor?: string;
+    /** Content snapshot before the event. Only set for `updated`/`deleted`. */
+    before?: string;
+    /** Content snapshot after the event. Only set for `created`/`updated`. */
+    after?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EndSessionOptions {
+    /** Persist session-scoped facts to long-term (`'user'`) memory before closing. Default `true`. */
+    persist?: boolean;
+}
+interface EndSessionResult {
+    sessionId: string;
+    /** Number of session memories promoted to long-term storage. `0` when `persist: false`. */
+    persisted: number;
+}
+/**
+ * `client.memory` — long-term memory for the agent. The first iteration is a
+ * scaffolding placeholder: every method returns `not_implemented`. The real
+ * backend will be mem0 (`mem0ApiKey` / `MEM0_API_KEY`) and the public surface
+ * defined here is the contract callers can already type against.
+ */
+declare class MemoryModule {
+    private readonly _resolved;
+    constructor(_resolved: ResolvedConfig);
+    add(_content: MemoryContent, _request: AddMemoryRequest): Promise<Result<MemoryItem>>;
+    search(_query: string, _options?: SearchMemoryOptions): Promise<Result<readonly MemoryHit[]>>;
+    delete(_memoryId: string): Promise<Result<{
+        id: string;
+    }>>;
+    deleteAll(_request: DeleteAllMemoryRequest): Promise<Result<{
+        deleted: number;
+    }>>;
+    get(_memoryId: string): Promise<Result<MemoryItem>>;
+    list(_request: ListMemoryRequest): Promise<Result<ListMemoryResult>>;
+    update(_memoryId: string, _options: UpdateMemoryOptions): Promise<Result<MemoryItem>>;
+    history(_memoryId: string): Promise<Result<readonly MemoryHistoryEntry[]>>;
+    endSession(_sessionId: string, _options?: EndSessionOptions): Promise<Result<EndSessionResult>>;
+}
+
+declare const RUN_STEP_TYPES: readonly ["agent", "llm_call", "db_query", "http_fetch", "queue_publish", "hitl_pause", "tool_call", "rag_query", "storage_op"];
+type RunStepType = (typeof RUN_STEP_TYPES)[number];
+declare const STEP_TYPE_ATTRIBUTE = "stackbone.step.type";
+declare const RUN_ID_ATTRIBUTE = "stackbone.run.id";
+/**
+ * Minimal duck-typed view of an OpenTelemetry `ReadableSpan`. We mirror the
+ * shape the OTel SDK exposes on `@opentelemetry/sdk-trace-base` rather than
+ * importing the package so `@stackbone/sdk` doesn't pull the OTel runtime into
+ * every agent that doesn't enable Studio. Agents wire the processor with
+ * `provider.addSpanProcessor(new RunStepsSpanProcessor(...))` and the
+ * structural match satisfies TypeScript.
+ */
+interface SpanContextLike {
+    spanId: string;
+    traceId: string;
+}
+interface ReadableSpanLike {
+    spanContext(): SpanContextLike;
+    parentSpanContext?: SpanContextLike | undefined;
+    parentSpanId?: string | undefined;
+    name: string;
+    attributes: Record<string, unknown>;
+    status?: {
+        code: number;
+        message?: string;
+    } | undefined;
+    startTime?: [number, number] | undefined;
+    endTime?: [number, number] | undefined;
+    duration?: [number, number] | undefined;
+}
+interface PostgresLike {
+    unsafe(query: string, params?: unknown[]): Promise<unknown>;
+    end?(): Promise<void>;
+}
+interface RunStepsSpanProcessorOptions {
+    /**
+     * Postgres connection string of the install (local emulator at :5433 in
+     * dev, Neon TCP/HTTP URL in cloud). Falls back to `DATABASE_URL`.
+     */
+    connectionString?: string | undefined;
+    /** Flush trigger by buffer size. Defaults to 50. */
+    flushBatchSize?: number | undefined;
+    /** Flush trigger by elapsed time (ms). Defaults to 500. */
+    flushIntervalMs?: number | undefined;
+    /** Override how a span maps to a step type. */
+    resolveStepType?: ((span: ReadableSpanLike) => RunStepType) | undefined;
+    /** Test seam — inject a postgres-js-compatible client. */
+    sql?: PostgresLike | undefined;
+    /** Test seam — deterministic UUID generator. */
+    newId?: (() => string) | undefined;
+}
+/**
+ * Materialises every OTel span produced by the agent into a row of
+ * `stackbone_platform.run_steps`. Designed to coexist with the OTLP exporter:
+ * cloud builds register both processors so Postgres feeds Studio (paridad
+ * con local) and Tempo feeds Platform Ops with retention/aggregation. If a
+ * write fails the processor logs to stderr and keeps accepting spans —
+ * observability is never load-bearing for agent execution.
+ *
+ * Spec: docs/arquitectura/specs/stackbone-agent-protocol-v1.md §6.3
+ * ADR:  docs/arquitectura/decisiones/2026-05-03-stackbone-studio-datapath-y-scope-mvp.md §D9
+ */
+declare class RunStepsSpanProcessor {
+    private readonly buffer;
+    private readonly stepIdBySpanId;
+    private readonly batchSize;
+    private readonly intervalMs;
+    private readonly resolveStepType;
+    private readonly newId;
+    private readonly connectionString;
+    private readonly ownsSql;
+    private sql;
+    private timer;
+    private inFlight;
+    constructor(options?: RunStepsSpanProcessorOptions);
+    onStart(span: ReadableSpanLike): void;
+    onEnd(span: ReadableSpanLike): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private buildRow;
+    private armTimer;
+    private disarmTimer;
+    private flush;
+    private ensureSql;
+    private writeBatch;
+}
+
+interface AggregateRunCostOptions {
+    sql: PostgresLike;
+}
+interface AggregateRunCostResult {
+    costEstimatedUsd: number;
+}
+declare function aggregateRunCost(runId: string, options: AggregateRunCostOptions): Promise<AggregateRunCostResult>;
+
+declare const LOG_LEVELS: {
+    readonly trace: 10;
+    readonly debug: 20;
+    readonly info: 30;
+    readonly warn: 40;
+    readonly error: 50;
+    readonly fatal: 60;
+};
+type LogLevelName = keyof typeof LOG_LEVELS;
+type LogLevelNumber = (typeof LOG_LEVELS)[LogLevelName];
+interface LogRecord {
+    /** Pino-style numeric level. */
+    level: LogLevelNumber;
+    /** Epoch milliseconds. Pino uses `time` as a number. */
+    time: number;
+    msg: string;
+    run_id: string;
+    trace_id?: string;
+    installation_id?: string;
+    agent_id?: string;
+    [key: string]: unknown;
+}
+interface PlatformLoggerOptions {
+    runId: string;
+    installationId?: string | undefined;
+    agentId?: string | undefined;
+    /**
+     * When set (cloud), logs are batched and POSTed to `<endpoint>/v1/logs` as
+     * OTLP/HTTP/JSON. When unset (local), logs are appended to
+     * `<runsDir>/<runId>.jsonl`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`.
+     */
+    otelEndpoint?: string | undefined;
+    /** Local-only: directory where JSONL files live. Defaults to `~/.stackbone/dev/runs`. */
+    runsDir?: string | undefined;
+    /** Cloud-only: extra OTel resource attributes to send with every batch. */
+    resourceAttributes?: Record<string, string> | undefined;
+    /** Cloud-only: HTTP timeout per OTLP POST in ms. Defaults to 5_000. */
+    httpTimeoutMs?: number | undefined;
+    /** Flush trigger by buffer size. Defaults to 50. */
+    flushBatchSize?: number | undefined;
+    /** Flush trigger by elapsed time (ms). Defaults to 1_000. */
+    flushIntervalMs?: number | undefined;
+    /** Test seam — fetch implementation. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch | undefined;
+    /** Test seam — `fs.appendFile`-shaped sink the local destination uses. */
+    appendFileImpl?: ((path: string, data: string) => Promise<void>) | undefined;
+    /** Test seam — `fs.mkdir`-shaped helper the local destination uses. */
+    mkdirImpl?: ((path: string) => Promise<void>) | undefined;
+    /** Test seam — clock for `time` field. Defaults to `Date.now`. */
+    now?: (() => number) | undefined;
+    /** Override mode resolution (skips the env detection). */
+    mode?: PlatformLoggerMode | undefined;
+}
+type PlatformLoggerMode = 'local' | 'cloud';
+interface PinoLike {
+    trace(msgOrObj: unknown, msg?: string): void;
+    debug(msgOrObj: unknown, msg?: string): void;
+    info(msgOrObj: unknown, msg?: string): void;
+    warn(msgOrObj: unknown, msg?: string): void;
+    error(msgOrObj: unknown, msg?: string): void;
+    fatal(msgOrObj: unknown, msg?: string): void;
+}
+interface PlatformLogger extends PinoLike {
+    readonly mode: PlatformLoggerMode;
+    /** Bind extra fields and return a child logger sharing the same destination. */
+    child(bindings: Record<string, unknown>): PlatformLogger;
+    /** Force-flush pending writes (close file handle or POST OTLP batch). */
+    flush(): Promise<void>;
+    /** Stop accepting writes and release resources. */
+    close(): Promise<void>;
+}
+/**
+ * Creates a Pino-aligned logger that writes JSONL to disk in local mode and
+ * batches OTLP/HTTP/JSON log records to an OTel collector in cloud mode. Mode
+ * is resolved from `OTEL_EXPORTER_OTLP_ENDPOINT` or the explicit override.
+ */
+declare function createPlatformLogger(options: PlatformLoggerOptions): PlatformLogger;
+declare function defaultRunsDir(): string;
+
+declare class ObservabilityModule {
+    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.
+     */
+    spanProcessor(options?: RunStepsSpanProcessorOptions): RunStepsSpanProcessor;
+    flush(): Promise<Result<void>>;
+    /**
+     * 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.
+     */
+    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>;
+    /**
+     * 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.
+     */
+    closeRun(runId: string): Promise<Result<AggregateRunCostResult>>;
+    private resolveSql;
+}
+
+interface PublishRequest {
+    url: string;
+    body: unknown;
+    retries?: number;
+    delay?: number;
+    deduplicationId?: string;
+    headers?: Record<string, string>;
+}
+declare class QueuesModule {
+    private readonly _gate;
+    constructor(resolved: ResolvedConfig, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
+    gate?: ModuleGate);
+    publish(_request: PublishRequest): Promise<Result<{
+        messageId: string;
+    }>>;
+}
+
+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 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
+ * pulls the underlying `postgres-js` `Sql` from the shared
+ * `getDatabaseHandle()` exposed by `client.database`, so an agent that
+ * touches both surfaces still opens exactly one connection pool against
+ * `STACKBONE_POSTGRES_URL`.
+ *
+ * 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.
+ */
+declare class RagModule {
+    private readonly _resolved;
+    private readonly _getAi;
+    private readonly _gate;
+    constructor(_resolved: ResolvedConfig, _getAi: () => AiModule, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
+    gate?: ModuleGate);
+    ingest(request: IngestRequest): Promise<Result<IngestResponse>>;
+    /**
+     * Asynchronous ingest. Allocates a `stackbone_rag_jobs` row, returns the
+     * job id immediately, and exposes both an `AsyncIterable` of streaming
+     * progress events and the final `Result` so callers can `await` either
+     * surface — typical webhook handlers consume `events` and ignore `result`,
+     * tests `await result` directly. Cancellation is observed by flipping the
+     * row's status (e.g. via `POST /api/rag/jobs/:jobId/cancel`); the worker
+     * polls between chunk batches and bails out with `rag_ingest_cancelled`.
+     *
+     * Connection ownership: the `IngestJobWriter` is bound to the same SQL
+     * pulled off the shared `client.database` handle, so a single agent that
+     * issues `ingestAsync` and `client.database.select` in flight still opens
+     * exactly one pool against `STACKBONE_POSTGRES_URL`.
+     */
+    ingestAsync(request: IngestRequest): Promise<Result<IngestAsyncHandle>>;
+    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
+    private _testJobWriter?;
+    /** Test-only seam — assigned by `ingest-async.spec.ts`. */
+    private _testSqlOverride?;
+    delete(ids: string | string[], options?: DeleteOptions): Promise<Result<DeleteResponse>>;
+    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.
+     */
+    reset(): Promise<Result<void>>;
+    /**
+     * Pure helper — exposed verbatim from the chunker. No DB, no AI, no
+     * datapath traffic, so it is intentionally NOT gated.
+     */
+    chunk(text: string, options?: ChunkOptions): string[];
+    /**
+     * Pure helper — exposed verbatim from the parser. No DB, no AI, no
+     * datapath traffic, so it is intentionally NOT gated.
+     */
+    parse(input: ParseInput, options?: ParseOptions): Promise<string>;
+    /**
+     * Resolves the postgres-js `Sql` to use for this operation. Pulls `$client`
+     * off the shared Drizzle handle (single pool per agent process). Slice F03's
+     * NOTE about cross-module transaction propagation lives here: this is the
+     * seam where a future `database.transaction` integration plugs a tx-bound
+     * `Sql` into the pipeline instead of the pool-bound one.
+     *
+     * Configuration errors (`STACKBONE_POSTGRES_URL` unset) flow up as a
+     * `Result.err` with the same `database_not_configured` shape `client.database`
+     * raises, instead of throwing through the public surface.
+     */
+    private sql;
+    private withPipeline;
+}
+
+interface StorageObject {
+    key: string;
+    size: number;
+    lastModified?: Date;
+    etag?: string;
+}
+interface UploadOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+interface ListOptions {
+    prefix?: string;
+    /** Maximum number of objects to return per page. Must be > 0. */
+    limit?: number;
+    cursor?: string;
+}
+interface SignedUrlOptions {
+    /** Seconds until the URL expires. Defaults to 3600 (1h). */
+    expiresIn?: number;
+    /** Only honoured by `getSignedUploadUrl` — pinned into the signature so the uploader must send a matching `Content-Type`. */
+    contentType?: string;
+}
+interface SignedUrl {
+    url: string;
+    expiresAt: Date;
+}
+type StorageBody = Blob | Uint8Array | string;
+interface S3Settings {
+    client: S3Client;
+    endpoint: string;
+    bucket: string;
+    agentId: string;
+}
+/**
+ * Public surface behind `client.storage`. Wraps `@aws-sdk/client-s3` against
+ * R2 (prod) or MinIO (dev). Exposes a bucket-scoped API via `from(bucket)`.
+ *
+ * Multi-tenancy: every key is prefixed with `agentId/bucket/` before hitting
+ * S3. Credentials are scoped to the agent's physical bucket (env `S3_BUCKET`),
+ * and the `bucket` argument is a logical namespace the agent uses to organise
+ * its own objects. The full prefixed key is an internal detail — public
+ * methods accept and return the user-facing key (without prefix). Metadata
+ * tracking in `_storage_objects` (Neon) is out-of-scope for this iteration.
+ *
+ * Memory note: `download()` materialises the whole object as a `Blob` in
+ * memory. For agents that need to stream large objects, prefer
+ * `getSignedDownloadUrl()` and `fetch()` the URL directly to consume the
+ * stream incrementally.
+ */
+declare class StorageModule {
+    private readonly _resolved;
+    private _s3;
+    private readonly _gate;
+    constructor(_resolved: ResolvedConfig, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
+    gate?: ModuleGate);
+    from(bucket: string): StorageBucket;
+    private settings;
+}
+declare class StorageBucket {
+    private readonly bucketName;
+    private readonly resolveSettings;
+    private readonly gate;
+    constructor(bucketName: string, resolveSettings: () => Result<S3Settings>, gate: ModuleGate);
+    upload(key: string, body: StorageBody, options?: UploadOptions): Promise<Result<{
+        key: string;
+        etag?: string;
+    }>>;
+    download(key: string): Promise<Result<Blob>>;
+    list(options?: ListOptions): Promise<Result<{
+        objects: readonly StorageObject[];
+        nextCursor?: string;
+    }>>;
+    remove(key: string): Promise<Result<{
+        key: string;
+    }>>;
+    /**
+     * Returns the canonical S3-style URL for an object. Pure URL-builder — no
+     * S3 round-trip — so this method intentionally bypasses the contract gate.
+     * Whether the URL is publicly fetchable depends on the bucket policy; for
+     * private buckets, use `getSignedDownloadUrl` instead.
+     */
+    getPublicUrl(key: string): Result<string>;
+    getSignedUploadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
+    getSignedDownloadUrl(key: string, options?: SignedUrlOptions): Promise<Result<SignedUrl>>;
+    /**
+     * Resolves S3 settings, validates the user key, and prefixes it with
+     * `${agentId}/${bucketName}/`. Rejects path-traversal segments (`..`) so a
+     * caller-controlled key cannot escape the agent's namespace.
+     */
+    private resolve;
+}
+
+/**
+ * Each accessor builds its module on first access and caches it — env vars
+ * and partner SDK init costs are paid only when the agent actually touches
+ * that surface.
+ */
+declare class StackboneClient {
+    private readonly resolved;
+    private _database?;
+    private _storage?;
+    private _ai?;
+    private _queues?;
+    private _rag?;
+    private _memory?;
+    private _observability?;
+    private _approval?;
+    private _secrets?;
+    private _connections?;
+    private _config?;
+    private _events?;
+    private _prompts?;
+    private _httpClient?;
+    constructor(resolved: ResolvedConfig);
+    private http;
+    get database(): DatabaseModule;
+    get storage(): StorageModule;
+    get ai(): AiModule;
+    get queues(): QueuesModule;
+    get rag(): RagModule;
+    get memory(): MemoryModule;
+    get observability(): ObservabilityModule;
+    get approval(): ApprovalFacade;
+    get secrets(): SecretsFacade;
+    get connections(): ConnectionsFacade;
+    get config(): ConfigFacade;
+    get events(): EventsFacade;
+    get prompts(): PromptsFacade;
+    /**
+     * Read-only view of the most recently resolved Stackbone Agent Protocol
+     * contract for this client's `stackboneApiUrl`. Returns `null` until a
+     * handshake has resolved successfully (the handshake fires lazily on the
+     * first gated module call — slices #4/#5). Synchronous, never throws,
+     * performs no fetches.
+     */
+    get contract(): ContractResponse | null;
+}
+declare function createClient(config?: ClientConfig): StackboneClient;
+
+export { type AddMemoryRequest, type AggregateRunCostOptions, type AggregateRunCostResult, 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 GeneratedImage, type GetPromptOptions, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type IngestChunk, type IngestRequest, type IngestRequestAutoEmbed, type IngestRequestPrecomputed, type IngestResponse, LOG_LEVELS, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LogLevelName, type LogLevelNumber, type LogRecord, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type ParseInput, type ParseOptions, type PinoLike, type PlatformLogger, type PlatformLoggerMode, type PlatformLoggerOptions, type PostgresLike, type Prompt, type PublishRequest, RUN_ID_ATTRIBUTE, RUN_STEP_TYPES, type RagIngestProgress, type ReadableSpanLike, type Result, type RetrieveHit, type RetrieveRequest, type RetrieveRequestAutoEmbed, type RetrieveRequestPrecomputed, type RunStepType, RunStepsSpanProcessor, type RunStepsSpanProcessorOptions, STEP_TYPE_ATTRIBUTE, type SdkError, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, type SpanContextLike, StackboneClient, type StorageBody, type StorageObject, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, aggregateRunCost, createClient, createPlatformLogger, defaultRunsDir };