@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/be/seed-skills/index.ts

@@ -16,8 +16,6 @@ import agentBrowserContent from "../../../templates/skills/agent-browser/content
 };
 import appsConfig from "../../../templates/skills/apps/config.json" with { type: "text" };
 import appsContent from "../../../templates/skills/apps/content.md" with { type: "text" };
-import artifactsConfig from "../../../templates/skills/artifacts/config.json" with { type: "text" };
-import artifactsContent from "../../../templates/skills/artifacts/content.md" with { type: "text" };
 import askUserConfig from "../../../templates/skills/ask-user/config.json" with { type: "text" };
 import askUserContent from "../../../templates/skills/ask-user/content.md" with { type: "text" };
 import assetNamespacesConfig from "../../../templates/skills/asset-namespaces/config.json" with {
@@ -38,6 +36,8 @@ import brainstormingConfig from "../../../templates/skills/brainstorming/config.
 import brainstormingContent from "../../../templates/skills/brainstorming/content.md" with {
   type: "text",
 };
+import chatSdkConfig from "../../../templates/skills/chat-sdk/config.json" with { type: "text" };
+import chatSdkContent from "../../../templates/skills/chat-sdk/content.md" with { type: "text" };
 import codeQualityConfig from "../../../templates/skills/code-quality/config.json" with {
   type: "text",
 };
@@ -96,6 +96,12 @@ import downloadTaskAttachmentConfig from "../../../templates/skills/download-tas
 import downloadTaskAttachmentContent from "../../../templates/skills/download-task-attachment/content.md" with {
   type: "text",
 };
+import emailDomainHealthConfig from "../../../templates/skills/email-domain-health/config.json" with {
+  type: "text",
+};
+import emailDomainHealthContent from "../../../templates/skills/email-domain-health/content.md" with {
+  type: "text",
+};
 import engineeringStandardsConfig from "../../../templates/skills/engineering-standards/config.json" with {
   type: "text",
 };
@@ -144,6 +150,8 @@ import planningConfig from "../../../templates/skills/planning/config.json" with
 import planningContent from "../../../templates/skills/planning/content.md" with { type: "text" };
 import qaConfig from "../../../templates/skills/qa/config.json" with { type: "text" };
 import qaContent from "../../../templates/skills/qa/content.md" with { type: "text" };
+import qaLoomConfig from "../../../templates/skills/qa-loom/config.json" with { type: "text" };
+import qaLoomContent from "../../../templates/skills/qa-loom/content.md" with { type: "text" };
 import questioningConfig from "../../../templates/skills/questioning/config.json" with {
   type: "text",
 };
@@ -268,9 +276,11 @@ import wtsExpertConfig from "../../../templates/skills/wts-expert/config.json" w
 import wtsExpertContent from "../../../templates/skills/wts-expert/content.md" with {
   type: "text",
 };
+import type { Skill } from "../../types";
 import {
   computeContentHash,
   createSkill,
+  deleteSkill,
   deleteSkillFile,
   getDbClient,
   getSkillByName,
@@ -278,7 +288,9 @@ import {
   updateSkill,
   upsertSkillFiles,
 } from "../db";
+import { deleteSeedState, getSeedState } from "../seed/state-db";
 import type { Seeder, SeedItem } from "../seed/types";
+import { parseSkillContent } from "../skill-parser";
 import bundledFilesManifest from "./bundled-files.generated.json";
 import { buildSkillContent, type SkillTemplateConfig } from "./render";
 
@@ -319,11 +331,11 @@ const BUILT_IN_SKILL_FILES = bundledFilesManifest as Record<string, SeedSkillFil
 const BUILT_IN_SKILL_SOURCES = [
   { config: agentBrowserConfig, body: agentBrowserContent },
   { config: appsConfig, body: appsContent },
-  { config: artifactsConfig, body: artifactsContent },
   { config: askUserConfig, body: askUserContent },
   { config: assetNamespacesConfig, body: assetNamespacesContent },
   { config: attioInteractionConfig, body: attioInteractionContent },
   { config: brainstormingConfig, body: brainstormingContent },
+  { config: chatSdkConfig, body: chatSdkContent },
   { config: codeQualityConfig, body: codeQualityContent },
   { config: codeReviewingConfig, body: codeReviewingContent },
   { config: commsConfig, body: commsContent },
@@ -335,6 +347,7 @@ const BUILT_IN_SKILL_SOURCES = [
   { config: delegateWorkConfig, body: delegateWorkContent },
   { config: designDocsConfig, body: designDocsContent },
   { config: downloadTaskAttachmentConfig, body: downloadTaskAttachmentContent },
+  { config: emailDomainHealthConfig, body: emailDomainHealthContent },
   { config: engineeringStandardsConfig, body: engineeringStandardsContent },
   { config: heartbeatRunbookConfig, body: heartbeatRunbookContent },
   { config: implementingConfig, body: implementingContent },
@@ -347,6 +360,7 @@ const BUILT_IN_SKILL_SOURCES = [
   { config: phaseRunningConfig, body: phaseRunningContent },
   { config: planningConfig, body: planningContent },
   { config: qaConfig, body: qaContent },
+  { config: qaLoomConfig, body: qaLoomContent },
   { config: questioningConfig, body: questioningContent },
   { config: researchingConfig, body: researchingContent },
   { config: reviewOfferedTaskConfig, body: reviewOfferedTaskContent },
@@ -524,6 +538,94 @@ async function syncSeededSkillFiles(skillId: string, files: SeedSkillFile[]): Pr
   if (files.length > 0) await upsertSkillFiles(skillId, files);
 }
 
+/**
+ * Skills this catalog used to seed and no longer ships. Dropping a template
+ * alone leaves its last seeded row live on every existing install, so agents
+ * keep reading instructions for a removed feature. `artifacts` documented the
+ * PM2 + localtunnel serving path, removed together with PM2.
+ */
+export const RETIRED_SEED_SKILLS: readonly string[] = ["artifacts"];
+
+/**
+ * True when every user-editable column outside the seed hash still holds what
+ * `skillsSeeder.apply` writes. The seed hash covers only content,
+ * systemDefault, userInvocable and bundled files, so an edit to any other
+ * column (description, model, allowedTools, source fields, ...) is invisible
+ * to it. The seeder writes the description from the same config as the
+ * content's frontmatter, so a pristine row's description equals the
+ * frontmatter one; every other column keeps its insert default.
+ */
+function metadataAsSeeded(skill: Skill, fileCount: number): boolean {
+  let seededDescription: string;
+  try {
+    seededDescription = parseSkillContent(skill.content).description;
+  } catch {
+    return false;
+  }
+
+  return (
+    skill.description === seededDescription &&
+    skill.type === "personal" &&
+    skill.isComplex === fileCount > 0 &&
+    skill.isEnabled &&
+    !skill.disableModelInvocation &&
+    skill.allowedTools === null &&
+    skill.model === null &&
+    skill.effort === null &&
+    skill.context === null &&
+    skill.agent === null &&
+    skill.sourceUrl === null &&
+    skill.sourceRepo === null &&
+    skill.sourcePath === null &&
+    skill.sourceBranch === "main" &&
+    skill.sourceHash === null &&
+    skill.lastFetchedAt === null
+  );
+}
+
+/**
+ * Delete each retired skill the seeder still owns: a `seed_state` row exists,
+ * the live copy hashes to what was last seeded, and its metadata is as seeded.
+ * A skill the seeder never recorded, or one a user edited since (content,
+ * files or metadata), is left in place.
+ */
+export async function retireSeedSkills(
+  names: readonly string[] = RETIRED_SEED_SKILLS,
+): Promise<string[]> {
+  const retired: string[] = [];
+
+  for (const name of names) {
+    const existing = await getSkillByName(name, "swarm");
+    if (!existing) continue;
+
+    const state = await getSeedState("skill", name);
+    if (!state) continue;
+
+    const liveFiles = (await getSkillFiles(existing.id)).map((file) => ({
+      path: file.path,
+      content: file.content,
+    }));
+    const liveHash = skillSeedHash(
+      existing.content,
+      existing.systemDefault,
+      liveFiles,
+      existing.userInvocable,
+    );
+    if (liveHash !== state.seededHash || !metadataAsSeeded(existing, liveFiles.length)) {
+      console.warn(`[seed:skill] kept retired skill "${name}": edited since it was seeded`);
+      continue;
+    }
+
+    await getDbClient().transaction(async () => {
+      await deleteSkill(existing.id);
+      await deleteSeedState("skill", name);
+    });
+    retired.push(name);
+  }
+
+  return retired;
+}
+
 type SkillSeedItem = SeedItem & { skill: SeedSkill };
 
 export const skillsSeeder: Seeder<SkillSeedItem> = {
@@ -611,4 +713,6 @@ export const skillsSeeder: Seeder<SkillSeedItem> = {
       await syncSeededSkillFiles(created.id, skill.files);
     });
   },
+
+  retire: () => retireSeedSkills(),
 };

package/src/be/sql-connections.ts

@@ -0,0 +1,118 @@
+import { getResolvedConfig } from "@/be/db";
+import { registerVolatileSecret, scrubSecrets } from "@/utils/secret-scrubber";
+import type { ScriptConnectionRecord } from "./script-connections";
+
+export const SQL_MAX_ROWS = 1000;
+/** Serialized JSON budget for one response; rows past it are dropped and `truncated` is set. */
+export const SQL_MAX_BYTES = 5 * 1024 * 1024;
+const SQL_FETCH_BATCH = 100;
+
+export type SqlQueryResult = {
+  rows: Record<string, unknown>[];
+  rowCount: number;
+  truncated: boolean;
+};
+type SqlRow = Record<string, unknown>;
+/** Feeds fetched batches to `take` until it returns false or the cursor is drained. */
+type SqlExecutor = (
+  dsn: string,
+  query: string,
+  params: unknown[],
+  take: (batch: SqlRow[]) => boolean,
+) => Promise<void>;
+
+/** Only Postgres: Bun `SQL` would open a `sqlite://` URL as a file on the API host. Never echo the DSN. */
+export function assertPostgresDsn(dsn: string): void {
+  if (!URL.canParse(dsn) || !["postgres:", "postgresql:"].includes(new URL(dsn).protocol)) {
+    throw new Error("SQL connection DSN must be a postgres:// or postgresql:// URL.");
+  }
+}
+
+/** Resolve the encrypted DSN server-side. No process.env fallback: a lead must not point it at API env vars. */
+export async function resolveSqlDsn(
+  connection: ScriptConnectionRecord,
+  agentId: string,
+): Promise<string> {
+  const key = connection.authConfigKey;
+  if (!key) throw new Error("SQL connection has no DSN config key.");
+  const repoId = connection.scope === "repo" ? (connection.scopeId ?? undefined) : undefined;
+  const dsn = (await getResolvedConfig(agentId, repoId)).find((c) => c.key === key)?.value;
+  if (!dsn) throw new Error(`SQL connection DSN '${key}' is not set.`);
+  registerVolatileSecret(dsn, key);
+  if (URL.canParse(dsn)) registerVolatileSecret(decodeURIComponent(new URL(dsn).password), key);
+  assertPostgresDsn(dsn);
+  return dsn;
+}
+
+// Read-only enforcement point. Every layer is enforced by Postgres, never by inspecting the SQL:
+// 1. default_transaction_read_only=on for the whole session, 2. an explicit READ ONLY transaction,
+// 3. one statement per call over the extended protocol, 4. a fresh connection closed after each call.
+// Bun runs a parameterless `unsafe()` over the simple protocol, which accepts `commit; ...; insert`,
+// so the parameterless case goes through the tagged-template path instead. Never use `.simple()`.
+// The statement runs as a server-side cursor fetched in batches, so the API never holds more than
+// one batch past the caps. DECLARE only accepts SELECT, VALUES, TABLE and WITH ... SELECT.
+const asTemplate = (text: string): TemplateStringsArray => Object.assign([text], { raw: [text] });
+
+const defaultExecutor: SqlExecutor = async (dsn, query, params, take) => {
+  // Bun.SQL global, not `import { SQL } from "bun"`: the node-target CLI bundle cannot import "bun".
+  const sql = new Bun.SQL({
+    adapter: "postgres",
+    url: dsn,
+    max: 1,
+    connectionTimeout: 10,
+    connection: { default_transaction_read_only: "on", statement_timeout: 30_000 },
+  });
+  try {
+    await sql.begin("read only", async (tx) => {
+      const declare = `declare swarm_sql_cursor no scroll cursor for ${query}`;
+      await (params.length > 0 ? tx.unsafe(declare, params) : tx(asTemplate(declare)));
+      const fetchNext = asTemplate(`fetch ${SQL_FETCH_BATCH} from swarm_sql_cursor`);
+      for (;;) {
+        const batch = [...((await tx(fetchNext)) as SqlRow[])];
+        if (!take(batch) || batch.length < SQL_FETCH_BATCH) return;
+      }
+    });
+  } finally {
+    await sql.close();
+  }
+};
+
+let sqlExecutorForTesting: SqlExecutor | null = null;
+
+export function setSqlExecutorForTesting(executor: SqlExecutor | null): void {
+  sqlExecutorForTesting = executor;
+}
+
+export async function runReadOnlyQuery(
+  dsn: string,
+  query: string,
+  params: unknown[] = [],
+): Promise<SqlQueryResult> {
+  const rows: SqlRow[] = [];
+  let bytes = 0;
+  let truncated = false;
+  const take = (batch: SqlRow[]): boolean => {
+    for (const row of batch) {
+      const size = Buffer.byteLength(
+        JSON.stringify(row, (_, v) => (typeof v === "bigint" ? v.toString() : v)),
+      );
+      if (rows.length >= SQL_MAX_ROWS || bytes + size > SQL_MAX_BYTES) {
+        truncated = true;
+        return false;
+      }
+      bytes += size;
+      rows.push(row);
+    }
+    return true;
+  };
+  try {
+    await (sqlExecutorForTesting ?? defaultExecutor)(dsn, query, params, take);
+    return { rows, rowCount: rows.length, truncated };
+  } catch (err) {
+    const code = (err as { errno?: unknown }).errno;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      scrubSecrets(typeof code === "string" ? `${message} (SQLSTATE ${code})` : message),
+    );
+  }
+}

package/src/be/swarm-config-guard.ts

@@ -1,7 +1,9 @@
+import { validateChatSdkAdaptersValue } from "../integrations/chat-sdk/schema";
 import { validateQuickJSPoolSize } from "../scripts-runtime/executors/quickjs-pool-config";
 import { normalizeSlackReactionShortcode } from "../slack/reaction-shortcode";
 import { ProviderNameSchema } from "../types";
 import { API_DRAIN_MAX_MS_LIMIT } from "../utils/api-drain";
+import { envExportRestrictedError, isEnvExportRestrictedKey } from "../utils/config-env-export";
 import { parseEnabledTools } from "../utils/enabled-tools";
 import { normalizeOrgWebsite } from "../utils/org-website";
 import { parseTaskToolManifest } from "../utils/task-tool-manifest";
@@ -24,13 +26,47 @@ import { isTierConfigKey, validateTierConfigValue } from "./model-tier-keys";
  * rejected at every write path (DB helpers, HTTP routes, MCP tools).
  */
 // Lead activation is also deployment-only: leads can write ordinary global config.
+// CHAT_SDK_API_URL_OVERRIDES points Chat SDK adapters (and the secrets they carry)
+// at another host, so it must never come from a config row.
+/**
+ * Teams SDK env fallbacks; a config row must not redirect the bot token.
+ * `@microsoft/teams.apps` reads these from `process.env`. Operators may still
+ * store them (they are not reserved), they just never reach env through
+ * `getInjectableGlobalConfigs`.
+ */
+export const TEAMS_SDK_ENV_KEYS = [
+  "SERVICE_URL",
+  "TENANT_ID",
+  "CLIENT_ID",
+  "CLIENT_SECRET",
+  "MANAGED_IDENTITY_CLIENT_ID",
+  "CLOUD",
+] as const;
+
+/** SQL literal list for the `NOT IN (...)` injection denylist in db.ts. */
+export function teamsSdkEnvKeysSql(): string {
+  return TEAMS_SDK_ENV_KEYS.map((key) => `'${key}'`).join(", ");
+}
+
 const RESERVED_KEYS = new Set([
   "API_KEY",
   "SECRETS_ENCRYPTION_KEY",
   "CORS_ALLOW_ANY_ORIGIN",
   "EXTENSION_ALLOW_LEAD_ACTIVATION",
+  "CHAT_SDK_API_URL_OVERRIDES",
 ]);
 
+// Config keys the API server owns for its own use and must NEVER hand out over
+// HTTP or to a script — workers/entrypoints read config to build their env, and
+// the agent-fs bootstrap admin key would let a compromised worker administer the
+// shared org. The API materializes these into its own process.env at boot via
+// getInjectableGlobalConfigs, so no HTTP consumer legitimately needs them.
+const API_ONLY_CONFIG_KEYS = new Set(["API_AGENT_FS_API_KEY", "SLACK_SIGNING_SECRET"]);
+
+export function isApiOnlyConfigKey(key: string): boolean {
+  return API_ONLY_CONFIG_KEYS.has(key);
+}
+
 /** Config rows owned by dedicated API surfaces, not the generic config API. */
 export const INTERNAL_CONFIG_KEYS = new Set(["onboarding_state", "runtime_owner_id"]);
 
@@ -254,6 +290,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     ["RUNTIME_WAKE_GRACE_SEC", "RUNTIME_WAKE_REROUTE_SEC", "RUNTIME_ROUTING_INTERVAL_MS"],
     0,
   ),
