@yycholla/pi-dynamic-workflows 3.3.0

package/dist/accept-workflow-guidance.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { WORKFLOW_AUTHORING_FROZEN_FILES } from "./workflow-authoring-coverage.js";
+const COVERAGE_MANIFEST_PATH = "src/workflow-authoring-coverage.ts";
+function sha256(source) {
+    return createHash("sha256").update(source).digest("hex");
+}
+function manifestEntry(path, hash) {
+    return `    path: ${JSON.stringify(path)},\n    sha256: ${JSON.stringify(hash)},`;
+}
+/**
+ * Accepts reviewed changes to explicitly named frozen workflow-authoring files.
+ *
+ * Throws before writing when no path is supplied, a path is not frozen, a file
+ * is missing, or the coverage manifest no longer contains the expected entry.
+ */
+export function acceptWorkflowGuidance(root, requestedPaths) {
+    if (requestedPaths.length === 0) {
+        throw new Error("Pass at least one frozen workflow-authoring path to accept.");
+    }
+    const frozenByPath = new Map(WORKFLOW_AUTHORING_FROZEN_FILES.map((entry) => [entry.path, entry]));
+    const paths = [...new Set(requestedPaths.map((path) => path.replace(/^\.\//, "")))];
+    const entries = paths.map((path) => {
+        const frozen = frozenByPath.get(path);
+        if (frozen === undefined) {
+            throw new Error(`${path} is not a frozen workflow-authoring guidance file.`);
+        }
+        const absolute = join(root, path);
+        if (!existsSync(absolute)) {
+            throw new Error(`Frozen workflow-authoring guidance file is missing: ${path}.`);
+        }
+        return {
+            path,
+            previousSha256: frozen.sha256,
+            sha256: sha256(readFileSync(absolute, "utf8")),
+        };
+    });
+    const manifestPath = join(root, COVERAGE_MANIFEST_PATH);
+    const originalManifest = readFileSync(manifestPath, "utf8");
+    let nextManifest = originalManifest;
+    for (const entry of entries) {
+        const previous = manifestEntry(entry.path, entry.previousSha256);
+        if (!nextManifest.includes(previous)) {
+            throw new Error(`Coverage manifest does not contain the expected frozen entry for ${entry.path}.`);
+        }
+        nextManifest = nextManifest.replace(previous, manifestEntry(entry.path, entry.sha256));
+    }
+    if (nextManifest !== originalManifest) {
+        writeFileSync(manifestPath, nextManifest);
+    }
+    return entries.map((entry) => ({ ...entry, changed: entry.previousSha256 !== entry.sha256 }));
+}

package/dist/adversarial-review.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Adversarial review mode for workflows.
+ * Agents cross-check each other's findings for higher quality results.
+ */
+export interface AdversarialReviewConfig {
+    /** Number of independent reviewers per finding. */
+    reviewerCount: number;
+    /** Whether to filter out findings that don't survive cross-checking. */
+    filterContested: boolean;
+    /** Minimum agreement threshold (0-1). */
+    agreementThreshold: number;
+}
+/**
+ * Generate an adversarial-review workflow. The script is static and reads its
+ * inputs from `args` (task/reviewers/threshold) — no string interpolation.
+ *
+ * Each finding is judged independently by N reviewers who are told to REFUTE it;
+ * a finding survives only when the share of reviewers calling it real meets the
+ * agreement threshold.
+ */
+export declare function generateAdversarialReviewWorkflow(): string;
+/**
+ * Generate a multi-perspective analysis workflow.
+ *
+ * `topic` and each `perspectives` entry are user-supplied strings baked
+ * directly into the generated script's source, so every one is embedded via
+ * JSON.stringify — a proper JS string literal that can't be broken out of by
+ * a quote, backslash, or backtick in the value.
+ */
+export declare function generateMultiPerspectiveWorkflow(topic: string, perspectives: string[]): string;

package/dist/adversarial-review.js

@@ -0,0 +1,107 @@
+/**
+ * Adversarial review mode for workflows.
+ * Agents cross-check each other's findings for higher quality results.
+ */
+/**
+ * Generate an adversarial-review workflow. The script is static and reads its
+ * inputs from `args` (task/reviewers/threshold) — no string interpolation.
+ *
+ * Each finding is judged independently by N reviewers who are told to REFUTE it;
+ * a finding survives only when the share of reviewers calling it real meets the
+ * agreement threshold.
+ */
+export function generateAdversarialReviewWorkflow() {
+    return `export const meta = {
+  name: 'adversarial_review',
+  description: 'Adversarial review: findings cross-checked by independent skeptics',
+  phases: [
+    { title: 'Investigate' },
+    { title: 'Refute' },
+    { title: 'Consensus' },
+  ],
+}
+
+const task = (args && args.task) || ''
+const reviewers = (args && args.reviewers) || 2
+const threshold = (args && args.threshold) || 0.5
+
+phase('Investigate')
+const investigation = await agent(
+  'Investigate the following and list concrete, individually-checkable findings:\\n' + task,
+  { label: 'investigate', schema: { type: 'object', properties: { findings: { type: 'array', items: { type: 'string' } } }, required: ['findings'] } }
+)
+const findings = investigation.findings || []
+
+phase('Refute')
+const judged = await parallel(findings.map((f, i) => () =>
+  parallel(Array.from({ length: reviewers }, (_, r) => () =>
+    agent(
+      'You are a skeptical reviewer. Try to REFUTE this finding for the task below. ' +
+      'Default to real=false when uncertain. Investigate with the available tools if needed.\\n\\n' +
+      'TASK: ' + task + '\\nFINDING: ' + f,
+      { label: 'refute ' + (i + 1) + '.' + (r + 1), schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } }, required: ['real'] } }
+    )
+  )).then((votes) => {
+    const valid = votes.filter(Boolean)
+    const realCount = valid.filter((v) => v && v.real).length
+    const ratio = valid.length ? realCount / valid.length : 0
+    return { finding: f, realVotes: realCount, totalVotes: valid.length, survives: ratio >= threshold }
+  })
+))
+
+const survivors = judged.filter((j) => j && j.survives)
+
+phase('Consensus')
+const report = await agent(
+  'Write a final review report. Include ONLY the findings that survived adversarial review (listed below), ' +
+  'each with a short justification. Note how many were discarded.\\n\\n' +
+  'SURVIVING FINDINGS JSON:\\n' + JSON.stringify(survivors),
+  { label: 'consensus' }
+)
+
+return { total: findings.length, survivors, report }`;
+}
+/**
+ * Generate a multi-perspective analysis workflow.
+ *
+ * `topic` and each `perspectives` entry are user-supplied strings baked
+ * directly into the generated script's source, so every one is embedded via
+ * JSON.stringify — a proper JS string literal that can't be broken out of by
+ * a quote, backslash, or backtick in the value.
+ */
+export function generateMultiPerspectiveWorkflow(topic, perspectives) {
+    const perspectiveAgents = perspectives
+        .map((p, i) => {
+        const label = p
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 20) || `perspective-${i + 1}`;
+        return `  () => agent(${JSON.stringify(`Analyze from ${p} perspective: `)} + topic, { label: ${JSON.stringify(label)} }),`;
+    })
+        .join("\n");
+    return `export const meta = {
+  name: 'multi_perspective_analysis',
+  description: ${JSON.stringify(`Analyze from ${perspectives.length} different perspectives`)},
+  phases: [
+    { title: 'Perspective Analysis' },
+    { title: 'Synthesis' },
+  ],
+};
+
+phase('Perspective Analysis');
+const topic = ${JSON.stringify(topic)};
+const analyses = await parallel([
+${perspectiveAgents}
+]);
+
+phase('Synthesis');
+const synthesis = await agent(
+  'Synthesize these different perspectives into a balanced analysis:\\n' +
+  'Analyses: ' + JSON.stringify(analyses) + '\\n' +
+  'Topic: ' + topic,
+  { label: 'synthesizer' }
+);
+
+return { analyses, synthesis };`;
+}

package/dist/agent-history.d.ts

@@ -0,0 +1,20 @@
+export type AgentHistoryRole = "user" | "assistant" | "tool";
+export type AgentHistoryKind = "text" | "toolCall" | "toolResult" | "error";
+export interface AgentHistoryEntry {
+    role: AgentHistoryRole;
+    kind: AgentHistoryKind;
+    text: string;
+    toolName?: string;
+    /** Source path for file-oriented tool calls rendered specially by the pager. */
+    path?: string;
+    /** Pi's display-oriented edit diff, preserved from EditToolDetails. */
+    diff?: string;
+    isError?: boolean;
+    timestamp?: number;
+}
+export interface AgentHistoryOptions {
+    maxEntries?: number;
+    maxTextChars?: number;
+    maxTotalChars?: number;
+}
+export declare function compactAgentHistory(messages: unknown[], options?: AgentHistoryOptions): AgentHistoryEntry[];

package/dist/agent-history.js

@@ -0,0 +1,122 @@
+const DEFAULT_MAX_ENTRIES = 40;
+const DEFAULT_MAX_TEXT_CHARS = 2000;
+const DEFAULT_MAX_TOTAL_CHARS = 20000;
+export function compactAgentHistory(messages, options = {}) {
+    const maxEntries = positiveInt(options.maxEntries, DEFAULT_MAX_ENTRIES);
+    const maxTextChars = positiveInt(options.maxTextChars, DEFAULT_MAX_TEXT_CHARS);
+    const maxTotalChars = positiveInt(options.maxTotalChars, DEFAULT_MAX_TOTAL_CHARS);
+    const entries = [];
+    for (const raw of messages) {
+        const message = asRecord(raw);
+        if (!message)
+            continue;
+        const role = message.role;
+        const timestamp = typeof message.timestamp === "number" ? message.timestamp : undefined;
+        if (role === "user") {
+            const text = textFromContent(message.content);
+            if (text.trim())
+                entries.push({ role: "user", kind: "text", text, timestamp });
+            continue;
+        }
+        if (role === "assistant") {
+            for (const part of Array.isArray(message.content) ? message.content : []) {
+                const block = asRecord(part);
+                if (!block || typeof block.type !== "string")
+                    continue;
+                if (block.type === "text" && typeof block.text === "string" && block.text.trim()) {
+                    entries.push({ role: "assistant", kind: "text", text: block.text, timestamp });
+                }
+                else if (block.type === "toolCall" && typeof block.name === "string") {
+                    const args = asRecord(block.arguments);
+                    const filePath = (block.name === "write" || block.name === "edit") && typeof args?.path === "string" ? args.path : undefined;
+                    const writeContent = block.name === "write" && filePath && typeof args?.content === "string" ? args.content : undefined;
+                    entries.push({
+                        role: "assistant",
+                        kind: "toolCall",
+                        toolName: block.name,
+                        // A write's JSON envelope is both noisy and likely to be truncated
+                        // into invalid JSON. Preserve its source directly so the pager can
+                        // render it as code. Edit calls retain their path so the pager can
+                        // pair the compact call header with the result's native Pi diff.
+                        text: writeContent ?? stringifyCompact(block.arguments ?? {}),
+                        path: filePath,
+                        timestamp,
+                    });
+                }
+            }
+            if (typeof message.errorMessage === "string" && message.errorMessage.trim()) {
+                entries.push({ role: "assistant", kind: "error", text: message.errorMessage, isError: true, timestamp });
+            }
+            continue;
+        }
+        if (role === "toolResult") {
+            const toolName = typeof message.toolName === "string" ? message.toolName : undefined;
+            const text = textFromContent(message.content) || "(no text output)";
+            const details = asRecord(message.details);
+            const diff = toolName === "edit" && typeof details?.diff === "string" ? details.diff : undefined;
+            entries.push({
+                role: "tool",
+                kind: message.isError ? "error" : "toolResult",
+                toolName,
+                text,
+                diff,
+                isError: Boolean(message.isError),
+                timestamp,
+            });
+        }
+    }
+    return fitEntries(entries, maxEntries, maxTextChars, maxTotalChars);
+}
+function fitEntries(entries, maxEntries, maxTextChars, maxTotalChars) {
+    const fitted = [];
+    let total = 0;
+    for (const entry of entries.slice(-maxEntries).reverse()) {
+        const remaining = maxTotalChars - total;
+        if (remaining <= 0)
+            break;
+        // Treat an edit diff as the entry's primary display payload. Keeping it
+        // within the same per-entry and total bounds prevents EditToolDetails from
+        // bypassing history compaction with a large changed file.
+        let entryBudget = Math.min(maxTextChars, remaining);
+        const diff = entry.diff ? truncateText(entry.diff, entryBudget) : undefined;
+        entryBudget -= diff?.length ?? 0;
+        const text = truncateText(entry.text, entryBudget);
+        fitted.unshift({ ...entry, text, diff });
+        total += text.length + (diff?.length ?? 0);
+    }
+    return fitted;
+}
+function textFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        const block = asRecord(part);
+        return block?.type === "text" && typeof block.text === "string" ? block.text : "";
+    })
+        .filter(Boolean)
+        .join("");
+}
+function stringifyCompact(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function truncateText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    if (maxChars <= 20)
+        return text.slice(0, maxChars);
+    return `${text.slice(0, maxChars - 20)}... [truncated]`;
+}
+function positiveInt(value, fallback) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : undefined;
+}

