@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.41

package/dist/tools/agent-tool.js

@@ -0,0 +1,229 @@
+/**
+ * `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';
+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 (2026-05-27): `z.strictObject` rejects ANY additional or
+ * aliased fields at parse time. Matches the openclaude FileEditTool /
+ * FileWriteTool posture (research memo §1.1). 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 (2026-05-27): 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 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