@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/tools/agent-tool.js

@@ -1,229 +0,0 @@
-/**
- * `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