@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/shared/skill-mount.ts

@@ -0,0 +1,214 @@
+/**
+ * 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.
+ * The archive's transport, the rebuild and the file modes are the shared
+ * archive mount's (`archive-mount.ts`), one copy for skills and plugins.
+ *
+ * Also the one statement of where a skill's files live under the platform
+ * dir ({@link SKILL_CONTENT_PATTERN}), which both harnesses' confined reads
+ * consult when a turn's tool lists deny `Skill`, each by the real path the
+ * read would open ({@link skillContentReadCheck}, the Cursor hook's
+ * `realpathSync`).
+ */
+
+import { agentFs } from "./agent-fs.js";
+import { join, posix, relative, sep } from "node:path";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { Skill } from "@stigmer/apis/ai/stigmer/agentic/skill/v1/api_pb";
+import { extractZipFileEntries } from "./zip-extract.js";
+import { downloadArchive, resetDirectory, writeArchiveEntries } from "./archive-mount.js";
+import { holdsPluginManifest, manifestEvalDir, withoutEvalSuite } from "./plugin-mount.js";
+import { STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
+
+/** Subdirectory of the platform dir where skill mounts live. */
+export const SKILLS_SUBDIR = "skills";
+
+/**
+ * A skill's files, as a path relative to the platform dir in posix form: a
+ * mounted skill (`skills/<name>/…`), or anything under `plugins/`, a
+ * mounted plugin's tree and its cached archive (`plugin-mount.ts`). The
+ * whole tree counts because a manifest may declare its skills anywhere in
+ * the package and a root skill is the package itself; the tree is there
+ * for the plugin's hooks, which run it as processes, never for the agent
+ * to read. A turn whose tool lists deny `Skill` is refused a read of any of
+ * them, on both engines; the Cursor hook embeds this pattern's source and
+ * flags. Matched without regard to case: on a case-insensitive filesystem
+ * `Skills/a/SKILL.md` is the same file, and on any other the platform dir
+ * holds no such name to over-refuse.
+ */
+export const SKILL_CONTENT_PATTERN = /^(?:skills|plugins)(?:\/|$)/i;
+
+/** The native engine's virtual prefix for the platform dir. */
+const PLATFORM_PREFIX = `/${STIGMER_LOCAL_STATE_DIR}/`;
+
+/** Whether a canonical virtual path (`/.stigmer/…`, the native engine's) names a skill's files. */
+export function isSkillContentPath(virtualPath: string): boolean {
+  const normalized = posix.normalize(virtualPath);
+  return normalized.toLowerCase().startsWith(PLATFORM_PREFIX) && SKILL_CONTENT_PATTERN.test(normalized.slice(PLATFORM_PREFIX.length));
+}
+
+/**
+ * Whether a native `read_file` of this canonical virtual path would open a
+ * skill's files: by its text ({@link isSkillContentPath}), or, for a path
+ * under `.stigmer/`, by the real path it resolves to inside the platform
+ * dir. The native route follows a link that stays inside the platform dir
+ * (`execute-deep-agent/platform-route.ts`), so a link a plugin's hook leaves
+ * under `plugin-data/` pointing into `skills/` reads the skill unless its
+ * real path is judged; the Cursor hook judges every read the same way.
+ * Compared without regard to case, as the pattern is. A path that does not
+ * resolve (nothing there, a dangling link) opens nothing and is not
+ * refused here. Costs two `realpath` calls, and only on a turn that denies
+ * `Skill`. Without a platform dir there is nothing to resolve against.
+ */
+export function skillContentReadCheck(platformDir: string | undefined): (virtualPath: string) => Promise<boolean> {
+  return async (virtualPath) => {
+    if (isSkillContentPath(virtualPath)) return true;
+    const normalized = posix.normalize(virtualPath);
+    if (platformDir === undefined || !normalized.toLowerCase().startsWith(PLATFORM_PREFIX)) return false;
+    try {
+      const [root, target] = await Promise.all([agentFs().realpath(platformDir), agentFs().realpath(join(platformDir, normalized.slice(PLATFORM_PREFIX.length)))]);
+      const inside = relative(root.toLowerCase(), target.toLowerCase()).split(sep).join("/");
+      return !inside.startsWith("../") && inside !== ".." && SKILL_CONTENT_PATTERN.test(inside);
+    } catch {
+      return false;
+    }
+  };
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 agentFs().readFile(join(skillDir, MOUNT_MARKER_FILE))).toString("utf8");
+    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 over the shared archive transport
+ * (`archive-mount.ts` `downloadArchive`: the URL lane first, the unary RPC
+ * against a server that predates it).
+ *
+ * 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> {
+  return downloadArchive(
+    {
+      mintDownloadUrl: (key) => client.getSkillArtifactDownloadUrl(key),
+      fetchUnary: (key) => client.getSkillArtifact(key),
+    },
+    artifactStorageKey,
+  );
+}
+
+/**
+ * (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 archive
+ * mount's escape check): the server already rejects traversal at push, and
+ * this is the runner's defence in depth.
+ *
+ * A plugin's root skill mounts nothing under the archive's `evals/`, or
+ * under the directory the archive's own manifest moves the suite to
+ * (`experimental.evals`), matched by its cleaned, root-relative name as the
+ * plugin mount matches it (`plugin-mount.ts` `withoutEvalSuite`,
+ * `manifestEvalDir`). Its archive is the whole plugin, one stored before
+ * the install left the suite out still carries it, and an agent under test
+ * must not read the cases it is graded on. A root skill's archive is told
+ * by the plugin manifest it always holds (`holdsPluginManifest`). Any other
+ * skill keeps its own `evals/`: a skill pushed on its own may keep its
+ * tests there (skill-creator's `evals/evals.json`), and a plugin's other
+ * skills never hold the plugin's suite, since the install refuses a suite
+ * directory that overlaps a skill and leaves each skill's own `evals/` out
+ * of its archive.
+ */
+export async function writeSkillMount(
+  skill: Skill,
+  skillDir: string,
+  artifactBytes: Uint8Array | undefined,
+): Promise<void> {
+  await resetDirectory(skillDir);
+
+  await agentFs().writeFile(join(skillDir, "SKILL.md"), skill.spec!.skillMd);
+
+  const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
+  if (artifactMounted) {
+    const extracted = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
+    const entries = holdsPluginManifest(extracted) ? withoutEvalSuite(extracted, manifestEvalDir(extracted)) : extracted;
+    await writeArchiveEntries(skillDir, entries, "skill artifact");
+  }
+
+  const versionHash = skill.status?.versionHash ?? "";
+  if (versionHash !== "") {
+    const marker: MountMarker = { versionHash, artifactMounted };
+    await agentFs().writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker));
+  }
+}