package/dist/agent-registry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Named workflow subagent definitions ("agentType" registry).
+ *
+ * A workflow script can route an agent() call to a reusable, named definition:
+ *
+ *   agent("audit this dir", { agentType: "security-auditor" })
+ *
+ * Definitions live as Markdown files under `.pi/agents/*.md` (project, cwd-relative)
+ * and `~/.pi/agent/agents/*.md` (user — `getAgentDir() + "agents"`, honoring the
+ * `PI_CODING_AGENT_DIR` override), matching pi-coding-agent's own built-in agent
+ * discovery convention. The legacy `~/.pi/agents/*.md` location is still scanned as
+ * a deprecated fallback (with a one-time warning) so users who followed this repo's
+ * earlier docs are not silently broken; the new location wins on a name collision.
+ * Frontmatter binds the subagent's tools, model, and a body prompt; project
+ * definitions win over both user-level locations on a name collision. This mirrors
+ * Claude Code's `.claude/agents` registry: agentType is a real binding of
+ * tools+model+system-prompt, not a prose hint.
+ *
+ * Bound today: `tools` (allowlist), `disallowedTools` (denylist), `model`,
+ * and the markdown body (`prompt`). Parsed-but-ignored for now (documented): `mcp`, `skills`, `background`.
+ * Wired: `isolation` ("worktree") → createWorktree() in workflow.ts.
+ */
+export interface AgentDefinition {
+    /** Stable identity used as the `agentType` value. */
+    name: string;
+    /** One-line summary (for discoverability in the tool guideline). */
+    description?: string;
+    /** Allowlist of coding-tool names the subagent may use. Undefined = all. */
+    tools?: string[];
+    /** Denylist of coding-tool names, applied after the allowlist. */
+    disallowedTools?: string[];
+    /** Model spec (`provider/modelId` or bare id) for this subagent. */
+    model?: string;
+    /** Isolation mode. When "worktree", agents using this type run in a git worktree. */
+    isolation?: "worktree";
+    /** Markdown body, prepended to the subagent's task as role guidance. */
+    prompt: string;
+    /** Where the definition was loaded from (project wins over user). */
+    source: "project" | "user";
+}
+export type AgentRegistry = Map<string, AgentDefinition>;
+/**
+ * Parse one agent-definition markdown file. Returns null only when there is no
+ * usable content (no name derivable and an empty body).
+ */
+export declare function parseAgentDefinition(content: string, source: "project" | "user", fileName: string): AgentDefinition | null;
+/**
+ * Load the agent registry once for a run. Scans the project dir, then the
+ * user dir, then — as a deprecated fallback — the legacy user dir; the FIRST
+ * definition for a name wins (project > user > legacy user, then filename
+ * order), so a name collision is resolved deterministically and silently.
+ *
+ * When a definition is only found at the legacy location (not shadowed by
+ * the new user dir), a single deprecation warning is logged for this call
+ * telling the user to move their files — not one warning per legacy file.
+ *
+ * `opts` overrides the scanned directories (used by tests).
+ */
+export declare function loadAgentRegistry(cwd: string, opts?: {
+    projectDir?: string;
+    userDir?: string;
+    legacyUserDir?: string;
+}): AgentRegistry;
+/** Resolve an agentType name to its definition, or undefined if not registered. */
+export declare function resolveAgentType(name: string | undefined, registry: AgentRegistry): AgentDefinition | undefined;
+/**
+ * Apply a definition's tool policy to a tool list: keep only allowlisted names
+ * (when an allowlist is given), then drop any denylisted names. Generic over any
+ * object with a `name` so it is unit-testable without real ToolDefinitions.
+ */
+export declare function applyToolPolicy<T extends {
+    name: string;
+}>(tools: T[], allow?: string[], deny?: string[]): T[];
+/**
+ * A stable identity string for a resolved definition, folded into the resume
+ * call-hash so editing an agent `.md` invalidates that call's cached result.
+ */
+export declare function agentDefinitionKey(def: AgentDefinition | undefined): string | null;
+/** List registered agent types for discoverability in the tool guideline. */
+export declare function listAgentTypes(registry: AgentRegistry): Array<{
+    name: string;
+    description?: string;
+}>;

