@runravel/ravel 0.1.0

package/src/runtime/lifecycle.ts

@@ -0,0 +1,85 @@
+import type { RegistryNode, RegistrySnapshot } from "../control-plane/registry.js";
+import type { ModelTier } from "../schemas/common.js";
+import { AgentRuntime, type AgentRuntimeDeps } from "./agent.js";
+import type { AuditSink } from "../trust/audit.js";
+
+export interface LifecycleDeps extends AgentRuntimeDeps {
+  audit: AuditSink;
+}
+
+/** A node id is a manager-altitude node if it has children. */
+function tierForNode(node: RegistryNode): ModelTier {
+  return node.childIds.length > 0 ? "opus" : "sonnet";
+}
+
+/** Stable fingerprint of the parts of a node that affect runtime behavior. */
+function fingerprint(node: RegistryNode): string {
+  return JSON.stringify({ spec: node.spec, tools: node.tools });
+}
+
+/**
+ * Owns the live set of agent runtimes and reconciles it against registry
+ * snapshots. Reconciliation is a diff:
+ * - new node            → spawn a runtime
+ * - removed node        → drain it, then drop it (in-flight work finishes)
+ * - changed node config → swap config in place (no disruption to a running task)
+ *
+ * Editing a folder thus flows: watcher compiles a snapshot → lifecycle diffs →
+ * agents are spawned/drained/updated deliberately. Nothing mutates a running
+ * agent directly.
+ */
+export class Lifecycle {
+  private readonly agents = new Map<string, AgentRuntime>();
+  private readonly fingerprints = new Map<string, string>();
+  private appliedVersion = -1;
+
+  constructor(private readonly deps: LifecycleDeps) {}
+
+  get(nodeId: string): AgentRuntime | undefined {
+    return this.agents.get(nodeId);
+  }
+
+  all(): AgentRuntime[] {
+    return [...this.agents.values()];
+  }
+
+  version(): number {
+    return this.appliedVersion;
+  }
+
+  async applySnapshot(snapshot: RegistrySnapshot): Promise<void> {
+    const next = new Set(snapshot.nodes.keys());
+
+    // Removed nodes: drain and drop.
+    for (const id of [...this.agents.keys()]) {
+      if (!next.has(id)) {
+        const agent = this.agents.get(id)!;
+        agent.drain();
+        this.agents.delete(id);
+        this.fingerprints.delete(id);
+        await this.deps.audit.append("agent.drained", { nodeId: id, data: {} });
+      }
+    }
+
+    // Added or changed nodes.
+    for (const node of snapshot.nodes.values()) {
+      const existing = this.agents.get(node.id);
+      const fp = fingerprint(node);
+      if (!existing) {
+        const agent = new AgentRuntime(node, this.deps, tierForNode(node));
+        this.agents.set(node.id, agent);
+        this.fingerprints.set(node.id, fp);
+        await this.deps.audit.append("agent.spawned", {
+          nodeId: node.id,
+          data: { name: node.spec.name, role: node.spec.role },
+        });
+      } else if (this.fingerprints.get(node.id) !== fp) {
+        existing.updateNode(node);
+        this.fingerprints.set(node.id, fp);
+        await this.deps.audit.append("agent.updated", { nodeId: node.id, data: {} });
+      }
+    }
+
+    this.appliedVersion = snapshot.version;
+  }
+}

package/src/runtime/officeActions.ts

