@desplega.ai/agent-swarm 1.95.0 → 1.97.0

package/src/be/scripts/boot-reembed.ts

@@ -1,17 +1,17 @@
 /**
  * Post-listen backfill: embed scripts that are missing embeddings (e.g. after
- * boot seeding with scriptEmbeddingMode: "skip"). Runs once per boot,
- * async/non-blocking, idempotent, no-op when every non-scratch script already
- * has an embedding row.
+ * boot seeding with scriptEmbeddingMode: "skip") AND re-embed scripts whose
+ * stored embedding has the wrong dimension (e.g. 1536d legacy rows vs current
+ * 512d). Runs once per boot, async/non-blocking, idempotent, no-op when clean.
  *
  * Mirrors the memory boot-reembed pattern (src/be/memory/boot-reembed.ts).
  */
 
 import { getDb } from "@/be/db";
 import type { ScriptScope } from "@/types";
-import { embedScript } from "./embeddings";
+import { embeddingProvider, embedScript } from "./embeddings";
 
-type ScriptMissingEmbedding = {
+type ScriptRow = {
   id: string;
   name: string;
   scope: ScriptScope;
@@ -31,35 +31,65 @@ type ScriptMissingEmbedding = {
   updatedAt: string;
 };
 
+function toScriptRecord(row: ScriptRow) {
+  return {
+    ...row,
+    scopeId: row.scopeId ?? null,
+    isScratch: row.isScratch === 1,
+    typeChecked: row.typeChecked === 1,
+    createdByAgentId: row.createdByAgentId ?? null,
+  };
+}
+
 export async function runBootReembedScripts(): Promise<void> {
   const db = getDb();
+  const provider = embeddingProvider();
+  const expectedBytes = provider.dimensions * Float32Array.BYTES_PER_ELEMENT;
 
   const missing = db
-    .prepare<ScriptMissingEmbedding, []>(
+    .prepare<ScriptRow, []>(
       `SELECT s.* FROM scripts s
        LEFT JOIN script_embeddings e ON e.scriptId = s.id
        WHERE s.isScratch = 0 AND e.scriptId IS NULL`,
     )
     .all();
 
-  if (missing.length === 0) {
+  const wrongDim = db
+    .prepare<ScriptRow, []>(
+      `SELECT s.* FROM scripts s
+       JOIN script_embeddings e ON e.scriptId = s.id
+       WHERE s.isScratch = 0 AND length(e.embedding) != ${expectedBytes}`,
+    )
+    .all();
+
+  if (missing.length === 0 && wrongDim.length === 0) {
     return;
   }
 
-  console.log(`[boot-reembed-scripts] starting: ${missing.length} scripts missing embeddings`);
+  if (missing.length > 0) {
+    console.log(`[boot-reembed-scripts] ${missing.length} scripts missing embeddings`);
+  }
+  if (wrongDim.length > 0) {
+    console.log(
+      `[boot-reembed-scripts] ${wrongDim.length} scripts with wrong-dimension embeddings (expected ${expectedBytes} bytes)`,
+    );
+  }
+
+  // Probe: verify the provider can actually generate embeddings
+  const probe = await provider.embed("test");
+  if (!probe) {
+    console.warn(
+      `[boot-reembed-scripts] skipped: no working embedding provider (missing OpenAI key?)`,
+    );
+    return;
+  }
 
   let embedded = 0;
   let failed = 0;
 
-  for (const row of missing) {
+  for (const row of [...missing, ...wrongDim]) {
     try {
-      await embedScript({
-        ...row,
-        scopeId: row.scopeId ?? null,
-        isScratch: row.isScratch === 1,
-        typeChecked: row.typeChecked === 1,
-        createdByAgentId: row.createdByAgentId ?? null,
-      });
+      await embedScript(toScriptRecord(row));
       embedded++;
     } catch (err) {
       failed++;
@@ -70,5 +100,15 @@ export async function runBootReembedScripts(): Promise<void> {
     }
   }
 
-  console.log(`[boot-reembed-scripts] complete: embedded=${embedded} failed=${failed}`);
+  const afterWrongDim =
+    db
+      .prepare<{ count: number }, []>(
+        `SELECT COUNT(*) as count FROM script_embeddings
+         WHERE length(embedding) != ${expectedBytes}`,
+      )
+      .get()?.count ?? 0;
+
+  console.log(
+    `[boot-reembed-scripts] complete: embedded=${embedded} failed=${failed} remaining_wrong_dim=${afterWrongDim}`,
+  );
 }

package/src/be/scripts/embeddings.ts

@@ -42,7 +42,7 @@ export type ScriptSearchResult = {
 
 let providerOverride: EmbeddingProvider | null = null;
 
-function embeddingProvider(): EmbeddingProvider {
+export function embeddingProvider(): EmbeddingProvider {
   return providerOverride ?? getEmbeddingProvider();
 }
 
@@ -82,6 +82,13 @@ export async function embedScript(script: ScriptRecord): Promise<void> {
   const embedding = await provider.embed(text);
   if (!embedding) return;
 
+  if (embedding.length !== provider.dimensions) {
+    console.error(
+      `[script-embed] dimension mismatch for "${script.name}": expected=${provider.dimensions} got=${embedding.length}, skipping`,
+    );
+    return;
+  }
+
   getDb()
     .prepare(
       `INSERT INTO script_embeddings (
@@ -204,20 +211,24 @@ export async function searchScripts(args: {
   const candidates = candidateRows(args.scope, args.scopeId);
   if (candidates.length === 0) return lexicalFallback(args);
 
-  return candidates
-    .map((row) => {
-      const script = rowToScript(row);
-      const semanticScore = cosineSimilarity(queryEmbedding, deserializeEmbedding(row.embedding));
-      const bonus = nameMatchBonus(script, args.query);
-      return {
-        script,
-        score: 0.7 * semanticScore + 0.3 * bonus,
-        semanticScore,
-        nameMatchBonus: bonus,
-      };
-    })
-    .sort((a, b) => b.score - a.score)
-    .slice(0, args.limit ?? 10);
+  const results: ScriptSearchResult[] = [];
+  for (const row of candidates) {
+    const stored = deserializeEmbedding(row.embedding);
+    if (stored.length !== queryEmbedding.length) continue;
+    const script = rowToScript(row);
+    const semanticScore = cosineSimilarity(queryEmbedding, stored);
+    const bonus = nameMatchBonus(script, args.query);
+    results.push({
+      script,
+      score: 0.7 * semanticScore + 0.3 * bonus,
+      semanticScore,
+      nameMatchBonus: bonus,
+    });
+  }
+
+  if (results.length === 0) return lexicalFallback(args);
+
+  return results.sort((a, b) => b.score - a.score).slice(0, args.limit ?? 10);
 }
 
 export async function reembedAllScripts(): Promise<void> {

package/src/commands/provider-credentials.ts

@@ -29,6 +29,21 @@ import { scrubSecrets } from "../utils/secret-scrubber";
 
 export type SupportedProvider = "claude" | "claude-managed" | "codex" | "devin" | "opencode" | "pi";
 
+/**
+ * True when the pi harness should use the AWS SDK Bedrock path: either an
+ * explicit `BEDROCK_AUTH_MODE=sdk`, or — preserving prefix-inference semantics —
+ * `BEDROCK_AUTH_MODE` absent with a `MODEL_OVERRIDE=amazon-bedrock/*` selection.
+ * Single source of truth for the gate so the live-test arm and the worker
+ * reconcile loop agree with `checkPiMonoCredentials`.
+ */
+export function isBedrockSdkMode(env: Record<string, string | undefined>): boolean {
+  const mode = env.BEDROCK_AUTH_MODE?.toLowerCase();
+  return (
+    mode === "sdk" ||
+    (mode === undefined && Boolean(env.MODEL_OVERRIDE?.toLowerCase().startsWith("amazon-bedrock/")))
+  );
+}
+
 /**
  * Static documentation of which env vars each provider considers when running
  * `checkCredentials`. Used by the dashboard to render hints before any worker
@@ -243,7 +258,7 @@ function parseCodexOAuthAccess(blob: string | undefined): string | null {
  * | `codex`          | `~/.codex/auth.json` (file) → `CODEX_OAUTH` (env OAuth) → `OPENAI_API_KEY` | OpenAI `/v1/models` (api-key path only) |
  * | `opencode`       | `OPENROUTER_API_KEY` → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` (pi-style) | matching provider's `/v1/models` |
  * | `pi`             | `OPENROUTER_API_KEY` → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY`           | matching provider's `/v1/models` |
- * | `pi` (bedrock)   | `MODEL_OVERRIDE=amazon-bedrock/*` → AWS SDK default credential chain    | presence-only (validated at first inference call) |
+ * | `pi` (bedrock)   | `MODEL_OVERRIDE=amazon-bedrock/*` → AWS SDK default credential chain    | presence-only (real check is the worker-side Bedrock enumeration) |
  * | `devin`          | `DEVIN_API_KEY` (+ `DEVIN_API_BASE_URL` override)                       | `${baseUrl}/v1/sessions?limit=1` |
  *
  * Returns `{ok: true, latency_ms}` on 2xx, `{ok: false, error, latency_ms}`
@@ -302,20 +317,14 @@ export async function validateProviderCredentials(provider: string): Promise<Liv
       }
       case "pi":
       case "opencode": {
-        // For the pi Bedrock path, the real credential check is the
-        // `ListFoundationModels` probe that `checkProviderCredentials` (the
-        // `pi` dynamic-import arm) already ran.  That probe result is already
-        // in `buildCredStatusReport` — the live-test is a pass-through / no-op
-        // so we never issue a second AWS SDK call here (which would drag the
-        // SDK into the wrong binary or make slow IMDS calls on non-EC2 hosts).
-        // Bedrock mode: explicit BEDROCK_AUTH_MODE=sdk OR
-        //               absent BEDROCK_AUTH_MODE + amazon-bedrock/ MODEL_OVERRIDE prefix.
-        if (
-          provider === "pi" &&
-          (env.BEDROCK_AUTH_MODE?.toLowerCase() === "sdk" ||
-            (env.BEDROCK_AUTH_MODE === undefined &&
-              env.MODEL_OVERRIDE?.toLowerCase().startsWith("amazon-bedrock/")))
-        ) {
+        // For the pi Bedrock path, the real credential check is the AWS SDK
+        // enumeration (`ListFoundationModels` + `ListInferenceProfiles`) that
+        // `checkProviderCredentials` (the `pi` dynamic-import arm) already ran.
+        // That result is already in `buildCredStatusReport` — the live-test is a
+        // pass-through / no-op so we never issue a second AWS SDK call here
+        // (which would drag the SDK into the wrong binary or make slow IMDS
+        // calls on non-EC2 hosts).
+        if (provider === "pi" && isBedrockSdkMode(env)) {
           return presenceCheckOk();
         }
         // Both pi-mono and opencode resolve credentials in the same order:
@@ -408,6 +417,18 @@ export async function buildCredStatusReport(
       testedAt: Date.now(),
     };
   }
+  // Include the Bedrock enumeration block when the pi probe ran in Bedrock SDK
+  // mode (bedrockRegion is only set by checkPiMonoCredentials in that branch).
+  const bedrock: AgentCredStatus["bedrock"] =
+    presence.bedrockRegion !== undefined
+      ? {
+          region: presence.bedrockRegion,
+          probedAt: Date.now(),
+          ready: presence.ready,
+          models: presence.bedrockModels ?? [],
+          error: presence.ready ? undefined : (presence.hint ?? undefined),
+        }
+      : null;
   return {
     ready: presence.ready,
     missing: presence.missing ?? [],
@@ -417,6 +438,7 @@ export async function buildCredStatusReport(
     latestModel: null,
     reportedAt: Date.now(),
     reportKind: kind,
+    bedrock,
   };
 }
 

package/src/commands/runner.ts

@@ -45,6 +45,7 @@ import {
   isRateLimitMessage,
   MAX_RATE_LIMIT_RESET_MS,
   parseRateLimitResetTime,
+  type RateLimitWindowTelemetry,
   resolveCodexCreditsExhaustedCooldownMs,
 } from "../utils/error-tracker.ts";
 import { resolveHarnessProvider } from "../utils/harness-provider.ts";
@@ -60,6 +61,7 @@ import { resolveClaudeMdPath, syncProfileFilesToServer } from "./profile-sync.ts
 import {
   buildCredStatusReport,
   buildLatestModelReport,
+  isBedrockSdkMode,
   isCredCheckDisabled,
   reportCredStatus,
   reportLatestModel,
@@ -1124,6 +1126,35 @@ async function reportKeyRateLimit(
   }
 }
 
+async function reportKeyRateLimitWindows(
+  apiUrl: string,
+  apiKey: string,
+  keyType: string,
+  keySuffix: string,
+  keyIndex: number,
+  windows: RateLimitWindowTelemetry,
+): Promise<void> {
+  if (Object.keys(windows).length === 0) return;
+  try {
+    await fetch(`${apiUrl}/api/keys/report-rate-limit-windows`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        keyType,
+        keySuffix,
+        keyIndex,
+        windows,
+      }),
+    });
+    console.log(`[credentials] Reported rate-limit windows for key ...${keySuffix}`);
+  } catch {
+    // Non-blocking
+  }
+}
+
 /** Clear a stale rate-limit record after a successful task (fire-and-forget) */
 async function reportKeyClearRateLimit(
   apiUrl: string,
@@ -3405,6 +3436,17 @@ async function checkCompletedProcesses(
           rateLimitedUntil,
         ).catch(() => {});
       }
+
+      if (credentialInfo && result.rateLimitWindows) {
+        reportKeyRateLimitWindows(
+          apiConfig.apiUrl,
+          apiConfig.apiKey,
+          credentialInfo.keyType,
+          credentialInfo.keySuffix,
+          credentialInfo.keyIndex,
+          result.rateLimitWindows,
+        ).catch(() => {});
+      }
       let bridgeDiagnostics: Awaited<ReturnType<typeof getBridgeFailureDiagnostics>> | undefined;
       if (result.exitCode !== 0 && harnessProvider === "claude" && workingDir) {
         bridgeDiagnostics = await getBridgeFailureDiagnostics(workingDir);
@@ -3848,6 +3890,16 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   let lastHarnessReconcileAt = 0;
   const HARNESS_RECONCILE_INTERVAL_MS = 10_000;
 
+  // Throttle for the periodic Bedrock model-enumeration refresh. The credential
+  // report below only re-runs on a harness_provider change (boot + provider
+  // swap), so enabling Bedrock access after boot would otherwise never reach the
+  // picker. This timer re-runs the enumeration on a fixed interval, decoupled
+  // from the harness-change gate, so the UI stays accurate. 5 minutes keeps it
+  // cheap (one bounded AWS enumeration per tick) while still surfacing newly
+  // granted access within a few minutes.
+  let lastBedrockRefreshAt = 0;
+  const BEDROCK_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+
   // Create API config for ping/close
   const apiConfig: ApiConfig = { apiUrl, apiKey, agentId };
 
@@ -4572,6 +4624,22 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           .catch((err) =>
             console.warn(`[${role}] cred_status post_task report failed (non-fatal): ${err}`),
           );
+      } else if (
+        currentHarness === "pi" &&
+        isBedrockSdkMode(process.env) &&
+        Date.now() - lastBedrockRefreshAt > BEDROCK_REFRESH_INTERVAL_MS
+      ) {
+        // Bedrock enumeration drifts independently of the harness_provider:
+        // access granted (or revoked) in the AWS console after boot won't flip
+        // the provider, so the harness-change gate above never fires. Re-run the
+        // enumeration on the throttled interval so the picker reflects the live
+        // account state. One bounded AWS round-trip per tick.
+        lastBedrockRefreshAt = Date.now();
+        buildCredStatusReport(currentHarness, process.env, {}, "post_task")
+          .then((snap) => reportCredStatus(apiUrl, apiKey, agentId, snap))
+          .catch((err) =>
+            console.warn(`[${role}] bedrock enumeration refresh failed (non-fatal): ${err}`),
+          );
       }
     }
 

package/src/http/agents.ts

@@ -615,6 +615,7 @@ export async function handleAgentsRest(
         latestModel: null,
         reportedAt: parsed.body.latest_model.reportedAt,
         reportKind: "post_task" as const,
+        bedrock: null,
       };
       finalAgent =
         updateAgentCredStatus(parsed.params.id, {

package/src/http/api-keys.ts

@@ -6,6 +6,7 @@ import {
   getKeyCostSummary,
   getKeyStatuses,
   markKeyRateLimited,
+  recordKeyRateLimitWindows,
   recordKeyUsage,
   setApiKeyName,
 } from "../be/db";
@@ -58,6 +59,37 @@ const reportRateLimit = route({
   auth: { apiKey: true },
 });
 
+const rateLimitWindowSchema = z.object({
+  status: z.string(),
+  utilization: z.number().optional(),
+  resetsAt: z.number().optional(),
+  isUsingOverage: z.boolean().optional(),
+  surpassedThreshold: z.number().optional(),
+  lastSeenAt: z.string().datetime(),
+});
+
+const reportRateLimitWindows = route({
+  method: "post",
+  path: "/api/keys/report-rate-limit-windows",
+  pattern: ["api", "keys", "report-rate-limit-windows"],
+  summary: "Record provider-emitted rate-limit window telemetry for an API key",
+  tags: ["API Keys"],
+  body: z.object({
+    keyType: z.string(),
+    keySuffix: z.string().min(1).max(10),
+    keyIndex: z.number().int().min(0),
+    windows: z.record(z.string(), rateLimitWindowSchema),
+    scope: z.string().optional(),
+    scopeId: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Rate-limit window telemetry recorded" },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
 const getAvailable = route({
   method: "get",
   path: "/api/keys/available",
@@ -196,6 +228,25 @@ export async function handleApiKeys(
     return true;
   }
 
+  // POST /api/keys/report-rate-limit-windows
+  if (reportRateLimitWindows.match(req.method, pathSegments)) {
+    const parsed = await reportRateLimitWindows.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const { keyType, keySuffix, keyIndex, windows, scope, scopeId } = parsed.body;
+    try {
+      recordKeyRateLimitWindows(keyType, keySuffix, keyIndex, windows, scope, scopeId ?? null);
+      json(res, { success: true, message: `Rate-limit windows recorded for ...${keySuffix}` });
+    } catch (err) {
+      jsonError(
+        res,
+        err instanceof Error ? err.message : "Failed to record rate-limit windows",
+        500,
+      );
+    }
+    return true;
+  }
+
   // GET /api/keys/available
   if (getAvailable.match(req.method, pathSegments)) {
     const parsed = await getAvailable.parse(req, res, pathSegments, queryParams);

package/src/http/config.ts

@@ -14,6 +14,7 @@ import {
   reservedKeyError,
   validateConfigValue,
 } from "../be/swarm-config-guard";
+import { registerVolatileSecret } from "../utils/secret-scrubber";
 import { reloadGlobalConfigsAndIntegrations, scheduleIntegrationsReload } from "./core";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
@@ -152,7 +153,15 @@ export async function handleConfig(
       parsed.query.agentId || undefined,
       parsed.query.repoId || undefined,
     );
-    json(res, { configs: includeSecrets ? configs : maskSecrets(configs) });
+    const result = includeSecrets ? configs : maskSecrets(configs);
+    if (includeSecrets) {
+      for (const c of result) {
+        if (c.isSecret && c.value) {
+          registerVolatileSecret(c.value, `config:${c.key}`);
+        }
+      }
+    }
+    json(res, { configs: result });
     return true;
   }
 
@@ -199,8 +208,11 @@ export async function handleConfig(
       jsonError(res, "Config not found", 404);
       return true;
     }
-    const result = includeSecrets ? config : maskSecrets([config])[0];
-    json(res, result);
+    const singleResult = includeSecrets ? config : maskSecrets([config])[0]!;
+    if (includeSecrets && singleResult.isSecret && singleResult.value) {
+      registerVolatileSecret(singleResult.value, `config:${singleResult.key}`);
+    }
+    json(res, singleResult);
     return true;
   }
 
@@ -212,7 +224,15 @@ export async function handleConfig(
       scope: parsed.query.scope || undefined,
       scopeId: parsed.query.scopeId || undefined,
     });
-    json(res, { configs: includeSecrets ? configs : maskSecrets(configs) });
+    const listResult = includeSecrets ? configs : maskSecrets(configs);
+    if (includeSecrets) {
+      for (const c of listResult) {
+        if (c.isSecret && c.value) {
+          registerVolatileSecret(c.value, `config:${c.key}`);
+        }
+      }
+    }
+    json(res, { configs: listResult });
     return true;
   }
 

package/src/http/index.ts

@@ -576,6 +576,15 @@ httpServer
       .catch((err) => {
         console.error("[boot-reembed-scripts] startup backfill failed (non-fatal):", err);
       });
+
+    // One-time scrub: retroactively redact any session_logs rows containing
+    // sensitive patterns that pre-date the defense-in-depth scrub layer.
+    // Idempotent, tracked via seed_state.
+    import("../be/boot-scrub-logs")
+      .then(({ runBootScrubLogs }) => runBootScrubLogs())
+      .catch((err) => {
+        console.error("[boot-scrub-logs] startup scrub failed (non-fatal):", err);
+      });
   })
   .on("error", (err) => {
     console.error("HTTP Server Error:", err);

package/src/prompts/session-templates.ts

@@ -158,6 +158,27 @@ When you finish a task:
 - **Failure**: Use \`store-progress\` with status: "failed" and failureReason: "<what went wrong>"
 
 Always include meaningful output - the lead agent reviews your work.
+
+#### Credential Hygiene
+
+When you retrieve secrets via \`get-config\` (with \`includeSecrets: true\`), **never pass secret values directly on a command line or embed them in tool output**. Command arguments are logged.
+
+**Safe pattern:** Write the secret to a temporary \`.env\` file, then source it:
+\`\`\`bash
+# Write to temp file (not logged)
+echo "MY_TOKEN=<value>" > /tmp/.task-env && source /tmp/.task-env
+# Use the variable (value stays out of logs)
+curl -H "Authorization: Bearer $MY_TOKEN" https://api.example.com
+rm /tmp/.task-env
+\`\`\`
+
+**Unsafe pattern (NEVER do this):**
+\`\`\`bash
+# The literal secret appears in the logged command
+curl -H "Authorization: Bearer lin_oauth_abc123..." https://api.example.com
+\`\`\`
+
+The same applies to \`store-progress\` output — never include raw secret values in progress text, output, or failure reasons.
 `,
   variables: [],
   category: "system",

package/src/providers/claude-adapter.ts

@@ -674,6 +674,7 @@ class ClaudeSession implements ProviderSession {
       isError: (exitCode ?? 1) !== 0,
       failureReason,
       rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
+      rateLimitWindows: this.errorTracker.getRateLimitWindows(),
     };
   }
 

package/src/providers/codex-adapter.ts

@@ -1024,6 +1024,7 @@ export class CodexSession implements ProviderSession {
             isError: true,
             failureReason: terminalError.message,
             rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
+            rateLimitWindows: this.errorTracker.getRateLimitWindows(),
           });
           return;
         }
@@ -1045,6 +1046,7 @@ export class CodexSession implements ProviderSession {
         isError,
         failureReason: terminalError?.message,
         rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
+        rateLimitWindows: this.errorTracker.getRateLimitWindows(),
       });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -1059,6 +1061,7 @@ export class CodexSession implements ProviderSession {
         isError: true,
         failureReason: message,
         rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
+        rateLimitWindows: this.errorTracker.getRateLimitWindows(),
       });
     } finally {
       // Session-end summarization. Pure addition for codex — no behavior to

package/src/providers/harness-version.ts

@@ -1,6 +1,53 @@
-export function readPkgVersion(packageName: string): string | undefined {
+import { spawnSync } from "node:child_process";
+
+type PackageJson = { version?: unknown };
+
+type ReadPkgVersionOptions = {
+  requirePackageJson?: (specifier: string) => PackageJson;
+  spawn?: typeof spawnSync;
+};
+
+const cliVersionCommands: Record<string, { command: string; args: string[] }> = {
+  "@earendil-works/pi-coding-agent": { command: "pi", args: ["--version"] },
+  "@opencode-ai/sdk": { command: "opencode", args: ["--version"] },
+};
+
+function normalizeVersion(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function parseCliVersion(output: string): string | undefined {
+  return output.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/)?.[0];
+}
+
+function readCliVersion(packageName: string, spawn: typeof spawnSync): string | undefined {
+  const command = cliVersionCommands[packageName];
+  if (!command) return undefined;
+
+  try {
+    const result = spawn(command.command, command.args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return parseCliVersion(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+  } catch {
+    return undefined;
+  }
+}
+
+export function readPkgVersion(
+  packageName: string,
+  {
+    requirePackageJson = (specifier) => require(specifier) as PackageJson,
+    spawn = spawnSync,
+  }: ReadPkgVersionOptions = {},
+): string | undefined {
+  const cliVersion = readCliVersion(packageName, spawn);
+  if (cliVersion) return cliVersion;
+
   try {
-    return require(`${packageName}/package.json`).version;
+    const version = normalizeVersion(requirePackageJson(`${packageName}/package.json`).version);
+    if (version) return version;
   } catch {
     return undefined;
   }