@pugi/cli 0.1.0-beta.12 → 0.1.0-beta.13

package/dist/tools/agent-tool.js

@@ -0,0 +1,192 @@
+/**
+ * `agent` tool — β2 S3 (2026-05-26).
+ *
+ * Exposes the subagent spawn primitive as a first-class tool call so
+ * the root Mira persona (or any orchestrator-capable parent loop) can
+ * delegate a brief to a specialist child via the standard tool-use
+ * grammar instead of via the legacy `<pugi-delegate>` XML sidechannel.
+ *
+ * Grammar:
+ *
+ *   {
+ *     "role":    "coder" | "verifier" | "reviewer" | "researcher" | ...,
+ *     "brief":   "one-paragraph task description",
+ *     "isolation":  "worktree" | "shared_fs" | "auto"   // optional, default "auto"
+ *   }
+ *
+ * Returns a JSON envelope:
+ *
+ *   {
+ *     "ok":          true,
+ *     "taskId":      "subagent-<uuid>",
+ *     "role":        "coder",
+ *     "personaSlug": "dev",
+ *     "status":      "shipped" | "blocked" | "failed",
+ *     "summary":     "...",
+ *     "filesChanged": ["src/...", "src/..."],
+ *     "toolCallCount": N,
+ *     "tokensIn":  N,
+ *     "tokensOut": N,
+ *     "durationMs": N,
+ *     "worktreePath":  "/path/.pugi/worktrees/<uuid>"  // only when worktree isolation used
+ *   }
+ *
+ * Why expose this as a tool rather than baking it into the engine
+ * loop directly:
+ *
+ *   - The model's existing tool-use grammar is what every modern Anvil
+ *     provider speaks natively. Wrapping delegation as a tool means the
+ *     model can decide WHEN to spawn a child the same way it decides
+ *     when to read/edit/bash — no special-case prompt engineering.
+ *   - The `agent` tool is gated by the isolation-matrix capability map
+ *     (only `orchestrator`-class roles see it in their tools schema).
+ *     A coder/reviewer/verifier cannot recursively spawn grandchildren
+ *     because they never see the `agent` tool in the first place.
+ *   - The audit log threads cleanly: parent's `tool_call: agent(...)`
+ *     pairs with the child's `subagent.spawned/tool_call/completed`
+ *     events, and a single SSE replay yields the full tree.
+ */
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { relative as relativePath } from 'node:path';
+import { spawnSubagentWithOutcome } from '../core/subagents/spawn.js';
+/**
+ * Argument schema. `isolation: 'auto'` defers to the role-default
+ * isolation tier (set by `isolationForRole` in dispatcher.ts). The
+ * explicit `worktree` opt-in forces worktree isolation even for roles
+ * whose default is `shared_fs_serialized`; `shared_fs` does the
+ * inverse (forces shared-fs even for roles whose default is `worktree`).
+ *
+ * The role enum mirrors the SDK's SubagentRole — keep both in lockstep.
+ */
+export const agentToolArgsSchema = z.object({
+    role: z.enum([
+        'orchestrator',
+        'architect',
+        'coder',
+        'verifier',
+        'reviewer',
+        'researcher',
+        'release',
+        'devops',
+        'design_qa',
+    ]),
+    brief: z
+        .string()
+        .min(1, 'brief must not be empty')
+        .max(8000, 'brief must be ≤ 8000 chars'),
+    isolation: z.enum(['worktree', 'shared_fs', 'auto']).optional(),
+});
+/**
+ * Dispatch a subagent via the `agent` tool. Returns the JSON envelope
+ * the executor wraps into the tool result frame. Throws when the
+ * arguments fail schema validation — the executor catches and feeds
+ * the message back to the model so it can correct itself.
+ */
+export async function agentTool(args, ctx) {
+    const validated = agentToolArgsSchema.parse(args);
+    if (!ctx.engineClient) {
+        // Hard refusal: the `agent` tool is real-backend-only. Surfacing a
+        // structured envelope (instead of throwing) lets the model decide
+        // whether to abandon the delegation or to fall back to in-process
+        // work. Throwing here would terminate the parent loop on a tool
+        // error frame, which is the wrong UX when the issue is config.
+        return {
+            ok: false,
+            taskId: `subagent-rejected-${randomUUID()}`,
+            role: validated.role,
+            personaSlug: '',
+            status: 'failed',
+            summary: 'agent tool unavailable: no engine client wired through the parent dispatch. '
+                + 'Run pugi via the standard CLI entrypoints; the in-memory test harness does '
+                + 'not currently support real subagent spawn.',
+            filesChanged: [],
+            toolCallCount: 0,
+            tokensIn: 0,
+            tokensOut: 0,
+            durationMs: 0,
+        };
+    }
+    // β2 S10 pre-flight (best-effort): refuse the spawn if the child's
+    // role-default token budget exceeds the parent's remaining budget.
+    // The check is conservative — it uses the child's DEFAULT envelope
+    // because we do not know the actual run cost ahead of time. Roles
+    // can downscale via SubagentTask.budget overrides; this gate just
+    // catches the gross case (parent has 5k left, child default 80k).
+    if (ctx.parentBudgetRemaining?.tokens !== undefined) {
+        const { budgetForRole } = await import('../core/subagents/dispatcher.js');
+        const childDefault = budgetForRole(validated.role, undefined);
+        if (childDefault.tokens > ctx.parentBudgetRemaining.tokens) {
+            return {
+                ok: false,
+                taskId: `subagent-budget-refused-${randomUUID()}`,
+                role: validated.role,
+                personaSlug: '',
+                status: 'blocked',
+                summary: `agent spawn refused: child '${validated.role}' default budget is ${childDefault.tokens} tokens `
+                    + `but parent has only ${ctx.parentBudgetRemaining.tokens} tokens remaining. `
+                    + 'Tighten the child task budget or finish the parent first.',
+                filesChanged: [],
+                toolCallCount: 0,
+                tokensIn: 0,
+                tokensOut: 0,
+                durationMs: 0,
+            };
+        }
+    }
+    const task = {
+        id: `subagent-${randomUUID()}`,
+        role: validated.role,
+        prompt: validated.brief,
+        // `auto` permission mode matches the parent loop's default; the
+        // isolation-matrix capability gate provides the load-bearing
+        // restriction layer regardless of permissionMode.
+        permissionMode: 'auto',
+    };
+    const useWorktree = validated.isolation === 'worktree'
+        ? true
+        : validated.isolation === 'shared_fs'
+            ? false
+            : undefined; // 'auto' → defer to role default
+    const outcome = await spawnSubagentWithOutcome(task, ctx.session, {
+        engineClient: ctx.engineClient,
+        ...(useWorktree !== undefined ? { useWorktreeIsolation: useWorktree } : {}),
+    });
+    const envelope = {
+        // `ok` = subagent did not crash. Both `shipped` (real work) and
+        // `replied` (text-only completion, added 2026-05-26) count as
+        // non-crash outcomes; the caller can branch on the explicit
+        // `status` field below if it needs to distinguish them.
+        ok: outcome.result.status === 'shipped' || outcome.result.status === 'replied',
+        taskId: outcome.result.taskId,
+        role: outcome.result.role,
+        personaSlug: outcome.result.personaSlug,
+        status: outcome.result.status,
+        summary: outcome.result.summary,
+        filesChanged: outcome.result.filesChanged,
+        toolCallCount: outcome.result.toolCallCount,
+        tokensIn: outcome.result.tokensIn,
+        tokensOut: outcome.result.tokensOut,
+        durationMs: outcome.result.durationMs,
+    };
+    if (outcome.worktreeHandle) {
+        // β2a r2 (Codex P1, 2026-05-26): emit the worktree path RELATIVE to
+        // the parent session's workspace root. The envelope is JSON-stringified
+        // into the parent loop's tool_result frame and from there flows to the
+        // provider on every subsequent assistant turn — shipping the absolute
+        // path (`/Users/<operator>/Web/.../.pugi/worktrees/<uuid>`) leaks the
+        // operator's home directory to the upstream provider on every spawn.
+        //
+        // The composeSummary path (dispatcher-real.ts §β2a r1) already scrubs
+        // the summary text via the same `relative()` wrapping; this is the
+        // matching fix for the structured envelope field that r1 missed.
+        // The relative form (`.pugi/worktrees/<uuid>`) is enough for the
+        // operator's local `pugi worktree promote/drop` commands which run
+        // resolved against ctx.session.root anyway.
+        const relPath = relativePath(ctx.session.root, outcome.worktreeHandle.path)
+            || outcome.worktreeHandle.path;
+        envelope.worktreePath = relPath;
+    }
+    return envelope;
+}
+//# sourceMappingURL=agent-tool.js.map

