@tangle-network/agent-profile-materialize 0.20.6 → 0.20.8

package/dist/harness-prompt.d.ts

@@ -0,0 +1,18 @@
+import type { AgentProfile } from "@tangle-network/agent-interface";
+import type { HarnessId } from "./harness.js";
+/**
+ * Whether a run keeps the harness's own system prompt, so that a host's
+ * environment context joins the profile's addition instead of replacing the
+ * harness prompt.
+ *
+ * A profile that declares prompt intent (`prompt.instructions` or
+ * `prompt.appendSystemPrompt`) without `prompt.systemPrompt` asked for the
+ * harness prompt to stay in force: that is what `appendSystemPrompt` means.
+ * A host that replaced it with its own template would delete exactly what the
+ * profile kept. On 2026-10-03 every Discovery research director ran under the
+ * sandbox's app-builder template this way: claude-code through
+ * `--system-prompt`, opencode through a generated primary agent.
+ */
+export declare function keepsHarnessSystemPrompt(profile: AgentProfile | undefined, harness: HarnessId | string | undefined): boolean;
+/** Join prompt additions in order, skipping empty ones. */
+export declare function joinSystemPromptAdditions(...additions: Array<string | undefined>): string | undefined;

package/dist/harness-prompt.js

@@ -0,0 +1,44 @@
+/**
+ * Harnesses whose adapter can carry a host's environment context as an
+ * ADDITION to the harness's own system prompt:
+ *
+ * - claude-code and pi: `--append-system-prompt`.
+ * - opencode: the addition file that opencode.json names in `instructions`
+ *   (OPENCODE_APPEND_SYSTEM_PROMPT_FILE). OpenCode's own prompt stays because
+ *   no profile primary agent replaces it.
+ * - codex: `developer_instructions`, which codex sends after its own base
+ *   instructions.
+ *
+ * Every other harness keeps the host's replacement, unchanged.
+ */
+const HARNESSES_WITH_ADDITIVE_HOST_PROMPT = new Set(["claude-code", "pi", "opencode", "codex"]);
+/**
+ * Whether a run keeps the harness's own system prompt, so that a host's
+ * environment context joins the profile's addition instead of replacing the
+ * harness prompt.
+ *
+ * A profile that declares prompt intent (`prompt.instructions` or
+ * `prompt.appendSystemPrompt`) without `prompt.systemPrompt` asked for the
+ * harness prompt to stay in force: that is what `appendSystemPrompt` means.
+ * A host that replaced it with its own template would delete exactly what the
+ * profile kept. On 2026-10-03 every Discovery research director ran under the
+ * sandbox's app-builder template this way: claude-code through
+ * `--system-prompt`, opencode through a generated primary agent.
+ */
+export function keepsHarnessSystemPrompt(profile, harness) {
+    const prompt = profile?.prompt;
+    if (!prompt || prompt.systemPrompt !== undefined)
+        return false;
+    const declaresIntent = (prompt.instructions?.length ?? 0) > 0 ||
+        prompt.appendSystemPrompt !== undefined;
+    return (declaresIntent &&
+        harness !== undefined &&
+        HARNESSES_WITH_ADDITIVE_HOST_PROMPT.has(harness));
+}
+/** Join prompt additions in order, skipping empty ones. */
+export function joinSystemPromptAdditions(...additions) {
+    const parts = additions
+        .map((addition) => addition?.trim())
+        .filter((addition) => Boolean(addition));
+    return parts.length > 0 ? parts.join("\n\n") : undefined;
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, A
 export { OPENCODE_NATIVE_TOOL_IDS, openCodeNativeToolId, } from "./control-maps.js";
 export type { HarnessId } from "./harness.js";
 export { HARNESS_SKILL_DIRS, harnessAutoLoadsAgentContextFile, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_CONTEXT_PATHS, MATERIALIZER_HARNESSES, markMaterializerContextFile, skillDirForHarness, } from "./harness.js";
+export { joinSystemPromptAdditions, keepsHarnessSystemPrompt, } from "./harness-prompt.js";
 export type { OpenCodeMcpConfig } from "./mcp.js";
 export { openCodeMcpConfig } from "./mcp.js";
 export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";

package/dist/index.js

@@ -2,6 +2,7 @@
 export { applyAgentCandidateWorkspacePlan, materializeCandidateProfile, } from "./candidate.js";
 export { OPENCODE_NATIVE_TOOL_IDS, openCodeNativeToolId, } from "./control-maps.js";
 export { HARNESS_SKILL_DIRS, harnessAutoLoadsAgentContextFile, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_CONTEXT_PATHS, MATERIALIZER_HARNESSES, markMaterializerContextFile, skillDirForHarness, } from "./harness.js";
+export { joinSystemPromptAdditions, keepsHarnessSystemPrompt, } from "./harness-prompt.js";
 export { openCodeMcpConfig } from "./mcp.js";
 export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";
 export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, resolvePiRuntimePaths, } from "./pi-models-config.js";

