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

package/README.md

@@ -13,17 +13,14 @@ Official TypeScript SDK for [Stackbone](https://stackbone.ai) — the marketplac
 - **Database** — Direct Postgres access through a lazy Drizzle ORM wrapper bound to the agent's connection string, with full type-safe queries, transactions, and `sql` template literals — Drizzle is re-exported via `@stackbone/sdk/db` so the agent's `package.json` only depends on `@stackbone/sdk`
 - **Storage** — S3-compatible object storage (Cloudflare R2 in prod, MinIO in dev) with automatic per-agent key prefixing and signed URLs
 - **AI** — Wrapper around the official `openai` SDK pointed at OpenRouter, so 300+ chat, embedding and image models are reachable through a single OpenAI-compatible API
-- **Queues** _(coming soon)_ — Cross-container HTTP push via QStash, with typed job payloads through module augmentation
 - **RAG** — Document parsing, chunking and `pgvector`-backed retrieval through a flat, ceremony-free API
-- **Memory** _(surface defined; runtime pending)_ — Long-term agent memory backed by mem0: ingest text or whole conversations, semantic search, per-user / per-session / per-agent scoping, GDPR delete-all, audit history and session lifecycle hooks
-- **Prompts** _(surface defined; runtime pending)_ — Managed prompts stored in the Stackbone control plane: fetch by name with optional version pinning, compile Mustache `{{var}}` templates against a variables map, and full CRUD so prompts can evolve without rebuilding the container
 - **Observability** — OpenTelemetry span processor + run-cost aggregator + per-run logger
 - **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
-- **Connections / Events** — OAuth integrations (Notion, GDrive, Slack…) and an organization event bus
+- **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
 
@@ -40,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',
@@ -72,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.
@@ -83,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));
 });
@@ -116,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.
@@ -127,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',
@@ -135,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,
@@ -159,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
@@ -173,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.' },
@@ -189,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,
@@ -206,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.',
 });
@@ -214,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:
@@ -230,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 },
 );
@@ -244,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',
@@ -262,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,
@@ -273,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,
@@ -287,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,
 });
@@ -296,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.
@@ -331,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',
@@ -349,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':
@@ -370,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,
@@ -381,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: {
@@ -405,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()],
@@ -436,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 }
 ```
 
@@ -452,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']);
@@ -470,98 +495,29 @@ const { data: cfg } = await stackbone.config.getMany<{
 
 `secrets.get` returns `secrets_not_found` (with the name in `meta`) when the secret is missing; `config.get` returns `config_not_found` symmetrically. Both `getMany` calls return whatever subset the organization has registered — no error for missing entries.
 
-### Memory
-
-`client.memory` is the agent's long-term memory surface. The first iteration is a **scaffolding placeholder** — every method returns `not_implemented`. The public types and signatures defined here are stable and the contract callers can already type their integrations against. The real backend will be [mem0](https://mem0.ai) (`mem0ApiKey` / `MEM0_API_KEY`).
-
-Memories are scoped along three axes:
-
-- `'user'` — long-term, persists across sessions of a given end user. Default.
-- `'session'` — short-lived; collapsed (or dropped) when `endSession()` runs.
-- `'agent'` — shared across every user of the agent (preferences, global knowledge).
-
-```ts
-// Ingest a fact (raw text or an OpenAI-shaped conversation).
-const { data: memory } = await stackbone.memory.add(
-  'The user prefers replies in Spanish and addresses them by their last name.',
-  { userId: 'user_42', scope: 'user', metadata: { source: 'onboarding' } },
-);
-
-// Or ingest a whole conversation — the backend summarises it into facts.
-await stackbone.memory.add(
-  [
-    { role: 'user', content: 'Call me Mr. Torres please.' },
-    { role: 'assistant', content: 'Got it, Mr. Torres.' },
-  ],
-  { userId: 'user_42', sessionId: 'sess_abc', scope: 'session' },
-);
-
-// Semantic search across the user's memories.
-const { data: hits } = await stackbone.memory.search('how should I address this user?', {
-  userId: 'user_42',
-  limit: 5,
-  threshold: 0.7,
-  includeScopes: ['user', 'agent'],
-});
-```
-
-Management — read, paginate, edit and audit a single fact:
-
-```ts
-const { data: memory } = await stackbone.memory.get(memoryId);
-
-const { data: page } = await stackbone.memory.list({
-  userId: 'user_42',
-  limit: 50,
-  cursor: previousCursor,
-});
-
-await stackbone.memory.update(memoryId, {
-  content: 'The user prefers replies in Spanish.',
-  metadata: { reviewed: true },
-});
-
-const { data: events } = await stackbone.memory.history(memoryId);
-```
-
-Deletion — single fact, all data for a user (GDPR), or end-of-session collapse:
-
-```ts
-// Forget one fact.
-await stackbone.memory.delete(memoryId);
-
-// GDPR: forget everything we have on this user.
-await stackbone.memory.deleteAll({ userId: 'user_42' });
+### Memory (pending)
 