package/dist/tools/apply-patch.js

@@ -261,6 +261,25 @@ export function applyPatch(ctx, patch, opts = {}) {
         recordToolResult(ctx.session, toolCallId, 'error', 'empty_patch');
         return result;
     }
+    // β7 L4: pre-flight conflict-marker check. A patch that still carries
+    // unresolved `<<<<<<<`/`=======`/`>>>>>>>` lines is almost always
+    // operator error (copy-pasted a half-resolved merge instead of the
+    // clean diff). `git apply` would reject it with a confusing
+    // "corrupt patch" message; the dedicated reason makes the failure
+    // obvious. We only check at body line starts so a legitimate diff
+    // that adds a string literal containing `<<<<<<<` for tests still
+    // applies.
+    if (containsConflictMarkers(patch)) {
+        const result = {
+            ok: false,
+            filesChanged: [],
+            reason: 'conflict_markers',
+            detail: 'patch body contains unresolved git conflict markers (<<<<<<<, =======, >>>>>>>). ' +
+                'Resolve the conflict first or use --3way with --base=<sha> to defer to git.',
+        };
+        recordToolResult(ctx.session, toolCallId, 'error', 'conflict_markers');
+        return result;
+    }
     const paths = extractPatchPaths(patch);
     if (paths.length === 0) {
         const result = {
@@ -486,10 +505,52 @@ function runGit(args, cwd, stdin) {
         env: { ...process.env, LANG: 'C', LC_ALL: 'C' },
     });
 }
