@stigmer/runner 3.0.1

package/src/shared/skill-writer.ts

@@ -0,0 +1,300 @@
+/**
+ * Skill writing and prompt generation for the deep-agent execution path.
+ *
+ * Follows the Agent Skills specification progressive disclosure model:
+ *
+ * 1. Metadata (startup) — skill name + description injected into
+ *    the system prompt so the agent knows which skills are available.
+ * 2. Instructions (activation) — the agent reads SKILL.md from the
+ *    filesystem when it decides to activate a skill.
+ * 3. Resources (on demand) — scripts, references, and assets are
+ *    loaded by the agent only when required.
+ *
+ * Skills live under `.stigmer/skills/{name}/` relative to the workspace root.
+ * Returned paths are workspace-relative so that the agent's sandbox backend
+ * resolves them correctly regardless of mount strategy.
+ */
+
+import type { WorkspaceBackend } from "./workspace/types.js";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { extractZipFileEntries } from "./zip-extract.js";
+
+const SKILLS_RELATIVE_BASE = ".stigmer/skills";
+const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface SkillPathMap {
+  /** Map from skill metadata ID to workspace-relative directory path. */
+  readonly paths: ReadonlyMap<string, string>;
+}
+
+// ─── Fetch ───────────────────────────────────────────────────────────────
+
+/**
+ * Merge skill refs from agent and session specs (union, dedup by slug,
+ * session wins on collision).
+ */
+export function mergeSkillRefs(
+  agentRefs: readonly ApiResourceReference[],
+  sessionRefs: readonly ApiResourceReference[],
+): ApiResourceReference[] {
+  const bySlug = new Map<string, ApiResourceReference>();
+  for (const ref of agentRefs) {
+    if (ref.slug) bySlug.set(ref.slug, ref);
+  }
+  for (const ref of sessionRefs) {
+    if (ref.slug) bySlug.set(ref.slug, ref);
+  }
+  return [...bySlug.values()];
+}
+
+/**
+ * Fetch all skills by their ApiResourceReference. Failures for individual
+ * skills are logged and skipped (non-fatal).
+ */
+export async function fetchSkillsByRefs(
+  client: StigmerClient,
+  refs: readonly ApiResourceReference[],
+): Promise<Skill[]> {
+  if (refs.length === 0) return [];
+
+  const results: Skill[] = [];
+  const fetches = refs.map(async (ref) => {
+    try {
+      return await client.getSkillByReference(ref);
+    } catch (err) {
+      console.warn(
+        `[skill-writer] Failed to fetch skill ${ref.org}/${ref.slug}: ` +
+        `${err instanceof Error ? err.message : String(err)}`,
+      );
+      return null;
+    }
+  });
+
+  const settled = await Promise.all(fetches);
+  for (const skill of settled) {
+    if (skill) results.push(skill);
+  }
+  return results;
+}
+
+// ─── Write ───────────────────────────────────────────────────────────────
+
+/**
+ * Write skill artifacts to the workspace. Returns a map of
+ * skill-id -> workspace-relative directory path.
+ *
+ * For each skill:
+ * - If a ZIP artifact is available, extract it to .stigmer/skills/{name}/
+ * - Otherwise, write just the SKILL.md from the spec
+ * - Make scripts executable
+ */
+export async function writeSkills(
+  skills: readonly Skill[],
+  workspaceBackend: WorkspaceBackend,
+  artifacts: ReadonlyMap<string, Uint8Array>,
+): Promise<SkillPathMap> {
+  const paths = new Map<string, string>();
+
+  for (const skill of skills) {
+    const name = skill.spec?.name || skill.metadata?.slug || "unknown";
+    const skillId = skill.metadata?.id ?? name;
+    const relativeDir = `${SKILLS_RELATIVE_BASE}/${name}`;
+    paths.set(skillId, relativeDir);
+
+    const artifactBytes = artifacts.get(skillId);
+    if (skill.spec?.skillMd) {
+      const skillMdPath = `${relativeDir}/SKILL.md`;
+      await workspaceBackend.writeFile(skillMdPath, skill.spec.skillMd);
+      if (artifactBytes && artifactBytes.length > 0) {
+        await extractZipToWorkspaceExcluding(artifactBytes, "SKILL.md", relativeDir, workspaceBackend);
+      }
+    } else if (artifactBytes && artifactBytes.length > 0) {
+      await extractZipToWorkspace(artifactBytes, relativeDir, workspaceBackend);
+    }
+
+    await makeScriptsExecutable(relativeDir, workspaceBackend);
+  }
+
+  return { paths };
+}
+
+/**
+ * Compute skill paths without writing anything (for resume integrity checks).
+ */
+export function computeSkillPaths(skills: readonly Skill[]): Map<string, string> {
+  const paths = new Map<string, string>();
+  for (const skill of skills) {
+    const name = skill.spec?.name || skill.metadata?.slug || "unknown";
+    const skillId = skill.metadata?.id ?? name;
+    paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
+  }
+  return paths;
+}
+
+/**
+ * Check workspace integrity for resume fast-path.
+ * Returns true if the sentinel SKILL.md file exists for the first skill.
+ */
+export async function checkSkillIntegrity(
+  skills: readonly Skill[],
+  workspaceBackend: WorkspaceBackend,
+): Promise<boolean> {
+  if (skills.length === 0) return true;
+
+  const paths = computeSkillPaths(skills);
+  const firstPath = paths.values().next().value;
+  if (!firstPath) return true;
+
+  const sentinel = `${firstPath}/SKILL.md`;
+  return workspaceBackend.exists(sentinel);
+}
+
+// ─── ZIP extraction ──────────────────────────────────────────────────────
+
+async function extractZipToWorkspace(
+  zipBytes: Uint8Array,
+  targetDir: string,
+  backend: WorkspaceBackend,
+): Promise<void> {
+  const entries = await extractZipFileEntries(zipBytes);
+  for (const entry of entries) {
+    await backend.writeFile(`${targetDir}/${entry.path}`, entry.content);
+  }
+}
+
+async function extractZipToWorkspaceExcluding(
+  zipBytes: Uint8Array,
+  excludeName: string,
+  targetDir: string,
+  backend: WorkspaceBackend,
+): Promise<void> {
+  const entries = await extractZipFileEntries(zipBytes, { exclude: [excludeName] });
+  for (const entry of entries) {
+    await backend.writeFile(`${targetDir}/${entry.path}`, entry.content);
+  }
+}
+
+async function makeScriptsExecutable(
+  relativeDir: string,
+  backend: WorkspaceBackend,
+): Promise<void> {
+  const extensions = [...SCRIPT_EXTENSIONS].map(ext => `-name '*${ext}'`).join(" -o ");
+  const cmd = `find ${relativeDir} -type f \\( ${extensions} \\) -exec chmod +x {} \\; 2>/dev/null || true`;
+  try {
+    await backend.execute(cmd);
+  } catch {
+    // Non-fatal: scripts may not be executable in all environments
+  }
+}
+
+// ─── Prompt generation ───────────────────────────────────────────────────
+
+/**
+ * Generate the system prompt section following the Agent Skills spec
+ * progressive disclosure model.
+ *
+ * Only metadata (name + description + location) is injected. The agent
+ * reads SKILL.md on demand via filesystem tools.
+ */
+export function generatePromptSection(
+  skills: readonly Skill[],
+  skillPaths: ReadonlyMap<string, string>,
+): string {
+  if (skills.length === 0) return "";
+
+  const lines: string[] = [
+    "",
+    "",
+    "## Skills",
+    "",
+    "You have access to the following skills. Each skill provides specialized " +
+    "knowledge or capabilities.",
+    "",
+    "**Activation protocol**: To use a skill, read its SKILL.md file " +
+    "using the `read` tool. The SKILL.md contains detailed instructions, " +
+    "available tools, and usage examples.",
+    "",
+    "**Usage pattern**:",
+    "",
+    "1. Review the skill description below to determine relevance",
+    "2. Read `{location}/SKILL.md` for full instructions",
+    "3. Follow the skill's documented operations:",
+    "",
+    "`read {location}/references/schema.md`",
+    '`execute("python3 {location}/scripts/run.py")`',
+    "",
+  ];
+
+  for (const skill of skills) {
+    const name = skill.spec?.name || skill.metadata?.slug || "unknown";
+    const skillId = skill.metadata?.id ?? name;
+    const skillDir = skillPaths.get(skillId) ?? `${SKILLS_RELATIVE_BASE}/${name}`;
+    const description = skill.spec?.description || "(no description)";
+
+    lines.push(`### ${name}`);
+    lines.push(`**Description**: ${description}`);
+    lines.push(`**Location**: \`${skillDir}/\``);
+    lines.push(`**Activate**: \`read ${skillDir}/SKILL.md\``);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate a brief note listing skills excluded by relevance filtering.
+ *
+ * The agent can still request these skills by name if it determines
+ * they are needed mid-conversation.
+ */
+export function generateAlsoAvailableSection(
+  excludedNames: readonly string[],
+): string {
+  if (excludedNames.length === 0) return "";
+
+  const namesStr = excludedNames.map(n => `\`${n}\``).join(", ");
+  return (
+    "\n### Also Available\n\n" +
+    `These skills are installed but were not highlighted above: ${namesStr}. ` +
+    "If you determine one of them is relevant to your task, " +
+    "read its SKILL.md at `.stigmer/skills/<name>/SKILL.md` to activate it.\n"
+  );
+}
+
+// ─── Artifact fetching ───────────────────────────────────────────────────
+
+/**
+ * Download skill artifacts for all skills that have a storage key.
+ * Returns a map from skill ID to artifact bytes.
+ */
+export async function fetchSkillArtifacts(
+  client: StigmerClient,
+  skills: readonly Skill[],
+): Promise<Map<string, Uint8Array>> {
+  const artifacts = new Map<string, Uint8Array>();
+
+  const fetches = skills
+    .filter(s => s.status?.artifactStorageKey)
+    .map(async (skill) => {
+      const key = skill.status!.artifactStorageKey;
+      const skillId = skill.metadata?.id ?? skill.spec?.name ?? "unknown";
+      try {
+        const response = await client.getSkillArtifact(key);
+        if (response.artifact && response.artifact.length > 0) {
+          artifacts.set(skillId, response.artifact);
+        }
+      } catch (err) {
+        console.warn(
+          `[skill-writer] Failed to download artifact for ${skill.spec?.name}: ` +
+          `${err instanceof Error ? err.message : String(err)}. Falling back to SKILL.md only.`,
+        );
+      }
+    });
+
+  await Promise.all(fetches);
+  return artifacts;
+}

package/src/shared/status.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared status persistence utilities for all runner activities.
+ *
+ * Both ExecuteCursor and ExecuteDeepAgent need to persist execution status
+ * via gRPC, report setup progress phases, produce slim status payloads for
+ * Temporal return values, and generate UTC timestamps. These thin utilities
+ * are harness-agnostic — they operate on the common AgentExecutionStatus
+ * proto without knowledge of Cursor SDK or LangGraph event shapes.
+ */
+
+import { create, toJson } from "@bufbuild/protobuf";
+import {
+  AgentExecutionStatusSchema,
+  SetupProgressSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  ExecutionControlSignal,
+  ExecutionPhase,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+
+export function utcTimestamp(): string {
+  return new Date().toISOString().replace("+00:00", "Z");
+}
+
+/**
+ * Persist execution status via gRPC. Returns the control signal from the
+ * backend (e.g. STOP to abort the execution). Errors are logged and
+ * swallowed — a failed status update should not crash the activity.
+ */
+export async function persistStatus(
+  client: StigmerClient,
+  executionId: string,
+  status: AgentExecutionStatus,
+): Promise<ExecutionControlSignal> {
+  try {
+    const response = await client.updateStatus(executionId, status);
+    return response.signal;
+  } catch (err) {
+    console.error(`Failed to persist status for ${executionId}:`, err);
+    return ExecutionControlSignal.UNSPECIFIED;
+  }
+}
+
+/**
+ * Report a setup progress phase (e.g. "Resolving MCP servers") so the
+ * frontend can display a spinner with context.
+ */
+export async function reportSetupProgress(
+  client: StigmerClient,
+  executionId: string,
+  phase: string,
+): Promise<void> {
+  const status = create(AgentExecutionStatusSchema, {
+    phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+    setupProgress: create(SetupProgressSchema, { currentPhase: phase }),
+  });
+  await persistStatus(client, executionId, status);
+}
+
+/**
+ * Strip heavy fields from a full status, keeping only workflow-critical
+ * data for the Temporal return value. Messages and tool calls are already
+ * persisted via gRPC — including them in the Temporal payload would
+ * exceed size limits and cause serialization issues with protobuf bytes.
+ *
+ * Uses toJson() to produce canonical protobuf JSON (base64 bytes, string
+ * enums, omitted defaults) instead of returning a raw @bufbuild/protobuf
+ * message. Temporal's default JsonPayloadConverter calls JSON.stringify,
+ * which serializes Uint8Array bytes fields as {} — invalid protobuf JSON
+ * that the Java workflow's JsonFormat.Parser rejects.
+ */
+export function slimStatus(full: AgentExecutionStatus): unknown {
+  const slim = create(AgentExecutionStatusSchema, {
+    phase: full.phase,
+    error: full.error,
+    startedAt: full.startedAt,
+    completedAt: full.completedAt,
+    pendingApprovals: full.pendingApprovals,
+    structuredOutput: full.structuredOutput,
+  });
+  const json = toJson(AgentExecutionStatusSchema, slim);
+  if (full.structuredOutput) {
+    const jsonObj = json as Record<string, unknown>;
+    const hasField = "structuredOutput" in jsonObj;
+    console.log(
+      `[slimStatus] structuredOutput serialization: ` +
+      `inputPresent=true, outputFieldPresent=${hasField}, ` +
+      `outputKeys=${Object.keys(jsonObj).join(",")}`,
+    );
+  }
+  return json;
+}

package/src/shared/subagent-gate.ts

@@ -0,0 +1,117 @@
+/**
+ * Concurrency limiter for sub-agent execution.
+ *
+ * Wraps sub-agent runnables with a Promise-based semaphore that
+ * limits the number of concurrent sub-agent invocations. When the
+ * limit is reached, new invocations are rejected immediately with
+ * an error-shaped message (non-blocking) rather than queuing.
+ *
+ * This matches the Python `SubAgentGate` behavior: protect the
+ * parent agent's resources by hard-capping concurrency, and let
+ * the LLM adapt when a sub-agent cannot be started.
+ */
+
+import { RunnableLambda, type RunnableConfig } from "@langchain/core/runnables";
+
+const DEFAULT_MAX_CONCURRENT = 3;
+
+export interface SubAgentGateOptions {
+  readonly maxConcurrent?: number;
+}
+
+export class SubAgentGate {
+  private readonly max: number;
+  private active = 0;
+
+  constructor(options: SubAgentGateOptions = {}) {
+    this.max = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    if (this.max <= 0) {
+      throw new Error(`maxConcurrent must be positive, got ${this.max}`);
+    }
+  }
+
+  get activeCount(): number {
+    return this.active;
+  }
+
+  get maxConcurrent(): number {
+    return this.max;
+  }
+
+  get hasCapacity(): boolean {
+    return this.active < this.max;
+  }
+
+  /**
+   * Wrap a sub-agent's invoke function with concurrency gating.
+   *
+   * Returns a new function that checks capacity before invoking.
+   * If no capacity, returns an error-shaped response immediately.
+   */
+  wrap<TInput, TOutput>(
+    invoke: (input: TInput, config?: Record<string, unknown>) => Promise<TOutput>,
+    name: string,
+  ): (input: TInput, config?: Record<string, unknown>) => Promise<TOutput> {
+    return async (input: TInput, config?: Record<string, unknown>): Promise<TOutput> => {
+      if (!this.hasCapacity) {
+        console.warn(
+          `[SubAgentGate] Rejected '${name}': ${this.active}/${this.max} slots occupied`,
+        );
+        return {
+          messages: [{
+            role: "assistant",
+            content:
+              `Sub-agent '${name}' was NOT started — the maximum of ` +
+              `${this.max} concurrent sub-agents are already running. ` +
+              `Wait for an active sub-agent to complete before starting another, ` +
+              `or proceed without this sub-agent.`,
+          }],
+        } as TOutput;
+      }
+
+      this.active++;
+      try {
+        return await invoke(input, config);
+      } finally {
+        this.active--;
+      }
+    };
+  }
+
+  /**
+   * Wrap a sub-agent Runnable for use as `CompiledSubAgent.runnable`.
+   *
+   * Returns a `RunnableLambda` that checks capacity before delegating
+   * to the underlying runnable. When at capacity, returns an error-shaped
+   * response that deepagents surfaces to the parent agent as the task result.
+   */
+  wrapRunnable<TInput = Record<string, unknown>, TOutput = Record<string, unknown>>(
+    runnable: { invoke: (input: TInput, config?: RunnableConfig) => Promise<TOutput> },
+    name: string,
+  ): RunnableLambda<TInput, TOutput> {
+    return RunnableLambda.from(async (input: TInput, config?: RunnableConfig): Promise<TOutput> => {
+      if (!this.hasCapacity) {
+        console.warn(
+          `[SubAgentGate] Rejected '${name}': ${this.active}/${this.max} slots occupied`,
+        );
+        return {
+          messages: [{
+            role: "assistant",
+            content:
+              `Sub-agent '${name}' was NOT started — the maximum of ` +
+              `${this.max} concurrent sub-agents are already running. ` +
+              `Wait for an active sub-agent to complete before starting another, ` +
+              `or proceed without this sub-agent.`,
+          }],
+        } as TOutput;
+      }
+
+      this.active++;
+      try {
+        return await runnable.invoke(input, config);
+      } finally {
+        this.active--;
+      }
+    });
+  }
+}

package/src/shared/tool-kind.ts

@@ -0,0 +1,91 @@
+/**
+ * Harness-agnostic tool classification for the runner.
+ *
+ * Both harnesses emit engine-specific tool names — the native (deepagents)
+ * harness uses snake_case (edit_file, execute, grep), the Cursor harness uses
+ * PascalCase (StrReplace, Shell, Grep). This module is the single place that
+ * maps a tool name to the wire-level ToolKind, so every client renders a tool
+ * the same way regardless of which harness produced it.
+ *
+ * The SDK fallback resolver and the Go CLI mirror this mapping. The shared,
+ * machine-checked contract is test/fixtures/tool-view/classification.json — keep
+ * this table and that fixture in lockstep.
+ */
+
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+// Bare tool name -> ToolKind, covering both harness naming conventions. A name
+// found here is a built-in and wins over a non-empty mcp_server_slug (an MCP
+// server is not expected to shadow a built-in name; matching the legacy resolver).
+const TOOL_NAME_TO_KIND: ReadonlyMap<string, ToolKind> = new Map([
+  ["read", ToolKind.FILE_READ],
+  ["read_file", ToolKind.FILE_READ],
+  ["Read", ToolKind.FILE_READ],
+
+  ["write", ToolKind.FILE_WRITE],
+  ["write_file", ToolKind.FILE_WRITE],
+  ["create_file", ToolKind.FILE_WRITE],
+  ["overwrite_file", ToolKind.FILE_WRITE],
+  ["Write", ToolKind.FILE_WRITE],
+
+  ["edit", ToolKind.FILE_EDIT],
+  ["edit_file", ToolKind.FILE_EDIT],
+  ["str_replace_editor", ToolKind.FILE_EDIT],
+  ["StrReplace", ToolKind.FILE_EDIT],
+  ["EditNotebook", ToolKind.FILE_EDIT],
+
+  ["delete", ToolKind.FILE_DELETE],
+  ["delete_file", ToolKind.FILE_DELETE],
+  ["remove_file", ToolKind.FILE_DELETE],
+  ["Delete", ToolKind.FILE_DELETE],
+
+  ["shell", ToolKind.SHELL],
+  ["bash", ToolKind.SHELL],
+  ["execute", ToolKind.SHELL],
+  ["execute_command", ToolKind.SHELL],
+  ["run_command", ToolKind.SHELL],
+  ["terminal", ToolKind.SHELL],
+  ["Shell", ToolKind.SHELL],
+
+  ["grep", ToolKind.SEARCH],
+  ["glob", ToolKind.SEARCH],
+  ["search", ToolKind.SEARCH],
+  ["ripgrep", ToolKind.SEARCH],
+  ["find_files", ToolKind.SEARCH],
+  ["Grep", ToolKind.SEARCH],
+  ["Glob", ToolKind.SEARCH],
+  ["SemanticSearch", ToolKind.SEARCH],
+
+  ["ls", ToolKind.LIST],
+  ["list_directory", ToolKind.LIST],
+
+  ["WebFetch", ToolKind.FETCH],
+  ["WebSearch", ToolKind.WEB_SEARCH],
+
+  ["think", ToolKind.THINK],
+
+  ["write_todos", ToolKind.TODO],
+  ["updateTodos", ToolKind.TODO],
+  ["TodoWrite", ToolKind.TODO],
+
+  ["task", ToolKind.SUBAGENT],
+  ["Task", ToolKind.SUBAGENT],
+]);
+
+/**
+ * Classifies a tool call into its harness-agnostic ToolKind.
+ *
+ * Built-in names are matched first; any unrecognized name with a non-empty
+ * mcpServerSlug is an MCP tool; everything else is UNSPECIFIED (clients fall
+ * back to a name lookup, so this is never worse than no classification).
+ */
+export function classifyTool(name: string, mcpServerSlug?: string): ToolKind {
+  const builtin = TOOL_NAME_TO_KIND.get(name);
+  if (builtin !== undefined) {
+    return builtin;
+  }
+  if (mcpServerSlug && mcpServerSlug.length > 0) {
+    return ToolKind.MCP;
+  }
+  return ToolKind.UNSPECIFIED;
+}