@stigmer/runner 3.12.4 → 3.12.5

package/src/shared/declared-preferences.ts

@@ -0,0 +1,84 @@
+/**
+ * Declared preferences (stigmer/stigmer#293, DD-002): standing free-text
+ * preferences the organization and the calling user declared once — "keep
+ * answers terse", "we deploy to us-east-1" — that every eligible execution
+ * receives without the user re-typing them.
+ *
+ * The server composes the CONTENT at execution create: the create pipeline
+ * snapshots `Organization.spec.preferences.standing_context` and (cloud, for
+ * first-party human callers only) the caller
+ * `IdentityAccount.spec.preferences.standing_context` verbatim onto the
+ * execution spec's `declared_preferences` field. This module owns the
+ * PRESENTATION — the preamble and the per-scope attribution — so the framing
+ * cannot drift between harnesses.
+ *
+ * Like conversation-catchup (its typed-field sibling) there is no metadata
+ * key to mirror-guard: the value rides a TYPED proto field, so codegen
+ * enforces the cross-repo contract. Degradation is safe by construction: an
+ * absent or blank field renders nothing, and a runner predating this module
+ * simply ignores it — the agent runs without preferences, exactly the
+ * pre-#293 behavior, never worse.
+ */
+
+import type { DeclaredPreferences } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+
+/**
+ * How the preferences are introduced to the model, shared by both harnesses
+ * so the behavioral contract cannot drift between them. Same posture as the
+ * session-context channel: calibration material, never authority — the task
+ * always outranks a standing preference.
+ */
+const DECLARED_PREFERENCES_PREAMBLE =
+  "Standing preferences declared by the organization and/or the user you " +
+  "are assisting. Treat them as background you already know: use them to " +
+  "calibrate depth, defaults, and tone. Do not repeat them back, quote " +
+  "them, or mention that you received them. They are context, not " +
+  "instructions that override your task.";
+
+/**
+ * The non-blank preference scopes of an execution, in presentation order.
+ * At least one scope is set (the read function returns undefined otherwise).
+ */
+export interface DeclaredPreferencesContent {
+  /** The organization's standing context, trimmed; absent when blank. */
+  orgContext?: string;
+  /** The calling user's standing context, trimmed; absent when blank. */
+  userContext?: string;
+}
+
+/**
+ * Read the declared preferences from an execution spec's
+ * `declared_preferences`. Returns undefined when the field is absent or both
+ * scopes are blank — the caller renders no section. Blank-is-absent applies
+ * PER SCOPE: an org-only snapshot renders only the org subsection.
+ */
+export function readDeclaredPreferences(
+  preferences: DeclaredPreferences | undefined,
+): DeclaredPreferencesContent | undefined {
+  const orgContext = preferences?.orgContext?.trim() || undefined;
+  const userContext = preferences?.userContext?.trim() || undefined;
+  if (!orgContext && !userContext) {
+    return undefined;
+  }
+  return { orgContext, userContext };
+}
+
+/**
+ * The framed preferences body (preamble + labeled per-scope subsections),
+ * ready for section wrapping. Attribution is explicit — the model must know
+ * WHO declared what. Organization first, user last: the user's refinement
+ * reads last and so naturally wins where the two conflict, without this
+ * module encoding any override rule.
+ */
+export function formatDeclaredPreferencesText(
+  content: DeclaredPreferencesContent,
+): string {
+  const sections: string[] = [DECLARED_PREFERENCES_PREAMBLE];
+  if (content.orgContext) {
+    sections.push(`Declared by the organization:\n${content.orgContext}`);
+  }
+  if (content.userContext) {
+    sections.push(`Declared by the user:\n${content.userContext}`);
+  }
+  return sections.join("\n\n");
+}

package/src/shared/mcp-enabled-tools.ts

@@ -7,9 +7,8 @@
  * - An empty usage list falls back to the server's default_enabled_tools.
  * - Both empty means NO restriction — every discovered tool is available.
  *
