@stackbone/sdk 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,693 @@
+# @stackbone/sdk
+
+[![License](https://img.shields.io/badge/License-Proprietary-lightgrey.svg)](#license)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/types-TypeScript-blue.svg)](https://www.typescriptlang.org/)
+
+Official TypeScript SDK for [Stackbone](https://stackbone.ai) — the marketplace and managed runtime for containerized AI agents. Stackbone provisions a Postgres branch, object storage, an LLM gateway and the rest of the platform primitives for every agent; this SDK is the in-container surface those agents call.
+
+> "You write the agent. We connect it to the world."
+
+## Features
+
+- **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** _(coming soon)_ — 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** _(coming soon)_ — 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** _(coming soon)_ — OpenTelemetry traces and logs flushed through the platform collector
+- **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 workspace-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** _(coming soon)_ — OAuth integrations (Notion, GDrive, Slack…) and a workspace event bus
+- **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
+
+## Installation
+
+`@stackbone/sdk` is the SDK every published agent depends on. Inside the Stackbone monorepo it is available via the `@stackbone/sdk` workspace alias. From a generated agent project:
+
+```bash
+# Alpha (today)
+pnpm add @stackbone/sdk@alpha
+
+# Once we cut a stable release the unscoped tag will resolve to the latest
+# minor:
+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).
+
+## Quick Start
+
+### Initialize 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:
+
+```ts
+import { createClient } from '@stackbone/sdk';
+
+const stackbone = createClient();
+```
+
+Pass overrides explicitly when you need them — useful for local development against the emulator, or when running outside a Stackbone container:
+
+```ts
+import { createClient } from '@stackbone/sdk';
+
+const stackbone = createClient({
+  agentJwt: process.env.STACKBONE_AGENT_JWT,
+  stackboneApiUrl: 'http://localhost:3000',
+  agentId: 'agent_local_dev',
+  openrouterKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+### Database
+
+`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 { eq, integer, pgTable, text } from '@stackbone/sdk/db';
+
+// 1. Declare your tables — types flow end to end.
+const leads = pgTable('leads', {
+  id: integer('id').primaryKey(),
+  email: text('email').notNull(),
+  status: text('status').notNull(),
+  score: integer('score').notNull(),
+});
+
+const stackbone = createClient();
+
+// 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 stackbone.database
+  .insert(leads)
+  .values({ id: 1, email: 'jane@example.com', status: 'new', score: 0 });
+
+await stackbone.database.update(leads).set({ status: 'contacted' }).where(eq(leads.id, 1));
+
+await stackbone.database.delete(leads).where(eq(leads.id, 1));
+```
+
+Interactive transactions yield a `tx` with the same Drizzle surface as `client.database`:
+
+```ts
+await stackbone.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));
+});
+```
+
+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()`);
+```
+
+> 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.
+
+### Storage
+
+`client.storage` is bucket-scoped via `from(bucket)` and transparently prefixes every key with `${agentId}/${bucket}/` before talking to S3 / R2 / MinIO, so your agent code never has to think about multi-tenancy:
+
+```ts
+// Upload an object
+const { data, error } = await stackbone.storage
+  .from('uploads')
+  .upload('reports/2026-04-29.pdf', pdfBlob, {
+    contentType: 'application/pdf',
+    metadata: { source: 'leads-agent' },
+  });
+
+// Download an object (returns a Blob)
+const { data, error } = await stackbone.storage.from('uploads').download('reports/2026-04-29.pdf');
+
+// List objects (paginated)
+const { data, error } = await stackbone.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');
+```
+
+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
+  .from('uploads')
+  .getSignedUploadUrl('avatars/user-42.png', {
+    expiresIn: 600,
+    contentType: 'image/png',
+  });
+
+// 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
+  .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');
+```
+
+### AI
+
+`client.ai` mirrors the official `openai` SDK shape but every request is routed through OpenRouter, so you can pick from 300+ models with a single API key. The Stackbone platform attributes usage and billing back to the agent through OpenRouter Activity — no proxy in the middle.
+
+```ts
+// Chat completion
+const { data, error } = await stackbone.ai.chat.completions.create({
+  model: 'anthropic/claude-sonnet-4.5',
+  messages: [
+    { role: 'system', content: 'You are a sales qualification assistant.' },
+    { role: 'user', content: 'Score this lead: ...' },
+  ],
+});
+
+if (!error) {
+  console.log(data.choices[0]?.message.content);
+}
+```
+
+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({
+  model: 'anthropic/claude-sonnet-4.5',
+  messages: [{ role: 'user', content: 'Stream me a haiku.' }],
+  stream: true,
+});
+
+if (!error) {
+  for await (const chunk of stream) {
+    process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+  }
+}
+```
+
+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({
+  model: 'openai/text-embedding-3-small',
+  input: 'A red Spanish sword from the 11th century.',
+});
+
+// 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({
+  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();
+```
+
+Cancellation works the way you'd expect — pass an `AbortSignal` and aborts surface as `ai_aborted` on non-streaming calls:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5_000);
+
+const { data, error } = await stackbone.ai.chat.completions.create(
+  { model: 'anthropic/claude-sonnet-4.5', messages: [...] },
+  { signal: controller.signal },
+);
+```
+
+### RAG
+
+`client.rag` exposes a flat, ceremony-free retrieval API on top of `pgvector` running in the agent's Postgres branch. There are no collections to create, no handles to thread through your code: the schema is auto-provisioned on the first `ingest()` and the embedding dimensions are inferred from the first chunk.
+
+The fast path lets the SDK handle embeddings for you — pass an embedding `model` and the chunks as plain strings, and `client.rag` calls `client.ai.embeddings.create` internally with batching:
+
+```ts
+// 1. Parse a document → plain text. Supports text/*, text/markdown and application/pdf.
+const text = await stackbone.rag.parse(file);
+
+// 2. Split into chunks. Pure utility, no DB call.
+const chunks = stackbone.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({
+  id: 'doc-1',
+  chunks,
+  model: 'openai/text-embedding-3-small',
+  metadata: { source: 'manual-upload' },
+});
+
+// 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({
+  text: 'how does X work?',
+  model: 'openai/text-embedding-3-small',
+  topK: 5,
+  filter: { source: 'manual-upload' },
+});
+```
+
+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({
+  model: 'openai/text-embedding-3-small',
+  input: chunks,
+});
+
+await stackbone.rag.ingest({
+  id: 'doc-1',
+  chunks: chunks.map((content, i) => ({
+    content,
+    embedding: embeddings.data[i].embedding,
+  })),
+  metadata: { source: 'manual-upload' },
+});
+
+const { data: hits } = await stackbone.rag.retrieve({
+  embedding: queryEmbedding,
+  topK: 5,
+});
+```
+
+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 stackbone.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({
+  id: 'faq-1',
+  chunks: [...],
+  namespace: 'faqs',
+});
+
+await stackbone.rag.retrieve({ embedding, namespace: 'faqs' });
+await stackbone.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();
+```
+
+> `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.
+
+### Approval (Human-In-The-Loop)
+
+`client.approval` exposes a **fire-and-forget** primitive: the agent issues an approval request, the call returns immediately with the `approvalId` and a `callbackUrl`, and the control plane POSTs the human's decision to the endpoint the agent registered in `onDecide`. The callback is HMAC-signed (`Stackbone-Signature: t=<unix>,v1=<hex>`) so the agent can authenticate it without storing any per-approval secret.
+
+This shape decouples waiting from the container lifecycle — the agent does not have to keep a long-poll connection alive while a human reviews, which means it survives Neon scale-to-zero and arbitrary numbers of concurrent approvals without tying up sockets.
+
+```ts
+// 1. Issue an approval — returns immediately, the human reviews asynchronously.
+const { data, error } = await stackbone.airoval.request({
+  topic: 'lead.qualify',
+  payload: { leadId: 42, score: 0.6 },
+  title: 'Approve lead qualification',
+  description: 'Score is below the auto-qualify threshold (0.7).',
+  onDecide: '/approvals/lead-qualify',
+  timeout: '24h', // ISO duration or ms; default 24h
+  onTimeout: 'reject', // 'reject' | 'approve' | 'ignore'
+  approver: 'team:sales',
+  idempotencyKey: 'qualify-42',
+  metadata: { runId: 'r_123' },
+});
+// data: { approvalId, status: 'pending', callbackUrl, expiresAt }
+
+// 2. Receive the decision — `verify()` authenticates the inbound POST and
+//    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);
+  if (result.error) return c.text('invalid', 401);
+  switch (result.data.status) {
+    case 'approved':
+      await processLead(result.data.payload);
+      break;
+    case 'rejected':
+      await archiveLead(result.data.payload);
+      break;
+    case 'timed_out':
+    case 'cancelled':
+      // No payload — only `decidedAt` (and an optional `reason` for cancelled).
+      break;
+  }
+  return c.json({ ok: true });
+});
+```
+
+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({
+  status: 'pending',
+  topic: 'lead.qualify',
+  limit: 50,
+});
+```
+
+#### 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.
+
+```ts
+const sendInvoice = stackbone.airoval.tool({
+  name: 'send_invoice',
+  description: 'Send an invoice to a recipient.',
+  parameters: {
+    type: 'object',
+    properties: {
+      amount: { type: 'number' },
+      recipient: { type: 'string' },
+    },
+    required: ['amount', 'recipient'],
+  },
+  needsApproval: ({ amount }) => amount > 1000,
+  toRequest: (input) => ({
+    onDecide: '/approvals/send-invoice',
+    title: `Send invoice for $${input.amount}`,
+    description: `Recipient: ${input.recipient}`,
+  }),
+  execute: async ({ amount, recipient }) => sendInvoiceImpl(amount, recipient),
+});
+
+// Pass the tool to chat.completions.create — it speaks the OpenAI shape.
+const completion = await stackbone.ai.chat.completions.create({
+  model: 'anthropic/claude-sonnet-4.5',
+  messages,
+  tools: [sendInvoice.openaiSpec()],
+});
+
+// Drive the tool calls the LLM emitted.
+for (const call of completion.data?.choices[0]?.message.tool_calls ?? []) {
+  const r = await sendInvoice.invoke(JSON.parse(call.function.arguments));
+  if (r.error) return { error: r.error };
+  if (r.data.status === 'pending') {
+    // Approval was created. Persist agent state and break the loop —
+    // the decision callback will resume it.
+    return { pending: r.data.approvalId };
+  }
+  messages.push({
+    role: 'tool',
+    tool_call_id: call.id,
+    content: JSON.stringify(r.data.result),
+  });
+}
+```
+
+The signing key for `verify()` is read from `STACKBONE_APPROVAL_SIGNING_KEY` (or `approvalSigningKey` on `createClient`). Timestamp tolerance defaults to 300 seconds; tighten or override per call with `verify(req, { toleranceSeconds: 60 })`.
+
+### Secrets
+
+`client.secrets` reads workspace-encrypted secrets the user registered in the dashboard. The SDK is **read-only** by design — secrets are managed in the control plane, never written from inside an agent container. There is no client-side cache: every `get()` is a network call so dashboard rotations propagate immediately.
+
+```ts
+// Single secret — `secrets_not_found` error if the name is not registered.
+const { data: apiKey, error } = await stackbone.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']);
+// secrets: { STRIPE_API_KEY?: string; SLACK_BOT_TOKEN?: string }
+```
+
+### Config
+
+`client.config` reads dynamic per-agent configuration the user set in the dashboard (tone, thresholds, feature flags, prompts…). Like `secrets`, it is read-only and uncached — and the value is fully typed via the generic on `get`.
+
+```ts
+// Typed read — the generic narrows `data` to `'formal' | 'casual'`.
+const { data: tone } = await stackbone.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');
+
+// Bulk read — typed via the second generic; missing keys come back as omissions.
+const { data: cfg } = await stackbone.config.getMany<{
+  reply_tone: 'formal' | 'casual';
+  max_emails: number;
+}>(['reply_tone', 'max_emails']);
+```
+
+`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 workspace 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' });
+
+// 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.
+
+### 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:
+
+```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 workspace 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();
+```
+
+## 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:
+
+```ts
+const stackbone = createClient({
+  // Ed25519 JWT signed by the control plane                → STACKBONE_AGENT_JWT
+  agentJwt: '...',
+  // Stackbone control plane base URL (used by facades)        → STACKBONE_API_URL
+  stackboneApiUrl: 'https://api.stackbone.ai',
+  // Stable agent identifier used as storage key prefix     → STACKBONE_AGENT_ID
+  agentId: 'agent_abc123',
+  // Postgres connection string for `client.rag` / observability (escape hatch).
+  // Note: `client.database` reads `STACKBONE_POSTGRES_URL`, not this one.
+  databaseUrl: 'postgresql://...',
+  // 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
+  mem0ApiKey: '...',
+  mem0BaseUrl: 'https://api.mem0.ai',
+  // HMAC key for verifying approval-decision callbacks       → STACKBONE_APPROVAL_SIGNING_KEY
+  approvalSigningKey: '...',
+  // Object storage credentials                              → AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / S3_ENDPOINT / S3_BUCKET
+  s3: {
+    accessKeyId: '...',
+    secretAccessKey: '...',
+    endpoint: 'https://<account>.r2.cloudflarestorage.com',
+    bucket: 'stackbone-prod',
+  },
+  // OpenTelemetry exporter
+  otel: {
+    exporterOtlpEndpoint: 'https://otel.stackbone.ai',
+    resourceAttributes: 'service.name=my-agent',
+  },
+});
+```
+
+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.
+
+## Result Envelope and Error Handling
+
+Every SDK method returns the same discriminated union:
+
+```ts
+type Result<T> = { data: T; error: null } | { data: null; error: SdkError };
+
+interface SdkError {
+  code: string; // stable, machine-readable
+  message: string; // human-readable
+  cause?: unknown; // upstream error, when relevant
+  meta?: Record<string, unknown>; // status code, model, etc.
+}
+```
+
+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 });
+
+if (result.error) {
+  console.error(`[${result.error.code}] ${result.error.message}`, result.error.meta);
+  return;
+}
+
+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                                                                                                                              |
+
+## TypeScript Support
+
+The SDK is written in TypeScript and ships its own type definitions:
+
+```ts
+import { createClient, StackboneClient, type Result, type SdkError } from '@stackbone/sdk';
+
+const stackbone: StackboneClient = createClient();
+
+const result = await stackbone.ai.chat.completions.create({
+  model: 'anthropic/claude-sonnet-4.5',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+Chat, embeddings and streaming types are re-exported directly from the `openai` package — by design, an agent author who already knows the OpenAI SDK does not have to relearn anything.
+
+For typed queue payloads, augment the `QueueJobs` registry once and both publisher and consumer pick up the shape:
+
+```ts
+declare module '@stackbone/sdk/queues/types' {
+  interface QueueJobs {
+    'lead.qualified': { leadId: number; score: number };
+    'send-report': { reportId: string; recipient: string };
+  }
+}
+```
+
+## Runtime
+
+The SDK targets Node.js 24+ inside the agent container. It is not designed for browser bundles — direct database access, S3 SDK usage and the agent JWT all assume a server-side runtime. For browser-side flows (uploads, public asset access), use the signed URLs returned by `client.storage` and let the browser hit S3 directly.
+
+## Documentation
+
+- **[Stackbone TECH_STACK](../../docs/TECH_STACK.md)** — Normative stack and platform primitives
+- **[ADR — SDK monolítico del agente](../../docs/arquitectura/decisiones/2026-04-24-sdk-monolitico-agente.md)** — Why a single SDK, scope of every module, error model
+- **[Componente — SDK & Creator DX](../../docs/arquitectura/componentes/04-sdk-creator-dx.md)** — End-to-end developer experience for agent creators
+
+## License
+
+Proprietary © Stackbone. All rights reserved. This package is published privately for the Stackbone platform; it is not licensed for redistribution.
+
+---
+
+Built with ❤️ by the Stackbone team