@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/shared/plan-artifact.ts

@@ -0,0 +1,255 @@
+/**
+ * Plan-mode artifact publishing.
+ *
+ * When an execution runs in Plan mode (InteractionMode.PLAN), the agent's final
+ * message IS the plan. We publish that text as a first-class plan markdown
+ * RunArtifact so the UI can render a reviewable Plan card with
+ * copy/download, and a follow-up "Implement" execution can reference it
+ * deterministically.
+ *
+ * The artifact is named from the plan's own title — a hyphenated slug of its
+ * leading `# H1`, a `_<hash>` discriminator, and a `.plan.md` suffix (e.g.
+ * `plan-card-ux-cleanup_a1b2c3d4.plan.md`), so a downloaded plan lands as a
+ * recognizable file and the card, plan tab, and saved file all agree on one
+ * name. A plan with no derivable title falls back to a bare `<hash>.plan.md`.
+ *
+ * The `_<hash>` discriminator (first 8 hex of the plan content's SHA-256) is
+ * NOT for storage uniqueness — storage keys are already execution-scoped
+ * (`artifacts/{execId}/<name>`). It exists because the artifact BASENAME is a
+ * user-facing shared namespace: downloads save under it (see the artifact
+ * download disposition) and the artifact list surfaces it, so two same-titled
+ * plans would otherwise collide in the user's Downloads folder and read
+ * identically in the list. Deriving it from content (not a random or
+ * execution-scoped value) keeps naming honestly idempotent — identical content
+ * yields an identical name, so a finalize retry re-uploads to the same key,
+ * while any real edit yields a distinct one. A plain no-uniqueness-hash rule
+ * would be correct about storage but would overlook the download/list
+ * basename namespace.
+ *
+ * This is deliberately a single, harness-agnostic helper:
+ * - The native (deepagents) harness already auto-publishes files an agent
+ *   writes (InlinePublisher), but Plan mode is read-only, so there is no file to
+ *   publish — the plan lives only in the final message.
+ * - The Cursor harness has no artifact pipeline at all.
+ *
+ * Publishing the final message here, at finalization, gives both harnesses an
+ * identical, durable plan artifact derived from the single source of truth (the
+ * final AI message). It mirrors the InlinePublisher "publish a derived artifact"
+ * pattern: one immutable artifact, published once, never a parallel copy that
+ * can drift.
+ *
+ * The plan content is NOT duplicated as a separate stored blob beyond this
+ * artifact — the chat message remains the live/streamed view; the artifact is
+ * the durable/exportable view, detected by convention (a FILE artifact whose
+ * name satisfies {@link isPlanArtifactName}).
+ */
+
+import { createHash } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import type { RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { RunArtifactSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/artifact_pb";
+import {
+  RunArtifactKind,
+} from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import type { ArtifactStorage } from "./artifact-storage.js";
+import { utcTimestamp } from "./status.js";
+import { MessageType } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+import type { TurnRows } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+
+/**
+ * Legacy plan filename. Detection-only: {@link isPlanArtifactName} still
+ * accepts this exact name so plans published before named artifacts existed
+ * keep working. It is NEVER freshly emitted — a titleless plan now falls back
+ * to a bare `<hash>.plan.md` (see {@link planArtifactName}).
+ */
+export const PLAN_ARTIFACT_NAME = "plan.md";
+
+/**
+ * Suffix every named plan artifact carries. The UI keys plan detection on this
+ * suffix, so it must stay in sync with the SDK's `PLAN_ARTIFACT_SUFFIX`
+ * (`sdk/react/src/library/detect-plan-artifact.ts`). The two cannot share a
+ * module — the runner and the browser SDK have disjoint module graphs — so the
+ * constant is duplicated by design, mirroring {@link PLAN_ARTIFACT_NAME}.
+ */
+export const PLAN_ARTIFACT_SUFFIX = ".plan.md";
+
+/** Longest slug we derive from a plan title before the `_<id>.plan.md` tail. */
+const MAX_PLAN_SLUG_LENGTH = 60;
+
+/** Hex length of the content-hash discriminator appended to named plans. */
+const PLAN_ID_LENGTH = 8;
+
+/**
+ * Reports whether an artifact filename is a plan: the legacy exact name, or any
+ * `*.plan.md`. Kept in sync with the SDK's `isPlanArtifactName`.
+ */
+export function isPlanArtifactName(name: string): boolean {
+  return name === PLAN_ARTIFACT_NAME || name.endsWith(PLAN_ARTIFACT_SUFFIX);
+}
+
+// Plan-title extraction, mirrored from the SDK so the runner's derived filename
+// and the card's displayed title agree on one title from one source (the plan's
+// leading `# H1`). These three patterns are a verbatim copy of
+// `sdk/react/src/internal/markdown-components.tsx`
+// (`ENCLOSING_MARKDOWN_FENCE_RE`, `ENCLOSING_BARE_FENCE_RE`, `LEADING_H1_RE`)
+// and MUST stay in sync with it — a fence-wrapped plan whose title the card
+// unwraps must slug to that same title here, never to the fallback.
+const ENCLOSING_MARKDOWN_FENCE_RE =
+  /^(`{3,})[ \t]*(?:markdown|md)[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/i;
+const ENCLOSING_BARE_FENCE_RE = /^(`{3,})[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/;
+const LEADING_H1_RE = /^#[ \t]+(.+?)[ \t]*(?:\r?\n+|$)/;
+
+/**
+ * The plan's title: the leading `# H1` of the plan text, after the same
+ * plan-scoped enclosing-fence unwrap (tagged ```markdown``` or a bare ``` `)
+ * the document renderers apply. `undefined` when the plan has no leading H1.
+ */
+function extractPlanTitle(planText: string): string | undefined {
+  const trimmed = planText.trim();
+  let body = trimmed;
+  const tagged = ENCLOSING_MARKDOWN_FENCE_RE.exec(trimmed);
+  if (tagged) {
+    body = tagged[2];
+  } else {
+    const bare = ENCLOSING_BARE_FENCE_RE.exec(trimmed);
+    if (bare) body = bare[2];
+  }
+  const h1 = LEADING_H1_RE.exec(body.trim());
+  return h1 ? h1[1] : undefined;
+}
+
+/**
+ * Strips a leading "Plan" LABEL from a title, e.g. `Plan: Create X` -> `Create
+ * X`. The separator (`:` or a dash) is REQUIRED: this removes a redundant label
+ * (a plan document already announces itself via the `.plan.md` suffix and the
+ * Plan card framing) without ever clipping a real title word — a bare `\bplan\b`
+ * would wrongly turn "Plan card UX cleanup" into "card UX cleanup".
+ *
+ * Deliberately runner/filename-only and NOT mirrored into the SDK's title
+ * extraction: display surfaces render the message's own `# H1` faithfully
+ * (`extractLeadingH1` is general-purpose and render-time-only), so the clean
+ * title is fixed at the source — the plan-mode prompt tells the model not to
+ * prefix titles with "Plan:". This strip is the durable-artifact safety net for
+ * when the model (or the enforcement-less Cursor harness) drifts.
+ */
+function stripPlanLabel(title: string): string {
+  return title.replace(/^plan\s*[:\u2013\u2014-]\s*/i, "");
+}
+
+/**
+ * Slugifies a plan title into a filename-safe stem: lowercase, every run of
+ * non-alphanumerics collapsed to `-`, trimmed of leading/trailing `-`, and
+ * capped at {@link MAX_PLAN_SLUG_LENGTH}. Returns `""` for a title with no
+ * alphanumerics (e.g. only punctuation), which selects the fallback name.
+ */
+function slugifyPlanTitle(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_PLAN_SLUG_LENGTH)
+    .replace(/-+$/g, "");
+}
+
+/**
+ * Derives the plan artifact's filename from its text: `<slug>_<id>.plan.md`
+ * when the plan opens with a titled `# H1`, else a bare `<id>.plan.md`. The
+ * `<id>` is the first {@link PLAN_ID_LENGTH} hex of the content's SHA-256 — a
+ * user-facing discriminator for the shared download/list basename namespace,
+ * not a storage-uniqueness device (see the module doc).
+ */
+export function planArtifactName(planText: string): string {
+  const id = createHash("sha256")
+    .update(planText, "utf-8")
+    .digest("hex")
+    .slice(0, PLAN_ID_LENGTH);
+  const title = extractPlanTitle(planText);
+  const slug = title ? slugifyPlanTitle(stripPlanLabel(title)) : "";
+  return slug.length > 0
+    ? `${slug}_${id}${PLAN_ARTIFACT_SUFFIX}`
+    : `${id}${PLAN_ARTIFACT_SUFFIX}`;
+}
+
+/**
+ * Sandbox path recorded on the artifact for a given filename. Routes under
+ * `.stigmer/` (the session platform dir), so it never pollutes the user's
+ * workspace, and a follow-up execution can reference it via workspace file
+ * refs if desired.
+ */
+export function planArtifactSandboxPath(name: string): string {
+  return `.stigmer/plans/${name}`;
+}
+
+/**
+ * Returns the text of the last AI message in a completed turn's rows.
+ * Returns `undefined` when there is no AI message with content — the plan was
+ * empty and nothing should be published.
+ */
+export function extractFinalPlanText(rows: Pick<TurnRows, "messages">): string | undefined {
+  for (let i = rows.messages.length - 1; i >= 0; i--) {
+    const msg = rows.messages[i];
+    if (msg.type === MessageType.MESSAGE_AI && msg.content.trim().length > 0) {
+      return msg.content;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Publishes `planText` as a plan RunArtifact (named from its title —
+ * see {@link planArtifactName}) and registers it on `status.artifacts`.
+ * Idempotent: re-publishing replaces any existing plan artifact — matched by
+ * {@link isPlanArtifactName}, not exact name, so a re-plan whose title changed
+ * still supersedes rather than appends — preserving a single source of truth.
+ *
+ * Fire-and-forget by contract: a plan that fails to upload must never fail the
+ * execution. Errors are logged and swallowed.
+ */
+export async function publishPlanArtifact(opts: {
+  readonly status: RunStatus;
+  readonly executionId: string;
+  readonly planText: string;
+  readonly artifactStorage: ArtifactStorage;
+}): Promise<void> {
+  const { status, executionId, planText, artifactStorage } = opts;
+
+  if (planText.trim().length === 0) {
+    return;
+  }
+
+  try {
+    const content = Buffer.from(planText, "utf-8");
+    const contentHash = createHash("sha256").update(content).digest("hex");
+    const name = planArtifactName(planText);
+    const storageKey = `artifacts/${executionId}/${name}`;
+
+    await artifactStorage.upload(storageKey, content, "text/markdown");
+
+    const artifact = create(RunArtifactSchema, {
+      name,
+      sandboxPath: planArtifactSandboxPath(name),
+      kind: RunArtifactKind.FILE,
+      sizeBytes: BigInt(content.length),
+      storageKey,
+      createdAt: utcTimestamp(),
+      contentHash,
+    });
+
+    const existingIdx = status.artifacts.findIndex((a) => isPlanArtifactName(a.name));
+    if (existingIdx >= 0) {
+      status.artifacts[existingIdx] = artifact;
+    } else {
+      status.artifacts.push(artifact);
+    }
+
+    console.log(
+      `[plan-artifact] execution=${executionId} — published ${name} ` +
+      `(${content.length} bytes, hash=${contentHash.slice(0, 12)})`,
+    );
+  } catch (err) {
+    console.warn(
+      `[plan-artifact] execution=${executionId} — ` +
+      `failed to publish plan (non-fatal): ${err}`,
+    );
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * The Plan-mode filesystem permission rules — the enforcement twin of
+ * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
+ *
+ * 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.
+ *
+ * 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/turn-setup.ts to the parent graph AND threaded
+ * into every compiled sub-agent graph: deepagents' parent-permission
+ * inheritance covers only spec-style sub-agents, and ours are pre-built
+ * CompiledSubAgents, so each sub-agent graph must carry the rules itself
+ * (issue #255). Kept as its own side-effect-free module so tests can pin the
+ * production rules without dragging in the engine build's import graph.
+ *
+ * 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:
+ * it is the mode that clears `shellEnv`, and `shellEnv` is the single switch
+ * for shell capability on both the parent and sub-agent backends.
+ */
+
+import type { FilesystemPermission } from "deepagents";
+
+/**
+ * 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).
+ *
+ * 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(): FilesystemPermission[] {
+  return [{ operations: ["write"], paths: ["/**"], mode: "deny" }];
+}

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

@@ -0,0 +1,74 @@
+/**
+ * The Plan-mode prompt directive, shared by both harnesses.
+ *
+ * Plan mode's output contract spans three components that must agree:
+ * - the model produces the plan as its FINAL message (this directive),
+ * - the runner publishes that final message verbatim as a plan markdown
+ *   artifact, named from the plan's title (`plan-artifact.ts` —
+ *   `extractFinalPlanText`, `planArtifactName`),
+ * - the SDK promotes the same message to a first-class plan document in the
+ *   thread and offers "Build from plan".
+ *
+ * This module is the single source of truth for how the model is told to
+ * behave, so the two harnesses can never drift apart on the contract. Each
+ * harness wraps the directive in its own prompt framing (the Cursor harness
+ * uses XML-tag sections, the native harness markdown headings) — the framing
+ * is house style; the words are shared.
+ *
+ * Enforcement is separate from instruction: the native harness ALSO denies
+ * filesystem writes at the tool layer (see execute-deep-agent/turn-setup.ts), so
+ * for it this directive is guidance toward a well-formed plan, not the
+ * enforcement mechanism. The Cursor harness has no tool-level lever (the
+ * Cursor SDK exposes no mode parameter), so there this directive is the
+ * enforcement — a documented stopgap.
+ */
+
+/**
+ * Directive body injected into the system prompt of every Plan-mode
+ * execution. Deliberately explicit about the deliverable's shape: the final
+ * message is published verbatim as a plan document (whose filename is derived
+ * from the leading `#` title), so a fenced or chat-suffixed plan degrades the
+ * reviewable document the user sees.
+ *
+ * Fence hygiene inside the document is part of the same contract. A plan
+ * frequently quotes file content that itself contains fenced code blocks
+ * ("insert this section into README.md"); with a same-length outer fence the
+ * inner block's closer terminates the outer fence early and corrupts the
+ * rendered document — on every client (the react SDK and the terminal
+ * renderer alike). And because the plan viewers render top-level ```mermaid
+ * fences as diagrams, the directive steers diagrams into the plan body proper
+ * rather than leaving them buried, unrendered, inside quoted file content.
+ */
+export const PLAN_MODE_DIRECTIVE = [
+  "IMPORTANT: You are in Plan mode — a read-only analysis turn whose " +
+    "deliverable is an implementation plan.",
+  "",
+  "Constraints:",
+  "- Do NOT create, edit, or delete any files.",
+  "- Do NOT run commands that modify the filesystem or any external state.",
+  "- Only read, search, and analyze.",
+  "",
+  "Deliverable — your FINAL message IS the plan. It is published verbatim " +
+    "as a plan document that the user reviews and builds from, so:",
+  "- Write it as a complete, well-structured markdown document: start with " +
+    "a single `#` title and organize the work under `##` section headings. " +
+    "Use lists and tables where they aid scanning.",
+  '- Give the `#` title a concise, descriptive name for the work itself; do ' +
+    'NOT prefix it with "Plan:" (this document is already a plan — the ' +
+    "prefix is redundant and leaks into the plan's filename).",
+  "- Reference concrete file paths and describe the specific changes " +
+    "planned for each.",
+  "- Do NOT wrap the document in a code fence.",
+  "- When quoting content that itself contains fenced code blocks (e.g. a " +
+    "proposed file section with a code sample inside), open the outer fence " +
+    "with MORE backticks than any inner fence (four or more) — a same-length " +
+    "inner closer would terminate the outer fence early and corrupt the " +
+    "rendered document.",
+  "- Fenced ```mermaid blocks at the top level of the document render as " +
+    "diagrams in the plan viewer. When a diagram helps communicate the " +
+    "design (architecture, flows), include it directly in the plan body — " +
+    "not only inside quoted file content, where it stays unrendered source.",
+  '- Do NOT end with conversational closers ("Let me know...", "Shall I ' +
+    'proceed?") — the next step is the user\'s Build action, and trailing ' +
+    "chat would be published as part of the document.",
+].join("\n");

package/src/shared/platform-server-address.ts

@@ -0,0 +1,124 @@
+/**
+ * The Stigmer server's address for user-defined MCP servers — the reserved
+ * STIGMER_SERVER_ADDRESS key, and the one dial-target rule every writer of
+ * that key shares (stigmer/stigmer#1433, #1446).
+ *
+ * The runner is the one component that supplies it, because the runner is
+ * the one that knows where the consumer runs:
+ *
+ *   - A remote HTTP server receives the key only through a templated header,
+ *     so it needs the server's PUBLIC address: STIGMER_MCP_PUBLIC_ENDPOINT,
+ *     which the server hands every sandbox it provisions from its own
+ *     configuration (stigmer/stigmer#1447), or an operator names to a
+ *     runner it starts by hand.
+ *   - A stdio server is a child of this runner (only a local runner spawns
+ *     one; mcp-transport-guard.ts), so the address the runner itself dials,
+ *     STIGMER_BACKEND_ENDPOINT, is right for it by construction.
+ *
+ * No page supplies it: a value a page could write (a conversation's own
+ * secrets) is resolved ahead of every vault the user saved
+ * (stigmer/stigmer#1446).
+ *
+ * The runner FILLS, it never overrides: a non-empty value already in the
+ * environment (one the user saved or typed to aim a server elsewhere)
+ * stands. A key nobody can supply stays missing, and a
+ * header that templates it fails with the resolver's named
+ * PlaceholderResolutionError instead of dialing a guess.
+ *
+ * Injection is opt-in exactly as for the caller-identity keys
+ * (caller-identity.ts): only a server that reads the key (its plugin entry
+ * names it in `env`) receives it. Applied before filterEnvToDeclaredKeys at
+ * execution (mcp-resolver.ts) and before placeholder resolution in a tools
+ * listing (shared/mcp-tool-listing.ts), so both share one rule.
+ */
+
+import type { McpServerEntry } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/status_pb";
+import type { Config } from "../config.js";
+
+/**
+ * Reserved env key: the Stigmer server's gRPC dial target, host:port. The
+ * name the mcp-server reads its target from (mcp-server/src/config.ts) and
+ * `@stigmer/react-sdk` keeps out of its setup prompts
+ * (sdk/react/src/environment/systemEnvVars.ts); a cross-package string,
+ * pinned on every side.
+ */
+export const SERVER_ADDRESS_ENV_KEY = "STIGMER_SERVER_ADDRESS";
+
+/** The two runner-known endpoints an address can be filled from. */
+export type PlatformEndpoints = Pick<Config, "mcpPublicEndpoint" | "stigmerBackendEndpoint">;
+
+/**
+ * The gRPC dial target (host:port) for an endpoint, the shape
+ * STIGMER_SERVER_ADDRESS wants.
+ *
+ * An http(s) URL becomes its host with an explicit port: the URL's own, else
+ * 80 for http and 443 for https. The port is never left implicit, because
+ * the mcp-server derives TLS from it and assumes :443 with TLS for a
+ * non-loopback host that has none (mcp-server/src/config.ts). Any other
+ * input (a scheme-less host:port, a bare host) is already a dial target and
+ * passes through unchanged.
+ */
+export function grpcTarget(endpoint: string): string {
+  let url: URL;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return endpoint;
+  }
+  // `new URL("host:7234")` parses with `host:` as its scheme, so only a
+  // real http(s) URL is taken apart.
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return endpoint;
+  }
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  return `${url.hostname}:${port}`;
+}
+
+/**
+ * The address the platform supplies for a server of this transport, or
+ * `null` when the runner knows none: the operator's public endpoint for any
+ * transport, else the runner's own backend endpoint for a stdio child.
+ */
+export function platformServerAddress(
+  transport: McpServerTransport | undefined,
+  endpoints: PlatformEndpoints,
+): string | null {
+  if (endpoints.mcpPublicEndpoint) {
+    return grpcTarget(endpoints.mcpPublicEndpoint);
+  }
+  if (transport === "stdio") {
+    return grpcTarget(endpoints.stigmerBackendEndpoint);
+  }
+  return null;
+}
+
+/**
+ * Return the env map with STIGMER_SERVER_ADDRESS filled for `server` when it
+ * reads the key and the map holds no non-empty value for it; otherwise the
+ * map itself, unchanged. Never mutates its input.
+ */
+export function fillPlatformServerAddress(
+  server: McpServerEntry,
+  slug: string,
+  envVars: Record<string, string>,
+  endpoints: PlatformEndpoints,
+): Record<string, string> {
+  if (!server.env.includes(SERVER_ADDRESS_ENV_KEY) || envVars[SERVER_ADDRESS_ENV_KEY]) {
+    return envVars;
+  }
+  const value = platformServerAddress(server.transport.case, endpoints);
+  if (value === null) {
+    return envVars;
+  }
+  const source = endpoints.mcpPublicEndpoint
+    ? "STIGMER_MCP_PUBLIC_ENDPOINT"
+    : "STIGMER_BACKEND_ENDPOINT";
+  console.info(
+    `MCP server '${slug}': ${SERVER_ADDRESS_ENV_KEY} ` +
+    `filled from ${source} (no value in the server's own values)`,
+  );
+  return { ...envVars, [SERVER_ADDRESS_ENV_KEY]: value };
+}
+
+/** The transports a plugin's server entry declares (its `transport` oneof). */
+type McpServerTransport = NonNullable<McpServerEntry["transport"]["case"]>;