package/src/shared/skill-resolver.ts

@@ -0,0 +1,167 @@
+/**
+ * Resolves skill resources and writes them to the platform-managed directory.
+ *
+ * - Fetches skills via gRPC (by reference)
+ * - Mounts each skill via the shared skill-mount mechanics (SKILL.md +
+ *   extracted artifact, hash-keyed cache — see shared/skill-mount.ts)
+ * - Uses a platform-managed directory outside the workspace
+ * - Ensures the workspace `.stigmer` symlink (see workspace/stigmer-link.ts)
+ * - Returns metadata for prompt injection, each beside a reference to the
+ *   exact version mounted (the run's record of what it loaded)
+ *
+ * A turn-runtime phase (`harness/turn-context.ts` `mountSkills`): it reads
+ * the control plane, which only the runtime holds, and writes under the
+ * platform dir the runtime owns; the harness renders the returned metadata
+ * into its prompt in its own placement. Moved from
+ * `activities/execute-cursor/` in #1070; the native harness's twin
+ * (`skill-writer.ts` `fetchSkillsByRefs` + `mountSkills`) retired in #1096,
+ * and the module itself with it. This is the one skills path for every
+ * harness.
+ *
+ * The mount is cached by the skill's content-addressed version hash
+ * (stigmer/stigmer#672): metadata is fetched on every execution (that keeps
+ * latest-version freshness), but the artifact download and file rewrite are
+ * skipped when the mounted content's hash already matches. The session's
+ * platform dir survives across executions, so on an active session every
+ * message after the first pays a metadata read instead of a full artifact
+ * transfer.
+ */
+
+import { agentFs } from "./agent-fs.js";
+import { join } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { ApiResourceKind } from "@stigmer/apis/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceReference } from "@stigmer/apis/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/apis/ai/stigmer/commons/apiresource/io_pb";
+import { getPlatformDir } from "./workspace/platform-dir.js";
+import {
+  SKILLS_SUBDIR,
+  mountIsFresh,
+  downloadArtifact,
+  writeSkillMount,
+} from "./skill-mount.js";
+import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
+
+/** One mounted skill as a prompt renders it: its name, its description, and the workspace-relative path of its SKILL.md. */
+export interface SkillMetadata {
+  name: string;
+  description: string;
+  path: string;
+}
+
+/**
+ * One mounted skill: what the prompt renders, and the skill by id at the
+ * version hash mounted (empty for a skill whose last version failed to
+ * archive). A skill that did not mount yields neither.
+ */
+export interface ResolvedSkill {
+  readonly metadata: SkillMetadata;
+  readonly loaded: ApiResourceReference;
+}
+
+export interface SkillResolverOptions {
+  sessionId: string;
+  primaryWorkspaceDir: string;
+}
+
+/**
+ * Resolve skill references into written SKILL.md files and prompt metadata.
+ *
+ * Platform mount pattern: skills are written to
+ * ~/.stigmer/sessions/{sessionId}/platform/skills/{name}/SKILL.md
+ * with a symlink from {workspace}/.stigmer -> the platform dir.
+ */
+export async function resolveSkills(
+  client: StigmerClient,
+  skillRefs: ApiResourceReference[],
+  options: SkillResolverOptions,
+): Promise<ResolvedSkill[]> {
+  console.log(
+    `[resolveSkills] sessionId=${options.sessionId}, ` +
+    `primaryWorkspaceDir=${options.primaryWorkspaceDir ?? "(undefined)"}, ` +
+    `skillRefCount=${skillRefs.length}, ` +
+    `refs=[${skillRefs.map(r => `${r.org || "(default)"}/${r.slug}`).join(", ")}]`,
+  );
+
+  if (skillRefs.length === 0) return [];
+
+  const platformDir = getPlatformDir(options.sessionId);
+  const skillsDir = join(platformDir, SKILLS_SUBDIR);
+  await agentFs().mkdir(skillsDir, { recursive: true });
+
+  await ensureStigmerSymlink(options.primaryWorkspaceDir, platformDir);
+  console.log(
+    `[resolveSkills] symlink created: ${join(options.primaryWorkspaceDir, STIGMER_LOCAL_STATE_DIR)} -> ${platformDir}`,
+  );
+
+  const results: ResolvedSkill[] = [];
+
+  for (const ref of skillRefs) {
+    try {
+      const skill = await client.getSkillByReference(ref);
+      const spec = skill.spec;
+      if (!spec?.skillMd) {
+        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
+        continue;
+      }
+
+      const name = spec.name || skill.metadata?.slug || "unknown";
+      const skillDir = join(skillsDir, name);
+      const versionHash = skill.status?.versionHash ?? "";
+      const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
+      const meta: SkillMetadata = {
+        name,
+        description: spec.description || `Skill: ${name}`,
+        path: join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md"),
+      };
+      const resolved: ResolvedSkill = {
+        metadata: meta,
+        loaded: create(ApiResourceReferenceSchema, {
+          org: skill.metadata?.org ?? "",
+          kind: ApiResourceKind.skill,
+          id: skill.metadata?.id ?? "",
+          version: versionHash,
+        }),
+      };
+
+      if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
+        results.push(resolved);
+        console.log(
+          `[resolveSkills] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`,
+        );
+        continue;
+      }
+
+      let artifactBytes: Uint8Array | undefined;
+      if (wantsArtifact) {
+        try {
+          artifactBytes = await downloadArtifact(client, skill.status!.artifactStorageKey);
+        } catch (err) {
+          // Deliberate degradation, but LOUD (#675): the session still gets
+          // SKILL.md (better than a dead run), yet a skill silently missing
+          // its scripts/references was exactly how oversized artifacts hid.
+          console.error(
+            `[resolveSkills] artifact download FAILED for ${ref.org || "(default)"}/${ref.slug} ` +
+            `(key=${skill.status!.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
+            `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`,
+          );
+        }
+      }
+
+      await writeSkillMount(skill, skillDir, artifactBytes);
+      results.push(resolved);
+      console.log(`[resolveSkills] wrote skill: ${name} -> ${meta.path}`);
+    } catch (err) {
+      console.warn(
+        `[resolveSkills] failed to resolve skill ${ref.org}/${ref.slug}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+
+  console.log(
+    `[resolveSkills] completed: ${results.length}/${skillRefs.length} skills resolved`,
+  );
+
+  return results;
+}

package/src/shared/stall-watchdog.ts

@@ -0,0 +1,122 @@
+/**
+ * Progress-based stall watchdog.
+ *
+ * Long-running agent turns are kept alive against Temporal by a periodic
+ * keep-alive heartbeat (see {@link ./heartbeat.ts}). That heartbeat proves the
+ * runner *process* is alive, but it says nothing about whether the agent is
+ * making *progress*: a turn that wedges inside the harness stream loop (a tool
+ * call that never returns, a model connection that silently dies) keeps
+ * heartbeating forever and never times out. The execution then sits at
+ * RUN_IN_PROGRESS indefinitely.
+ *
+ * This watchdog closes that gap. It is an *out-of-band* timer: callers report
+ * progress via {@link StallWatchdog.recordActivity} on every stream event AND
+ * every token delta, and the watchdog fires `onStall` once if no progress is
+ * reported for `stallMs`. "Out-of-band" is the deliberate correctness property
+ * — the check runs on its own timer rather than inside the consumer's loop, so
+ * it catches a true "no new events for N minutes" hang. An in-band check that
+ * only runs when the loop advances cannot fire while the loop is blocked
+ * awaiting the next event, which is exactly the wedge we need to detect.
+ *
+ * This module is the convergence target for stall detection across harnesses:
+ * the Cursor harness wires it here, and the native deep-agent harness has its
+ * own (harness-local, in-band) check that should later converge onto this one.
+ */
+
+/**
+ * Canonical default stall window. Harnesses may override with a larger value
+ * when their tool calls routinely run longer without emitting stream activity.
+ */
+export const DEFAULT_STALL_TIMEOUT_MS = 120_000;
+
+/**
+ * Thrown / reported when an agent stream makes no progress for longer than the
+ * configured stall window. Carries the observed idle duration so callers can
+ * build an actionable, recognizable error message.
+ */
+export class StallTimeoutError extends Error {
+  constructor(
+    public readonly stalledMs: number,
+    detail?: string,
+  ) {
+    super(
+      `Agent stream stalled: no activity for ${Math.round(stalledMs / 1000)}s` +
+        (detail ? ` (${detail})` : ""),
+    );
+    this.name = "StallTimeoutError";
+  }
+}
+
+/**
+ * Recognizable prefix on every stall-induced failure message. Single source of
+ * truth so callers (and any future UI/log keying) match on one constant.
+ */
+export const STALL_ERROR_PREFIX = "[StallTimeoutError]";
+
+/**
+ * Build the user-facing failure text for a stall. Keeps the canonical wording
+ * (prefix + actionable "Retry or resume.") next to the error it describes.
+ */
+export function formatStallFailure(error: StallTimeoutError): string {
+  return `${STALL_ERROR_PREFIX} ${error.message}. Retry or resume.`;
+}
+
+export interface StallWatchdog {
+  /** Reset the idle timer. Call on every stream event AND every token delta. */
+  recordActivity(): void;
+  /** Disarm the watchdog. Idempotent; safe to call in a `finally`. */
+  stop(): void;
+}
+
+/**
+ * Start an out-of-band stall watchdog.
+ *
+ * @param stallMs  Idle window after which `onStall` fires.
+ * @param onStall  Invoked at most once with the observed idle duration (ms)
+ *                 when `Date.now() - lastActivityAt` exceeds `stallMs`. The
+ *                 watchdog disarms itself before invoking, so `onStall` runs
+ *                 exactly once even if its handler is slow.
+ *
+ * The poll interval is `stallMs / 4` capped at 15s: frequent enough to detect a
+ * stall promptly without busy-looping, and bounded so a large `stallMs` still
+ * polls on a sane cadence.
+ */
+export function startStallWatchdog(
+  stallMs: number,
+  onStall: (idleMs: number) => void,
+): StallWatchdog {
+  let lastActivityAt = Date.now();
+  let fired = false;
+  let timer: ReturnType<typeof setInterval> | undefined;
+
+  const tickMs = Math.min(Math.max(Math.floor(stallMs / 4), 1), 15_000);
+
+  const disarm = (): void => {
+    if (timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  };
+
+  timer = setInterval(() => {
+    if (fired) return;
+    const idleMs = Date.now() - lastActivityAt;
+    if (idleMs >= stallMs) {
+      fired = true;
+      disarm();
+      onStall(idleMs);
+    }
+  }, tickMs);
+  // Do not keep the event loop alive solely for the watchdog.
+  timer.unref?.();
+
+  return {
+    recordActivity(): void {
+      lastActivityAt = Date.now();
+    },
+    stop(): void {
+      fired = true;
+      disarm();
+    },
+  };
+}