@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/tools/agent-tool.js

@@ -0,0 +1,229 @@
+/**
+ * `agent` tool — β2 S3 .
+ *
+ * Exposes the subagent spawn primitive as a first-class tool call so
+ * the root Pugi 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';
+import { inheritCacheContext } from '../core/dispatch/cache-handoff.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.
+ *
+ * Leak P0 L2 : `z.strictObject` rejects ANY additional or
+ * aliased fields at parse time. Matches the the standard file-edit grammar /
+ * FileWriteTool posture (). The model-facing JSON
+ * schema already declares `additionalProperties: false`; the strict
+ * Zod variant is defense-in-depth — if the bridge ever bypasses the
+ * model-side gate (raw test fixture, internal dispatch), the runtime
+ * still refuses unknown keys instead of silently dropping them.
+ */
+export const agentToolArgsSchema = z.strictObject({
+    role: z.enum([
+        'orchestrator',
+        'architect',
+        'coder',
+        'verifier',
+        'reviewer',
+        'researcher',
+        'release',
+        'devops',
+        'design_qa',
+    ]).describe('SubagentRole — selects persona + isolation tier.'),
+    brief: z
+        .string()
+        .min(1, 'brief must not be empty')
+        .max(8000, 'brief must be ≤ 8000 chars')
+        .describe('One-paragraph task description forwarded to the child as the user prompt. '
+        + 'Be concrete: include filenames, expected behavior, and acceptance criteria.'),
+    isolation: z
+        .enum(['worktree', 'shared_fs', 'auto'])
+        .optional()
+        .describe('Optional override. `worktree` forces a scratch git worktree for write isolation; '
+        + '`shared_fs` forces same-tree execution; `auto` (default) defers to the role tier.'),
+});
+/**
+ * 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',
+    };
+    // L10 : synthesize a prompt-cache inheritance handle for
+    // the child before we dispatch. The handle is persisted under
+    // `.pugi/cache-refs/<childAgentId>.json` so:
+    //  - The child engine loop's first turn (dispatcher-real.ts) can
+    //    forward parent_cache_id onto Anvil — provider-dependent honour
+    //    (Anthropic cache_control breakpoints today; OpenAI/Gemini
+    //    silently ignore until Anvil grows per-provider adapters).
+    //  - Operators can introspect via `pugi dispatch list-cache-refs`.
+    //  - `pugi dispatch clear-cache-refs --older-than 1h` can GC after
+    //    a long session.
+    // Failure to persist must NOT block the dispatch — the handle is a
+    // best-effort optimisation; if disk is full or the workspace root is
+    // read-only, we degrade silently to a cache-miss dispatch.
+    try {
+        inheritCacheContext(ctx.session.id, task.id, {
+            workspaceRoot: ctx.session.root,
+            ...(ctx.now ? { now: ctx.now } : {}),
+        });
+    }
+    catch {
+        // Silent degrade: cache inheritance is forward-compat, not load-bearing.
+    }
+    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) 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): 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

@@ -1,22 +1,22 @@
 /**
- * apply_patch tool — α7.7 Phase 1.
+ * apply_patch tool — Phase 1.
  *
  * Accepts a unified diff (the format produced by `git diff` and
  * consumed by `git apply`) and lands it atomically into the workspace.
- * This is the third edit primitive alongside the α6.6 4-layer diff
+ * This is the third edit primitive alongside the 4-layer diff
  * escalation: where the layers escalate from minimal `oldString`/
  * `newString` blocks up to full-file rewrites, apply_patch covers the
  * unified-diff dialect that OpenAI Codex and most external tools emit.
  *
  * Why we have both:
  *
- *   - The 4-layer escalation maximises model-side success rate on
- *     conversational edits (Claude / Gemini / OpenAI all have a
- *     preferred dialect that maps onto one of the layers).
- *   - apply_patch is the "external tools speak this" path. A model
- *     emits a single unified diff (the format `git diff` produces),
- *     and we run it through `git apply` with the same security gate
- *     the layers use.
+ *  - The 4-layer escalation maximises model-side success rate on
+ *    conversational edits (Claude / Gemini / OpenAI all have a
+ *    preferred dialect that maps onto one of the layers).
+ *  - apply_patch is the "external tools speak this" path. A model
+ *    emits a single unified diff (the format `git diff` produces),
+ *    and we run it through `git apply` with the same security gate
+ *    the layers use.
  *
  * Security: every file mentioned in the patch goes through the same
  * `applySecurityGate` chokepoint as the layers (see
@@ -55,7 +55,7 @@ import { recordToolCall, recordToolResult, recordFileMutation } from '../core/se
  * touched paths feeds the security gate — EVERY file goes through
  * `applySecurityGate` before we trust `git apply` to do anything.
  *
- * Security (R1 fix 2026-05-26, PR #413 r1): git emits C-style quoted
+ * Security (R1 fix, PR r1): git emits C-style quoted
  * path headers when a path contains "unusual" bytes (high bits, control
  * chars, double-quote, backslash) and `core.quotePath` is true (the
  * default). The literal header looks like
@@ -140,11 +140,11 @@ function stripQuotedHalf(after, prefix) {
  * (default) git writes paths with high-bit / control / quote bytes as
  * C-string escapes inside double quotes:
  *
- *   `"\.env"` -> `.env`         (backslash before . is just a literal)
- *   `"a\"b"`  -> `a"b`          (escaped double-quote)
- *   `"a\\b"`  -> `a\b`          (escaped backslash)
- *   `"a\tb"`  -> `a` + TAB + `b`
- *   `"a\341\210\264"` -> `a` + UTF-8 bytes 0xe1 0x88 0xb4
+ *  `"\.env"` -> `.env`        (backslash before . is just a literal)
+ *  `"a\"b"` -> `a"b`         (escaped double-quote)
+ *  `"a\\b"` -> `a\b`         (escaped backslash)
+ *  `"a\tb"` -> `a` + TAB + `b`
+ *  `"a\341\210\264"` -> `a` + UTF-8 bytes 0xe1 0x88 0xb4
  *
  * Accepts a path that is EITHER already unquoted (passed through) OR an
  * inner string previously stripped of its surrounding quotes. The
@@ -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 = {
@@ -272,12 +291,12 @@ export function applyPatch(ctx, patch, opts = {}) {
         recordToolResult(ctx.session, toolCallId, 'error', 'invalid_patch');
         return result;
     }
-    // SECURITY GATE — reuse the α6.6 chokepoint. Every path in the patch
+    // SECURITY GATE — reuse the chokepoint. Every path in the patch
     // is validated against:
-    //   1. workspace containment (no ../../ escapes)
-    //   2. protected-file basenames (.env, *.pem, id_rsa, etc.)
-    //   3. symlink escape (an in-workspace symlink pointing to /etc/hosts
-    //      or a protected basename gets rejected here)
+    //  1. workspace containment (no ../../ escapes)
+    //  2. protected-file basenames (.env, *.pem, id_rsa, etc.)
+    //  3. symlink escape (an in-workspace symlink pointing to /etc/hosts
+    //     or a protected basename gets rejected here)
     for (const file of paths) {
         const gate = applySecurityGate(file, { cwd: ctx.root, toolName: 'layer-c' });
         if (!gate.ok) {
@@ -349,7 +368,7 @@ export function applyPatch(ctx, patch, opts = {}) {
         recordToolResult(ctx.session, toolCallId, 'success', `dry-run ok, ${paths.length} files`);
         return result;
     }
-    // R1 fix (2026-05-26, PR #413 r1, Fix 6): snapshot which paths exist
+    // R1 fix (2026-05-26, PR r1, Fix 6): snapshot which paths exist
     // BEFORE the apply so rollbackFiles can decide between
     // `git checkout -- <file>` (for files that existed) and `fs.rmSync`
     // (for files the patch was creating that may have been half-written
@@ -409,16 +428,16 @@ export function applyPatch(ctx, patch, opts = {}) {
  * only on the rare path where `git apply` fails AFTER `git apply --check`
  * passed.
  *
- * R1 fix (2026-05-26, PR #413 r1, Fix 6): a multi-file patch that
+ * R1 fix (2026-05-26, PR r1, Fix 6): a multi-file patch that
  * creates new files leaves them on disk when `git apply` fails partway —
  * `git checkout -- <file>` does NOT delete a path that was never tracked
  * (the file was created by the failed apply). We split paths into two
  * groups using the pre-apply snapshot:
  *
- *   - existed-before  -> `git checkout -- <file>` restores tracked content.
- *   - created-by-apply -> `fs.rmSync(file, { force: true })` removes the
- *     half-written file so the workspace ends up identical to its
- *     pre-apply state.
+ *  - existed-before -> `git checkout -- <file>` restores tracked content.
+ *  - created-by-apply -> `fs.rmSync(file, { force: true })` removes the
+ *    half-written file so the workspace ends up identical to its
+ *    pre-apply state.
  *
  * This keeps the dispatcher's invariant: a tool result of `ok: false`
  * means the workspace is unchanged.
@@ -470,7 +489,7 @@ function rollbackFiles(cwd, paths, preExisting) {
     return { ok: true };
 }
 function runGit(args, cwd, stdin) {
-    // R1 fix (2026-05-26, PR #413 r1, P2 #13): force the English C locale
+    // R1 fix (2026-05-26, PR r1, P2 #13): force the English C locale
     // for the git child process. The `already_applied` reason-coding
     // below greps stderr for the literal English string
     // "already exists in working directory"; on a host where git was
@@ -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