@stigmer/runner 3.12.2 → 3.12.4

package/src/activities/execute-deep-agent/shell-env.ts

@@ -1,19 +1,22 @@
 /**
  * Shell environment for the native harness `execute` tool.
  *
- * Per-execution snapshot: runner-manager rotates `STIGMER_TOKEN` in
- * `process.env` at runtime, so this must run inside setup for each execution,
- * never once at process start.
+ * Since #508's boot capture, runner secrets never LIVE in `process.env`, so
+ * the denylist below is defense-in-depth: it keeps this surface safe even if
+ * something re-plants a secret in the environment after boot (a test, an
+ * embedder, a future regression). Still built per execution — the snapshot
+ * must reflect the env as it is now, not at process start.
  */
 
-import { RUNNER_CREDENTIAL_ENV_KEYS } from "../../shared/runner-credential-keys.js";
+import { RUNNER_SECRET_ENV_KEYS } from "../../shared/runner-credential-keys.js";
 
 /**
  * Runner-internal keys that must never reach agent shell commands: every
- * credential the runner holds for its own outbound calls (issue #385). The
- * names — and the rule for adding one — live in runner-credential-keys.ts.
+ * credential the runner holds for its own outbound calls (issue #385) plus
+ * the runner's encryption keys (issue #508). The names — and the rules for
+ * adding one — live in runner-credential-keys.ts.
  */
-export const SHELL_ENV_DENYLIST: readonly string[] = RUNNER_CREDENTIAL_ENV_KEYS;
+export const SHELL_ENV_DENYLIST: readonly string[] = RUNNER_SECRET_ENV_KEYS;
 
 /**
  * Build the environment map passed to deepagents' LocalShellBackend.

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -9,6 +9,9 @@
  *   same `permissions` option it bakes into the graph, keeping the rules
  *   and their normalization shim coupled.
  * - Fresh loop detection (independent cycle tracking)
+ * - Tool intent (issue #276) — the shell tool's bind-time schema gains the
+ *   optional model-authored `description`, so sub-agent shell rows carry
+ *   intent titles exactly like the parent's
  * - Fresh tool truncation (same limits as parent)
  * - Periodic execution budget (interval=30, max=4 advisories)
  * - Approval gate (so a mutating tool *inside* a sub-agent is gated, not
@@ -43,6 +46,7 @@ import { createPathNormalizationMiddleware } from "../../middleware/path-normali
 import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
 import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
 import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
+import { createToolIntentMiddleware } from "../../middleware/tool-intent.js";
 import {
   createApprovalGateMiddleware,
   type ApprovalGateConfig,
@@ -83,7 +87,8 @@ export interface SubAgentMiddlewareOptions {
  *
  * Returns an ordered array mirroring the parent composition:
  * [path normalization] → loop detection → execution budget (periodic) →
- * tool truncation → [approval gate] → cost cap view → error hints.
+ * tool intent → tool truncation → [approval gate] → cost cap view →
+ * error hints.
  * Normalization is outermost so everything downstream observes canonical
  * workspace-absolute paths (matching the parent). The gate sits before the
  * cost-cap view so an approval pause happens before budget accounting, and
@@ -107,6 +112,10 @@ export function buildSubAgentMiddleware(
     maxWarnings: SUB_AGENT_MAX_ADVISORIES,
   }));
 
+  // Sub-agent shell rows render in the same thread as the parent's and must
+  // carry the same model-authored intent titles (issue #276).
+  stack.push(createToolIntentMiddleware());
+
   stack.push(createToolTruncationMiddleware(options.toolTruncation));
 
   if (options.approvalGate) {

package/src/client/stigmer-client.ts

@@ -35,7 +35,7 @@ import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinst
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type { GetArtifactResponse } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import type { GetArtifactResponse, SkillArtifactDownloadUrl } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { create } from "@bufbuild/protobuf";
 import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
@@ -583,6 +583,17 @@ export class StigmerClient {
     return this.skillQuery.getArtifact({ artifactStorageKey });
   }
 
+  /**
+   * Mint an HTTP download URL for a skill artifact (#675). Preferred over
+   * getSkillArtifact for the actual bytes: the unary response is capped by
+   * the server's 10MB gRPC message limit, while skills may be 100MB.
+   * Throws ConnectError with Code.Unimplemented against servers that
+   * predate the transfer lane — callers fall back to getSkillArtifact.
+   */
+  async getSkillArtifactDownloadUrl(artifactStorageKey: string): Promise<SkillArtifactDownloadUrl> {
+    return this.skillQuery.getArtifactDownloadUrl({ artifactStorageKey });
+  }
+
   async createArtifact(input: CreateArtifactInput): Promise<Artifact> {
     return this.artifactCommand.create(input);
   }

