@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/integrations/chat-sdk/test-hooks.ts

@@ -0,0 +1,37 @@
+/**
+ * Test-only seams for the Chat SDK adapters. Production code never calls
+ * `setChatSdkTestHooks`, so every hook is unset in a running API. The
+ * operator schema rejects `webhookVerifier`, and this module is the only
+ * other way to set one.
+ */
+export interface ChatSdkTestHooks {
+  /**
+   * Replaces the Bot Framework JWT check of the Teams adapter. Tests cannot
+   * mint a Microsoft-signed token, so they inject `() => true`.
+   */
+  teamsWebhookVerifier?: (request: Request, body: string) => boolean | Promise<boolean>;
+  /**
+   * Bot token factory for the Teams adapter, so an outbound send needs no
+   * MSAL call to login.microsoftonline.com.
+   */
+  teamsToken?: () => string;
+  /**
+   * Skips the Discord Gateway loop. The loop logs in through `discord.js`
+   * against the real Discord API, which `apiUrl` does not redirect.
+   */
+  disableDiscordGateway?: boolean;
+  /** Typing keepalive interval, shortened so a test sees several renewals. */
+  typingIntervalMs?: number;
+  /** Typing keepalive hard cap, shortened so a test can reach it. */
+  typingMaxMs?: number;
+}
+
+let hooks: ChatSdkTestHooks = {};
+
+export function setChatSdkTestHooks(next: ChatSdkTestHooks): void {
+  hooks = { ...next };
+}
+
+export function getChatSdkTestHooks(): Readonly<ChatSdkTestHooks> {
+  return hooks;
+}

package/src/integrations/chat-sdk/thread-buffer.ts

@@ -0,0 +1,100 @@
+import type { Attachment } from "chat";
+import { type AdditiveBuffer, createAdditiveBuffer } from "@/tasks/additive-buffer";
+import { trackBackground } from "./background";
+import { flushChatThread } from "./inbound";
+import { stopTypingKeepalive } from "./typing";
+
+/** One inbound message waiting in its thread's buffer. */
+export interface ChatBufferedMessage {
+  messageId: string;
+  channelId: string;
+  /** Mention-stripped text. */
+  text: string;
+  userId: string;
+  userName?: string;
+  botMentioned: boolean;
+  isDirectMessage: boolean;
+  attachments: Attachment[];
+}
+
+const DEFAULT_BUFFER_MS = 10_000;
+
+function configuredBufferMs(): number {
+  const value = Number(process.env.CHAT_SDK_BUFFER_MS);
+  return Number.isFinite(value) && value > 0 ? value : DEFAULT_BUFFER_MS;
+}
+
+let buffer: AdditiveBuffer<ChatBufferedMessage> | undefined;
+let bufferMs = 0;
+/** Set while shutdown flushes every waiting thread; those flushes keep `dependsOn`. */
+let draining = false;
+/**
+ * Tail of each thread's flush chain. The additive buffer clears a key before
+ * it awaits `onFlush`, so a second flush of one thread can start while the
+ * first still routes, downloads files or creates its task. Chaining keeps the
+ * task order (and `dependsOn`) of one thread; different threads run in parallel.
+ */
+const flushChains = new Map<string, Promise<void>>();
+
+/** Run `work` after every earlier flush of `threadId`. A failed flush does not block the next one. */
+function runInThreadOrder(threadId: string, work: () => Promise<void>): Promise<void> {
+  const previous = flushChains.get(threadId) ?? Promise.resolve();
+  const run = previous.then(work);
+  const tail = run.catch(() => {});
+  flushChains.set(threadId, tail);
+  void tail.then(() => {
+    if (flushChains.get(threadId) === tail) flushChains.delete(threadId);
+  });
+  return run;
+}
+
+/**
+ * Keyed by the raw SDK `thread.id` (`<adapter>:<platform id>`, colons
+ * included); the key is never split. A changed `CHAT_SDK_BUFFER_MS` applies
+ * once no thread is waiting on the old timer.
+ */
+function getBuffer(): AdditiveBuffer<ChatBufferedMessage> {
+  const ms = configuredBufferMs();
+  if (!buffer || (ms !== bufferMs && buffer.keys().length === 0)) {
+    bufferMs = ms;
+    buffer = createAdditiveBuffer<ChatBufferedMessage>({
+      timeoutMs: ms,
+      label: "chat",
+      onFlush: async (items, threadId, reason) => {
+        // Read now: `draining` can change while this flush waits in the chain.
+        const immediate = reason === "manual" && !draining;
+        // Tracked so shutdown drains timer-driven flushes before the DB closes.
+        const work = runInThreadOrder(threadId, () => flushChatThread(threadId, items, immediate));
+        trackBackground(work);
+        // A failed flush created no task, so no relay will stop the indicator.
+        await work.catch(() => stopTypingKeepalive(threadId));
+      },
+    });
+  }
+  return buffer;
+}
+
+/** Add a message to its thread's buffer and reset the debounce timer. */
+export function bufferChatMessage(threadId: string, item: ChatBufferedMessage): void {
+  getBuffer().enqueue(threadId, item);
+}
+
+/** Flush now with no `dependsOn` (the `!now` command). */
+export async function instantFlushChat(threadId: string): Promise<void> {
+  await getBuffer().instantFlush(threadId);
+}
+
+export function isChatThreadBuffered(threadId: string): boolean {
+  return buffer?.isBuffered(threadId) ?? false;
+}
+
+/** Shutdown: turn every waiting thread into its task instead of dropping it. */
+export async function flushAllChatBuffers(): Promise<void> {
+  if (!buffer) return;
+  draining = true;
+  try {
+    for (const threadId of buffer.keys()) await buffer.instantFlush(threadId);
+  } finally {
+    draining = false;
+  }
+}