@@ -0,0 +1,58 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * Office actions are consequential business actions (send email, send a
+ * proposal, deliver to a client). They are defined once here and used by BOTH:
+ * - the in-process MCP tool ([officeTools.ts]) — so the model can *request* them
+ *   (which routes through the approval gate), and
+ * - the async ActionExecutor — which *performs* the approved action.
+ *
+ * The effect is deliberately simple (append a durable record to the run's
+ * `shared/_office_log.md`); wiring a real provider (SMTP, CRM, delivery portal)
+ * means replacing the body of `runOfficeAction` while the approval semantics
+ * stay identical.
+ */
+export const OFFICE_ACTIONS = {
+  send_email: { verb: "email", description: "Send an outbound email. Consequential and externally visible." },
+  send_proposal: { verb: "proposal", description: "Send a proposal/quote to a prospect. Consequential and externally visible." },
+  deliver_to_client: { verb: "delivery", description: "Deliver final files to a client. Irreversible client-facing action." },
+} as const;
+
+export type OfficeActionName = keyof typeof OFFICE_ACTIONS;
+export const OFFICE_TOOL_NAMES = Object.keys(OFFICE_ACTIONS) as OfficeActionName[];
+
+export function isOfficeAction(name: string): name is OfficeActionName {
+  return name in OFFICE_ACTIONS;
+}
+
+export interface OfficeActionContext {
+  /** Workspace root; the action writes under `cwd/shared`. */
+  cwd: string;
+  nodeId?: string;
+  runId?: string;
+}
+
+export interface OfficeActionResult {
+  ok: boolean;
+  result?: string;
+  error?: string;
+}
+
+/** Perform an office action deterministically (no model involved). */
+export async function runOfficeAction(
+  name: string,
+  input: unknown,
+  ctx: OfficeActionContext,
+): Promise<OfficeActionResult> {
+  if (!isOfficeAction(name)) return { ok: false, error: `unknown office action "${name}"` };
+  const def = OFFICE_ACTIONS[name];
+  try {
+    const dir = path.join(ctx.cwd, "shared");
+    await fs.mkdir(dir, { recursive: true });
+    await fs.appendFile(path.join(dir, "_office_log.md"), `- ${def.verb}: ${JSON.stringify(input)}\n`, "utf8");
+    return { ok: true, result: `${def.verb} recorded in shared/_office_log.md` };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/runtime/officeTools.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { OFFICE_ACTIONS, OFFICE_TOOL_NAMES, isOfficeAction, runOfficeAction } from "./officeActions.js";
+
+export { OFFICE_TOOL_NAMES } from "./officeActions.js";
+
+/** Zod input shapes for the MCP tool definitions (executor doesn't need these). */
+const SHAPES: Record<string, z.ZodRawShape> = {
+  send_email: { to: z.string().describe("recipient"), subject: z.string().optional(), body: z.string().optional() },
+  send_proposal: { to: z.string().describe("recipient"), summary: z.string().optional() },
+  deliver_to_client: {
+    to: z.string().optional(),
+    files: z.string().optional().describe("what is being delivered"),
+    summary: z.string().optional(),
+  },
+};
+
+/**
+ * Build an in-process MCP server exposing only the office tools the agent was
+ * granted. The tool handlers delegate to the shared `runOfficeAction`, so the
+ * synchronous MCP path and the async executor path do exactly the same thing.
+ * Returns null if no office tool was granted (no MCP overhead added).
+ *
+ * Note: under the platform's default *deferred* approval mode these tools are
+ * gated to "deny" and never actually execute here — they exist so the model can
+ * *request* the action, which the broker records as a proposal. The real effect
+ * happens later via the executor on human approval.
+ */
+export function buildOfficeServer(grantedNames: string[], cwd: string): McpServerConfig | null {
+  const granted = grantedNames.filter(isOfficeAction);
+  if (granted.length === 0) return null;
+
+  const tools = granted.map((name) =>
+    tool(name, OFFICE_ACTIONS[name].description, SHAPES[name]!, async (args: Record<string, unknown>) => {
+      const r = await runOfficeAction(name, args, { cwd });
+      return { content: [{ type: "text" as const, text: r.ok ? (r.result ?? "OK") : `error: ${r.error}` }] };
+    }),
+  );
+
+  return createSdkMcpServer({ name: "office", version: "1.0.0", tools });
+}

package/src/runtime/sdkEngine.ts

@@ -0,0 +1,213 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { Options, McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentEngine, EngineRequest, EngineResult, EngineToolUse } from "./engine.js";
+import { emptyUsage, type Usage } from "../domain/types.js";
+import { usageFor } from "../domain/pricing.js";
+import type { McpServerSpec, ToolsConfig } from "../schemas/tools.js";
+import { MODEL_IDS } from "../schemas/common.js";
+import { buildOfficeServer } from "./officeTools.js";
+import { buildGenericMemoryServer } from "../memory/genericTools.js";
+import { buildPluginServer } from "../plugins/server.js";
+
+/**
+ * Assemble the MCP servers for a call: declared servers + in-process servers for
+ * the granted tools — `office` actions, generic `mem` primitives (text/json/queue),
+ * and any team-provided `plugin` tools. Domain connectors (X/PDL, watchlists, etc.)
+ * live in team plugins, not the runtime. The plugin/mem servers are built only when a
+ * `toolContext` is present (FakeEngine omits it). Exported so the wiring can be
+ * asserted without an API key.
+ */
+export function assembleMcpServers(req: EngineRequest): Record<string, McpServerConfig> {
+  // Per-node credentials (the agent's `.env` chain); resolved for declared MCP servers.
+  const nodeEnv = req.nodeEnv ?? {};
+
+  const servers = toSdkMcpServers(req.tools, nodeEnv);
+  const grantedNames = req.tools.tools.filter((t) => t.policy !== "deny").map((t) => t.name);
+
+  const office = buildOfficeServer(grantedNames, req.cwd);
+  if (office) servers["office"] = office;
+
+  if (req.toolContext) {
+    // Generic, domain-agnostic memory primitives (text / json / queue).
+    const mem = buildGenericMemoryServer(grantedNames, {
+      nodeId: req.toolContext.nodeId,
+      managerNodeId: req.toolContext.managerNodeId,
+      memory: req.toolContext.memory,
+    });
+    if (mem) servers["mem"] = mem;
+    // Team-provided plugin tools (scoped to this node's team).
+    if (req.toolContext.pluginTools) {
+      const plugin = buildPluginServer(grantedNames, req.toolContext.pluginTools, {
+        nodeId: req.toolContext.nodeId,
+        managerNodeId: req.toolContext.managerNodeId,
+        memory: req.toolContext.memory,
+        cwd: req.cwd,
+        env: req.toolContext.pluginEnv ?? {},
+      });
+      if (plugin) servers["plugin"] = plugin;
+    }
+  }
+  return servers;
+}
+
+/**
+ * Translate our MCP specs into the SDK's McpServerConfig, resolving credentials
+ * from the node's scoped env first, then the host `process.env`. So a per-agent
+ * `.env` key reaches an external MCP's stdio env or `${VAR}` http headers.
+ */
+function toSdkMcpServers(tools: ToolsConfig, nodeEnv: Record<string, string>): Record<string, McpServerConfig> {
+  const out: Record<string, McpServerConfig> = {};
+  for (const [name, spec] of Object.entries(tools.mcpServers)) {
+    out[name] = toSdkMcpServer(spec, nodeEnv);
+  }
+  return out;
+}
+
+/** Substitute `${VAR}` placeholders from the node's env, then process.env. */
+function subst(value: string, nodeEnv: Record<string, string>): string {
+  return value.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (_m, k: string) => nodeEnv[k] ?? process.env[k] ?? "");
+}
+
+function toSdkMcpServer(spec: McpServerSpec, nodeEnv: Record<string, string>): McpServerConfig {
+  if (spec.type === "stdio") {
+    const env: Record<string, string> = {};
+    for (const key of spec.env ?? []) {
+      const val = nodeEnv[key] ?? process.env[key];
+      if (val !== undefined) env[key] = val;
+    }
+    return {
+      type: "stdio",
+      command: spec.command,
+      ...(spec.args ? { args: spec.args } : {}),
+      ...(Object.keys(env).length ? { env } : {}),
+    };
+  }
+  // http | sse — substitute ${VAR} placeholders in header values from node env.
+  const headers = spec.headers
+    ? Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, subst(v, nodeEnv)]))
+    : undefined;
+  return {
+    type: spec.type,
+    url: spec.url,
+    ...(headers ? { headers } : {}),
+  };
+}
+
+/**
+ * The production AgentEngine: drives the Claude Agent SDK's agent loop.
+ *
+ * - `canUseTool` is wired to the runtime's approval gate, so every tool call is
+ *   gated by our permission policy / HITL queue — not the SDK's own prompts.
+ * - The kill-switch/budget abort signal is passed straight through.
+ * - Usage is reported per assistant turn so the runtime can enforce token/cost
+ *   budgets between turns.
+ *
+ * Requires ANTHROPIC_API_KEY (or an `ant auth login` profile) in the environment.
+ */
+export class SdkEngine implements AgentEngine {
+  constructor() {
+    // Claude Code (the SDK) uses a family of models, not just the one we pass
+    // per agent: a background "haiku" for cheap auxiliary work (summarization,
+    // topic/title detection) and a default "sonnet"/"opus" for others. Left
+    // alone, this build's default sonnet is the older 4-5. Pin all three to
+    // current-gen so background calls stay on models we actually chose. Any
+    // value the operator already exported is respected.
+    process.env["ANTHROPIC_DEFAULT_OPUS_MODEL"] ??= MODEL_IDS.opus;
+    process.env["ANTHROPIC_DEFAULT_SONNET_MODEL"] ??= MODEL_IDS.sonnet;
+    process.env["ANTHROPIC_DEFAULT_HAIKU_MODEL"] ??= MODEL_IDS.haiku;
+    // Suppress Claude Code's non-essential network traffic (telemetry, auto-update,
+    // error reporting). Note: this does NOT stop its baked-in background model
+    // calls (title/topic generation, etc.) — only the ApiEngine avoids those.
+    process.env["CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"] ??= "1";
+  }
+
+  async run(req: EngineRequest): Promise<EngineResult> {
+    const abortController = new AbortController();
+    // Bridge the runtime's signal into the SDK's own AbortController.
+    if (req.signal.aborted) abortController.abort();
+    else req.signal.addEventListener("abort", () => abortController.abort(), { once: true });
+
+    const toolUses: EngineToolUse[] = [];
+
+    const options: Options = {
+      model: req.model,
+      systemPrompt: req.systemPrompt,
+      cwd: req.cwd,
+      abortController,
+      // Scope the built-in toolset to only what this agent needs. `[]` disables
+      // all built-in tools, dropping thousands of tokens of schemas per call.
+      tools: req.builtinTools,
+      ...(req.maxTurns !== undefined ? { maxTurns: req.maxTurns } : {}),
+      mcpServers: assembleMcpServers(req),
+      permissionMode: "default",
+      canUseTool: async (toolName, input) => {
+        toolUses.push({ name: toolName, input });
+        const decision = await req.decide({ name: toolName, input });
+        if (decision === "allow") {
+          return { behavior: "allow", updatedInput: input };
+        }
+        return {
+          behavior: "deny",
+          message:
+            "Queued for human approval — do not retry; continue without it and note it as pending in your summary.",
+          interrupt: false,
+        };
+      },
+    };
+
+    let finalText = "";
+    let usage: Usage = emptyUsage();
+    let stopReason: EngineResult["stopReason"] = "done";
+    let error: string | undefined;
+
+    try {
+      for await (const message of query({ prompt: req.prompt, options })) {
+        if (message.type === "assistant") {
+          // Report this turn's usage (cache-aware) so the runtime can enforce
+          // budgets mid-run and surface cache reads/writes.
+          const u = message.message.usage;
+          if (u) {
+            req.onUsage?.(
+              usageFor(
+                req.model,
+                u.input_tokens ?? 0,
+                u.output_tokens ?? 0,
+                u.cache_read_input_tokens ?? 0,
+                u.cache_creation_input_tokens ?? 0,
+              ),
+            );
+          }
+        } else if (message.type === "result") {
+          finalText = message.subtype === "success" ? message.result : "";
+          // The SDK's total_cost_usd is authoritative (already cache-aware); keep
+          // the token breakdown for visibility.
+          usage = {
+            inputTokens: message.usage.input_tokens ?? 0,
+            outputTokens: message.usage.output_tokens ?? 0,
+            cacheReadTokens: message.usage.cache_read_input_tokens ?? 0,
+            cacheCreationTokens: message.usage.cache_creation_input_tokens ?? 0,
+            usd: message.total_cost_usd,
+          };
+          if (message.subtype !== "success") {
+            stopReason = "error";
+            error = message.errors.join("; ") || message.subtype;
+          }
+        }
+      }
+    } catch (err) {
+      if (abortController.signal.aborted) {
+        return { text: finalText, usage, stopReason: "aborted", toolUses };
+      }
+      return {
+        text: "",
+        usage,
+        stopReason: "error",
+        toolUses,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+
+    if (abortController.signal.aborted) stopReason = "aborted";
+    return { text: finalText, usage, stopReason, toolUses, ...(error ? { error } : {}) };
+  }
+}

package/src/schemas/agent.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { Budget, ModelRef } from "./common.js";
+import { parseFrontmatter } from "./frontmatter.js";
+
+/**
+ * The authored shape of an `agent.md` file. Frontmatter carries machine fields;
+ * the markdown body becomes the agent's system prompt.
+ *
+ * Hierarchy note: an agent's *position* in the folder tree (its parent and
+ * children) defines escalation and permission scope, NOT execution flow. Who
+ * does what work is decided by processes (see ProcessSpec) and by the
+ * orchestrator dispatching task contracts.
+ */
+export const AgentSpec = z
+  .object({
+    /** Human-readable name, e.g. "Sales Manager". */
+    name: z.string().min(1),
+    /** Role title used in prompts and routing, e.g. "manager", "researcher". */
+    role: z.string().min(1).optional(),
+    /** Model tier or explicit id. Defaults are applied by the runtime per altitude. */
+    model: ModelRef.optional(),
+    /**
+     * How much latitude this agent has when acting.
+     * - `orchestrated`: only acts on dispatched task contracts; no self-directed loops.
+     * - `bounded`: may act autonomously within its budget and approval policy.
+     */
+    autonomy: z.enum(["orchestrated", "bounded"]).default("orchestrated"),
+    /** Default budget ceiling applied to this agent's tasks unless overridden. */
+    budget: Budget.optional(),
+    /** Free-text escalation guidance surfaced to the agent. */
+    escalation: z.string().optional(),
+    /** The system prompt. Sourced from the markdown body, never frontmatter. */
+    systemPrompt: z.string().min(1, "agent.md must have a non-empty body (the system prompt)"),
+  })
+  .strict();
+
+export type AgentSpec = z.infer<typeof AgentSpec>;
+
+/**
+ * Parse and validate raw `agent.md` content into an AgentSpec.
+ * Throws a ZodError on invalid input — the caller (registry compiler) turns
+ * that into a diagnostic and keeps the last-good snapshot.
+ */
+export function parseAgentSpec(source: string): AgentSpec {
+  const { frontmatter, body } = parseFrontmatter(source);
+  return AgentSpec.parse({ ...frontmatter, systemPrompt: body });
+}

package/src/schemas/common.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+/**
+ * Logical model tiers. Authors pick a tier; the runtime resolves it to a
+ * concrete model id (see `resolveModel`). Orchestrator/manager agents default
+ * to opus for planning; workers default to sonnet. An author may also pass a
+ * raw model id string to pin an exact model.
+ */
+export const ModelTier = z.enum(["opus", "sonnet", "haiku"]);
+export type ModelTier = z.infer<typeof ModelTier>;
+
+/** Concrete model ids the platform knows about (latest as of build). */
+export const MODEL_IDS: Record<ModelTier, string> = {
+  opus: "claude-opus-4-8",
+  sonnet: "claude-sonnet-4-6",
+  haiku: "claude-haiku-4-5",
+};
+
+/** A model field accepts a known tier or an explicit model-id string. */
+export const ModelRef = z.union([ModelTier, z.string().min(1)]);
+export type ModelRef = z.infer<typeof ModelRef>;
+
+export function resolveModel(ref: ModelRef | undefined, fallback: ModelTier): string {
+  const value = ref ?? fallback;
+  if (value in MODEL_IDS) return MODEL_IDS[value as ModelTier];
+  return value; // explicit model id passed through verbatim
+}
+
+/**
+ * A budget bounds the work an agent or task may do before it must terminate or
+ * escalate. All fields are optional ceilings; the runtime enforces whichever
+ * are present. This is the core guard against runaway autonomous loops.
+ */
+export const Budget = z
+  .object({
+    tokens: z.number().int().positive().optional(),
+    usd: z.number().positive().optional(),
+    seconds: z.number().int().positive().optional(),
+    /** Max orchestration turns / dispatch cycles before forced termination. */
+    turns: z.number().int().positive().optional(),
+  })
+  .strict();
+export type Budget = z.infer<typeof Budget>;
+
+/**
+ * Per-tool permission policy. `auto` runs without asking, `ask` routes through
+ * the human approval queue (HITL), `deny` blocks the tool entirely. The default
+ * is intentionally `ask` — consequential actions should pause for a human until
+ * an owner explicitly trusts them.
+ */
+export const PermissionPolicy = z.enum(["auto", "ask", "deny"]);
+export type PermissionPolicy = z.infer<typeof PermissionPolicy>;

package/src/schemas/frontmatter.ts

@@ -0,0 +1,36 @@
+import { parse as parseYaml } from "yaml";
+
+/**
+ * Splits a markdown document into its YAML frontmatter and body.
+ *
+ * Supports the conventional `---\n<yaml>\n---\n<body>` form. If no frontmatter
+ * fence is present, the whole document is treated as the body with empty
+ * frontmatter — this keeps authoring forgiving (an `agent.md` that is pure prose
+ * is still valid; only the schema decides what is required).
+ */
+export interface ParsedDocument {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+export function parseFrontmatter(source: string): ParsedDocument {
+  const match = source.match(FRONTMATTER_RE);
+  if (!match) {
+    return { frontmatter: {}, body: source.trim() };
+  }
+
+  const [, rawYaml = "", body = ""] = match;
+  let frontmatter: Record<string, unknown> = {};
+  if (rawYaml.trim().length > 0) {
+    const parsed: unknown = parseYaml(rawYaml);
+    if (parsed !== null && typeof parsed === "object") {
+      frontmatter = parsed as Record<string, unknown>;
+    } else if (parsed !== null && parsed !== undefined) {
+      throw new Error("Frontmatter must be a YAML mapping (key: value pairs)");
+    }
+  }
+
+  return { frontmatter, body: body.trim() };
+}

package/src/schemas/process.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { Budget } from "./common.js";
+import { parseFrontmatter } from "./frontmatter.js";
+
+/**
+ * What kicks off a process. Agents are event-driven and otherwise idle — a
+ * process does no work until its trigger fires.
+ * - `manual`: started by the owner (chat / button / API).
+ * - `schedule`: started on a cron expression.
+ * - `event`: started by an external event (webhook / MCP) keyed by `event`.
+ */
+export const ProcessTrigger = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("manual") }).strict(),
+  z.object({ type: z.literal("schedule"), cron: z.string().min(1) }).strict(),
+  z.object({ type: z.literal("event"), event: z.string().min(1) }).strict(),
+]);
+export type ProcessTrigger = z.infer<typeof ProcessTrigger>;
+
+/**
+ * A first-class playbook. Processes are how work actually flows — they cut
+ * across the org hierarchy. The `owner` role decomposes the playbook into task
+ * contracts and dispatches them; `participants` are roles the process may
+ * involve.
+ *
+ * The markdown body is the playbook itself (the steps, in prose), handed to the
+ * owning agent as the goal to decompose.
+ */
+export const ProcessSpec = z
+  .object({
+    name: z.string().min(1),
+    trigger: ProcessTrigger.default({ type: "manual" }),
+    /** Role that owns execution (decomposes + dispatches). Must resolve to an agent. */
+    owner: z.string().min(1),
+    /** Roles this process may involve, for routing/validation. */
+    participants: z.array(z.string().min(1)).default([]),
+    /** Explicit, checkable completion criteria. Drives termination. */
+    definitionOfDone: z.string().min(1),
+    /**
+     * Step names (or tool names) that always require human approval regardless
+     * of per-tool policy — a process-level safety gate.
+     */
+    approvals: z.array(z.string().min(1)).default([]),
+    /** Budget ceiling for one run of this process. */
+    budget: Budget.optional(),
+    /** The playbook steps, sourced from the markdown body. */
+    playbook: z.string().min(1, "process.md must have a non-empty body (the playbook)"),
+  })
+  .strict();
+export type ProcessSpec = z.infer<typeof ProcessSpec>;
+
+/** Parse and validate raw `*.process.md` content. Throws ZodError on invalid input. */
+export function parseProcessSpec(source: string): ProcessSpec {
+  const { frontmatter, body } = parseFrontmatter(source);
+  return ProcessSpec.parse({ ...frontmatter, playbook: body });
+}