-// Close a session and consolidate its facts into long-term memory (default).
-const { data } = await stackbone.memory.endSession('sess_abc', { persist: true });
-// data: { sessionId, persisted }
-```
-
-> Until the mem0 integration ships, every method returns `{ data: null, error: { code: 'not_implemented', ... } }`. The shape of the responses described here is the contract callers can already write code against.
+Long-term memory is a pending surface: its public types (`AddMemoryRequest`, `MemoryItem`, `MemoryHit`, `MemoryScope`, …) are exported from `@stackbone/sdk` so creators can type their integrations today, but there is no live `client.memory` accessor yet. The mem0-backed runtime will be added in a future release and promoted into the Features list above. See the [Coming Soon](#coming-soon) section for the full pending set.
 
 ### Coming Soon
 
-The following modules are part of the public surface but currently return a `not_implemented` error. They will land iteratively as the platform rolls out:
+The following surfaces have stable public **types** (so creators can write code against them today) but no runtime yet. They live under `src/surfaces/pending/` in the SDK source and do NOT appear as `client.X` accessors — importing the types directly from `@stackbone/sdk` is the supported path while the runtime is in flight:
 
 ```ts
-// Push an HTTP job to another agent (QStash-backed under the hood).
-await stackbone.queues.publish({
-  url: 'https://agent-b.stackbone.ai/invoke',
-  body: { leadId: 42 },
-  retries: 3,
-});
-
-// Emit an event to the organization event bus.
-await stackbone.events.emit('lead.qualified', { leadId: 42 });
-
-// List OAuth connections the user attached (Notion, GDrive, Slack…).
-const { data: connections } = await stackbone.connections.list();
+import type {
+  PublishRequest,
+  AddMemoryRequest,
+  MemoryHit,
+  Prompt,
+  CreatePromptRequest,
+} from '@stackbone/sdk';
 ```
 
+The pending surfaces are `queues` (cross-container HTTP push), `memory` (mem0-backed long-term memory), `prompts` (managed prompts with `{{var}}` templates), `connections` (OAuth integrations) and `events` (organisation event bus). When their runtime lands they will be promoted into the live `client.X` set described in the Features section above.
+
 ## 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({
@@ -577,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
@@ -602,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
 
@@ -622,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);
@@ -634,18 +588,24 @@ 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` |
-| `secrets_*`       | `client.secrets`       | `secrets_invalid_request`, `secrets_not_found`, `secrets_invalid_response`                                                                                                         |
-| `config_*`        | `client.config`        | `config_invalid_request`, `config_not_found`, `config_invalid_response`                                                                                                            |
-| `memory_*`        | `client.memory`        | reserved for the future mem0-backed implementation; today every method returns `not_implemented`                                                                                   |
-| `http_*`          | facade HTTP client     | `http_unauthorized`, `http_timeout`, `http_rate_limited`, `http_server_error`                                                                                                      |
-| `*_missing`       | configuration          | `database_not_configured`, `agent_id_missing`, `openrouter_key_missing`, `database_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.
 
 ## TypeScript Support
 

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';