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

package/CHANGELOG.md

@@ -7,8 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- **Breaking:** removed the `client.observability` surface (`spanProcessor`,
+  `logger`, `closeRun`, `closeLogger`, `flush`). Observability is no longer a
+  creator-facing `client` module: agent code logs through the handler-scoped
+  `ctx.logger` (already bound to the run) — plain `console.*` is captured and
+  correlated too — and the Studio run timeline is produced by the runtime, not
+  by code the agent registers. The platform primitives (`PlatformLogger`,
+  `RunStepsSpanProcessor`, `aggregateRunCost`) stay available on the
+  `@stackbone/sdk/observability` subpath, consumed by the runtime wrapper and
+  the agent emulator.
+
 ### Changed
 
+- The runtime now injects the SDK client into every handler context as
+  `ctx.client` — one `StackboneClient` per process, shared across invocations.
+  Agent code reads it off the invocation context (`async run({ input, client })
+{ ... }`) instead of constructing one at module scope, so a module-level
+  `const client = createClient()` is no longer required. `createClient()` stays
+  exported as an escape hatch for building a client outside a handler (scripts,
+  tests, one-off tasks) or with explicit config overrides.
+
+- `client.queues` is now live (was a `notImplemented` stub). `publish`,
+  `schedule`, `unschedule` and `listSchedules` make authenticated calls to the
+  control-plane BullMQ dispatcher (`/api/v1/agent/queues/*`) using the existing
+  `STACKBONE_AGENT_JWT` channel — the agent never touches Redis.
+  **Breaking:** `publish` now takes `{ name, payload, retries?, delay?,
+deduplicationId? }` and returns `{ messageId }` (was `{ url, body, retries?,
+delay?, deduplicationId?, headers? }`). `name` is the opaque job name (e.g.
+  `send-email`), `payload` the opaque body, `delay` defers delivery in ms and
+  `retries` overrides the platform retry default per job. New public request
+  types `ScheduleRequest` / `UnscheduleRequest` are exported from the barrel.
+  Errors surface under the new `queues_*` prefix.
+
 - `ResolvedConfig` is now an opaque, typed snapshot — the live `env`
   channel is gone. Every consumer used to read environment variables with
   the pattern `resolved.config.fieldX ?? resolved.env['FIELDX']`, which

package/README.md