package/src/integrations/chat-sdk/typing.ts

@@ -0,0 +1,65 @@
+import { errorMessage } from "./logger";
+import { getChatInstance, isChatSdkStopping } from "./runtime";
+import { assertTrustedChatTarget } from "./teams-origin";
+import { getChatSdkTestHooks } from "./test-hooks";
+
+/** Telegram shows one typing action for about 5 s, so renew it before that. */
+const TYPING_INTERVAL_MS = 4_000;
+/** Hard cap: a task that never relays must not show typing forever. */
+const TYPING_MAX_MS = 15 * 60 * 1000;
+
+const keepalives = new Map<string, ReturnType<typeof setInterval>>();
+
+/**
+ * Show the typing indicator in `threadId` until `stopTypingKeepalive`, the
+ * hard cap, or the adapter stops. Idempotent per thread id. Adapters without
+ * `startTyping` and untrusted Teams service URLs are skipped.
+ */
+export function startTypingKeepalive(adapter: string, threadId: string): void {
+  if (keepalives.has(threadId)) return;
+  // A shutdown flush creates tasks too; no indicator for a reply that comes after a restart.
+  if (isChatSdkStopping()) return;
+  // Typing sends the Teams bot token to the service URL in the thread id.
+  try {
+    assertTrustedChatTarget(threadId);
+  } catch {
+    return;
+  }
+  if (typeof getChatInstance(adapter)?.getAdapter(adapter)?.startTyping !== "function") return;
+
+  const hooks = getChatSdkTestHooks();
+  const maxMs = hooks.typingMaxMs ?? TYPING_MAX_MS;
+  const startedAt = Date.now();
+  let warned = false;
+  const sendTyping = async (): Promise<void> => {
+    const target = getChatInstance(adapter)?.getAdapter(adapter);
+    if (Date.now() - startedAt >= maxMs || typeof target?.startTyping !== "function") {
+      stopTypingKeepalive(threadId);
+      return;
+    }
+    try {
+      await target.startTyping(threadId);
+    } catch (error) {
+      if (warned) return;
+      warned = true;
+      console.warn(`[chat-sdk] Typing indicator failed for ${threadId}: ${errorMessage(error)}`);
+    }
+  };
+  const timer = setInterval(() => void sendTyping(), hooks.typingIntervalMs ?? TYPING_INTERVAL_MS);
+  timer.unref();
+  keepalives.set(threadId, timer);
+  void sendTyping();
+}
+
+export function stopTypingKeepalive(threadId: string): void {
+  const timer = keepalives.get(threadId);
+  if (!timer) return;
+  clearInterval(timer);
+  keepalives.delete(threadId);
+}
+
+/** Stop every keepalive. For `stopChatSdk`. */
+export function stopAllTypingKeepalives(): void {
+  for (const timer of keepalives.values()) clearInterval(timer);
+  keepalives.clear();
+}