+  CHAT_SDK_ADAPTERS: validateChatSdkAdaptersValue,
   TASK_TOOL_MANIFESTS: (value) => {
     try {
       if (typeof value !== "string") throw new Error("Expected JSON string");
@@ -380,8 +417,10 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "OPENROUTER_APP_ATTRIBUTION",
     "CURSOR_NATIVE_SYSTEM_PROMPT",
     "SLACK_DISABLE",
+    "CHAT_SDK_ENABLED",
     "SLACK_RENDER_V2",
     "SLACK_RENDER_V2_DELEGATION",
+    "SLACK_BLOCK_EXTERNAL_CHANNELS",
     "GITHUB_DISABLE",
     "GITLAB_DISABLE",
     "AZURE_DEVOPS_DISABLE",
@@ -473,6 +512,10 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   ...integerValidators(["APPROVAL_REQUEST_AUTO_CANCELLATION_DAYS"], 0),
   // 0 turns the shutdown drain off; the shutdown path clamps to the same limit.
   ...boundedIntegerValidators(["API_DRAIN_MAX_MS"], 0, API_DRAIN_MAX_MS_LIMIT),
+  // Chat SDK thread buffer window. 0 or an invalid value falls back to the 10 s
+  // default in thread-buffer.ts; above 10 minutes a
+  // reply waits longer than any operator expects.
+  ...boundedIntegerValidators(["CHAT_SDK_BUFFER_MS"], 1, 600_000),
   // Below ~100 tokens the preamble can't fit a useful summary; above 20000
   // (~80k chars) it risks the SIGTERM-143 context-saturation failure mode
   // the cap exists to prevent (see context-preamble.ts).
@@ -494,3 +537,13 @@ export function validateConfigValue(key: string, value: unknown): string | null
   const validator = VALIDATED_KEYS[key.toUpperCase()];
   return validator ? validator(value) : null;
 }
+
+/**
+ * Rejects `exportToEnv: true` for keys only the API server reads. Omitting the
+ * flag is fine: the write path stores false for those keys.
+ */
+export function validateExportToEnv(key: string, exportToEnv: boolean | undefined): string | null {
+  return exportToEnv === true && isEnvExportRestrictedKey(key)
+    ? envExportRestrictedError(key)
+    : null;
+}

package/src/cli.tsx

@@ -303,12 +303,6 @@ const COMMAND_HELP: Record<
     options: "  Internal command; no user-facing options",
     examples: `  ${binName} session-summary-stdin`,
   },