package/dist/mcp.d.ts

@@ -1,4 +1,11 @@
 export declare function materializeMcp(h: HarnessId, mcp: Record<string, ActiveAgentProfileMcpServer>, plan: WorkspacePlan, add: AddPlanFile, unsupported: (d: Unsupported["dimension"], r: string) => void): void;
+/**
+ * The header a harness sends to a remote MCP server whose tool-call timeout it
+ * raised, carrying the timeout it applied in milliseconds. A server may hold a
+ * call for nearly that long. A server that does not see the header must assume
+ * the harness default, 60 s for Claude Code and Codex.
+ */
+export declare const MCP_TOOL_TIMEOUT_HEADER = "X-Mcp-Tool-Timeout-Ms";
 /** OpenCode-native MCP configuration used by workspace and startup paths. */
 export type OpenCodeMcpConfig = Record<string, {
     type: "remote";

package/dist/mcp.js

@@ -1,13 +1,21 @@
 export function materializeMcp(h, mcp, plan, add, unsupported) {
     switch (h) {
         case "claude-code": {
+            // Claude applies one MCP tool-call timeout to every server, so the
+            // longest declared one wins and is what each declaring server is told.
+            const timeouts = mcpToolTimeouts(mcp, h, unsupported);
+            const toolTimeoutMs = timeouts.size > 0 ? Math.max(...timeouts.values()) : undefined;
+            if (toolTimeoutMs !== undefined) {
+                setPlanEnvironment(plan, "MCP_TOOL_TIMEOUT", String(toolTimeoutMs));
+            }
             const servers = {};
             for (const [name, server] of Object.entries(mcp)) {
                 if (server.url) {
+                    const headers = withAppliedToolTimeout(server.headers, timeouts.has(name) ? toolTimeoutMs : undefined);
                     servers[name] = {
                         type: server.transport ?? "http",
                         url: server.url,
-                        ...(server.headers ? { headers: server.headers } : {}),
+                        ...(headers ? { headers } : {}),
                     };
                     continue;
                 }
@@ -30,13 +38,14 @@ export function materializeMcp(h, mcp, plan, add, unsupported) {
             unsupported("mcp", "nanoclaw MCP must be injected through options.mcpServers by its SDK adapter");
             break;
         case "codex": {
+            const timeouts = mcpToolTimeouts(mcp, h, unsupported);
             const servers = [];
             for (const [name, server] of Object.entries(mcp).sort(([left], [right]) => compareStrings(left, right))) {
                 if (server.url && server.transport === "sse") {
                     unsupported("mcp", `codex: remote MCP server "${name}" uses unsupported SSE transport`);
                     continue;
                 }
-                servers.push(concatWorkspacePlanArguments(`${tomlStr(name)} = `, codexMcpServerToml(name, server, plan)));
+                servers.push(concatWorkspacePlanArguments(`${tomlStr(name)} = `, codexMcpServerToml(name, server, plan, timeouts.get(name))));
             }
             if (servers.length > 0) {
                 // Runtime overrides do not require persisted project trust. Header values
@@ -143,13 +152,69 @@ function tomlInlineStringTable(values) {
         .map(([key, value]) => `${tomlStr(key)} = ${tomlStr(value)}`)
         .join(", ")} }`;
 }
-function codexMcpServerToml(name, server, plan) {
+/**
+ * The header a harness sends to a remote MCP server whose tool-call timeout it
+ * raised, carrying the timeout it applied in milliseconds. A server may hold a
+ * call for nearly that long. A server that does not see the header must assume
+ * the harness default, 60 s for Claude Code and Codex.
+ */
+export const MCP_TOOL_TIMEOUT_HEADER = "X-Mcp-Tool-Timeout-Ms";
+const MIN_MCP_TOOL_TIMEOUT_MS = 1_000;
+const MAX_MCP_TOOL_TIMEOUT_MS = 3_600_000;
+/**
+ * The tool-call timeout a profile asks the harness to give one MCP server,
+ * from `metadata.toolTimeoutMs`. Profile metadata is open in every published
+ * schema, so a profile carrying it validates against older consumers, which
+ * ignore it. A malformed value is reported, never guessed.
+ */
+function mcpToolTimeoutMs(server, name, h, unsupported) {
+    const value = server.metadata?.toolTimeoutMs;
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < MIN_MCP_TOOL_TIMEOUT_MS ||
+        value > MAX_MCP_TOOL_TIMEOUT_MS) {
+        unsupported("mcp", `${h}: MCP server "${name}" metadata.toolTimeoutMs must be an integer from ${MIN_MCP_TOOL_TIMEOUT_MS} to ${MAX_MCP_TOOL_TIMEOUT_MS}`);
+        return undefined;
+    }
+    return value;
+}
+function mcpToolTimeouts(mcp, h, unsupported) {
+    const timeouts = new Map();
+    for (const [name, server] of Object.entries(mcp)) {
+        const value = mcpToolTimeoutMs(server, name, h, unsupported);
+        if (value !== undefined)
+            timeouts.set(name, value);
+    }
+    return timeouts;
+}
+function withAppliedToolTimeout(headers, appliedTimeoutMs) {
+    if (appliedTimeoutMs === undefined)
+        return headers;
+    return {
+        ...headers,
+        [MCP_TOOL_TIMEOUT_HEADER]: {
+            kind: "public",
+            value: String(appliedTimeoutMs),
+        },
+    };
+}
+function codexMcpServerToml(name, server, plan, toolTimeoutMs) {
     const fields = [];
+    // Codex takes whole seconds per server; the server is told what was applied.
+    const appliedTimeoutMs = toolTimeoutMs === undefined
+        ? undefined
+        : Math.ceil(toolTimeoutMs / 1000) * 1000;
+    if (appliedTimeoutMs !== undefined) {
+        fields.push(`tool_timeout_sec = ${appliedTimeoutMs / 1000}`);
+    }
     if (server.url) {
         fields.push(`url = ${tomlStr(server.url)}`);
-        if (server.headers && Object.keys(server.headers).length > 0) {
+        const headers = withAppliedToolTimeout(server.headers, appliedTimeoutMs);
+        if (headers && Object.keys(headers).length > 0) {
             const envHeaders = {};
-            for (const [header, value] of Object.entries(server.headers).sort(([left], [right]) => compareStrings(left, right))) {
+            for (const [header, value] of Object.entries(headers).sort(([left], [right]) => compareStrings(left, right))) {
                 const envName = `TANGLE_MCP_HEADER_${sha256(`${name}\0${header}`)
                     .slice(0, 24)
                     .toUpperCase()}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.20.6",
+  "version": "0.20.8",
   "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-dev-container, and VB).",
   "type": "module",
   "repository": {