package/src/schemas/tools.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { PermissionPolicy } from "./common.js";
+
+/**
+ * One MCP server the agent may connect to. Mirrors the Claude Agent SDK's
+ * McpServerConfig shape so entries can be passed through to the runtime with
+ * minimal translation. Credentials in `env` are resolved from the host
+ * environment at spawn time — never stored in the registry snapshot verbatim
+ * where they could leak into logs.
+ */
+export const McpServerSpec = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("stdio"),
+      command: z.string().min(1),
+      args: z.array(z.string()).optional(),
+      /** Env var names to forward from the host (values resolved at spawn). */
+      env: z.array(z.string()).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("http"),
+      url: z.string().url(),
+      headers: z.record(z.string()).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("sse"),
+      url: z.string().url(),
+      headers: z.record(z.string()).optional(),
+    })
+    .strict(),
+]);
+export type McpServerSpec = z.infer<typeof McpServerSpec>;
+
+/** A tool the agent may use, with its human-in-the-loop permission policy. */
+export const ToolGrant = z
+  .object({
+    name: z.string().min(1),
+    /** Default `ask` — consequential tools pause for human approval. */
+    policy: PermissionPolicy.default("ask"),
+    /** Optional note shown to the approver explaining what the tool does. */
+    description: z.string().optional(),
+  })
+  .strict();
+export type ToolGrant = z.infer<typeof ToolGrant>;
+
+/**
+ * The authored shape of a `tools.json` file: which tools and MCP servers an
+ * agent may use, and the permission policy for each tool.
+ */
+export const ToolsConfig = z
+  .object({
+    tools: z.array(ToolGrant).default([]),
+    mcpServers: z.record(McpServerSpec).default({}),
+    /** Default policy for any tool not explicitly listed in `tools`. */
+    defaultPolicy: PermissionPolicy.default("ask"),
+    /**
+     * Which built-in SDK file tools to auto-expose. `readonly` (default) gives
+     * the agent Read/Glob/Grep so it can read its staged files. `none` withholds
+     * them — for pure-judgment / memory-only agents that have no files to read
+     * and would otherwise waste turns wandering the filesystem. Explicitly
+     * granted built-ins (e.g. WebSearch) are unaffected either way.
+     */
+    builtins: z.enum(["readonly", "none"]).optional(),
+  })
+  .strict();
+export type ToolsConfig = z.infer<typeof ToolsConfig>;
+
+/** Parse and validate raw `tools.json` content. Throws ZodError on invalid input. */
+export function parseToolsConfig(source: string): ToolsConfig {
+  const data: unknown = JSON.parse(source);
+  return ToolsConfig.parse(data);
+}
+
+/** The config an agent gets when it has no `tools.json` — no tools, all `ask`. */
+export const EMPTY_TOOLS_CONFIG: ToolsConfig = {
+  tools: [],
+  mcpServers: {},
+  defaultPolicy: "ask",
+};