+/**
+ * β7 L4: detect unresolved git conflict markers in a patch body.
+ *
+ * Conflict markers in a unified diff are a sign of operator error —
+ * someone copy-pasted a half-merged file instead of the clean diff.
+ * `git apply` would reject the patch with a confusing parse error
+ * ("corrupt patch at line N"). We check at the START of body lines so
+ * a legitimate diff that adds a string literal containing `<<<<<<<`
+ * (rare but legitimate for tests) still applies.
+ *
+ * Conflict marker bytes in a unified diff body look like:
+ *
+ *   +<<<<<<< HEAD
+ *   +=======
+ *   +>>>>>>> branch
+ *
+ * The `+` prefix is the unified-diff line-add marker. We strip it
+ * before the marker check; without the strip, an INVERSE diff that
+ * REMOVES a real conflict marker (legitimate cleanup commit) would be
+ * a false positive.
+ *
+ * Returns true when ANY conflict marker is detected.
+ */
+export function containsConflictMarkers(patch) {
+    for (const line of patch.split('\n')) {
+        // Only inspect body lines (start with `+` or `-` — the diff add/del
+        // markers). Header lines (`diff --git`, `+++`, `---`, `@@`) are
+        // skipped because the marker tokens cannot appear in those positions.
+        if (!(line.startsWith('+') || line.startsWith('-')))
+            continue;
+        // Skip diff header lines (`+++ b/foo` / `--- a/foo`).
+        if (line.startsWith('+++') || line.startsWith('---'))
+            continue;
+        const body = line.slice(1);
+        if (body.startsWith('<<<<<<<') ||
+            body.startsWith('>>>>>>>') ||
+            body === '=======') {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Test-only surface for the apply-patch heuristics. Specs poke
  * `extractPatchPaths` directly to assert on the path-parsing layer
  * without paying for a real git invocation.
  */
-export const __test__ = { extractPatchPaths, runGit, unquoteGitPath };
+export const __test__ = { extractPatchPaths, runGit, unquoteGitPath, containsConflictMarkers };
 //# sourceMappingURL=apply-patch.js.map

package/dist/tools/mcp-tool.js

@@ -0,0 +1,260 @@
+import { callTool } from '../core/mcp/client.js';
+import { getMcpPermission, setMcpPermission, } from '../core/mcp/permission.js';
+/**
+ * Tool dispatcher for MCP-invoked tools (β4 M1 + M3 + M5).
+ *
+ * Tool names use the `mcp__<server>__<tool>` namespace (double-underscore
+ * separator, mirroring Claude Code's MCP envelope). The triple-underscore
+ * forms (`mcp__server__tool__sub`) collapse into the third segment when
+ * the upstream server itself uses underscores in its tool names — `split`
+ * on the first two `__` only, so any further `__` in the tool name part
+ * survive intact (e.g. `mcp__github__create_issue` -> server=`github`,
+ * tool=`create_issue`).
+ *
+ * Why double-underscore: native Pugi tools use single-token names
+ * (`read`, `grep`, `edit`, `bash`). The double-underscore prefix
+ * unambiguously segregates the MCP namespace from native names without
+ * needing per-name regex matching at every dispatch site.
+ *
+ * Permission flow:
+ *   1. Server trust gate (handled at registry-load time). If a server is
+ *      not `trusted`, its tools never reach the engine loop.
+ *   2. Per-(server, tool) permission cache (`./mcp/permission.ts`).
+ *      Unset on first dispatch -> caller must prompt. Cached `allow_always`
+ *      auto-passes; cached `deny` auto-refuses.
+ *
+ * This module is the bridge — it parses the namespaced name, finds the
+ * live connection in the registry, consults the cache, and (when
+ * approved) routes through `client.callTool`. Prompting is the executor's
+ * responsibility; this module exposes the cache lookup + dispatch
+ * primitives so the executor stays small.
+ */
+/**
+ * Prefix every MCP tool name carries on the engine-loop wire.
+ */
+export const MCP_TOOL_PREFIX = 'mcp__';
+/**
+ * Parse `mcp__<server>__<tool>` into `{ serverName, toolName }`. Returns
+ * null when the input does not match the namespace — callers use this as
+ * the "is this an MCP tool?" predicate.
+ *
+ * Server names cannot contain `__` by registry validation (they are JSON
+ * object keys); tool names CAN (e.g. `create_issue` has a single `_` but
+ * `read_directory` has none, so the only ambiguity is when an upstream
+ * tool uses double-underscore in its slug — extremely rare, but if it
+ * happens the second `__` boundary still parses correctly because we
+ * split on the FIRST occurrence after the prefix).
+ */
+export function parseMcpToolName(name) {
+    if (!name.startsWith(MCP_TOOL_PREFIX))
+        return null;
+    const tail = name.slice(MCP_TOOL_PREFIX.length);
+    const sep = tail.indexOf('__');
+    if (sep === -1)
+        return null;
+    const serverName = tail.slice(0, sep);
+    const toolName = tail.slice(sep + 2);
+    if (serverName.length === 0 || toolName.length === 0)
+        return null;
+    return { serverName, toolName };
+}
+/**
+ * Build the namespaced tool name from a server + tool pair. Inverse of
+ * `parseMcpToolName`. Used by `buildMcpToolDefs` to emit the schema.
+ */
+export function buildMcpToolName(serverName, toolName) {
+    return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
+}
+/**
+ * Build engine-loop tool definitions from every trusted server's
+ * surfaced tools. Empty array when no MCP servers are trusted — the
+ * schema builder can call this unconditionally without checking first.
+ */
+export function buildMcpToolDefs(registry) {
+    if (!registry)
+        return [];
+    const defs = [];
+    for (const state of registry.servers.values()) {
+        if (state.trust !== 'trusted')
+            continue;
+        for (const tool of state.surfacedTools) {
+            defs.push({
+                name: buildMcpToolName(state.name, tool.name),
+                description: descriptionFor(state.name, tool),
+                // The upstream server returns its own JSON Schema in `inputSchema`.
+                // We surface it verbatim — the loop client passes it through to
+                // the model, and the model emits arguments matching the upstream
+                // shape. Default to `{ type: 'object' }` when missing so the
+                // OpenAI-shaped tool envelope still validates.
+                parameters: tool.inputSchema ?? { type: 'object' },
+            });
+        }
+    }
+    // Sort stable so the schema bundle hash (used for caching/audit) is
+    // deterministic regardless of Map iteration order.
+    return defs.sort((a, b) => a.name.localeCompare(b.name));
+}
+function descriptionFor(serverName, tool) {
+    const base = tool.description?.trim() ?? `MCP tool ${tool.name} on server ${serverName}.`;
+    return `[MCP:${serverName}] ${base}`;
+}
+/**
+ * Look up the live connection + tool metadata for a parsed MCP tool name.
+ * Returns null when the server is not trusted, not connected, or does
+ * not expose the named tool. Callers MUST handle null — never throw,
+ * because the model may emit stale tool names after a server restart.
+ */
+export function resolveMcpTool(registry, parsed) {
+    if (!registry)
+        return null;
+    const state = registry.servers.get(parsed.serverName);
+    if (!state || state.trust !== 'trusted' || !state.connection)
+        return null;
+    const tool = state.surfacedTools.find((t) => t.name === parsed.toolName);
+    if (!tool)
+        return null;
+    return { state, connection: state.connection, tool };
+}
+/**
+ * The default prompt — used when no interactive bridge is wired (CI,
+ * non-TTY pipes). Returns `deny` so an unattended run never silently
+ * fires an MCP call the operator never approved. The deny is NOT
+ * persisted, so the next run with a wired prompt still has a chance to
+ * approve.
+ */
+export const defaultNonInteractiveMcpPrompt = async () => 'unset';
+/**
+ * Dispatch one MCP tool call. The flow:
+ *
+ *   1. Parse the namespaced tool name. Return error string when
+ *      malformed — the model sees the error and can self-correct.
+ *   2. Resolve the live connection. Return error when the server is not
+ *      trusted/connected or the tool is unknown.
+ *   3. Consult the permission cache. `deny` short-circuits. `allow_always`
+ *      proceeds. `unset` invokes the prompt; the operator's verdict is
+ *      persisted (allow_always/deny) or used one-shot (allow_once).
+ *   4. Parse the arguments string. Bad JSON -> error string.
+ *   5. Call `client.callTool` and stringify the content for the model.
+ *
+ * Throws ONLY on unrecoverable transport failures (e.g. the connection
+ * died mid-call). Tool-level errors from the upstream server are
+ * surfaced as `[MCP error] <message>` strings so the model can recover.
+ */
+export async function dispatchMcpTool(input) {
+    const parsed = parseMcpToolName(input.name);
+    if (!parsed) {
+        return `[MCP dispatch error] tool name "${input.name}" does not match the ${MCP_TOOL_PREFIX}<server>__<tool> namespace`;
+    }
+    const resolved = resolveMcpTool(input.registry, parsed);
+    if (!resolved) {
+        return `[MCP dispatch error] no trusted+connected server "${parsed.serverName}" exposes a tool named "${parsed.toolName}"`;
+    }
+    let args;
+    try {
+        args = parseArgumentsRaw(input.argumentsRaw);
+    }
+    catch (error) {
+        return `[MCP dispatch error] invalid JSON in arguments for ${input.name}: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    // Permission gate.
+    const cached = getMcpPermission(parsed.serverName, parsed.toolName);
+    let effective = cached;
+    if (cached === 'unset') {
+        const verdict = await input.prompt({
+            serverName: parsed.serverName,
+            toolName: parsed.toolName,
+            toolDescription: resolved.tool.description ?? '',
+            callArguments: args,
+        });
+        effective = verdict;
+        if (verdict === 'allow_always' || verdict === 'deny') {
+            setMcpPermission(parsed.serverName, parsed.toolName, verdict, resolveDecidedBy(input.decidedBy));
+        }
+    }
+    if (effective === 'deny') {
+        return `[MCP refused] operator denied ${parsed.serverName}:${parsed.toolName}`;
+    }
+    if (effective !== 'allow_once' && effective !== 'allow_always') {
+        // Includes `unset` returned by the non-interactive default prompt.
+        return `[MCP refused] no operator approval for ${parsed.serverName}:${parsed.toolName} (run from a TTY to approve)`;
+    }
+    // Dispatch.
+    let result;
+    try {
+        result = await callTool(resolved.connection, parsed.toolName, args, {
+            ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        });
+    }
+    catch (error) {
+        // Transport-level failure (timeout, child died mid-call). Surface
+        // as a recoverable string so the model can degrade gracefully.
+        return `[MCP transport error] ${parsed.serverName}:${parsed.toolName}: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    return renderMcpToolResult(result.content, result.isError, parsed);
+}
+function parseArgumentsRaw(raw) {
+    if (!raw || raw.trim() === '')
+        return {};
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('arguments must be a JSON object');
+    }
+    return parsed;
+}
+function resolveDecidedBy(override) {
+    return (override?.trim() ||
+        process.env.PUGI_TRUSTED_BY?.trim() ||
+        process.env.USER?.trim() ||
+        process.env.USERNAME?.trim() ||
+        'cli');
+}
+/**
+ * Project the MCP `content` payload into a single text string the model
+ * can ingest. MCP servers reply with `content: [{ type: 'text', text }]`
+ * by convention; we concatenate every `type: text` chunk and surface a
+ * `[MCP non-text content]` marker for other content kinds (images,
+ * resource references) which are not yet wired into Pugi's loop.
+ *
+ * `isError: true` from the upstream maps to a `[MCP error] ...` prefix
+ * so the model knows the call failed at the server, not at the
+ * transport.
+ */
+export function renderMcpToolResult(content, isError, parsed) {
+    const text = projectTextContent(content);
+    const prefix = isError ? `[MCP error ${parsed.serverName}:${parsed.toolName}] ` : '';
+    if (text === null) {
+        // Fallback to a JSON dump so the model sees SOMETHING — better than
+        // an opaque empty string when the upstream uses image / resource
+        // content kinds.
+        try {
+            return `${prefix}${JSON.stringify(content)}`;
+        }
+        catch {
+            return `${prefix}[MCP non-serialisable content]`;
+        }
+    }
+    return `${prefix}${text}`;
+}
+function projectTextContent(content) {
+    if (content === null || content === undefined)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const parts = [];
+    for (const entry of content) {
+        if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+            const obj = entry;
+            if (obj.type === 'text' && typeof obj.text === 'string') {
+                parts.push(obj.text);
+                continue;
+            }
+        }
+        // Non-text chunk — record a marker so the model knows something was
+        // dropped from the response.
+        parts.push('[MCP non-text content chunk]');
+    }
+    return parts.join('\n');
+}
+//# sourceMappingURL=mcp-tool.js.map