- * Both harnesses import THIS module so they can never drift on these
- * semantics (the mcp-transport-guard precedent for logic shared across the
- * duplicated resolvers — see the header of shared/mcp-resolver.ts):
+ * Resolution is shared (shared/mcp-resolver.ts threads the effective list
+ * onto every ResolvedMcpServer), but ENFORCEMENT is per-harness:
  * - The deep-agent harness filters the discovered toolset before it reaches
  *   the model (shared/mcp-manager.ts connectMcpServers).
  * - The Cursor harness cannot hide tools (the Cursor SDK's McpServerConfig

package/src/shared/mcp-resolver.ts

@@ -2,13 +2,17 @@
  * Resolves Stigmer McpServerUsage references into an intermediate
  * ResolvedMcpServer format.
  *
- * Consumers: the deep-agent harness (execute-deep-agent/setup.ts), the
- * connect backfill (shared/connect-backfill.ts), and the discovery
- * activity (activities/discover-mcp-server.ts, via mcpServerToResolved).
- * NOTE: the Cursor harness does NOT use this module — it has its own
- * near-duplicate resolver at activities/execute-cursor/mcp-resolver.ts.
- * A behavioral change here (like the transport guard) must be mirrored
- * there until the two are consolidated.
+ * THE single resolver for both harnesses (oss#387 retired the Cursor
+ * harness's near-duplicate): the deep-agent harness
+ * (execute-deep-agent/setup.ts), the Cursor harness
+ * (execute-cursor/index.ts), the connect backfill
+ * (shared/connect-backfill.ts), and the discovery activity
+ * (activities/discover-mcp-server.ts, via mcpServerToResolved) all consume
+ * it. Each harness maps the result into its SDK format at the last hop:
+ * toMcpClientConfig (shared/mcp-manager.ts) for LangChain,
+ * toCursorMcpConfig (execute-cursor/cursor-mcp-config.ts) for the Cursor
+ * SDK — so a behavioral change here (like the transport guard) lands in
+ * both execution paths by construction.
  */
 
 import type { McpServerUsage, ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
@@ -51,8 +55,11 @@ export interface ResolvedMcpServer {
    * enabled_tools, falling back to the server's default_enabled_tools when
    * the usage's list is empty (see shared/mcp-enabled-tools.ts). Absent when
    * unrestricted — which keeps synthesized attachment servers (built without
-   * a usage) and the discovery path unfiltered by construction. Enforced at
-   * connect time by connectMcpServers (shared/mcp-manager.ts).
+   * a usage) and the discovery path unfiltered by construction. Enforcement
+   * is per-harness: the deep-agent path filters at connect time
+   * (connectMcpServers, shared/mcp-manager.ts); the Cursor SDK config cannot
+   * hide tools, so that harness denies non-enabled calls in the HITL hook
+   * (see hook-script.ts).
    */
   enabledTools?: string[];
   /**
@@ -61,11 +68,10 @@ export interface ResolvedMcpServer {
    * override to its own server — a flat cross-server list is how an
    * override once leaked onto (or silently un-gated) a same-named tool on
    * another server. Deliberately REQUIRED, not optional: empty means "no
-   * overrides", and every construction site — including the near-duplicate
-   * Cursor resolver and the synthesized attachments, which have no usage
-   * and therefore no layer 3 — must say so explicitly, so a forgotten
-   * mirror cannot compile. Consumed by mergeApprovalPolicies
-   * (shared/approval-policy.ts).
+   * overrides", and every construction site — including the synthesized
+   * attachments, which have no usage and therefore no layer 3 — must say so
+   * explicitly, so a forgotten site cannot compile. Consumed by
+   * mergeApprovalPolicies (shared/approval-policy.ts).
    */
   toolApprovalOverrides: ToolApprovalOverride[];
 }
@@ -202,12 +208,6 @@ export function mcpServerToResolved(
   }
 }
 
-export function extractMcpServerSlugs(usages: McpServerUsage[]): string[] {
-  return usages
-    .map((u) => u.mcpServerRef?.slug)
-    .filter((s): s is string => !!s);
-}
-
 /**
  * Merge MCP server usages from agent (base) and session (overlay).
  *

package/src/shared/placeholder-resolver.ts

@@ -1,8 +1,10 @@
 /**
  * Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
  *
+ * Port of the Python agent-runner's PlaceholderResolver (strict mode only).
  * Always raises on unresolved placeholders — sending literal ${VAR} as an
- * HTTP header value produces cryptic auth failures from the remote server.
+ * HTTP header value (e.g. Authorization: Bearer ${API_KEY}) produces
+ * cryptic auth failures from the remote server.
  */
 
 const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
@@ -41,6 +43,9 @@ export function resolvePlaceholders(
 
 /**
  * Resolve placeholders in all values of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
  */
 export function resolveHeaders(
   headers: Record<string, string>,
@@ -55,7 +60,9 @@ export function resolveHeaders(
 
 /**
  * Filter env vars to only keys declared in the MCP server's spec.env.
- * Prevents secret over-sharing by restricting the environment to
+ *
+ * Mirrors the agent-runner's _filter_env_to_declared_keys: prevents
+ * secret over-sharing by restricting the subprocess/HTTP environment to
  * explicitly declared variables.
  */
 export function filterEnvToDeclaredKeys(

package/src/shared/plan-mode-permissions.ts

@@ -2,26 +2,25 @@
  * The Plan-mode filesystem permission rules — the enforcement twin of
  * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
  *
- * Plan mode is contained BY CONSTRUCTION on the native harness: these rules
- * deny every filesystem write everywhere AND scope reads to the session
- * workspace (issue #528 — owner ruling: the workspace is plan mode's read
- * boundary on cloud and desktop runners alike). Without the read boundary,
- * model-provided absolute paths reached anywhere the process account could
- * read — the pod filesystem (including /proc/self/environ) on cloud runners,
- * the user's whole home directory on desktop — while plan mode still carries
- * exfiltration-capable tools (web_fetch, MCP). Rules are first-match-wins
- * with a permissive default (deepagents' decidePathAccess), so order is
- * load-bearing: the workspace read-allow must precede the read-deny.
+ * Plan mode's policy is: reads anywhere in the workspace, writes nowhere.
+ * Only the write half needs a RULE. The read boundary that issue #528 built
+ * out of rules (workspace read-allow + read-deny, glob-escaped real root) is
+ * now STRUCTURAL: every native-harness backend is virtual-rooted
+ * (`virtualMode: true` — see cas-capture-backend.ts, issue #754), so every
+ * path a tool can express resolves inside the workspace root and traversal
+ * is rejected at resolution. A rule cannot widen that, and no workspace-root
+ * glob is needed to narrow it — which also retires the whole
+ * special-characters-in-the-root hazard (`escapeGlobLiteral` and its
+ * end-to-end matcher suite) that the real-path rules carried.
  *
- * The workspace-root pattern is matched as a STRING against the raw tool-call
- * path (micromatch, dot:true), before the backend touches disk. That is
- * exactly why the legitimate out-of-workspace reads keep working: skills,
- * attachments, and the approved plan live in the platform dir but are
- * addressed through the `{workspace}/.stigmer` symlink (see
- * shared/workspace/stigmer-link.ts), so their path strings are in-root even
- * though the bytes are not. The same holds for multi-workspace local entries
- * (`{workspace}/{name}` symlinks). A realpath-based boundary would break
- * both; do not "harden" this into one.
+ * Paths in these rules are VIRTUAL: "/" is the workspace root, matched by
+ * micromatch against the raw tool-call path (dot:true) after the
+ * path-normalization middleware has canonicalized it (relative → "/"-rooted;
+ * see middleware/path-normalization.ts). The legitimate platform-dir reads
+ * (skills, attachments, the approved plan) keep working exactly as before:
+ * they are addressed through the `{workspace}/.stigmer` symlink
+ * (shared/workspace/stigmer-link.ts), an in-root path string in either
+ * dialect.
  *
  * Applied in execute-deep-agent/setup.ts to the parent graph AND threaded
  * into every compiled sub-agent graph: deepagents' parent-permission
@@ -30,13 +29,6 @@
  * (issue #255). Kept as its own side-effect-free module so tests can pin the
  * production rules without dragging in setup.ts's import graph.
  *
- * Rules travel with a companion: every graph that carries them also installs
- * the path-normalization middleware (middleware/path-normalization.ts,
- * issues #429/#528), because deepagents' rule validation refuses
- * workspace-relative paths outright and its `ls`/`glob`/`grep` schema default
- * of "/" would deny the bare first listing. Both are derived from the same
- * expression at each composition site so they cannot drift apart.
- *
  * Invariant: never combine these rules with a shell-capable (sandbox)
  * backend — deepagents rejects that pairing at graph construction (see the
  * cas-capture-backend.ts header). Plan mode guarantees it by construction:
@@ -44,41 +36,18 @@
  * for shell capability on both the parent and sub-agent backends.
  */
 
-import { resolve } from "node:path";
 import type { FilesystemPermission } from "deepagents";
 
 /**
- * Backslash-escape every character micromatch/picomatch treats as glob
- * syntax, so the result matches the input literally. micromatch exports no
- * escape API of its own, and this is correctness, not caution: an unescaped
- * `(` in a desktop project path would make the workspace read-allow rule
- * silently never match — bricking every plan-mode read for that workspace.
- * Semantics are pinned end-to-end through deepagents' own matcher by the
- * special-character workspace suite in plan-mode-path-normalization.test.ts.
- */
-export function escapeGlobLiteral(literal: string): string {
-  return literal.replace(/[\\*?()[\]{}!+@]/g, "\\$&");
-}
-
-/**
- * Build the plan-mode rule set for a graph whose filesystem backend is
- * rooted at `workspaceRootDir`. The three rules read as the policy:
- * reads allowed in the workspace, reads denied everywhere else, writes
- * denied everywhere.
+ * Build the plan-mode rule set. One rule IS the policy: writes denied
+ * everywhere ("/**" is every virtual path; deepagents evaluates
+ * first-match-wins with a permissive default, so reads stay allowed —
+ * workspace-confined structurally, not by rule).
  *
- * `{root}/**` matches the root itself as well as its subtree (verified
- * against the installed micromatch), so one allow pattern suffices. The
- * root is `path.resolve`d first because enforcement canonicalizes incoming
- * paths (collapsed slashes, no trailing separator) before matching — a
- * trailing slash in the pattern would silently match nothing.
+ * Deliberately parameterless: the pre-#754 signature took the workspace root
+ * to build a real-path read fence; resurrecting a root-derived rule would
+ * silently mismatch the virtual dialect the enforcement now sees.
  */
-export function buildPlanModePermissions(
-  workspaceRootDir: string,
-): FilesystemPermission[] {
-  const canonicalRoot = resolve(workspaceRootDir);
-  return [
-    { operations: ["read"], paths: [`${escapeGlobLiteral(canonicalRoot)}/**`] },
-    { operations: ["read"], paths: ["/**"], mode: "deny" },
-    { operations: ["write"], paths: ["/**"], mode: "deny" },
-  ];
+export function buildPlanModePermissions(): FilesystemPermission[] {
+  return [{ operations: ["write"], paths: ["/**"], mode: "deny" }];
 }

package/src/shared/skill-mount.ts

@@ -0,0 +1,179 @@
+/**
+ * Skill mount mechanics — the ONE cache shape shared by both harnesses.
+ *
+ * A skill "mount" is the on-disk materialization of a skill inside the
+ * session's platform directory: `{platformDir}/skills/{name}/` holding
+ * SKILL.md plus the artifact's supporting files. Both harnesses write to
+ * that same physical location — the Cursor harness directly, the native
+ * (deep-agent) harness through the `.stigmer/` virtual namespace that
+ * LocalWorkspaceBackend routes there — so they MUST share one cache shape
+ * (issues #337/#672). This module owns that shape:
+ *
+ * - The mount is cached by the skill's content-addressed
+ *   `status.version_hash`: metadata is still fetched every execution
+ *   (that keeps latest-version freshness — push a skill update and the
+ *   very next message picks it up), but the artifact download and file
+ *   rewrite are skipped when the mounted content's hash already matches.
+ * - Remounts rebuild the directory from scratch, so files deleted between
+ *   skill versions never linger in the mount.
+ * - Crash-safe by ordering: the marker is stamped LAST, after every file
+ *   of the mount landed — a crash mid-write leaves no marker, so the next
+ *   execution remounts instead of trusting a partial tree.
+ *
+ * Extracted from execute-cursor/skill-resolver.ts (PR #682) when the
+ * deep-agent path adopted the same cache (issue #337). Orchestration —
+ * which skills to mount, prompt metadata, degradation logging — stays
+ * with each harness; only the per-skill-directory mechanics live here.
+ */
+
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { join, dirname, extname, resolve } from "node:path";
+import { ConnectError, Code } from "@connectrpc/connect";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { extractZipFileEntries } from "./zip-extract.js";
+
+/** Subdirectory of the platform dir where skill mounts live. */
+export const SKILLS_SUBDIR = "skills";
+
+/**
+ * Marker recording what a skill's mount directory currently holds. Written
+ * LAST, after every file of the mount landed — a crash mid-write leaves no
+ * marker, so the next execution remounts instead of trusting a partial tree.
+ */
+export const MOUNT_MARKER_FILE = ".stigmer-mount.json";
+
+export interface MountMarker {
+  /** Content-addressed version hash (`Skill.status.version_hash`) of the mounted content. */
+  versionHash: string;
+  /**
+   * Whether the artifact's files are part of the mount. `false` when the
+   * skill has no artifact OR when the download failed and the mount fell
+   * back to SKILL.md only — the latter makes the next execution retry the
+   * download rather than cache the degraded mount.
+   */
+  artifactMounted: boolean;
+}
+
+/**
+ * File extensions written with the executable bit set. The ZIP layer is
+ * deliberately mode-blind (path + bytes only, see zip-extract.ts), so
+ * extension is the only signal available for `./script.sh`-style
+ * invocation to work out of the mount.
+ */
+const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+
+/**
+ * Whether the mount at `skillDir` already holds this version's content.
+ *
+ * Fresh means: the marker's hash matches AND the mount isn't a degraded
+ * SKILL.md-only fallback when the skill does carry an artifact. Any read or
+ * parse failure counts as stale — the remount is the safe default.
+ */
+export async function mountIsFresh(
+  skillDir: string,
+  versionHash: string,
+  wantsArtifact: boolean,
+): Promise<boolean> {
+  try {
+    const raw = await readFile(join(skillDir, MOUNT_MARKER_FILE), "utf-8");
+    const marker = JSON.parse(raw) as Partial<MountMarker>;
+    return marker.versionHash === versionHash && (marker.artifactMounted === true || !wantsArtifact);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Download a skill artifact's ZIP bytes, transfer lane first (#675).
+ *
+ * The URL lane (getArtifactDownloadUrl → HTTP GET) carries any valid skill
+ * size; the unary getArtifact response is capped by the server's 10MB gRPC
+ * message limit. Servers that predate the lane (and cloud until its sibling
+ * lands) answer the mint with UNIMPLEMENTED — those fall back to the unary
+ * path, which behaves exactly as before for ≤10MB artifacts.
+ *
+ * Runs only on a mount-cache miss (the hash-keyed marker above) — a hit
+ * skips the transfer entirely, whichever lane would have carried it.
+ */
+export async function downloadArtifact(
+  client: StigmerClient,
+  artifactStorageKey: string,
+): Promise<Uint8Array | undefined> {
+  let minted;
+  try {
+    minted = await client.getSkillArtifactDownloadUrl(artifactStorageKey);
+  } catch (err) {
+    if (err instanceof ConnectError && err.code === Code.Unimplemented) {
+      const resp = await client.getSkillArtifact(artifactStorageKey);
+      return resp.artifact && resp.artifact.length > 0 ? resp.artifact : undefined;
+    }
+    throw err;
+  }
+
+  const resp = await fetch(minted.url);
+  if (!resp.ok) {
+    throw new Error(`artifact fetch failed: HTTP ${resp.status} from ${minted.url}`);
+  }
+  const bytes = new Uint8Array(await resp.arrayBuffer());
+  if (minted.sizeBytes > 0n && BigInt(bytes.length) !== minted.sizeBytes) {
+    throw new Error(
+      `artifact fetch truncated: got ${bytes.length} bytes, expected ${minted.sizeBytes}`,
+    );
+  }
+  return bytes.length > 0 ? bytes : undefined;
+}
+
+/**
+ * (Re)write a skill's mount directory from scratch.
+ *
+ * The directory is removed first so files deleted between versions don't
+ * linger in the mount, then SKILL.md and the artifact files are written, and
+ * the marker is stamped LAST (see MOUNT_MARKER_FILE for the crash-safety
+ * contract). SKILL.md always comes from `spec.skillMd` — the server's
+ * authoritative copy, which the push pipeline guarantees is non-empty
+ * (push.go hard-fails a ZIP without an extractable SKILL.md) — never from
+ * the zip; both the zip's SKILL.md and any stray marker-named entry are
+ * excluded from extraction so the mount's ownership of those two files is
+ * unconditional.
+ *
+ * Every extracted entry must resolve inside `skillDir`. The server already
+ * rejects traversal at push (google/safearchive), but this runner-side
+ * check is kept as defense-in-depth: it is the guard the deep-agent path
+ * used to get from LocalWorkspaceBackend's platform-path routing, preserved
+ * here when skill writes moved to direct fs.
+ */
+export async function writeSkillMount(
+  skill: Skill,
+  skillDir: string,
+  artifactBytes: Uint8Array | undefined,
+): Promise<void> {
+  await rm(skillDir, { recursive: true, force: true });
+  await mkdir(skillDir, { recursive: true });
+
+  await writeFile(join(skillDir, "SKILL.md"), skill.spec!.skillMd, "utf-8");
+
+  const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
+  if (artifactMounted) {
+    const normalizedSkillDir = resolve(skillDir);
+    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
+    for (const entry of entries) {
+      const filePath = resolve(normalizedSkillDir, entry.path);
+      if (filePath !== normalizedSkillDir && !filePath.startsWith(normalizedSkillDir + "/")) {
+        throw new Error(
+          `skill artifact entry escapes its mount directory: '${entry.path}'`,
+        );
+      }
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, entry.content, {
+        mode: SCRIPT_EXTENSIONS.has(extname(entry.path)) ? 0o755 : 0o644,
+      });
+    }
+  }
+
+  const versionHash = skill.status?.versionHash ?? "";
+  if (versionHash !== "") {
+    const marker: MountMarker = { versionHash, artifactMounted };
+    await writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker), "utf-8");
+  }
+}