@stigmer/runner 3.9.0 → 3.11.0

package/src/activities/execute-deep-agent/index.ts

@@ -32,6 +32,7 @@ import {
 } from "../../shared/workspace/stigmer-link.js";
 import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
+import { formatDatastoreDegradationNotice } from "../../shared/datastore-attachment.js";
 import { classifyTool } from "../../shared/tool-kind.js";
 import {
   POLICY_ENGINE_VERSION,
@@ -151,6 +152,25 @@ export function createDeepAgentActivities(config: Config) {
         const initialStatus = shouldSeedFromPersistedTranscript(setup.execution)
           ? seedStatusFromExecution(setup.execution)
           : create(AgentExecutionStatusSchema, {});
+
+        // Datastore degradation disclosure, operator half (issue #325): the
+        // prompt already tells the agent to disclose the outage; this makes
+        // it visible on the execution record without reading a transcript.
+        // Appended to initialStatus BEFORE streaming (not via a status
+        // builder): both the v2 and v3 stream paths construct their own
+        // builder around this same proto and only ever append messages, so
+        // this row survives whichever path runs and rides every persist.
+        if (setup.datastoreToolsMissing.length > 0) {
+          initialStatus.messages.push(create(AgentMessageSchema, {
+            type: MessageType.MESSAGE_SYSTEM,
+            content: formatDatastoreDegradationNotice(
+              setup.agent.spec?.datastoreUsages?.length ?? 0,
+              setup.datastoreToolsMissing,
+            ),
+            timestamp: utcTimestamp(),
+          }));
+        }
+
         const statusBuilder = new StatusBuilder(executionId, initialStatus);
 
         statusBuilder.setApprovalProvider({

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -26,6 +26,7 @@ import {
   buildImplementPlanDirective,
   findApprovedPlanPath,
 } from "../../shared/implement-plan-prompt.js";
+import type { InjectedFile } from "./attachment-injector.js";
 
 const RESPONSE_RULES = `
 
@@ -99,8 +100,11 @@ export interface PromptBuilderInput {
   containerRoot: string;
   skillsPromptSection: string;
   /**
-   * The `<available_datastores>` section (shared/datastore-attachment.ts
-   * formatDatastoresSection); empty when the agent uses no datastores.
+   * The datastores section (shared/datastore-attachment.ts
+   * formatDatastoresSection): `<available_datastores>` when the connected
+   * record-tool roster is complete, `<unavailable_datastores>` when setup's
+   * reconciliation found record tools missing (issue #325). Empty when the
+   * agent uses no datastores.
    */
   datastoresPromptSection?: string;
   /**
@@ -162,11 +166,10 @@ export interface PromptBuilderInput {
   sessionContext?: string;
 }
 
-export interface InjectedFile {
-  filename: string;
-  path: string;
-  size?: number | null;
-}
+// The prompt renders the injector's own result type — a local structural twin
+// once lived here and silently dropped the size field (`size` vs `sizeBytes`),
+// so the "(N bytes)" annotation never rendered. One type, one truth.
+export type { InjectedFile } from "./attachment-injector.js";
 
 /**
  * Which images ride the user message inline (in send order) and which
@@ -396,7 +399,7 @@ function buildReferencedFilesSection(
 }
 
 function buildInjectedFilesSection(
-  files: InjectedFile[],
+  files: readonly InjectedFile[],
   vision?: VisionPromptInfo,
 ): string {
   let section = "\n\n## Input Files\n\n";
@@ -410,8 +413,15 @@ function buildInjectedFilesSection(
     "Do NOT modify or delete these files.\n\n";
 
   for (const f of files) {
-    const sizeInfo = f.size != null ? ` (${f.size} bytes)` : "";
-    section += `- \`${f.path}\`${sizeInfo}\n`;
+    const sizeInfo = ` (${f.sizeBytes} bytes)`;
+    // A duplicate-renamed file (attachment-naming.ts) discloses its original
+    // name so the agent can connect "the two report.pdfs" in the user's
+    // message to distinct files on disk.
+    const renameInfo =
+      f.renamedFrom !== undefined
+        ? ` (renamed from duplicate '${f.renamedFrom}')`
+        : "";
+    section += `- \`${f.path}\`${sizeInfo}${renameInfo}\n`;
   }
 
   // The vision lines (shared wording, attachment-vision.ts) tell the model

package/src/activities/execute-deep-agent/setup.ts

@@ -8,7 +8,7 @@
  * the streaming phase needs.
  */
 
-import { createDeepAgent, type FilesystemPermission } from "deepagents";
+import { createDeepAgent } from "deepagents";
 import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
 import { z } from "zod";
@@ -33,11 +33,13 @@ import {
 } from "../../shared/caller-identity.js";
 import { readSessionContext } from "../../shared/session-context.js";
 import { connectMcpServers, type McpConnectionResult } from "../../shared/mcp-manager.js";
-import { resolveMcpServers } from "../../shared/mcp-resolver.js";
+import { mergeMcpServerUsages, resolveMcpServers } from "../../shared/mcp-resolver.js";
 import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js";
 import { backfillMcpServersIfNeeded } from "../../shared/connect-backfill.js";
 import {
+  DATASTORE_ATTACHMENT_SLUG,
   formatDatastoresSection,
+  missingRecordTools,
   synthesizeDatastoreAttachment,
 } from "../../shared/datastore-attachment.js";
 import {
@@ -56,6 +58,7 @@ import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import type { WorkspaceBackend, ProvisionResult } from "../../shared/workspace/types.js";
 import { createCasCaptureBackend } from "./cas-capture-backend.js";
 import { buildShellEnv } from "./shell-env.js";
+import { PLAN_MODE_PERMISSIONS } from "../../shared/plan-mode-permissions.js";
 import { CasCaptureObserver } from "./cas-capture-observer.js";
 import { isGitWorkTree, isPathCapturable } from "../../shared/filereview/git-substrate.js";
 import { deriveCaptureMode } from "../../shared/filereview/capture.js";
@@ -73,7 +76,7 @@ import type { ApprovalGateConfig } from "../../middleware/approval-gate.js";
 import { deriveExecutionFingerprintKey } from "../../shared/approval-fingerprint.js";
 import { getRunnerHitlMasterSecret } from "../../shared/fingerprint-secret.js";
 import { getModelPricing, ensureLoaded as ensurePricingLoaded } from "../../shared/model-pricing.js";
-import { getDefaultModel } from "../../shared/model-registry.js";
+import { getDefaultModel, getModelVisionCapability } from "../../shared/model-registry.js";
 import { buildChatModel } from "../../shared/model-client.js";
 import {
   loadArtifactStorageConfig,
@@ -126,6 +129,16 @@ export interface SetupResult {
   readonly session: Session;
   readonly workspaceBackend: WorkspaceBackend;
   readonly mcpConnection: McpConnectionResult | null;
+  /**
+   * Record tools declared via datastore_usages but absent from the connected
+   * stigmer-records roster this turn (issue #325). Empty = healthy (also when
+   * the agent uses no datastores). Non-empty selects the degraded prompt
+   * section in Step 8, and the activity surfaces it to operators as a
+   * MESSAGE_SYSTEM row — the vision-facts pattern: setup computes the honest
+   * struct, the caller discloses. Recomputed every turn, so a healed outage
+   * stops disclosing on the next turn.
+   */
+  readonly datastoreToolsMissing: readonly string[];
   readonly mergedEnvVars: Record<string, string>;
   readonly secretKeys: ReadonlySet<string>;
   readonly modelName: string;
@@ -348,20 +361,36 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         : async () => true,
     });
 
-    // Step 7: Resolve and connect MCP servers
-    const mcpServerUsages = [
-      ...(agent.spec!.mcpServerUsages || []),
-      ...(session.spec!.mcpServerUsages || []),
-    ];
+    // Step 7: Resolve and connect MCP servers. Session-wins-per-slug merge
+    // (the Cursor harness's blueprint semantics, shared so a duplicate slug
+    // resolves identically in both harnesses — one usage per server, whose
+    // enabled_tools is the one the connect-time filter honors).
+    const mcpServerUsages = mergeMcpServerUsages(
+      agent.spec!.mcpServerUsages || [],
+      session.spec!.mcpServerUsages || [],
+    );
     const datastoreUsages = agent.spec!.datastoreUsages || [];
 
     // The synthesized attachments' credential story (DD-006 D4): the
     // exchanged token authenticates the discovery reads per-call (the
     // messaging reach refuses a desktop runner's ambient embedded_runner
     // credential; undefined lets the ambient credential apply). The
-    // attachment header falls back to the ambient credential.
-    const exchangedRunnerToken =
-      await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    // attachment header falls back to the ambient credential. Unlike the
+    // env read (which hard-fails on a broken exchange — secrets are
+    // load-bearing there), this exchange is opportunistic: every consumer
+    // below degrades to an empty answer by contract, and the server
+    // refuses the ambient fallback safely, so a failed exchange must not
+    // kill the run.
+    let exchangedRunnerToken: string | undefined;
+    try {
+      exchangedRunnerToken =
+        await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    } catch (err) {
+      console.warn(
+        "[execute-deep-agent] Scoped-token exchange failed for attachment/discovery " +
+        `reads; degrading to the ambient credential: ${err instanceof Error ? err.message : err}`,
+      );
+    }
     const attachmentCredential = exchangedRunnerToken
       ?? config.stigmerTokenRef?.current
       ?? config.stigmerToken;
@@ -516,9 +545,16 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
 
     // Step 7c: Inject attachments. The vision budget rides along so image
     // attachments are selected for inline delivery while their bytes are
-    // already in hand (attachment-vision.ts owns all policy).
+    // already in hand (attachment-vision.ts owns all policy). The budget
+    // also carries the root model's registry vision capability — the root
+    // model is the only one that ever receives inline image blocks
+    // (sub-agents get a fresh task description, summarization reuses this
+    // same model instance) — so a model flagged `vision: false` degrades
+    // images honestly instead of shipping a payload its provider rejects.
     const attachments = execution.spec!.attachments || [];
-    const visionBudget = new VisionBudget(DEEP_AGENT_VISION_PROFILE);
+    const visionBudget = new VisionBudget(DEEP_AGENT_VISION_PROFILE, {
+      modelVision: await getModelVisionCapability(modelName),
+    });
     const injectedFiles = await injectAttachments({
       backend: workspaceBackend,
       attachments,
@@ -549,6 +585,28 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     }
     timing.mark("inject_attachments");
 
+    // Reconcile the declared datastores against the record tools actually
+    // connected (issue #325): the records roster always serves all five
+    // tools, so any absence means the store is degraded, and the prompt
+    // must say so instead of promising tools the agent does not have. The
+    // connected roster is post-connect truth — when usages exist, MCP
+    // connect always ran above (a thrown connect already failed the run).
+    const datastoreToolsMissing = datastoreUsages.length > 0 && mcpConnection
+      ? missingRecordTools(
+          (mcpConnection.serverToolMap[DATASTORE_ATTACHMENT_SLUG] ?? [])
+            .map((t) => t.name),
+        )
+      : [];
+    if (datastoreToolsMissing.length > 0) {
+      console.warn(
+        `[setup] Datastore record tools degraded: declared ` +
+        `${datastoreUsages.length} datastore usage(s) but the ` +
+        `'${DATASTORE_ATTACHMENT_SLUG}' roster is missing ` +
+        `[${datastoreToolsMissing.join(", ")}] — the prompt discloses the ` +
+        `outage instead of the available-datastores section.`,
+      );
+    }
+
     // Step 8: Build enhanced system prompt
     const systemPrompt = buildEnhancedSystemPrompt({
       instructions,
@@ -556,7 +614,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       containerRoot: workspaceBackend.rootDir,
       skillsPromptSection,
       datastoresPromptSection: datastoreUsages.length > 0
-        ? formatDatastoresSection(datastoreUsages)
+        ? formatDatastoresSection(datastoreUsages, datastoreToolsMissing)
         : undefined,
       // "" (nothing sendable) threads as undefined: the tool alone still
       // serves text sends inside a 24-hour window (DD-006 D6).
@@ -577,8 +635,11 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // Step 9: Construct the LLM model. Resolution to the provider API id
     // happens inside buildChatModel; modelName stays the registry id for
     // pricing, the native-thinking heuristic, and sub-agent inheritance.
-    const requestTimeoutMs =
-      parseInt(process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS ?? "0") || undefined;
+    // Operator input: only a positive integer means "bound the request" —
+    // unset, non-numeric, zero, and negative all normalize to no bound.
+    const parsedTimeoutMs =
+      Number.parseInt(process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS ?? "", 10);
+    const requestTimeoutMs = parsedTimeoutMs > 0 ? parsedTimeoutMs : undefined;
     const { model } = await buildChatModel({
       modelName,
       proxyEndpoint: config.proxyEndpoint ?? undefined,
@@ -614,12 +675,11 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // gate. Both flow into sub-agents via the shared config below.
     const leases = deriveActiveLeases(execution);
     const globalBypass = leases.global;
-    const agentOverrides = agent.spec!.mcpServerUsages?.flatMap(
-      u => u.toolApprovalOverrides ?? [],
-    ) ?? [];
+    // Layer-3 overrides ride each resolved server from its (session-wins
+    // merged) usage — see ResolvedMcpServer.toolApprovalOverrides (issue
+    // #349) — so there is no separate override input to pass here.
     const approvalPolicies = mergeApprovalPolicies(
       resolvedMcpServers?.resolvedServers ?? [],
-      agentOverrides,
       leases,
     );
 
@@ -760,6 +820,10 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         // Presence of shellEnv is the shell-capability switch for sub-agent
         // backends too (undefined in plan mode; see buildShellEnv above).
         shellEnv,
+        // Plan mode's deny-all-writes rule, mirrored onto every sub-agent graph
+        // (issue #255) — pre-built CompiledSubAgents never inherit the parent's
+        // permissions, so read-only-by-construction must be baked in here.
+        ...(isPlanMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
       });
       timing.mark("compile_subagents");
     }
@@ -773,16 +837,6 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       responseFormat = jsonSchemaToZod(outputSchema as unknown as Record<string, unknown>);
     }
 
-    // Plan mode is read-only. Deny every filesystem write operation at the tool
-    // level so write_file/edit_file/etc. cannot mutate the workspace — enforcing
-    // the InteractionMode.PLAN contract by construction, not by prompt. Rules are
-    // first-match-wins with a permissive default, so a single deny-all-writes
-    // rule is sufficient. (The Cursor harness enforces plan mode via its prompt
-    // prefix; the native harness enforces it here.)
-    const planModePermissions: FilesystemPermission[] = [
-      { operations: ["write"], paths: ["/**"], mode: "deny" },
-    ];
-
     // File capture point. Apply-then-review is universal (Slice 2b), so the
     // CAS-observing backend: git-tracked edits flow to disk (the turn-boundary
     // git diff is authoritative), and the shared CAS observer records the pre-turn
@@ -803,7 +857,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       middleware: middleware as any,
       subagents: compiledSubagents ?? undefined,
       ...(responseFormat ? { responseFormat } : {}),
-      ...(isPlanMode ? { permissions: planModePermissions } : {}),
+      ...(isPlanMode ? { permissions: PLAN_MODE_PERMISSIONS } : {}),
     } as Parameters<typeof createDeepAgent>[0]);
 
     // Step 11: Prepare invocation input and config. The conversation catchup
@@ -874,6 +928,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       session,
       workspaceBackend,
       mcpConnection,
+      datastoreToolsMissing,
       mergedEnvVars: envResult.mergedEnvVars,
       secretKeys: envResult.secretKeys,
       modelName,

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

@@ -15,12 +15,15 @@
  *   no approval gate — see deepagents-profiles.ts for the suppression half)
  * - Sub-agent backends are shell-capable outside plan mode (issue #248), mirroring
  *   the parent's backend selection in setup.ts
+ * - Sub-agent graphs carry the parent's filesystem permissions explicitly
+ *   (issue #255): pre-built CompiledSubAgents never inherit them, so plan
+ *   mode's deny-all-writes rule is baked into each graph at compile time
  * - Invalid configurations are logged and skipped (graceful degradation)
  * - Empty subagent list returns null (no subagents configured)
  */
 
 import { createDeepAgent, FilesystemBackend, LocalShellBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT } from "deepagents";
-import type { CompiledSubAgent } from "deepagents";
+import type { CompiledSubAgent, FilesystemPermission } from "deepagents";
 import type { StructuredTool } from "@langchain/core/tools";
 import type { RunnableConfig } from "@langchain/core/runnables";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
@@ -180,6 +183,18 @@ export interface SubagentTransformOptions {
    * backends, exactly like the parent's backend selection.
    */
   readonly shellEnv?: Record<string, string>;
+  /**
+   * Filesystem permission rules baked into each compiled sub-agent graph,
+   * inherited from the parent's rules in setup.ts (plan mode's deny-all-writes
+   * today). Required because deepagents' parent-permission inheritance covers
+   * only spec-style sub-agents — pre-built CompiledSubAgents bypass it, so
+   * without this a plan-mode sub-agent could still write (issue #255).
+   *
+   * Must not be combined with `shellEnv`: deepagents rejects permissions on an
+   * execution-capable backend (see the cas-capture-backend.ts header). Plan
+   * mode guarantees that by construction — it is the mode that clears shellEnv.
+   */
+  readonly permissions?: FilesystemPermission[];
 }
 
 // =========================================================================
@@ -525,6 +540,8 @@ export async function compileSubagents(
     readonly modelFactory?: (modelName: string) => Promise<BaseChatModel>;
     /** Shell env for `execute`; see {@link SubagentTransformOptions.shellEnv}. */
     readonly shellEnv?: Record<string, string>;
+    /** Per-graph filesystem rules; see {@link SubagentTransformOptions.permissions}. */
+    readonly permissions?: FilesystemPermission[];
   },
 ): Promise<CompiledSubAgent[]> {
   if (transformed.length === 0) return [];
@@ -560,6 +577,9 @@ export async function compileSubagents(
         tools: spec.tools.length > 0 ? spec.tools : undefined,
         middleware: middleware as unknown[],
         backend,
+        // Enforced inside this graph's own filesystem tools — and inherited by
+        // any spec-style sub-agent deepagents auto-injects one level deeper.
+        ...(opts.permissions ? { permissions: opts.permissions } : {}),
       } as Parameters<typeof createDeepAgent>[0]);
 
       const gatedRunnable = gate.wrapRunnable(
@@ -623,6 +643,7 @@ export async function transformAndCompileSubagents(
     costCap,
     modelFactory,
     shellEnv,
+    permissions,
   } = options;
 
   if (subAgents.length === 0 && !workspaceBackend.rootDir) {
@@ -743,6 +764,7 @@ export async function transformAndCompileSubagents(
     casObserver,
     modelFactory,
     shellEnv,
+    permissions,
   });
 
   if (compiled.length === 0) {

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

@@ -9,11 +9,16 @@
  *   bypassed) — installed only when the parent itself is gated
  *   (`approvalGate` present; absent under auto-approve-all)
  * - Shared cost cap view (parent's budget, no reset on sub-agent start)
+ * - Error hints (issue #255): a thrown tool error becomes a recoverable
+ *   ToolMessage exactly as on the parent. Without it, any tool throw — a
+ *   plan-mode permission denial, an MCP hiccup — propagated out of the
+ *   sub-agent graph and killed the whole delegated task, losing all its
+ *   accumulated work, where the parent's identical error is one failed
+ *   tool round the model adapts to.
  *
  * The sub-agent middleware stack does NOT include:
  * - Graceful stop (parent handles STOP signal propagation)
  * - OTel spans (parent's OTel context propagates automatically)
- * - Error hints (applied at tool level, not sub-agent level)
  *
  * Approval-gate note: the gate is what *creates* the LangGraph `interrupt()`.
  * A sub-agent's interrupt does surface at the parent checkpoint and resumes
@@ -31,6 +36,7 @@ import {
   createApprovalGateMiddleware,
   type ApprovalGateConfig,
 } from "../../middleware/approval-gate.js";
+import { createErrorHintsMiddleware } from "../../middleware/error-hints.js";
 
 const SUB_AGENT_ADVISORY_INTERVAL = 30;
 const SUB_AGENT_MAX_ADVISORIES = 4;
@@ -60,9 +66,11 @@ export interface SubAgentMiddlewareOptions {
  *
  * Returns an ordered array mirroring the parent composition:
  * loop detection → execution budget (periodic) → tool truncation →
- * [approval gate] → cost cap view. The gate sits before the cost-cap view so an
- * approval pause happens before budget accounting, matching the parent order
- * (…→ truncation → graceful-stop → approval gate → cost cap …).
+ * [approval gate] → cost cap view → error hints. The gate sits before the
+ * cost-cap view so an approval pause happens before budget accounting, and
+ * error hints come after the gate — both matching the parent order
+ * (…→ truncation → graceful-stop → approval gate → cost cap → error hints …),
+ * which keeps the gate's HITL interrupt outside the hints' try/catch.
  */
 export function buildSubAgentMiddleware(
   options: SubAgentMiddlewareOptions = {},
@@ -99,5 +107,7 @@ export function buildSubAgentMiddleware(
     stack.push(options.costCap.forSubAgent());
   }
 
+  stack.push(createErrorHintsMiddleware());
+
   return stack;
 }

package/src/activities/hydrate-workflow-execution.ts

@@ -267,7 +267,9 @@ async function fetchAndFlattenEnv(
 ): Promise<Record<string, unknown>> {
   // A desktop runner exchanges its bootstrap credential for a token scoped to
   // this workflow execution, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // No-op for cloud sandbox and OSS runners. A failed exchange throws and
+  // fails the activity: the bootstrap credential no longer decrypts
+  // (stigmer-cloud#218), so proceeding would hydrate redacted placeholders.
   const scopedToken = await client.acquireScopedRunnerToken({
     workflowExecutionId: executionId,
   });