package/src/jira/adf.ts

@@ -13,6 +13,8 @@
  * debug line is emitted so unhandled cases surface during dev.
  */
 
+import { getNodeEnv } from "../utils/node-env";
+
 type AdfNode = {
   type?: string;
   text?: string;
@@ -93,7 +95,7 @@ export function extractText(adf: unknown): string {
       }
       default: {
         // Unknown node — descend into content if present.
-        if (process.env.NODE_ENV !== "production" && type) {
+        if (getNodeEnv() !== "production" && type) {
           console.log(`[jira.adf] unknown node type: ${type}`);
         }
         for (const child of asNodeArray(node.content)) visit(child);

package/src/kv-reserved-namespaces.ts

@@ -9,6 +9,8 @@ const RESERVED_FAMILIES = new Map([
   // step-9: Comb's "Send to swarm" claims (`comb:sent`).
   ["comb", "namespace is reserved for Comb; use POST /api/comb/review-batches"],
   ["worker", "namespace is reserved for worker nudges"],
+  // Durable dedupe for SLACK_BLOCK_EXTERNAL_CHANNELS alerts (src/slack/external-channel.ts).
+  ["slack-external-alert", "namespace is reserved for Slack external channel alerts"],
 ]);
 
 export function isReservedNamespace(namespace: string): boolean {

package/src/oauth/mcp-wrapper.ts

@@ -1,5 +1,6 @@
 import * as oauth from "oauth4webapi";
 import { isEnvFlagEnabled } from "../utils/env-flag";
+import { isDevOrTestNodeEnv } from "../utils/node-env";
 import { registerVolatileSecret, scrubSecrets } from "../utils/secret-scrubber";
 
 /**
@@ -113,19 +114,22 @@ export function publicEndpointSsrfOptions(): SsrfGuardOptions {
   // or the explicit override flag — may fetch private/insecure endpoints.
   // Local dev entrypoints (`bun run dev:http` / `start:http`) set
   // NODE_ENV=development.
-  const env = process.env.NODE_ENV;
-  const dev =
-    env === "development" || env === "test" || process.env.ALLOW_PRIVATE_NETWORK_URLS === "true";
+  const dev = isDevOrTestNodeEnv() || process.env.ALLOW_PRIVATE_NETWORK_URLS === "true";
   return {
     allowPrivateHosts: dev,
     allowInsecure: dev,
   };
 }
 
-function defaultSsrfOptions(): SsrfGuardOptions {
+/**
+ * Guard for MCP OAuth endpoints (discovery, DCR, token exchange, refresh,
+ * revocation). http:// is allowed only in an explicit development/test
+ * environment; private hosts stay behind MCP_OAUTH_ALLOW_PRIVATE_HOSTS.
+ */
+export function mcpOAuthSsrfOptions(): SsrfGuardOptions {
   return {
     allowPrivateHosts: isEnvFlagEnabled("MCP_OAUTH_ALLOW_PRIVATE_HOSTS", false),
-    allowInsecure: process.env.NODE_ENV !== "production",
+    allowInsecure: isDevOrTestNodeEnv(),
   };
 }
 
@@ -144,7 +148,7 @@ async function safeFetch(
   init?: RequestInit,
   timeoutMs: number = DEFAULT_FETCH_TIMEOUT_MS,
 ): Promise<Response> {
-  assertUrlSafe(url, defaultSsrfOptions());
+  assertUrlSafe(url, mcpOAuthSsrfOptions());
   return fetch(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(timeoutMs) });
 }
 

package/src/otel-impl.ts

@@ -30,6 +30,7 @@ import { NodeSDK } from "@opentelemetry/sdk-node";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 import pkg from "../package.json";
 import type { DbRetentionSweepMetric, SpanOptions, SwarmSpan, SwarmSpanKind } from "./otel";
+import { getNodeEnv } from "./utils/node-env";
 import { scrubSecrets } from "./utils/secret-scrubber";
 
 type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
@@ -174,7 +175,7 @@ export async function boot(serviceRole: string, options: BootOptions = {}): Prom
 
   const configuredResourceAttributes = parseResourceAttributes();
   const deploymentEnvironment =
-    configuredResourceAttributes["deployment.environment"] || process.env.NODE_ENV || "development";
+    configuredResourceAttributes["deployment.environment"] || getNodeEnv() || "development";
   const serviceName = resolveServiceName(serviceRole);
   sdk = new NodeSDK({
     resource: resourceFromAttributes({

package/src/pages/version.ts

@@ -1,4 +1,5 @@
-import { createPageVersion, getPage, getPageVersions } from "../be/db";
+import { createPageVersion, getPage } from "../be/db";
+import { getPageEditCounter } from "../be/db/page-versions";
 import type { PageSnapshot, PageVersion } from "../types";
 
 /**
@@ -8,7 +9,7 @@ import type { PageSnapshot, PageVersion } from "../types";
  * Mirrors `snapshotWorkflow` (src/workflows/version.ts:13-44).
  *
  * 1. Load current page state
- * 2. Get max version number for this page (page_versions ORDER BY version DESC)
+ * 2. Get max version number for this page (MAX(page_versions.version))
  * 3. Insert page_versions row with version+1 and the pre-update snapshot
  *
  * Throws on missing parent. Callers in HTTP handlers wrap this in a try/catch
@@ -24,9 +25,7 @@ export async function snapshotPage(
     throw new Error(`Page ${pageId} not found — cannot create snapshot`);
   }
 
-  const existingVersions = await getPageVersions(pageId);
-  const maxVersion = existingVersions.length > 0 ? existingVersions[0]!.version : 0;
-  const nextVersion = maxVersion + 1;
+  const nextVersion = await getPageEditCounter(pageId);
 
   const snapshot: PageSnapshot = {
     title: page.title,

package/src/prompts/base-prompt.ts

@@ -8,11 +8,15 @@
  *   E          outputs (gated on AGENT_FS_API_URL and the pages capability)
  *   H          deployment-gated notes: slack, steering
  *   I          tools and skills (harness tool discovery, skills, MCP server names)
- *   J          agent notes: CLAUDE.md for codex, opencode, pi, only when edited
- *   K          repository (per task)
+ *   J          agent notes: CLAUDE.md, only when edited
  *
- * The runner appends the requester profile, the operator SYSTEM_PROMPT, and a
- * cwd warning after this.
+ * The runner appends the operator SYSTEM_PROMPT after this.
+ *
+ * Nothing here may vary per task, requester, or session: the provider caches
+ * the system prompt as a prefix, and one changed byte re-bills everything
+ * after it. Per-task context (repository, scripts-only Slack, requester
+ * profile, cwd warning) goes into the task prompt instead; see
+ * `getTaskContextPrompt` and the runner's `buildTaskSessionPrompts`.
  */
 
 import type { ProviderTraits } from "../providers/types";
@@ -44,13 +48,28 @@ const BOOTSTRAP_TOTAL_MAX_CHARS = 120_000;
 
 /**
  * Per-section cap applied to the *repo* CLAUDE.md when it is inlined (opencode
- * only). The agent-swarm OSS one is ~18 KB and the biggest volatile component
- * of the system prompt.
+ * only). The agent-swarm OSS one is ~18 KB and the biggest piece of the task
+ * context.
  */
 const REPO_CLAUDE_MD_MAX_CHARS = 12_000;
 
-/** Providers that do not load the agent's CLAUDE.md natively. Claude does. */
-const CLAUDE_MD_INJECT_PROVIDERS: ReadonlySet<string> = new Set(["codex", "opencode", "pi"]);
+/**
+ * Providers that get the agent's CLAUDE.md in the system prompt. Claude also
+ * keeps the editable copy at ~/.claude/CLAUDE.md but excludes it from its
+ * memory load (claude-flag-settings.ts), so it is read once, from the cached
+ * system prompt instead of an uncached message.
+ */
+const CLAUDE_MD_INJECT_PROVIDERS: ReadonlySet<string> = new Set([
+  "claude",
+  "codex",
+  "opencode",
+  "pi",
+]);
+
+/** Where each provider's editable CLAUDE.md lives, for the truncation notice. */
+function claudeMdSourcePath(provider: string): string {
+  return provider === "claude" ? "~/.claude/CLAUDE.md" : "/workspace/CLAUDE.md";
+}
 
 /** Providers that get the repo CLAUDE.md inlined until native loading is verified. */
 const REPO_CLAUDE_MD_INLINE_PROVIDERS: ReadonlySet<string> = new Set(["opencode"]);
@@ -95,36 +114,61 @@ export type BasePromptArgs = {
   soulMd?: string;
   identityMd?: string;
   claudeMd?: string;
-  repoContext?: {
-    claudeMd?: string | null;
-    clonePath: string;
-    warning?: string | null;
-    autoStashes?: { ref: string; message: string }[];
-    guidelines?: {
-      prChecks: string[];
-      mergeChecks: string[];
-      allowMerge?: boolean;
-      review: string[];
-    } | null;
-  };
-  /** Slack context from the current task, if present */
-  slackContext?: { channelId: string; threadTs?: string };
   /** Pre-fetched skill summaries for the tools and skills section */
   skillsSummary?: { name: string; description: string }[];
   /** Names of the MCP servers connected for this agent */
   mcpServers?: string[];
 };
 
-export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
-  const { role, agentId, traits } = args;
+export type RepoContext = {
+  claudeMd?: string | null;
+  clonePath: string;
+  warning?: string | null;
+  autoStashes?: { ref: string; message: string }[];
+  guidelines?: {
+    prChecks: string[];
+    mergeChecks: string[];
+    allowMerge?: boolean;
+    review: string[];
+  } | null;
+};
+
+export type SlackTaskContext = { channelId: string; threadTs?: string };
+
+/** Inputs for the per-task context that rides in the task prompt. */
+export type TaskContextPromptArgs = Pick<
+  BasePromptArgs,
+  "role" | "traits" | "provider" | "scriptsOnly" | "serverCapabilities"
+> & {
+  repoContext?: RepoContext;
+  /** Slack context from the current task, if present */
+  slackContext?: SlackTaskContext;
+};
+
+function promptFlags(args: Pick<BasePromptArgs, "traits" | "provider" | "scriptsOnly">) {
   const {
     hasMcp = true,
     hasToolSearch = false,
     hasLocalEnvironment: hasLocalEnv = true,
     nativeSkillDiscovery = true,
-  } = traits ?? {};
+  } = args.traits ?? {};
+  const scriptsOnly = args.scriptsOnly ?? process.env.SCRIPTS_ONLY_MCP === "true";
+  return {
+    hasMcp,
+    hasToolSearch,
+    hasLocalEnv,
+    nativeSkillDiscovery,
+    provider: args.provider ?? "claude",
+    // Experimental scripts-only MCP surface (code-mode).
+    scriptsOnlyMode: hasMcp && scriptsOnly,
+  };
+}
+
+export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
+  const { role, agentId, traits } = args;
+  const { hasMcp, hasToolSearch, hasLocalEnv, nativeSkillDiscovery, provider, scriptsOnlyMode } =
+    promptFlags(args);
   const steerModes = traits?.steerModes ?? [];
-  const provider = args.provider ?? "claude";
 
   const defaultsInput = {
     name: args.name ?? agentId,
@@ -168,8 +212,6 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
 
   // Experimental scripts-only MCP surface (code-mode): named swarm tools are
   // not registered, so tell the agent everything goes through script-run.
-  const scriptsOnly = args.scriptsOnly ?? process.env.SCRIPTS_ONLY_MCP === "true";
-  const scriptsOnlyMode = hasMcp && scriptsOnly;
   if (scriptsOnlyMode) {
     const scriptsOnlyResult = await resolveTemplateAsync("system.agent.scripts_only_mode", {});
     prompt += `\n${scriptsOnlyResult.text}`;
@@ -199,13 +241,6 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
     const slackResult = await resolveTemplateAsync("system.agent.slack", {});
     prompt += slackResult.text;
   }
-  if (role !== "lead" && args.slackContext && scriptsOnlyMode && slackPromptToolsEnabled) {
-    const slackResult = await resolveTemplateAsync("system.agent.scripts_only_mode.slack", {
-      slackChannelId: args.slackContext.channelId,
-      slackThreadTs: args.slackContext.threadTs ?? "",
-    });
-    prompt += slackResult.text;
-  }
 
   if (
     hasMcp &&
@@ -244,9 +279,9 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
     prompt += toolsResult.text;
   }
 
-  // J. Agent notes (CLAUDE.md). Claude loads ~/.claude/CLAUDE.md and
-  // /workspace/CLAUDE.md natively; the others get it here, and only when it
-  // differs from the generated default.
+  // J. Agent notes (CLAUDE.md), only when it differs from the generated
+  // default. Claude excludes both ~/.claude/CLAUDE.md and /workspace/CLAUDE.md
+  // from its memory load (claude-flag-settings.ts), so this is its only copy.
   if (
     hasLocalEnv &&
     args.claudeMd &&
@@ -257,10 +292,42 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
       BOOTSTRAP_MAX_CHARS,
       Math.max(0, BOOTSTRAP_TOTAL_MAX_CHARS - prompt.length),
     );
-    prompt += truncateSection(args.claudeMd, "## Your notes (CLAUDE.md)", "CLAUDE.md", budget);
+    prompt += truncateSection(
+      args.claudeMd,
+      "## Your notes (CLAUDE.md)",
+      claudeMdSourcePath(provider),
+      budget,
+    );
   }
 
-  // K. Repository (per task). Never truncated except the inlined repo CLAUDE.md.
+  // Blocks start and end with a newline; collapse the seams to one blank line.
+  return prompt.replace(/\n{3,}/g, "\n\n");
+};
+
+/**
+ * Per-task context that used to close the system prompt: the repository block
+ * and the scripts-only Slack note. It rides in the task prompt so the system
+ * prompt stays byte-identical across an agent's sessions. Empty when the task
+ * has neither.
+ */
+export const getTaskContextPrompt = async (args: TaskContextPromptArgs): Promise<string> => {
+  const { hasMcp, hasLocalEnv, provider, scriptsOnlyMode } = promptFlags(args);
+  let prompt = "";
+
+  if (
+    args.role !== "lead" &&
+    args.slackContext &&
+    scriptsOnlyMode &&
+    areSlackPromptToolsEnabled(process.env, args.serverCapabilities)
+  ) {
+    const slackResult = await resolveTemplateAsync("system.agent.scripts_only_mode.slack", {
+      slackChannelId: args.slackContext.channelId,
+      slackThreadTs: args.slackContext.threadTs ?? "",
+    });
+    prompt += slackResult.text;
+  }
+
+  // Repository. Never truncated except the inlined repo CLAUDE.md.
   if (args.repoContext) {
     const repoResult = await resolveTemplateAsync(
       "system.agent.repository",
@@ -269,8 +336,7 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
     prompt += repoResult.text;
   }
 
-  // Blocks start and end with a newline; collapse the seams to one blank line.
-  return prompt.replace(/\n{3,}/g, "\n\n");
+  return prompt.replace(/\n{3,}/g, "\n\n").trim();
 };
 
 /**
@@ -331,7 +397,7 @@ function renderToolsAndSkillsVars(input: {
  * the heading lives in the template, the per-task pieces are built here.
  */
 function renderRepositoryVars(
-  repo: NonNullable<BasePromptArgs["repoContext"]>,
+  repo: RepoContext,
   ctx: { hasMcp: boolean; hasLocalEnv: boolean; provider: string },
 ): Record<string, string> {
   const vars: Record<string, string> = {
@@ -432,7 +498,7 @@ export function truncateRepoClaudeMd(content: string, clonePath: string, budget:
 function truncateSection(
   content: string | undefined,
   header: string,
-  fileName: string,
+  sourcePath: string,
   budget: number,
 ): string {
   if (!content || budget <= 0) return "";
@@ -441,7 +507,7 @@ function truncateSection(
   if (fullSection.length <= budget) return fullSection;
 
   const headerStr = `\n\n${header}\n\n`;
-  const notice = `\n\n[...truncated, see /workspace/${fileName} for full content]\n`;
+  const notice = `\n\n[...truncated, see ${sourcePath} for full content]\n`;
   const contentBudget = budget - headerStr.length - notice.length;
 
   if (contentBudget > 0) {

package/src/providers/acp-target-catalog.ts

@@ -1,3 +1,5 @@
+import { openAICompatibleBaseUrlVars, openAICompatibleKeyVars } from "@desplega/model-catalog";
+
 export const ACP_TARGET_IDS = [
   "opencode",
   "gemini",
@@ -40,6 +42,10 @@ export const ACP_TARGET_CATALOG: readonly AcpTargetCatalogEntry[] = [
       "OPENAI_API_KEY",
       "OPENROUTER_API_KEY",
       "OPENROUTER_BASE_URL",
+      // OpenAI-compatible registry providers: keys (canonical and alias),
+      // then their `<ID>_BASE_URL` overrides.
+      ...openAICompatibleKeyVars(),
+      ...openAICompatibleBaseUrlVars(),
       "GOOGLE_API_KEY",
       "GEMINI_API_KEY",
       "OPENCODE_CONFIG",

package/src/providers/acp-targets.ts

@@ -1,7 +1,12 @@
 import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { normalizeGrokModel } from "@desplega/model-catalog";
+import {
+  baseUrlOverride,
+  normalizeGrokModel,
+  providerBaseUrl,
+  providerForModel,
+} from "@desplega/model-catalog";
 import { clampContextPercent, getContextWindowSize } from "../utils/context-window";
 import {
   ACP_TARGET_IDS,
@@ -9,7 +14,11 @@ import {
   getAcpTargetCatalogEntry,
   isAcpTarget,
 } from "./acp-target-catalog";
-import { applyOpenRouterBaseUrlOverride, type OpencodeConfig } from "./opencode-adapter";
+import {
+  applyOpenRouterBaseUrlOverride,
+  buildOpenAICompatibleProviderBlock,
+  type OpencodeConfig,
+} from "./opencode-adapter";
 import { applyReasoningEffort } from "./reasoning-effort";
 import type { CostData, CostModelUsage, ProviderEvent, ProviderSessionConfig } from "./types";
 
@@ -140,10 +149,54 @@ function withOpencodeConfig(env: Record<string, string>, model: string): void {
     }
   }
   if (model.trim()) value.model = model.trim();
+  withCustomProviderBlock(value as OpencodeConfig, model.trim(), env);
   applyOpenRouterBaseUrlOverride(value as OpencodeConfig, env);
   env[key] = JSON.stringify(value);
 }
 
+/**
+ * OpenCode ships no provider for a registry entry models.dev does not list
+ * (`catalog: "registry"`, e.g. `helmcode`), so its models need the custom
+ * block. The key stays an `{env:…}` reference: the ACP subprocess env is the
+ * forwarded per-task env, where the var holds one picked key, so no literal
+ * key lands in `OPENCODE_CONFIG_CONTENT`. A built-in registry provider
+ * (`nan`) only gets `options.baseURL` when `<ID>_BASE_URL` is set. Values the
+ * operator already set in `OPENCODE_CONFIG_CONTENT` win over the defaults.
+ */
+function withCustomProviderBlock(
+  config: OpencodeConfig,
+  model: string,
+  env: Record<string, string>,
+): void {
+  const provider = providerForModel(model);
+  if (!provider) return;
+  const existing = config.provider?.[provider.id];
+  if (provider.catalog !== "registry") {
+    const baseURL = baseUrlOverride(provider, env);
+    if (!baseURL) return;
+    config.provider = {
+      ...config.provider,
+      [provider.id]: { ...existing, options: { baseURL, ...existing?.options } },
+    };
+    return;
+  }
+  const block = buildOpenAICompatibleProviderBlock(
+    provider,
+    `{env:${provider.envVar}}`,
+    model.slice(provider.id.length + 1),
+    providerBaseUrl(provider, env),
+  );
+  config.provider = {
+    ...config.provider,
+    [provider.id]: {
+      ...block,
+      ...existing,
+      options: { ...block.options, ...existing?.options },
+      models: { ...block.models, ...existing?.models },
+    },
+  };
+}
+
 function parseCommand(command: string, args: string | undefined): string[] {
   const trimmed = command.trim();
   if (!trimmed) {
@@ -252,7 +305,7 @@ const geminiTargetProfile: AcpTargetProfile = {
 /**
  * Copilot CLI has no system-prompt flag. Under `--acp` it reads custom
  * instructions from the git root, the cwd, and every directory listed in
- * COPILOT_CUSTOM_INSTRUCTIONS_DIRS. Verified against 1.0.96: from those extra
+ * COPILOT_CUSTOM_INSTRUCTIONS_DIRS. Verified against 1.0.97: from those extra
  * directories it loads `.github/instructions/*.instructions.md`, but not
  * `AGENTS.md`. So the swarm prompt goes into a per-task directory outside the
  * repo, and the repo's own AGENTS.md is never touched.