@@ -18,9 +18,9 @@ Official TypeScript SDK for [Stackbone](https://stackbone.ai) — the marketplac
 - **Approval** — Human-in-the-loop inbox: fire-and-forget approval requests, HMAC-signed decision callbacks, and an LLM tool wrapper that gates execution behind human review
 - **Secrets** — Read organization-encrypted secrets registered in the dashboard, no client-side cache so rotations propagate immediately
 - **Config** — Typed reads of dynamic per-agent configuration the user set in the dashboard
-- **Coming soon (types only)** — `queues` (cross-container HTTP push via QStash), `memory` (mem0-backed long-term memory), `prompts` (managed prompts with `{{var}}` templates), `connections` (OAuth integrations) and `events` (org-wide event bus). Public types are exported from `@stackbone/sdk` today; the runtime is not wired yet, so there is no live `client.X` accessor.
+- **Coming soon (types only)** — `queues` (cross-container HTTP push via the BullMQ job dispatcher), `memory` (mem0-backed long-term memory), `prompts` (managed prompts with `{{var}}` templates), `connections` (OAuth integrations) and `events` (org-wide event bus). Public types are exported from `@stackbone/sdk` today; the runtime is not wired yet, so there is no live `client.X` accessor.
 - **TypeScript-first** — Full type definitions and a uniform `Result<T>` envelope on every method (no thrown errors at the SDK boundary)
-- **Lazy initialization** — Modules and partner SDKs are constructed on first access, so env vars rotated by the control plane after `createClient()` are still picked up
+- **Lazy initialization** — Modules and partner SDKs are constructed on first access, so env vars rotated by the control plane after the client is built are still picked up
 
 ## Installation
 
@@ -37,26 +37,44 @@ pnpm add @stackbone/sdk
 
 > Requires Node.js 24 or newer (the runtime your agent container ships with). The SDK is server-only — it is not built for the browser.
 
-Need a copy-pasteable starting point? See the [`example/`](https://github.com/stackbone/stackbone/tree/main/libs/sdk/example) directory in the repository — one ESM and one CJS file showing the canonical agent shape (schema with `@stackbone/sdk/db`, `createClient`, async handler).
+Need a copy-pasteable starting point? See the [`example/`](https://github.com/stackbone/stackbone/tree/main/libs/sdk/example) directory in the repository — one ESM and one CJS file showing the canonical agent shape (schema with `@stackbone/sdk/db`, the runtime-injected `ctx.client`, async handler).
 
 ## Quick Start
 
-### Initialize the Client
+### The Client
 
-In production, every option falls back to an environment variable injected by the platform at provisioning time, so a zero-arg call is the common case:
+You don't construct the client. The runtime builds a single `StackboneClient` per process — wired from the env vars the platform injects at provisioning time — and hands it to every handler as `ctx.client`. Define your agent with `defineAgent` and destructure `client` (and `input`) off the invocation context:
 
 ```ts
-import { createClient } from '@stackbone/sdk';
-
-const stackbone = createClient();
+import { defineAgent, z } from '@stackbone/sdk';
+
+export default defineAgent({
+  invoke: {
+    input: z.object({ email: z.string() }),
+    output: z.object({ id: z.number() }),
+    async run({ input, client }) {
+      const [row] = await client.database
+        .insert(leads)
+        .values({ email: input.email, status: 'new', score: 0 })
+        .returning();
+      return { id: row.id };
+    },
+  },
+});
 ```
 
-Pass overrides explicitly when you need them — useful for local development against the emulator, or when running outside a Stackbone container:
+#### Escape hatch — `createClient()`
+
+`createClient()` is still exported for when you need a client **outside** a handler (a script, a test, a one-off task) or want to override config explicitly — useful for local development against the emulator or when running outside a Stackbone container. In normal agent code you never need it; reach for `ctx.client` instead.
 
 ```ts
 import { createClient } from '@stackbone/sdk';
 
-const stackbone = createClient({
+// Zero-arg: every option falls back to an injected env var.
+const stackbone = createClient();
+
+// Or pass overrides explicitly.
+const local = createClient({
   agentJwt: process.env.STACKBONE_AGENT_JWT,
   stackboneApiUrl: 'http://localhost:3000',
   agentId: 'agent_local_dev',
@@ -69,7 +87,7 @@ const stackbone = createClient({
 `client.database` is a lazy [Drizzle ORM](https://orm.drizzle.team/) instance bound to the agent's Postgres connection (`STACKBONE_POSTGRES_URL`). The full Drizzle surface (`select`, `insert`, `update`, `delete`, `transaction`, `execute`, `query`, `sql\`\``) is exposed verbatim, and the column builders live behind the `@stackbone/sdk/db`subpath so the creator never has to install`drizzle-orm`, `drizzle-orm/pg-core`or`postgres` directly.
 
 ```ts
-import { createClient } from '@stackbone/sdk';
+import { defineAgent, z } from '@stackbone/sdk';
 import { eq, integer, pgTable, text } from '@stackbone/sdk/db';
 
 // 1. Declare your tables — types flow end to end.
@@ -80,29 +98,39 @@ const leads = pgTable('leads', {
   score: integer('score').notNull(),
 });
 
-const stackbone = createClient();
+export default defineAgent({
+  invoke: {
+    input: z.object({}),
+    output: z.object({}),
+    async run({ client }) {
+      // 2. Query — `data` is typed from the schema, no codegen needed.
+      const rows = await client.database
+        .select()
+        .from(leads)
+        .where(eq(leads.status, 'qualified'))
+        .limit(20);
 
-// 2. Query — `data` is typed from the schema, no codegen needed.
-const rows = await stackbone.database
-  .select()
-  .from(leads)
-  .where(eq(leads.status, 'qualified'))
-  .limit(20);
+      // 3. Mutate.
+      await client.database
+        .insert(leads)
+        .values({ id: 1, email: 'jane@example.com', status: 'new', score: 0 });
 
-// 3. Mutate.
-await stackbone.database
-  .insert(leads)
-  .values({ id: 1, email: 'jane@example.com', status: 'new', score: 0 });
+      await client.database.update(leads).set({ status: 'contacted' }).where(eq(leads.id, 1));
 
-await stackbone.database.update(leads).set({ status: 'contacted' }).where(eq(leads.id, 1));
+      await client.database.delete(leads).where(eq(leads.id, 1));
 
-await stackbone.database.delete(leads).where(eq(leads.id, 1));
+      return {};
+    },
+  },
+});
 ```
 
+The snippets below assume the `client` destructured off `ctx` inside a handler (`async run({ client }) { ... }`).
+
 Interactive transactions yield a `tx` with the same Drizzle surface as `client.database`:
 
 ```ts
-await stackbone.database.transaction(async (tx) => {
+await client.database.transaction(async (tx) => {
   await tx.insert(leads).values({ id: 2, email: 'b@x.com', status: 'new', score: 0 });
   await tx.update(leads).set({ status: 'qualified' }).where(eq(leads.id, 2));
 });
@@ -113,7 +141,7 @@ For raw SQL, reach for the `sql` tag re-exported from `@stackbone/sdk/db`:
 ```ts
 import { sql } from '@stackbone/sdk/db';
 
-const { rows } = await stackbone.database.execute(sql`SELECT NOW()`);
+const { rows } = await client.database.execute(sql`SELECT NOW()`);
 ```
 
 > If `STACKBONE_POSTGRES_URL` is unset, the first call to `client.database` raises `database_not_configured` with a hint to run `stackbone dev`. Migrations are governed by the `stackbone db migrate *` CLI commands — `client.database` itself is just the runtime query surface.
@@ -124,7 +152,7 @@ const { rows } = await stackbone.database.execute(sql`SELECT NOW()`);
 
 ```ts
 // Upload an object
-const { data, error } = await stackbone.storage
+const { data, error } = await client.storage
   .from('uploads')
   .upload('reports/2026-04-29.pdf', pdfBlob, {
     contentType: 'application/pdf',
@@ -132,22 +160,22 @@ const { data, error } = await stackbone.storage
   });
 
 // Download an object (returns a Blob)
-const { data, error } = await stackbone.storage.from('uploads').download('reports/2026-04-29.pdf');
+const { data, error } = await client.storage.from('uploads').download('reports/2026-04-29.pdf');
 
 // List objects (paginated)
-const { data, error } = await stackbone.storage
+const { data, error } = await client.storage
   .from('uploads')
   .list({ prefix: 'reports/', limit: 50 });
 
 // Delete an object
-const { data, error } = await stackbone.storage.from('uploads').remove('reports/2026-04-29.pdf');
+const { data, error } = await client.storage.from('uploads').remove('reports/2026-04-29.pdf');
 ```
 
 Signed URLs and a public URL helper are exposed for direct browser uploads / downloads:
 
 ```ts
 // Pre-signed upload URL (1h by default; clamp the contentType into the signature)
-const { data: upload } = await stackbone.storage
+const { data: upload } = await client.storage
   .from('uploads')
   .getSignedUploadUrl('avatars/user-42.png', {
     expiresIn: 600,
@@ -156,12 +184,12 @@ const { data: upload } = await stackbone.storage
 
 // Pre-signed download URL — prefer this over `download()` for large objects,
 // since `download()` materialises the entire body in memory as a Blob.
-const { data: download } = await stackbone.storage
+const { data: download } = await client.storage
   .from('uploads')
   .getSignedDownloadUrl('reports/2026-04-29.pdf');
 
 // Canonical public URL (only fetchable for public buckets)
-const { data: url } = stackbone.storage.from('uploads').getPublicUrl('avatars/user-42.png');
+const { data: url } = client.storage.from('uploads').getPublicUrl('avatars/user-42.png');
 ```
 
 ### AI
@@ -170,7 +198,7 @@ const { data: url } = stackbone.storage.from('uploads').getPublicUrl('avatars/us
 
 ```ts
 // Chat completion
-const { data, error } = await stackbone.ai.chat.completions.create({
+const { data, error } = await client.ai.chat.completions.create({
   model: 'anthropic/claude-sonnet-4.5',
   messages: [
     { role: 'system', content: 'You are a sales qualification assistant.' },
@@ -186,7 +214,7 @@ if (!error) {
 Streaming uses the same method with `stream: true`. The `Result` envelope only covers the handshake — once the stream is open, mid-flight errors propagate through the iterator, so wrap your `for await` loop in `try/catch`:
 
 ```ts
-const { data: stream, error } = await stackbone.ai.chat.completions.create({
+const { data: stream, error } = await client.ai.chat.completions.create({
   model: 'anthropic/claude-sonnet-4.5',
   messages: [{ role: 'user', content: 'Stream me a haiku.' }],
   stream: true,
@@ -203,7 +231,7 @@ Embeddings, image generation and a model catalogue are first-class too:
 
 ```ts
 // Embeddings — returns the standard OpenAI shape
-const { data, error } = await stackbone.ai.embeddings.create({
+const { data, error } = await client.ai.embeddings.create({
   model: 'openai/text-embedding-3-small',
   input: 'A red Spanish sword from the 11th century.',
 });
@@ -211,14 +239,14 @@ const { data, error } = await stackbone.ai.embeddings.create({
 // Image generation — OpenRouter routes image models through chat completions;
 // the SDK normalises the response so callers see the OpenAI-shaped payload.
 // Returns `ai_no_image_generated` if the model produces zero images.
-const { data, error } = await stackbone.ai.images.generate({
+const { data, error } = await client.ai.images.generate({
   model: 'google/gemini-2.5-flash-image',
   prompt: 'A medieval Spanish sword on a velvet cushion, museum lighting',
 });
 
 // List available models — preserves OpenRouter-specific fields like
 // `pricing`, `context_length`, `supported_parameters`, `architecture`
-const { data, error } = await stackbone.ai.models.list();
+const { data, error } = await client.ai.models.list();
 ```
 
 Cancellation works the way you'd expect — pass an `AbortSignal` and aborts surface as `ai_aborted` on non-streaming calls:
@@ -227,7 +255,7 @@ Cancellation works the way you'd expect — pass an `AbortSignal` and aborts sur
 const controller = new AbortController();
 setTimeout(() => controller.abort(), 5_000);
 
-const { data, error } = await stackbone.ai.chat.completions.create(
+const { data, error } = await client.ai.chat.completions.create(
   { model: 'anthropic/claude-sonnet-4.5', messages: [...] },
   { signal: controller.signal },
 );
@@ -241,16 +269,16 @@ The fast path lets the SDK handle embeddings for you — pass an embedding `mode
 
 ```ts
 // 1. Parse a document → plain text. Supports text/*, text/markdown and application/pdf.
-const text = await stackbone.rag.parse(file);
+const text = await client.rag.parse(file);
 
 // 2. Split into chunks. Pure utility, no DB call.
-const chunks = stackbone.rag.chunk(text, { size: 512, overlap: 64 });
+const chunks = client.rag.chunk(text, { size: 512, overlap: 64 });
 
 // 3. Ingest. The SDK embeds the chunks for you in batches of 128 and
 //    provisions the schema on the first call (HNSW + cosine, dims inferred
 //    from the first batch). Re-ingesting the same `id` atomically replaces
 //    all of that document's chunks.
-await stackbone.rag.ingest({
+await client.rag.ingest({
   id: 'doc-1',
   chunks,
   model: 'openai/text-embedding-3-small',
@@ -259,7 +287,7 @@ await stackbone.rag.ingest({
 
 // 4. Retrieve. Pass the user's question and the same model — the SDK embeds
 //    it for you and returns hits scored in [0, 1] (cosine similarity).
-const { data: hits } = await stackbone.rag.retrieve({
+const { data: hits } = await client.rag.retrieve({
   text: 'how does X work?',
   model: 'openai/text-embedding-3-small',
   topK: 5,
@@ -270,12 +298,12 @@ const { data: hits } = await stackbone.rag.retrieve({
 The escape hatch — pass embeddings precomputed yourself (different provider, custom dimensions, your own batching, deterministic offline tests):
 
 ```ts
-const { data: embeddings } = await stackbone.ai.embeddings.create({
+const { data: embeddings } = await client.ai.embeddings.create({
   model: 'openai/text-embedding-3-small',
   input: chunks,
 });
 
-await stackbone.rag.ingest({
+await client.rag.ingest({
   id: 'doc-1',
   chunks: chunks.map((content, i) => ({
     content,
@@ -284,7 +312,7 @@ await stackbone.rag.ingest({
   metadata: { source: 'manual-upload' },
 });
 
-const { data: hits } = await stackbone.rag.retrieve({
+const { data: hits } = await client.rag.retrieve({
   embedding: queryEmbedding,
   topK: 5,
 });
@@ -293,29 +321,29 @@ const { data: hits } = await stackbone.rag.retrieve({
 Delete by id (whole document) or by metadata predicate:
 
 ```ts
-await stackbone.rag.delete('doc-1');
-await stackbone.rag.delete(['doc-1', 'doc-2']);
+await client.rag.delete('doc-1');
+await client.rag.delete(['doc-1', 'doc-2']);
 
-await stackbone.rag.deleteWhere({ source: 'manual-upload' });
+await client.rag.deleteWhere({ source: 'manual-upload' });
 ```
 
 Logical separation between document sets is via an optional `namespace` (default `'default'`). Backed by an indexed column in the same table — no extra physical collections to manage:
 
 ```ts
-await stackbone.rag.ingest({
+await client.rag.ingest({
   id: 'faq-1',
   chunks: [...],
   namespace: 'faqs',
 });
 
-await stackbone.rag.retrieve({ embedding, namespace: 'faqs' });
-await stackbone.rag.deleteWhere({}, { namespace: 'faqs' });
+await client.rag.retrieve({ embedding, namespace: 'faqs' });
+await client.rag.deleteWhere({}, { namespace: 'faqs' });
 ```
 
 If you switch embedding models (e.g. `text-embedding-3-small` → `text-embedding-3-large`) the dimensions will not match what the table was provisioned with. The next `ingest()` returns `rag_dim_mismatch` with the exact stored vs received dims. Recreate the schema with:
 
 ```ts
-await stackbone.rag.reset();
+await client.rag.reset();
 ```
 
 > `parse()` is intentionally minimal: passthrough for text and markdown, `unpdf` for text-only PDFs (no OCR, no layout reconstruction). For complex documents (scanned PDFs, Office files, multi-column layouts) the recommended path is to parse upstream of the SDK and pass the resulting text into `chunk()` directly.
@@ -328,7 +356,7 @@ This shape decouples waiting from the container lifecycle — the agent does not
 
 ```ts
 // 1. Issue an approval — returns immediately, the human reviews asynchronously.
-const { data, error } = await stackbone.airoval.request({
+const { data, error } = await client.airoval.request({
   topic: 'lead.qualify',
   payload: { leadId: 42, score: 0.6 },
   title: 'Approve lead qualification',
@@ -346,7 +374,7 @@ const { data, error } = await stackbone.airoval.request({
 //    returns a typed Decision<T>. Pass the raw `Request` (Fetch / Hono /
 //    undici) and switch on `decision.status`.
 app.post('/approvals/lead-qualify', async (c) => {
-  const result = await stackbone.airoval.verify<{ leadId: number; score: number }>(c.req.raw);
+  const result = await client.airoval.verify<{ leadId: number; score: number }>(c.req.raw);
   if (result.error) return c.text('invalid', 401);
   switch (result.data.status) {
     case 'approved':
@@ -367,9 +395,9 @@ app.post('/approvals/lead-qualify', async (c) => {
 Operations on existing approvals:
 
 ```ts
-await stackbone.airoval.cancel(approvalId, 'no longer needed');
-const { data: record } = await stackbone.airoval.get<LeadPayload>(approvalId);
-const { data: page } = await stackbone.airoval.list({
+await client.airoval.cancel(approvalId, 'no longer needed');
+const { data: record } = await client.airoval.get<LeadPayload>(approvalId);
+const { data: page } = await client.airoval.list({
   status: 'pending',
   topic: 'lead.qualify',
   limit: 50,
@@ -378,10 +406,10 @@ const { data: page } = await stackbone.airoval.list({
 
 #### Approval-gated LLM tools
 
-`stackbone.airoval.tool()` wraps an LLM tool so the agent loop pauses for human review before `execute()` runs. When `needsApproval` returns `true`, `invoke()` opens an approval and returns a `pending` marker — the caller persists agent state and breaks the loop; the eventual decision callback (handled via `verify()`) is the signal to resume.
+`client.airoval.tool()` wraps an LLM tool so the agent loop pauses for human review before `execute()` runs. When `needsApproval` returns `true`, `invoke()` opens an approval and returns a `pending` marker — the caller persists agent state and breaks the loop; the eventual decision callback (handled via `verify()`) is the signal to resume.
 
 ```ts
-const sendInvoice = stackbone.airoval.tool({
+const sendInvoice = client.airoval.tool({
   name: 'send_invoice',
   description: 'Send an invoice to a recipient.',
   parameters: {
@@ -402,7 +430,7 @@ const sendInvoice = stackbone.airoval.tool({
 });
 
 // Pass the tool to chat.completions.create — it speaks the OpenAI shape.
-const completion = await stackbone.ai.chat.completions.create({
+const completion = await client.ai.chat.completions.create({
   model: 'anthropic/claude-sonnet-4.5',
   messages,
   tools: [sendInvoice.openaiSpec()],
@@ -433,13 +461,13 @@ The signing key for `verify()` is read from `STACKBONE_APPROVAL_SIGNING_KEY` (or
 
 ```ts
 // Single secret — `secrets_not_found` error if the name is not registered.
-const { data: apiKey, error } = await stackbone.secrets.get('STRIPE_API_KEY');
+const { data: apiKey, error } = await client.secrets.get('STRIPE_API_KEY');
 if (!error) {
   const stripe = new Stripe(apiKey);
 }
 
 // Bulk read at boot — one round-trip; missing names come back as omissions.
-const { data: secrets } = await stackbone.secrets.getMany(['STRIPE_API_KEY', 'SLACK_BOT_TOKEN']);
+const { data: secrets } = await client.secrets.getMany(['STRIPE_API_KEY', 'SLACK_BOT_TOKEN']);
 // secrets: { STRIPE_API_KEY?: string; SLACK_BOT_TOKEN?: string }
 ```
 
@@ -449,17 +477,17 @@ const { data: secrets } = await stackbone.secrets.getMany(['STRIPE_API_KEY', 'SL
 
 ```ts
 // Typed read — the generic narrows `data` to `'formal' | 'casual'`.
-const { data: tone } = await stackbone.config.get<'formal' | 'casual'>('reply_tone');
+const { data: tone } = await client.config.get<'formal' | 'casual'>('reply_tone');
 
 // Complex JSON — pass the full shape as the generic.
 interface Preferences {
   tone: 'formal' | 'casual';
   maxEmailsPerDay: number;
 }
-const { data: prefs } = await stackbone.config.get<Preferences>('preferences');
+const { data: prefs } = await client.config.get<Preferences>('preferences');
 
 // Bulk read — typed via the second generic; missing keys come back as omissions.
-const { data: cfg } = await stackbone.config.getMany<{
+const { data: cfg } = await client.config.getMany<{
   reply_tone: 'formal' | 'casual';
   max_emails: number;
 }>(['reply_tone', 'max_emails']);
@@ -489,7 +517,7 @@ The pending surfaces are `queues` (cross-container HTTP push), `memory` (mem0-ba
 
 ## Configuration
 
-`createClient` accepts a single configuration object. Every field is optional and falls back to an environment variable, which the platform injects into the agent container at boot:
+The runtime-injected `ctx.client` is already configured from the env vars the platform injects, so agent code rarely touches these fields. They matter when you reach for the `createClient()` escape hatch: `createClient` accepts a single configuration object where every field is optional and falls back to an environment variable, which the platform injects into the agent container at boot:
 
 ```ts
 const stackbone = createClient({
@@ -505,8 +533,6 @@ const stackbone = createClient({
   // OpenRouter credentials                                  → OPENROUTER_API_KEY / OPENROUTER_BASE_URL
   openrouterKey: '...',
   openrouterBaseUrl: 'https://openrouter.ai/api/v1',
-  // QStash credentials (queues)                             → QSTASH_TOKEN / QSTASH_CURRENT_SIGNING_KEY / QSTASH_NEXT_SIGNING_KEY
-  qstashToken: '...',
   // RAG document parser                                     → LLAMA_PARSE_API_KEY
   llamaParseApiKey: '...',
   // mem0 credentials (memory module)                        → MEM0_API_KEY / MEM0_BASE_URL
@@ -530,7 +556,7 @@ const stackbone = createClient({
 });
 ```
 
-Inside a Stackbone-hosted container all of these are pre-populated, so production agent code is just `createClient()`. For local development the `stackbone dev` emulator wires up the same env vars against MinIO, a local Postgres branch and your own OpenRouter key.
+Inside a Stackbone-hosted container all of these are pre-populated, so production agent code just reads `ctx.client` (a zero-arg `createClient()` would resolve the same values). For local development the `stackbone dev` emulator wires up the same env vars against MinIO, a local Postgres branch and your own OpenRouter key.
 
 ## Result Envelope and Error Handling
 
@@ -550,7 +576,7 @@ interface SdkError {
 Narrowing on `error` automatically refines `data` to `T`, so the typical caller looks like:
 
 ```ts
-const result = await stackbone.ai.chat.completions.create({ model, messages });
+const result = await client.ai.chat.completions.create({ model, messages });
 
 if (result.error) {
   console.error(`[${result.error.code}] ${result.error.message}`, result.error.meta);
@@ -562,22 +588,22 @@ console.log(result.data.choices[0]?.message.content);
 
 Each module ships its own stable code prefix so you can pattern-match without parsing the message:
 
-| Prefix            | Source                 | Examples                                                                                                                                                                                                                                                                                                 |
-| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ai_*`            | `client.ai`            | `ai_unauthorized`, `ai_credits_exhausted`, `ai_rate_limited`, `ai_aborted`, `ai_no_image_generated`                                                                                                                                                                                                      |
-| `s3_*`            | `client.storage`       | `s3_credentials_missing`, `s3_invalid_key`, `s3_error`                                                                                                                                                                                                                                                   |
-| `rag_*`           | `client.rag`           | `rag_invalid_request`, `rag_dim_mismatch`, `rag_embedding_failed`, `rag_error`                                                                                                                                                                                                                           |
-| `approval_*`      | `client.approval`      | `approval_invalid_request`, `approval_invalid_signature`, `approval_signature_expired`, `approval_signing_key_missing`, `approval_invalid_payload`, `approval_tool_execute_failed`, `approval_unauthorized`, `approval_forbidden`, `approval_not_found`, `approval_rate_limited`, `approval_unavailable` |
-| `secrets_*`       | `client.secrets`       | `secrets_invalid_request`, `secrets_not_found`, `secrets_invalid_response`, `secrets_unauthorized`, `secrets_forbidden`, `secrets_rate_limited`, `secrets_unavailable`                                                                                                                                   |
-| `config_*`        | `client.config`        | `config_invalid_request`, `config_not_found`, `config_invalid_response`, `config_unauthorized`, `config_forbidden`, `config_rate_limited`, `config_unavailable`                                                                                                                                          |
-| `memory_*`        | `client.memory`        | reserved for the future mem0-backed implementation; today every method returns `not_implemented`                                                                                                                                                                                                         |
-| `http_*`          | transport-level errors | `http_timeout`, `http_aborted`, `http_network_error`, `http_parse_error`, `http_request_failed` — surface-level statuses (401/403/404/429/5xx) remap to `<surface>_*` codes                                                                                                                              |
-| `database_*`      | `client.database`      | `database_not_configured` (raised when `STACKBONE_POSTGRES_URL` is unset)                                                                                                                                                                                                                                |
-| `observability_*` | `client.observability` | `observability_close_run_failed`                                                                                                                                                                                                                                                                         |
-| `contract_*`      | gated surfaces         | `contract_malformed`, `contract_unreachable`, `contract_version_unsupported` — emitted by any gated call when the contract handshake fails                                                                                                                                                               |
-| `capability_*`    | gated surfaces         | `capability_unavailable` — emitted when the negotiated contract advertises no support for the surface                                                                                                                                                                                                    |
-| `*_missing`       | configuration          | `agent_id_missing`, `openrouter_key_missing`, `database_url_missing`, `stackbone_api_url_missing`                                                                                                                                                                                                        |
-| `not_implemented` | stubbed module surface | returned by every "coming soon" method until it ships                                                                                                                                                                                                                                                    |
+| Prefix            | Source                                                          | Examples                                                                                                                                                                                                                                                                                                 |
+| ----------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ai_*`            | `client.ai`                                                     | `ai_unauthorized`, `ai_credits_exhausted`, `ai_rate_limited`, `ai_aborted`, `ai_no_image_generated`                                                                                                                                                                                                      |
+| `s3_*`            | `client.storage`                                                | `s3_credentials_missing`, `s3_invalid_key`, `s3_error`                                                                                                                                                                                                                                                   |
+| `rag_*`           | `client.rag`                                                    | `rag_invalid_request`, `rag_dim_mismatch`, `rag_embedding_failed`, `rag_error`                                                                                                                                                                                                                           |
+| `approval_*`      | `client.approval`                                               | `approval_invalid_request`, `approval_invalid_signature`, `approval_signature_expired`, `approval_signing_key_missing`, `approval_invalid_payload`, `approval_tool_execute_failed`, `approval_unauthorized`, `approval_forbidden`, `approval_not_found`, `approval_rate_limited`, `approval_unavailable` |
+| `secrets_*`       | `client.secrets`                                                | `secrets_invalid_request`, `secrets_not_found`, `secrets_invalid_response`, `secrets_unauthorized`, `secrets_forbidden`, `secrets_rate_limited`, `secrets_unavailable`                                                                                                                                   |
+| `config_*`        | `client.config`                                                 | `config_invalid_request`, `config_not_found`, `config_invalid_response`, `config_unauthorized`, `config_forbidden`, `config_rate_limited`, `config_unavailable`                                                                                                                                          |
+| `memory_*`        | `client.memory`                                                 | reserved for the future mem0-backed implementation; today every method returns `not_implemented`                                                                                                                                                                                                         |
+| `http_*`          | transport-level errors                                          | `http_timeout`, `http_aborted`, `http_network_error`, `http_parse_error`, `http_request_failed` — surface-level statuses (401/403/404/429/5xx) remap to `<surface>_*` codes                                                                                                                              |
+| `database_*`      | `client.database`                                               | `database_not_configured` (raised when `STACKBONE_POSTGRES_URL` is unset)                                                                                                                                                                                                                                |
+| `observability_*` | run-cost rollup (`@stackbone/sdk/observability`, runtime-wired) | `observability_close_run_failed`                                                                                                                                                                                                                                                                         |
+| `contract_*`      | gated surfaces                                                  | `contract_malformed`, `contract_unreachable`, `contract_version_unsupported` — emitted by any gated call when the contract handshake fails                                                                                                                                                               |
+| `capability_*`    | gated surfaces                                                  | `capability_unavailable` — emitted when the negotiated contract advertises no support for the surface                                                                                                                                                                                                    |
+| `*_missing`       | configuration                                                   | `agent_id_missing`, `openrouter_key_missing`, `database_url_missing`, `stackbone_api_url_missing`                                                                                                                                                                                                        |
+| `not_implemented` | stubbed module surface                                          | returned by every "coming soon" method until it ships                                                                                                                                                                                                                                                    |
 
 > The canonical inventory of every code lives in `src/errors/codes.ts` as a typed catalog (`SdkErrorCode`). The table above is the human-readable summary; adding or removing a code is a single-file edit there and the compiler refuses any literal `code` value not declared in the catalog. Pattern-match against `SdkErrorCode` (exported from `@stackbone/sdk`) for full type narrowing, or call `isSdkErrorCode(raw)` to widen a wire string back into the catalog.
 

package/db/index.d.cts

@@ -1,3 +1,4 @@
 export * from 'drizzle-orm';
 export * from 'drizzle-orm/pg-core';
 export { ColumnsWithTable, SelectedFields, SelectedFieldsFlat, SelectedFieldsOrdered, TableConfig } from 'drizzle-orm/pg-core';
+import '@stackbone/rag-core/schema';

package/db/index.d.ts

@@ -1,3 +1,4 @@
 export * from 'drizzle-orm';
 export * from 'drizzle-orm/pg-core';
 export { ColumnsWithTable, SelectedFields, SelectedFieldsFlat, SelectedFieldsOrdered, TableConfig } from 'drizzle-orm/pg-core';
+import '@stackbone/rag-core/schema';