-  artifact: {
-    usage: `${binName} artifact <subcommand> [options]`,
-    description: "Manage agent artifacts (serve, list, etc.).",
-    options: "  -h, --help             Show this help",
-    examples: [`  ${binName} artifact serve`, `  ${binName} artifact help`].join("\n"),
-  },
   x: {
     usage: `${binName} x <target> [args]`,
     description:
@@ -445,7 +439,6 @@ function printHelp(command?: string) {
     ["hook", "Handle Claude Code hook events (stdin)"],
     ["codex-hook", "Handle Codex CLI hook events (stdin, steering delivery)"],
     ["session-summary-stdin", "Generate a Claude session summary (internal, stdin)"],
-    ["artifact", "Manage agent artifacts"],
     ["x", "Execute external command routes"],
     ["scripts", "Reusable scripts maintenance"],
     ["rbac", "RBAC role management (bootstrap)"],
@@ -774,15 +767,6 @@ if (args.showHelp || args.command === "help" || args.command === undefined) {
   const { runSessionSummaryFromStdin } = await import("./hooks/hook.ts");
   await runSessionSummaryFromStdin();
   process.exit(process.exitCode ?? 0);
-} else if (args.command === "artifact") {
-  // Pass all args after "artifact" directly
-  const artifactArgs = process.argv.slice(process.argv.indexOf("artifact") + 1);
-  const { runArtifact } = await import("./commands/artifact");
-  await runArtifact(artifactArgs[0] || "help", {
-    additionalArgs: artifactArgs.slice(1),
-    port: args.port,
-    key: args.key,
-  });
 } else if (args.command === "x") {
   const xArgs = process.argv.slice(process.argv.indexOf("x") + 1);
   const { runXCommand } = await import("./commands/x");

package/src/commands/onboard/non-interactive.ts

@@ -1,3 +1,4 @@
+import { openAICompatibleProviders, providerKeyVars } from "@desplega/model-catalog";
 import {
   type HarnessProvider,
   type InstallProvider,
@@ -42,8 +43,9 @@ type ProviderStateKey =
   | "awsSessionToken"
   | "awsProfile";
 
-const ACCEPTED_CREDENTIALS =
-  "Set one of: CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY (Claude Code); OPENAI_API_KEY (OpenAI); OPENROUTER_API_KEY (OpenRouter); or AWS_REGION plus AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or AWS_PROFILE and a Bedrock MODEL_OVERRIDE.";
+const ACCEPTED_CREDENTIALS = `Set one of: CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY (Claude Code); OPENAI_API_KEY (OpenAI); OPENROUTER_API_KEY (OpenRouter); or AWS_REGION plus AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or AWS_PROFILE and a Bedrock MODEL_OVERRIDE. ${openAICompatibleProviders()
+  .map((p) => `${p.displayName} (${providerKeyVars(p).join(" or ")})`)
+  .join(" and ")} keys for pi/opencode are added from the dashboard.`;
 
 const DEFERRED_CREDENTIAL_LABEL = "no credential yet";
 

package/src/commands/profile-sync.ts

@@ -146,9 +146,9 @@ const PROFILE_FIELD_DETAILS: Record<
   },
   claudeMd: {
     label:
-      "claudeMd (/workspace/CLAUDE.md for non-Claude harnesses; ~/.claude/CLAUDE.md for Claude)",
+      "claudeMd (~/.claude/CLAUDE.md for Claude; /workspace/CLAUDE.md for non-Claude harnesses, which Claude excludes from its memory load)",
     recoveryGuidance:
-      "Inspect and shrink the live CLAUDE.md source first, moving durable tail content into memory. After a worker restart, non-Claude harnesses can use /workspace/CLAUDE.md.pre-boot-<timestamp>.bak as the fallback copy; Claude's native ~/.claude/CLAUDE.md source is not archived by that boot step.",
+      "Inspect and shrink the live CLAUDE.md source first, moving durable tail content into memory. Claude edits ~/.claude/CLAUDE.md; editing /workspace/CLAUDE.md does not reach a Claude session. After a worker restart, non-Claude harnesses can use /workspace/CLAUDE.md.pre-boot-<timestamp>.bak as the fallback copy; Claude's native ~/.claude/CLAUDE.md source is not archived by that boot step.",
   },
   toolsMd: {
     label: `toolsMd (${TOOLS_MD_PATH})`,
@@ -510,7 +510,9 @@ export function planClaudeMdSync(state: {
  * materializes from the `claudeMd` DB field at boot (`runner.ts`) and that the
  * base-prompt truncation notice tells NON-Claude harnesses (codex/pi/opencode)
  * to edit. Distinct from CLAUDE_MD_PATH; this is the FS→DB source for the
- * non-Claude providers that previously had no sync path at all.
+ * non-Claude providers that previously had no sync path at all. Written for
+ * every harness (a container can live-swap providers), but Claude sessions
+ * skip it via `claudeMdExcludes` (`src/providers/claude-flag-settings.ts`).
  */
 export const WORKSPACE_CLAUDE_MD_PATH = "/workspace/CLAUDE.md";
 

package/src/commands/provider-credentials.ts

@@ -18,6 +18,13 @@
  * runs the predicate itself — it just reads the agent row.
  */
 
+import {
+  type OpenAICompatibleProvider,
+  openAICompatibleKeyVars,
+  openAICompatibleProviders,
+  providerBaseUrl,
+  providerKeyFromEnv,
+} from "@desplega/model-catalog";
 import { deriveDefaultRoute, validateRoute } from "@desplega/model-routing";
 import { ACP_TARGET_IDS, isAcpTarget } from "../providers/acp-target-catalog";
 import { checkAmpCredentials, liveTestAmpCredentials } from "../providers/amp-adapter";
@@ -116,8 +123,13 @@ export const REQUIRED_CRED_VARS_BY_PROVIDER: Record<SupportedProvider, readonly
   ],
   codex: ["OPENAI_API_KEY", "CODEX_OAUTH"],
   devin: ["DEVIN_API_KEY", "DEVIN_ORG_ID"],
-  opencode: ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
-  pi: ["ANTHROPIC_API_KEY", "OPENROUTER_API_KEY", "OPENAI_API_KEY"],
+  opencode: [
+    "OPENROUTER_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    ...openAICompatibleKeyVars(),
+  ],
+  pi: ["ANTHROPIC_API_KEY", "OPENROUTER_API_KEY", "OPENAI_API_KEY", ...openAICompatibleKeyVars()],
   // The ACP target owns its auth; custom targets still need a command.
   acp: [],
   dsh: ["DEEPSEEK_API_KEY", "OPENROUTER_API_KEY"],
@@ -323,6 +335,29 @@ async function checkOpenRouter(apiKey: string): Promise<LiveValidationResult> {
   };
 }
 
+/**
+ * `GET <baseUrl>/models` with a Bearer key against an OpenAI-compatible
+ * registry provider (NaN, Helmcode). Lists models, runs no inference.
+ * `baseUrl` defaults to the registry entry; the probe passes the
+ * `<ID>_BASE_URL` override, and tests inject a fake server.
+ */
+export async function checkOpenAICompatibleProvider(
+  provider: OpenAICompatibleProvider,
+  apiKey: string,
+  baseUrl: string = provider.baseUrl,
+): Promise<LiveValidationResult> {
+  const r = await timedFetch(`${baseUrl.replace(/\/+$/, "")}/models`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (r.ok) return { ok: true, latency_ms: r.latency_ms };
+  return {
+    ok: false,
+    error: scrubSecrets(`HTTP ${r.status}: ${r.bodyText.slice(0, 200)}`),
+    latency_ms: r.latency_ms,
+  };
+}
+
 /**
  * Mirror of the disk check in `checkCodexCredentials` — true when the worker
  * has a materialised `~/.codex/auth.json`, which is the canonical "logged in"
@@ -365,7 +400,7 @@ function parseCodexOAuthAccess(blob: string | undefined): string | null {
  * | `claude`         | default route: Foundry / Bedrock / Vertex → gateway (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`) → `CLAUDE_CODE_OAUTH_TOKEN` → `ANTHROPIC_API_KEY` | the route's own `/v1/models`; OAuth presence-only; cloud routes skipped |
  * | `claude-managed` | `ANTHROPIC_API_KEY` (managed agents always use API key + managed envs)  | Anthropic `/v1/models`         |
  * | `codex`          | `~/.codex/auth.json` (file) → `CODEX_OAUTH` (env OAuth) → `OPENAI_API_KEY` | OpenAI `/v1/models` (api-key path only) |
- * | `opencode`       | auth.json (file) → `OPENROUTER_API_KEY` → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` | file presence-only, otherwise provider's `/v1/models` |
+ * | `opencode`       | auth.json (file) → `OPENROUTER_API_KEY` → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → each registry provider key (`NAN_API_KEY` or `HELMCODE_API_NAN`, `HELMCODE_API_KEY`) | file presence-only, otherwise provider's `/v1/models` |
  * | `pi`             | auth.json (file) → provider API keys, including model-specific keys   | file/model-specific key presence-only, otherwise provider's `/v1/models` |
  * | `acp`            | target-specific (the ACP target process owns its own auth)              | presence-only (validated by the target process) |
  * | `pi` (bedrock)   | `MODEL_OVERRIDE=amazon-bedrock/*` → AWS SDK default credential chain    | presence-only (real check is the worker-side Bedrock enumeration) |
@@ -459,17 +494,28 @@ export async function validateProviderCredentials(
         // decision, including any injected filesystem probe used by reports.
         if (status.ready && status.satisfiedBy === "file") return presenceCheckOk();
         // Preserve the live-probe order for supported env keys:
-        // OPENROUTER → ANTHROPIC → OPENAI.
+        // OPENROUTER → ANTHROPIC → OPENAI, then the OpenAI-compatible
+        // registry providers in declaration order (NaN, canonical key or
+        // alias → Helmcode) at their `<ID>_BASE_URL`, so existing env
+        // combinations keep their probe.
         if (env.OPENROUTER_API_KEY) return checkOpenRouter(env.OPENROUTER_API_KEY);
         if (env.ANTHROPIC_API_KEY) return checkAnthropicApiKey(env.ANTHROPIC_API_KEY);
         if (env.OPENAI_API_KEY) return checkOpenAiApiKey(env.OPENAI_API_KEY);
+        for (const direct of openAICompatibleProviders()) {
+          const key = providerKeyFromEnv(direct, env);
+          if (key) {
+            return checkOpenAICompatibleProvider(direct, key, providerBaseUrl(direct, env));
+          }
+        }
         // Model-specific keys (e.g. GEMINI_API_KEY) can satisfy readiness
         // without a probeable endpoint. The harness validates them at inference.
         if (status.ready) return presenceCheckOk();
         return {
           ok: false,
-          error:
-            "No usable credential found (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY).",
+          error: `No usable credential found (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, ${openAICompatibleProviders()
+            .map((p) => p.envVar)
+            .join(", ")
+            .replace(/, (?=[^,]*$)/, ", or ")}).`,
           latency_ms: Date.now() - startedAt,
         };
       }