@stackbone/sdk 0.1.0-alpha.5 → 0.1.0-alpha.6

package/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0-alpha.6] - 2026-06-17
+
 ### Added
 
 - **`client.connections` surface (gated by the new `connections.actions`

package/index.cjs

@@ -8877,7 +8877,8 @@ var journalTerminalStatusSchema = zod.z.enum([
 ]);
 var journalJobStatusSchema = zod.z.enum([
   ...journalTerminalStatusSchema.options,
-  "running"
+  "running",
+  "lost"
 ]);
 var jobStatusSchema = zod.z.enum([
   ...bullmqJobStatusSchema.options,
@@ -8979,6 +8980,27 @@ zod.z.object({
   queue: zod.z.string(),
   status: jobStatusSchema
 });
+zod.z.object({
+  items: zod.z.array(bullmqJobSchema)
+});
+zod.z.object({
+  purged: zod.z.number().int().nonnegative()
+});
+zod.z.object({
+  payload: jsonObject(),
+  retries: zod.z.number().int().nonnegative().optional(),
+  delay: zod.z.number().int().nonnegative().optional()
+});
+zod.z.object({
+  message_id: zod.z.string(),
+  queue: queueNameSchema
+});
+zod.z.object({
+  name: queueNameSchema
+});
+zod.z.object({
+  limit: zod.z.coerce.number().int().min(1).max(50).default(10)
+});
 
 // ../shared/validators/src/lib/agents/queue-jobs.ts
 var MAX_JOB_ATTEMPTS = 20;
@@ -9937,7 +9959,7 @@ var ApprovalFacade = class {
     const fallback = onTimeoutToFallback(options.onTimeout);
     const callbackUrl = options.onDecide;
     try {
-      const rows = await sql.data`
+      const rows = await this._getDatabase().runShared((db) => db`
         INSERT INTO stackbone_platform.approvals (
               topic, payload, callback_url, idempotency_key,
               fallback, metadata, timeout_at
@@ -9956,7 +9978,7 @@ var ApprovalFacade = class {
           RETURNING id, callback_url,
                     to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at,
                     to_char(timeout_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS timeout_at
-      `;
+      `);
       const row = rows[0];
       if (!row) {
         return err({
@@ -9991,13 +10013,13 @@ var ApprovalFacade = class {
       const patch = reason ? {
         cancelReason: reason
       } : {};
-      await sql.data`
+      await this._getDatabase().runShared((db) => db`
         UPDATE stackbone_platform.approvals
            SET status = 'cancelled',
                decided_at = now(),
                metadata = metadata || ${JSON.stringify(patch)}::jsonb
          WHERE id = ${approvalId}::uuid AND status = 'pending'
-      `;
+      `);
       return ok(void 0);
     } catch (cause) {
       return err({
@@ -10017,14 +10039,14 @@ var ApprovalFacade = class {
     const sql = this.sql();
     if (sql.error) return err(sql.error);
     try {
-      const rows = await sql.data`
+      const rows = await this._getDatabase().runShared((db) => db`
         SELECT id, topic, status, payload, metadata,
                to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at,
                to_char(timeout_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS timeout_at
           FROM stackbone_platform.approvals
          WHERE id = ${approvalId}::uuid
          LIMIT 1
-      `;
+      `);
       const row = rows[0];
       if (!row) {
         return err({
@@ -10049,7 +10071,7 @@ var ApprovalFacade = class {
     if (sql.error) return err(sql.error);
     const limit = clampLimit(options.limit);
     try {
-      const rows = await sql.data`
+      const rows = await this._getDatabase().runShared((db) => db`
         SELECT id, topic, status, payload, metadata,
                to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at,
                to_char(timeout_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS timeout_at
@@ -10058,7 +10080,7 @@ var ApprovalFacade = class {
            AND (${options.topic ?? null}::text IS NULL OR topic = ${options.topic ?? null})
          ORDER BY created_at DESC, id DESC
          LIMIT ${limit}
-      `;
+      `);
       return ok({
         items: rows.map((row) => toRecord(row))
       });
@@ -10224,9 +10246,9 @@ var ConfigFacade = class {
     const sql = this.sql();
     if (sql.error) return err(sql.error);
     try {
-      const rows = await sql.data`
+      const rows = await this._getDatabase().runShared((db) => db`
         SELECT payload FROM stackbone_platform.agent_config WHERE id = 1
-      `;
+      `);
       return ok(rows[0]?.payload ?? null);
     } catch (cause) {
       return err({
@@ -10300,6 +10322,10 @@ function isPoolTerminatedError(error) {
   return typeof code === "string" && POOL_TERMINATED_ERROR_CODES.has(code);
 }
 __name(isPoolTerminatedError, "isPoolTerminatedError");
+function invalidatePoolHandle() {
+  cachedHandle = null;
+}
+__name(invalidatePoolHandle, "invalidatePoolHandle");
 async function runWithColdStartRetry(firstAttempt, retryAttempt) {
   try {
     return await firstAttempt();
@@ -10468,6 +10494,48 @@ var DatabaseModule = class {
   // a half-baked tx. The contract gate fires before the first attempt.
   transaction = /* @__PURE__ */ __name((...args) => withColdStartRetry(() => getDatabaseHandle(this._databaseUrl).transaction(...args), this._gate), "transaction");
   /**
+  * Cross-surface raw-SQL runner carrying the SAME cold-start resilience the
+  * query-builder verbs above get. Sibling agent-local surfaces (`approval`,
+  * `config`, `secrets`, `prompts`) that issue tagged-template queries over the
+  * shared postgres-js `Sql` MUST execute them through this instead of caching
+  * `shared().$client` once and calling it directly. Otherwise a dead pooled
+  * socket — Fly Machines suspending the Machine between invokes, or a
+  * WSL2/Docker localhost relay dropping an idle connection during a long LLM
+  * step — surfaces as an unretried `CONNECTION_ENDED`/`ECONNRESET`. That is
+  * exactly the asymmetry that let `client.approval.request` fail while the
+  * `client.database.insert` right before it recovered.
+  *
+  * `fn` receives a FRESH `$client` on each attempt, so the single retry runs
+  * against the rebuilt pool. Whole-operation granularity is replayed as a
+  * unit — pass a multi-statement `sql.begin(...)` transaction or a helper that
+  * fires several queries and the replay re-runs all of it; postgres-js never
+  * commits a half-applied tx, so that is safe. SQLSTATE application errors
+  * pass straight through without a retry. Like `shared()`/`raw()`, the
+  * contract gate is intentionally NOT consulted here — gating surfaces gate at
+  * their own call sites.
+  */
+  runShared(fn) {
+    return withColdStartRetry(() => fn(getDatabaseHandle(this._databaseUrl).$client));
+  }
+  /**
+  * `Result`-shaped sibling of `runShared` for surfaces whose driver swallows
+  * the dead-socket error into a returned `Result.err.cause` instead of
+  * throwing it — today only `client.rag`, whose `RagPipeline` returns a
+  * `Result` rather than throwing. `attempt` runs once; if it comes back with a
+  * pool-terminated `cause`, the pool is rebuilt and `attempt` replays exactly
+  * once, then its result (success or the fresh error) is returned verbatim.
+  * The `Result` contract is preserved end to end: a still-dead socket on the
+  * replay surfaces as the surface's own `Result.err`, never as a raw throw.
+  */
+  async runSharedResult(attempt) {
+    const first = await attempt();
+    if (!first.error || !isPoolTerminatedError(first.error.cause)) return first;
+    process.stderr.write(`[stackbone/sdk] database cold-start reconnect: rebuilding pool after ${first.error.cause.code ?? "unknown"}
+`);
+    invalidatePoolHandle();
+    return attempt();
+  }
+  /**
   * Canonical accessor for the **shared-handles pattern**. Returns the
   * process-wide Drizzle handle backing `client.database`. Cross-surface
   * SDK consumers (RAG today, memory / queues tomorrow) call this — never
@@ -10569,12 +10637,12 @@ var PromptsFacade = class {
     const sql = this.sql();
     if (sql.error) return err(sql.error);
     try {
-      const head = await fetchHead(sql.data, key);
+      const head = await this._getDatabase().runShared((db) => fetchHead(db, key));
       if (!head) {
         return err(notFound(key));
       }
       if (options?.version !== void 0 && options.version !== head.current_version) {
-        const content = await fetchVersionContent(sql.data, key, options.version);
+        const content = await this._getDatabase().runShared((db) => fetchVersionContent(db, key, options.version));
         if (content === null) {
           return err({
             code: "prompts_not_found",
@@ -10625,7 +10693,7 @@ var PromptsFacade = class {
     const sql = this.sql();
     if (sql.error) return err(sql.error);
     try {
-      const rows = await sql.data`
+      const rows = await this._getDatabase().runShared((db) => db`
         SELECT p.key, p.name, p.description, p.current_version, p.metadata,
                p.created_at, p.updated_at, v.content
           FROM stackbone_platform.prompts p
@@ -10634,7 +10702,7 @@ var PromptsFacade = class {
          WHERE p.deleted_at IS NULL
          ORDER BY p.key
          LIMIT ${limit}
-      `;
+      `);
       return ok({
         items: rows.map((row) => rowToPrompt(row, row.current_version, row.content))
       });
@@ -10661,7 +10729,7 @@ var PromptsFacade = class {
     if (sql.error) return err(sql.error);
     const variables = extractVars(request.template);
     try {
-      const head = await sql.data.begin(async (tx) => {
+      const head = await this._getDatabase().runShared((db) => db.begin(async (tx) => {
         await tx`
           INSERT INTO stackbone_platform.prompts
             (key, name, description, current_version, metadata)
@@ -10689,7 +10757,7 @@ var PromptsFacade = class {
            WHERE p.key = ${request.key}
         `;
         return rows[0];
-      });
+      }));
       if (!head) {
         return err({
           code: "prompts_unavailable",
@@ -10722,7 +10790,7 @@ var PromptsFacade = class {
     const sql = this.sql();
     if (sql.error) return err(sql.error);
     try {
-      const head = await sql.data.begin(async (tx) => {
+      const head = await this._getDatabase().runShared((db) => db.begin(async (tx) => {
         await tx`SELECT pg_advisory_xact_lock(hashtext(${`prompts:${key}`}))`;
         const existing = await tx`
           SELECT p.key, p.name, p.description, p.current_version, p.metadata,
@@ -10766,7 +10834,7 @@ var PromptsFacade = class {
            WHERE p.key = ${key}
         `;
         return rows[0] ?? null;
-      });
+      }));
       if (head === null) {
         return err(notFound(key));
       }
@@ -10781,12 +10849,12 @@ var PromptsFacade = class {
     const sql = this.sql();
     if (sql.error) return err(sql.error);
     try {
-      const rows = await sql.data`
+      const rows = await this._getDatabase().runShared((db) => db`
         UPDATE stackbone_platform.prompts
            SET deleted_at = now(), updated_at = now()
          WHERE key = ${key} AND deleted_at IS NULL
          RETURNING key
-      `;
+      `);
       const deleted = rows.length;
       if (deleted === 0) {
         return err(notFound(key));
@@ -11870,8 +11938,10 @@ var RagModule = class {
       const sql = this.sql();
       if (sql.error) return err(sql.error);
       try {
-        await sql.data`DROP TABLE IF EXISTS rag_chunks`;
-        await sql.data`DROP TABLE IF EXISTS _rag_meta`;
+        await this._getDatabase().runShared(async (db) => {
+          await db`DROP TABLE IF EXISTS rag_chunks`;
+          await db`DROP TABLE IF EXISTS _rag_meta`;
+        });
         return ok(void 0);
       } catch (cause) {
         return err(toRagError(cause, "Reset failed"));
@@ -11921,13 +11991,15 @@ var RagModule = class {
     }
   }
   async withPipeline(embedder, run) {
-    const pipeline = new RagPipeline({
-      sqlProvider: /* @__PURE__ */ __name(() => this.sql(), "sqlProvider"),
-      ...embedder && {
-        embedder
-      }
+    return this._getDatabase().runSharedResult(async () => {
+      const pipeline = new RagPipeline({
+        sqlProvider: /* @__PURE__ */ __name(() => this.sql(), "sqlProvider"),
+        ...embedder && {
+          embedder
+        }
+      });
+      return await run(pipeline);
     });
-    return await run(pipeline);
   }
 };
 function countChunks(request) {
@@ -15810,12 +15882,12 @@ var SecretsFacade = class {
     if (sql.error) return err(sql.error);
     let rows;
     try {
-      rows = await sql.data`
+      rows = await this._getDatabase().runShared((db) => db`
         SELECT version, nonce, ciphertext
           FROM stackbone_platform.secrets
          WHERE name = ${name}
          LIMIT 1
-      `;
+      `);
     } catch (cause) {
       return err({
         code: "secrets_unavailable",
@@ -15861,11 +15933,11 @@ var SecretsFacade = class {
     if (sql.error) return err(sql.error);
     let rows;
     try {
-      rows = await sql.data`
+      rows = await this._getDatabase().runShared((db) => db`
         SELECT name, version, nonce, ciphertext
           FROM stackbone_platform.secrets
          WHERE name = ANY(${names})
-      `;
+      `);
     } catch (cause) {
       return err({
         code: "secrets_unavailable",
@@ -17274,9 +17346,7 @@ var STORED_TO_SDK_ENV = {
   S3_REGION: "STACKBONE_S3_REGION",
   // OpenRouter (`client.ai`) — identity.
   OPENROUTER_API_KEY: "OPENROUTER_API_KEY",
-  OPENROUTER_BASE_URL: "OPENROUTER_BASE_URL",
-  // Axiom (observability) — identity.
-  AXIOM_TOKEN: "AXIOM_TOKEN"
+  OPENROUTER_BASE_URL: "OPENROUTER_BASE_URL"
 };
 function rehydrateSystemSecretsRows(env, rows, cipher, databaseUrl) {
   const applied = [];