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

package/CHANGELOG.md

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0-alpha.2] - 2026-05-18
+
+### Fixed
+
+- `client.rag.ingest` (batched mode, e.g. when an `onProgress` callback or a
+  `jobWriter` is wired): every chunk batch was wrapping its INSERT in a
+  transaction that first ran `DELETE FROM rag_chunks WHERE namespace=? AND
+  doc_id=?`. With N batches per document, only the rows inserted by the LAST
+  batch survived — every earlier slice was wiped by the next batch's DELETE.
+  Split the DELETE into a single `clearDocument` call before the loop;
+  `ingestDocument` now only INSERTs its slice.
+- `client.rag` error mapping: `42P01 relation does not exist` was only
+  translated to `SdkError('rag_schema_missing')` from the pipeline path.
+  `reset()`, the database-handle resolver, and `client.rag.ingestAsync`'s job
+  writer used a divergent local copy of `toRagError` that surfaced the raw
+  Postgres code instead. Consolidated all three call sites onto a shared
+  `modules/rag/errors.ts` so the schema-missing hint is consistent.
+- `RunStepsSpanProcessor.stepIdBySpanId`: spans without a `stackbone.run.id`
+  attribute leaked their reservation in the map — `buildRow` returned early
+  before the cleanup line ran. Cleanup now happens unconditionally on every
+  `onEnd`, so dropped spans no longer accumulate.
+
+### Changed
+
+- OTLP log records sent by `createPlatformLogger` now carry the actual
+  installed SDK version under `scope.version`. Previously every record was
+  tagged with a hardcoded `'0.0.1'` regardless of what was published.
+- `client.rag.reset()` invalidates the cached schema fingerprint, so the
+  first ingest after a reset re-provisions the schema without serving a
+  stale `rag_dim_mismatch`.
+- `client.rag.ingest`: `ensureSchema` now memoises the verified dimensions
+  per `Sql` instance, dropping the per-call `_rag_meta` SELECT on the hot
+  path. The `stackbone_rag_jobs` writer also collapses its
+  `ensureCollection` lookup to a single `INSERT … ON CONFLICT … RETURNING`
+  (was a `SELECT` followed by an upsert) and trims `isCancelled` to
+  `SELECT status … LIMIT 1`.
+- `OtlpLogsBody` serialisation no longer iterates `Object.entries(LOG_LEVELS)`
+  per record to map level numbers to severity text — precomputed lookup
+  table replaces the linear scan.
+- `RagModule` test seams (`sqlProvider`, `jobWriterFactory`) now flow
+  through a typed 4th constructor parameter (`RagModuleTestDeps`) instead of
+  private fields mutated via `as unknown as` casts.
+
+## [0.1.0-alpha.1] - 2026-05-15
+
+### BREAKING
+
+- Runtime env contract collapsed under `STACKBONE_*`. The SDK no longer
+  reads `AWS_ACCESS_KEY_ID` / `S3_ACCESS_KEY` / `S3_ENDPOINT` /
+  `S3_BUCKET` / `S3_REGION` / `DATABASE_URL`. Creators must export
+  `STACKBONE_S3_ACCESS_KEY`, `STACKBONE_S3_SECRET_KEY`,
+  `STACKBONE_S3_ENDPOINT`, `STACKBONE_S3_BUCKET`, `STACKBONE_S3_REGION`,
+  `STACKBONE_POSTGRES_URL`. `client.storage` derives its multi-tenant
+  key prefix from `STACKBONE_AGENT_ID` (injected by `stackbone dev` and
+  the cloud runner) so the run-steps exporter and Studio Storage share
+  the same prefix.
+
+### Added
+
+- New validator schemas re-exported from the bundled `@stackbone/validators`
+  surface for the Studio Playground contract: `schemaResponseSchema`
+  (`{ input: JsonSchema | null, output: JsonSchema | null }`) and
+  `fixtureIdParamSchema`.
+
 ## [0.1.0-alpha.0] - 2026-05-14
 
 ### Added

package/README.md

@@ -15,13 +15,13 @@ Official TypeScript SDK for [Stackbone](https://stackbone.ai) — the marketplac
 - **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
+- **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 workspace-encrypted secrets registered in the dashboard, no client-side cache so rotations propagate immediately
+- **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** _(coming soon)_ — OAuth integrations (Notion, GDrive, Slack…) and a workspace event bus
+- **Connections / Events** — OAuth integrations (Notion, GDrive, Slack…) and an organization 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
 
@@ -327,7 +327,7 @@ await stackbone.rag.reset();
 
 `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.
+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 idle scale-to-zero and arbitrary numbers of concurrent approvals without tying up sockets.
 
 ```ts
 // 1. Issue an approval — returns immediately, the human reviews asynchronously.
@@ -432,7 +432,7 @@ The signing key for `verify()` is read from `STACKBONE_APPROVAL_SIGNING_KEY` (or
 
 ### 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.
+`client.secrets` reads organization-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.
@@ -468,7 +468,7 @@ const { data: cfg } = await stackbone.config.getMany<{
 }>(['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.
+`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
 
@@ -552,7 +552,7 @@ await stackbone.queues.publish({
   retries: 3,
 });
 
-// Emit an event to the workspace event bus.
+// 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…).
@@ -571,8 +571,8 @@ const stackbone = createClient({
   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.
+  // Postgres connection string for `client.database`, `client.rag` and the
+  // observability exporter                                  → STACKBONE_POSTGRES_URL
   databaseUrl: 'postgresql://...',
   // OpenRouter credentials                                  → OPENROUTER_API_KEY / OPENROUTER_BASE_URL
   openrouterKey: '...',
@@ -586,12 +586,13 @@ const stackbone = createClient({
   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
+  // Object storage credentials                              → STACKBONE_S3_ACCESS_KEY / STACKBONE_S3_SECRET_KEY / STACKBONE_S3_ENDPOINT / STACKBONE_S3_BUCKET / STACKBONE_S3_REGION
   s3: {
     accessKeyId: '...',
     secretAccessKey: '...',
     endpoint: 'https://<account>.r2.cloudflarestorage.com',
     bucket: 'stackbone-prod',
+    region: 'auto',
   },
   // OpenTelemetry exporter
   otel: {