package/src/config.ts

@@ -53,6 +53,7 @@ export const DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS = 120_000;
 // three construction sites — mirrors DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS).
 export { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
 import { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
+import { getRunnerSecret } from "./shared/runner-credential-store.js";
 
 export interface Config {
   readonly taskQueue: string;
@@ -158,9 +159,13 @@ export function loadConfig(): Config {
       : requireEnv("STIGMER_BACKEND_ENDPOINT"),
   );
 
-  const stigmerToken = (mode === "cloud" || proxyActive)
-    ? requireEnv("STIGMER_TOKEN")
-    : (process.env.STIGMER_TOKEN ?? null);
+  // Secrets resolve through the credential store, not process.env — the
+  // boot capture has already moved them out of the environment (#508).
+  const stigmerTokenValue = getRunnerSecret("STIGMER_TOKEN");
+  if ((mode === "cloud" || proxyActive) && !stigmerTokenValue) {
+    throw new Error("Required environment variable STIGMER_TOKEN is not set");
+  }
+  const stigmerToken = stigmerTokenValue ?? null;
 
   const mcpBridgeEndpoint = process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null;
 
@@ -170,8 +175,8 @@ export function loadConfig(): Config {
   // the SDK's authorization header (Cursor access token) passes through to
   // api2.cursor.sh unchanged.
   const cursorApiKey = proxyActive
-    ? (process.env.CURSOR_API_KEY ?? stigmerToken ?? "proxy-managed")
-    : (process.env.CURSOR_API_KEY ?? "");
+    ? (getRunnerSecret("CURSOR_API_KEY") ?? stigmerToken ?? "proxy-managed")
+    : (getRunnerSecret("CURSOR_API_KEY") ?? "");
 
   const workspaceRootDir = resolveWorkspaceRootDir();
 

package/src/encryption/config.ts

@@ -25,6 +25,8 @@
  * on the next runner boot — there is no live re-key.
  */
 
+import { getRunnerSecret } from "../shared/runner-credential-store.js";
+
 export interface EncryptionKey {
   readonly keyId: string;
   /** 32-byte AES-256 key. */
@@ -75,14 +77,18 @@ const AES_256_KEY_BYTES = 32;
 export function loadPayloadEncryptionConfig(
   bootstrap?: BootstrapKeyMaterial,
 ): PayloadEncryptionConfig | undefined {
-  const rawKey = process.env[KEY_ENV];
+  // Key VALUES resolve through the credential store (the #508 boot capture
+  // moves them out of process.env — agent shells must not read them); the
+  // *_KEY_ID companions are rotation bookkeeping, not secrets, and stay
+  // plain env reads.
+  const rawKey = getRunnerSecret(KEY_ENV);
   if (rawKey) {
     const primary: EncryptionKey = {
       keyId: requireKeyId(KEY_ID_ENV),
       key: parseKey(rawKey, KEY_ENV),
     };
 
-    const rawSecondary = process.env[SECONDARY_KEY_ENV];
+    const rawSecondary = getRunnerSecret(SECONDARY_KEY_ENV);
     const secondary: EncryptionKey | undefined = rawSecondary
       ? {
           keyId: requireKeyId(SECONDARY_KEY_ID_ENV),

package/src/main.ts

@@ -32,6 +32,10 @@ import { createInterface } from "node:readline";
 import { preflightNodeRuntime } from "./preflight.js";
 import { markBoot, emitRunnerBootTiming } from "./shared/cold-start-timing.js";
 import { loadConfig } from "./config.js";
+import {
+  captureRunnerSecrets,
+  getRunnerSecret,
+} from "./shared/runner-credential-store.js";
 import { initTracing, initMetrics } from "./otel.js";
 import { createStigmerRunner } from "./runner.js";
 import { createStigmerRunnerManager } from "./runner-manager.js";
@@ -214,11 +218,12 @@ async function runPoolMode(
   });
 
   // Sandbox credential self-renewal (see sandbox-token-renewal.ts). Watches
-  // the env var because manager.updateToken keeps it in lockstep with the
-  // manager's internal ref: a blank member's pool_sandbox token parks the
-  // loop, the claim's updateToken swaps in a renewable session token, and
-  // from then on renewal applies fresh tokens back through the same
-  // updateToken (which also cascades to the proxy-credential coordinator).
+  // the credential store because manager.updateToken keeps it in lockstep
+  // with the manager's internal ref: a blank member's pool_sandbox token
+  // parks the loop, the claim's updateToken swaps in a renewable session
+  // token, and from then on renewal applies fresh tokens back through the
+  // same updateToken (which also cascades to the proxy-credential
+  // coordinator).
   const { startSandboxTokenRenewal } = await import("./sandbox-token-renewal.js");
   const { StigmerClient } = await import("./client/stigmer-client.js");
   const renewalClient = new StigmerClient({
@@ -226,7 +231,7 @@ async function runPoolMode(
     token: null,
   });
   const tokenRenewal = startSandboxTokenRenewal({
-    getToken: () => process.env.STIGMER_TOKEN ?? null,
+    getToken: () => getRunnerSecret("STIGMER_TOKEN") ?? null,
     renew: (currentToken) =>
       renewalClient.getRunnerScopedToken({ renewal: true }, currentToken),
     applyToken: (token) => manager.updateToken(token),
@@ -449,6 +454,11 @@ async function main(): Promise<void> {
 
   checkBuildFreshness();
 
+  // Take custody of runner secrets before the config load reads them (#508).
+  // The factories capture too (they are the library boot doors); doing it
+  // here as well keeps main.ts's own late readers store-only from the start.
+  captureRunnerSecrets();
+
   const config = loadConfig();
   markBoot("config_loaded");
 

package/src/middleware/__tests__/tool-intent.test.ts

@@ -0,0 +1,266 @@
+/**
+ * Tool-intent middleware (issue #276): the shell tool's bind-time schema
+ * gains an optional model-authored `description`, execution never sees it,
+ * and the argument survives verbatim into the message history.
+ *
+ * The integration block drives a REAL deepagents graph, because the two
+ * claims that matter most are framework claims: (1) `wrapModelCall` receives
+ * the library's built-in `execute` tool and the clone reaches `bindTools`,
+ * and (2) the original tool's strip-parsing drops the extra argument before
+ * the backend's `execute(command)` runs.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+import { z } from "zod";
+import { tool } from "@langchain/core/tools";
+import { convertToOpenAITool } from "@langchain/core/utils/function_calling";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { MemorySaver } from "@langchain/langgraph";
+import { createDeepAgent } from "deepagents";
+import {
+  createToolIntentMiddleware,
+  INTENT_ARG,
+  INTENT_ARG_PROMPT,
+} from "../tool-intent.js";
+import { buildSubAgentMiddleware } from "../../activities/execute-deep-agent/subagent-wiring.js";
+import { createCasCaptureBackend } from "../../activities/execute-deep-agent/cas-capture-backend.js";
+import { CasCaptureObserver } from "../../activities/execute-deep-agent/cas-capture-observer.js";
+import {
+  ScriptedModel,
+  type ScriptSelector,
+} from "../../activities/execute-deep-agent/__test-utils__/scripted-model.js";
+
+/** A stand-in for deepagents' `execute` tool: same name, same schema shape. */
+function makeShellTool(executed: string[]) {
+  return tool(
+    async ({ command }: { command: string }) => {
+      executed.push(command);
+      return "ok";
+    },
+    {
+      name: "execute",
+      description: "Run a shell command",
+      schema: z.object({ command: z.string().describe("The shell command to execute") }),
+    },
+  );
+}
+
+function makeReadTool() {
+  return tool(async () => "contents", {
+    name: "read_file",
+    description: "Read a file",
+    schema: z.object({ file_path: z.string() }),
+  });
+}
+
+type BoundSchema = {
+  type?: string;
+  properties?: Record<string, { type?: string; description?: string }>;
+  required?: string[];
+};
+
+function schemaOf(t: unknown): BoundSchema {
+  return (t as { schema: BoundSchema }).schema;
+}
+
+async function runWrap(
+  mw: ReturnType<typeof createToolIntentMiddleware>,
+  tools: unknown[],
+): Promise<unknown[]> {
+  let seen: unknown[] = [];
+  const handler = vi.fn(async (req: { tools?: unknown[] }) => {
+    seen = req.tools ?? [];
+    return new AIMessage({ content: "" });
+  });
+  await mw.wrapModelCall!(
+    { model: {}, messages: [], tools, state: {}, runtime: {} } as never,
+    handler as never,
+  );
+  return seen;
+}
+
+describe("ToolIntentMiddleware (unit)", () => {
+  it("passes a tool-less request through untouched", async () => {
+    const mw = createToolIntentMiddleware();
+    const request = { model: {}, messages: [], state: {}, runtime: {} } as never;
+    const handler = vi.fn(async () => new AIMessage({ content: "" }));
+    await mw.wrapModelCall!(request, handler as never);
+    expect(handler).toHaveBeenCalledWith(request);
+  });
+
+  it("extends the shell tool's bound schema with the optional intent arg", async () => {
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [shell]);
+
+    expect(bound).toHaveLength(1);
+    expect(bound[0]).not.toBe(shell);
+    const schema = schemaOf(bound[0]);
+    expect(schema.properties?.command?.type).toBe("string");
+    expect(schema.properties?.[INTENT_ARG]).toEqual({
+      type: "string",
+      description: INTENT_ARG_PROMPT,
+    });
+    // Optional by construction: required is untouched.
+    expect(schema.required ?? []).not.toContain(INTENT_ARG);
+  });
+
+  it("passes non-shell tools through by reference", async () => {
+    const read = makeReadTool();
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [read, shell]);
+    expect(bound[0]).toBe(read);
+    expect(bound[1]).not.toBe(shell);
+  });
+
+  it("never shadows a real argument named like the intent arg", async () => {
+    const conflicting = tool(async () => "ok", {
+      name: "shell",
+      description: "A shell tool that already has a description arg",
+      schema: z.object({ command: z.string(), [INTENT_ARG]: z.string() }),
+    });
+    const bound = await runWrap(createToolIntentMiddleware(), [conflicting]);
+    expect(bound[0]).toBe(conflicting);
+  });
+
+  it("passes through tools whose schema is not an object schema", async () => {
+    const odd = { name: "bash", description: "odd", schema: 42 };
+    const bound = await runWrap(createToolIntentMiddleware(), [odd]);
+    expect(bound[0]).toBe(odd);
+  });
+
+  it("reuses one clone across model calls (referential stability)", async () => {
+    const mw = createToolIntentMiddleware();
+    const shell = makeShellTool([]);
+    const first = await runWrap(mw, [shell]);
+    const second = await runWrap(mw, [shell]);
+    expect(first[0]).toBe(second[0]);
+  });
+
+  it("emits a non-executable declaration that provider converters accept", async () => {
+    const shell = makeShellTool([]);
+    const bound = await runWrap(createToolIntentMiddleware(), [shell]);
+    const declaration = bound[0] as Record<string, unknown>;
+
+    // Deliberately NOT an executable tool — the agent's validation forbids
+    // swapping same-name executable instances, and execution belongs to the
+    // registered original. StructuredToolParams is the sanctioned shape.
+    expect(declaration.invoke).toBeUndefined();
+
+    // The shape every provider's bindTools converts like a structured tool.
+    const openAiTool = convertToOpenAITool(declaration as never) as {
+      function: { name: string; parameters: { properties: Record<string, unknown> } };
+    };
+    expect(openAiTool.function.name).toBe("execute");
+    expect(openAiTool.function.parameters.properties[INTENT_ARG]).toEqual({
+      type: "string",
+      description: INTENT_ARG_PROMPT,
+    });
+    expect(openAiTool.function.parameters.properties.command).toBeDefined();
+  });
+
+  it("is idempotent: an already-extended declaration passes through", async () => {
+    const mw = createToolIntentMiddleware();
+    const shell = makeShellTool([]);
+    const [firstPass] = await runWrap(mw, [shell]);
+    // A second middleware instance (e.g. a sub-agent stack composed over the
+    // same request) must not re-wrap the extended declaration.
+    const [secondPass] = await runWrap(createToolIntentMiddleware(), [firstPass]);
+    expect(secondPass).toBe(firstPass);
+  });
+});
+
+describe("ToolIntentMiddleware (real deepagents graph)", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "tool-intent-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("binds the extended execute schema to the model and strips the arg at execution", async () => {
+    const marker = join(root, "intent-marker.txt");
+    const script: ScriptSelector = () => ({
+      toolCalls: [{
+        name: "execute",
+        args: {
+          command: "echo ran > intent-marker.txt",
+          [INTENT_ARG]: "Write the marker file",
+        },
+        id: "exec_intent_1",
+      }],
+      done: "done",
+    });
+    const model = new ScriptedModel(script);
+
+    const observer = new CasCaptureObserver({ rootDir: root, isIgnored: async () => false });
+    const backend = await createCasCaptureBackend({ rootDir: root, observer, shellEnv: {} });
+
+    const checkpointer = new MemorySaver();
+    const agent = await createDeepAgent({
+      model,
+      checkpointer: checkpointer as never,
+      backend,
+      middleware: [createToolIntentMiddleware()],
+    } as Parameters<typeof createDeepAgent>[0]);
+
+    const config = { configurable: { thread_id: "intent-thread" }, recursionLimit: 50 };
+    await agent.invoke({ messages: [new HumanMessage({ content: "go" })] }, config);
+
+    // (1) The model saw the library's execute tool WITH the intent arg.
+    const boundExecute = model.boundTools.find(
+      (t) => (t as { name?: string }).name === "execute",
+    );
+    expect(boundExecute).toBeDefined();
+    const schema = schemaOf(boundExecute);
+    expect(schema.properties?.[INTENT_ARG]?.description).toBe(INTENT_ARG_PROMPT);
+    expect(schema.properties?.command).toBeDefined();
+    expect(schema.required ?? []).not.toContain(INTENT_ARG);
+
+    // (2) Execution ran the ORIGINAL tool: strip semantics dropped the intent
+    // arg and the command executed normally.
+    expect(await readFile(marker, "utf8")).toBe("ran\n");
+
+    // (3) The intent arg survived verbatim in the message history — the
+    // exact bytes the status builder persists onto ToolCall.args.
+    const state = (await agent.getState(config)) as unknown as {
+      values: { messages: Array<{ tool_calls?: Array<{ name: string; args: Record<string, unknown> }> }> };
+    };
+    const messages = state.values.messages;
+    const toolCall = messages
+      .flatMap((m) => m.tool_calls ?? [])
+      .find((tc) => tc.name === "execute");
+    expect(toolCall).toBeDefined();
+    expect(toolCall!.args[INTENT_ARG]).toBe("Write the marker file");
+    expect(toolCall!.args.command).toBe("echo ran > intent-marker.txt");
+  });
+});
+
+describe("sub-agent stack wiring", () => {
+  it("includes the tool-intent middleware in every sub-agent stack", () => {
+    const stack = buildSubAgentMiddleware({});
+    expect(stack.map((m) => m.name)).toContain("StigmerToolIntentMiddleware");
+  });
+});
+
+describe("wire-contract fixture", () => {
+  it("INTENT_ARG matches the cross-surface fixture key the SDK reads", () => {
+    // The reader side (sdk/react intent-title tests) asserts against the
+    // same file, so the writer and readers cannot drift apart silently.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const fixture = JSON.parse(
+      readFileSync(
+        resolve(here, "../../../../../../test/fixtures/tool-view/intent-title.json"),
+        "utf8",
+      ),
+    ) as { argField: string };
+    expect(INTENT_ARG).toBe(fixture.argField);
+  });
+});

package/src/middleware/index.ts

@@ -9,11 +9,12 @@
  *      workspace-absolute paths)
  *   1. Loop detection (always)
  *   2. Execution budget (always)
- *   3. Tool truncation (always)
- *   4. Graceful stop (always, inert until activated)
- *   5. Cost cap (conditional: only when maxCostUsd > 0)
- *   6. Error hints (always)
- *   7. OTel spans (always, no-op when OTel not configured)
+ *   3. Tool intent (always — bind-time shell schema extension, issue #276)
+ *   4. Tool truncation (always)
+ *   5. Graceful stop (always, inert until activated)
+ *   6. Cost cap (conditional: only when maxCostUsd > 0)
+ *   7. Error hints (always)
+ *   8. OTel spans (always, no-op when OTel not configured)
  */
 
 import type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
@@ -21,6 +22,7 @@ import type { GracefulStopMiddleware } from "./graceful-stop.js";
 import { createPathNormalizationMiddleware } from "./path-normalization.js";
 import { createLoopDetectionMiddleware } from "./loop-detection.js";
 import { createExecutionBudgetMiddleware } from "./execution-budget.js";
+import { createToolIntentMiddleware } from "./tool-intent.js";
 import { createToolTruncationMiddleware } from "./tool-truncation.js";
 import { createGracefulStopMiddleware } from "./graceful-stop.js";
 import { createApprovalGateMiddleware } from "./approval-gate.js";
@@ -51,6 +53,8 @@ export function buildMiddlewareStack(
 
   stack.push(createExecutionBudgetMiddleware(config.executionBudget));
 
+  stack.push(createToolIntentMiddleware());
+
   stack.push(createToolTruncationMiddleware(config.toolTruncation));
 
   const gracefulStop = createGracefulStopMiddleware();