package/dist/agent-registry.js

@@ -0,0 +1,190 @@
+/**
+ * Named workflow subagent definitions ("agentType" registry).
+ *
+ * A workflow script can route an agent() call to a reusable, named definition:
+ *
+ *   agent("audit this dir", { agentType: "security-auditor" })
+ *
+ * Definitions live as Markdown files under `.pi/agents/*.md` (project, cwd-relative)
+ * and `~/.pi/agent/agents/*.md` (user — `getAgentDir() + "agents"`, honoring the
+ * `PI_CODING_AGENT_DIR` override), matching pi-coding-agent's own built-in agent
+ * discovery convention. The legacy `~/.pi/agents/*.md` location is still scanned as
+ * a deprecated fallback (with a one-time warning) so users who followed this repo's
+ * earlier docs are not silently broken; the new location wins on a name collision.
+ * Frontmatter binds the subagent's tools, model, and a body prompt; project
+ * definitions win over both user-level locations on a name collision. This mirrors
+ * Claude Code's `.claude/agents` registry: agentType is a real binding of
+ * tools+model+system-prompt, not a prose hint.
+ *
+ * Bound today: `tools` (allowlist), `disallowedTools` (denylist), `model`,
+ * and the markdown body (`prompt`). Parsed-but-ignored for now (documented): `mcp`, `skills`, `background`.
+ * Wired: `isolation` ("worktree") → createWorktree() in workflow.ts.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { AGENTS_DIR } from "./config.js";
+function toStringArray(value) {
+    if (value == null)
+        return undefined;
+    // YAML list form: ["read", "grep"]
+    if (Array.isArray(value)) {
+        const arr = value.filter((v) => typeof v === "string" && v.trim().length > 0).map((v) => v.trim());
+        return arr.length ? arr : undefined;
+    }
+    // Comma-separated string form: "read, grep, find" — the form pi-coding-agent's
+    // parseFrontmatter returns and the form the official subagent example uses.
+    if (typeof value === "string" && value.trim().length > 0) {
+        const arr = value
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return arr.length ? arr : undefined;
+    }
+    return undefined;
+}
+/**
+ * Parse one agent-definition markdown file. Returns null only when there is no
+ * usable content (no name derivable and an empty body).
+ */
+export function parseAgentDefinition(content, source, fileName) {
+    let parsed;
+    try {
+        parsed = parseFrontmatter(content);
+    }
+    catch {
+        // Malformed frontmatter: treat the whole file as a body, name from filename.
+        parsed = { frontmatter: {}, body: content };
+    }
+    const fm = parsed.frontmatter;
+    const fmName = typeof fm.name === "string" ? fm.name.trim() : "";
+    const name = fmName || basename(fileName).replace(/\.md$/i, "").trim();
+    const prompt = parsed.body.trim();
+    if (!name && !prompt)
+        return null;
+    return {
+        name,
+        description: typeof fm.description === "string" ? fm.description.trim() || undefined : undefined,
+        tools: toStringArray(fm.tools),
+        disallowedTools: toStringArray(fm.disallowedTools),
+        model: typeof fm.model === "string" ? fm.model.trim() || undefined : undefined,
+        isolation: typeof fm.isolation === "string" && fm.isolation.toLowerCase().trim() === "worktree" ? "worktree" : undefined,
+        prompt,
+        source,
+    };
+}
+function readDefsFromDir(dir, source) {
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.toLowerCase().endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    const defs = [];
+    for (const file of files.sort()) {
+        try {
+            const def = parseAgentDefinition(readFileSync(join(dir, file), "utf-8"), source, file);
+            if (def)
+                defs.push(def);
+        }
+        catch {
+            // Skip unreadable/invalid files; never let one bad file break the registry.
+        }
+    }
+    return defs;
+}
+/**
+ * Load the agent registry once for a run. Scans the project dir, then the
+ * user dir, then — as a deprecated fallback — the legacy user dir; the FIRST
+ * definition for a name wins (project > user > legacy user, then filename
+ * order), so a name collision is resolved deterministically and silently.
+ *
+ * When a definition is only found at the legacy location (not shadowed by
+ * the new user dir), a single deprecation warning is logged for this call
+ * telling the user to move their files — not one warning per legacy file.
+ *
+ * `opts` overrides the scanned directories (used by tests).
+ */
+export function loadAgentRegistry(cwd, opts) {
+    const projectDir = opts?.projectDir ?? join(cwd, AGENTS_DIR);
+    // User-level definitions live under the agent dir (e.g. ~/.pi/agent/agents/),
+    // matching the convention used by pi-coding-agent's built-in agent discovery
+    // and the official subagent extension example. Reading getAgentDir() also
+    // honors the PI_CODING_AGENT_DIR env override.
+    const userDir = opts?.userDir ?? join(getAgentDir(), "agents");
+    // Deprecated: this repo's docs used to point users at ~/.pi/agents/ before
+    // pi-coding-agent's convention (~/.pi/agent/agents/) was known. Keep scanning
+    // it as a fallback so those files don't silently stop resolving.
+    const legacyUserDir = opts?.legacyUserDir ?? join(homedir(), AGENTS_DIR);
+    const registry = new Map();
+    for (const def of readDefsFromDir(projectDir, "project")) {
+        if (def.name && !registry.has(def.name))
+            registry.set(def.name, def);
+    }
+    if (userDir !== projectDir) {
+        for (const def of readDefsFromDir(userDir, "user")) {
+            if (def.name && !registry.has(def.name))
+                registry.set(def.name, def);
+        }
+    }
+    if (legacyUserDir !== projectDir && legacyUserDir !== userDir) {
+        let warnedLegacy = false;
+        for (const def of readDefsFromDir(legacyUserDir, "user")) {
+            if (def.name && !registry.has(def.name)) {
+                registry.set(def.name, def);
+                if (!warnedLegacy) {
+                    console.warn(`[agent-registry] Loaded agent definition(s) from the deprecated location "${legacyUserDir}". ` +
+                        `Move them to "${userDir}" — the old location may stop being read in a future release.`);
+                    warnedLegacy = true;
+                }
+            }
+        }
+    }
+    return registry;
+}
+/** Resolve an agentType name to its definition, or undefined if not registered. */
+export function resolveAgentType(name, registry) {
+    if (!name)
+        return undefined;
+    return registry.get(name);
+}
+/**
+ * Apply a definition's tool policy to a tool list: keep only allowlisted names
+ * (when an allowlist is given), then drop any denylisted names. Generic over any
+ * object with a `name` so it is unit-testable without real ToolDefinitions.
+ */
+export function applyToolPolicy(tools, allow, deny) {
+    let out = tools;
+    if (allow?.length) {
+        const allowSet = new Set(allow);
+        out = out.filter((t) => allowSet.has(t.name));
+    }
+    if (deny?.length) {
+        const denySet = new Set(deny);
+        out = out.filter((t) => !denySet.has(t.name));
+    }
+    return out;
+}
+/**
+ * A stable identity string for a resolved definition, folded into the resume
+ * call-hash so editing an agent `.md` invalidates that call's cached result.
+ */
+export function agentDefinitionKey(def) {
+    if (!def)
+        return null;
+    return JSON.stringify({
+        tools: def.tools ?? null,
+        disallowedTools: def.disallowedTools ?? null,
+        model: def.model ?? null,
+        isolation: def.isolation ?? null,
+        prompt: def.prompt,
+    });
+}
+/** List registered agent types for discoverability in the tool guideline. */
+export function listAgentTypes(registry) {
+    return [...registry.values()].map((d) => ({ name: d.name, description: d.description }));
+}