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

package/dist/core/subagents/dispatcher.js

@@ -1,352 +0,0 @@
-/**
- * Subagent dispatcher (β2 S1 + S4 —).
- *
- * The dispatcher is the runtime side of the @pugi/sdk subagent contracts.
- * Given a SubagentTask, it:
- *
- *  1. Resolves the role to a Cyber-Zoo persona via the local registry
- *     (apps/pugi-cli/src/core/agents/registry.ts, which itself sources
- *     @pugi/personas).
- *  2. Classifies isolation per the matrix (see isolationForRole).
- *  3. Builds the dispatch-time permission overrides (Vera as reviewer
- *     or verifier loses every edit/write/bash class — see
- *     permissionOverridesForRole).
- *  4. Emits subagent.spawned into the session events log.
- *  5. Drives the dispatch via one of two backends:
- *     - REAL (β2 S1): when ctx carries an EngineLoopClient, the child
- *       runs a genuine `runEngineLoop` against Anvil with a per-child
- *       tools schema gated by the isolation-matrix capability map
- *       (β2 S4). See `dispatcher-real.ts::runRealDispatch`.
- *     - STUB (M1 legacy): when no engine client is supplied, the
- *       dispatcher returns a `shipped` result with zero metrics so
- *       the legacy `inMemoryDispatcherContext` test path stays green.
- *       This is the back-compat door for the M1 spec coverage.
- *  6. Emits subagent.completed | blocked | failed into the session
- *     events log (real backend emits richer details; stub emits the
- *     M1-compatible shape).
- *  7. Returns the typed SubagentResult.
- *
- * Why we kept the stub path: the existing M1 spec coverage exercises
- * the dispatcher's contract surface (role-to-persona, isolation tier,
- * permission overrides, event ordering) without any HTTP transport.
- * β2 must not regress that surface — every existing assertion still
- * holds for in-memory contexts. The real backend is a strict superset.
- *
- * The dispatcher is the only place that knows the isolation matrix and
- * the permission overrides. Both surfaces are exported so engine adapter
- * code, tests, and the future REPL can introspect a role without
- * actually running a dispatch.
- */
-import { randomUUID } from 'node:crypto';
-import { subagentTaskSchema } from '@pugi/sdk';
-import { getPersonaForRole } from '../agents/registry.js';
-/* ------------------------------------------------------------------ */
-/* Isolation matrix                                                  */
-/* ------------------------------------------------------------------ */
-/**
- * M1 isolation matrix .
- *
- * The function is pure (same role in, same isolation out) and exported
- * separately so consumers (tests, REPL UI) can introspect without
- * dispatching.
- */
-export function isolationForRole(role) {
-    switch (role) {
-        case 'orchestrator':
-            return 'prompt_only';
-        case 'architect':
-        case 'verifier':
-        case 'reviewer':
-        case 'researcher':
-            return 'shared_fs_readonly';
-        case 'coder':
-        case 'release':
-        case 'devops':
-        case 'design_qa':
-            return 'shared_fs_serialized';
-    }
-}
-/* ------------------------------------------------------------------ */
-/* Permission overrides                                              */
-/* ------------------------------------------------------------------ */
-/**
- * Per-role permission overrides applied at dispatch time. The dominant
- * case is Vera's dual-role rule :
- * when dispatched as verifier OR reviewer, Vera gets edit: deny (which
- * we generalize to deny edit + write + bash, the three classes that can
- * mutate the workspace) so a review pass cannot accidentally patch what
- * it is reviewing.
- *
- * Read-only research roles (architect, researcher) get the same
- * three-class deny because their shared_fs_readonly isolation tier is
- * the load-bearing contract; repeating the override at the permission
- * layer is defense in depth so a future bug in isolation classification
- * cannot silently grant a write.
- *
- * Write-capable roles (coder, release, devops, design_qa) get no
- * override; they inherit the workspace permission settings as-is.
- *
- * orchestrator also gets no override; Pugi runs inside the parent
- * context, so the parent's permission settings already govern her.
- */
-export function permissionOverridesForRole(role) {
-    switch (role) {
-        case 'verifier':
-        case 'reviewer':
-            return DENY_ALL_WRITES_VERA;
-        case 'architect':
-        case 'researcher':
-            return DENY_ALL_WRITES_READONLY;
-        case 'orchestrator':
-        case 'coder':
-        case 'release':
-        case 'devops':
-        case 'design_qa':
-            return [];
-    }
-}
-const DENY_ALL_WRITES_VERA = Object.freeze([
-    {
-        toolClass: 'edit',
-        allowedPaths: Object.freeze([]),
-        reason: 'Vera dispatched as verifier/reviewer ',
-    },
-    {
-        toolClass: 'write',
-        allowedPaths: Object.freeze([]),
-        reason: 'Vera dispatched as verifier/reviewer ',
-    },
-    {
-        toolClass: 'bash',
-        allowedPaths: Object.freeze([]),
-        reason: 'Vera dispatched as verifier/reviewer ',
-    },
-]);
-const DENY_ALL_WRITES_READONLY = Object.freeze([
-    {
-        toolClass: 'edit',
-        allowedPaths: Object.freeze([]),
-        reason: 'read-only role (shared_fs_readonly isolation tier)',
-    },
-    {
-        toolClass: 'write',
-        allowedPaths: Object.freeze([]),
-        reason: 'read-only role (shared_fs_readonly isolation tier)',
-    },
-    {
-        toolClass: 'bash',
-        allowedPaths: Object.freeze([]),
-        reason: 'read-only role (shared_fs_readonly isolation tier)',
-    },
-]);
-/* ------------------------------------------------------------------ */
-/* Default budgets                                                   */
-/* ------------------------------------------------------------------ */
-// CEO escalation 2026-06-05: 120K coder budget exhausted mid-React-
-// build (120214 > 120000). Match the engine-level `code` task bump
-// (apps/pugi-cli/src/core/engine/budgets.ts:149 — 400K). Subagent
-// dispatches inherit the upstream caller's headroom, so this needs
-// to track the engine envelope.
-const DEFAULT_BUDGETS = Object.freeze({
-    orchestrator: { tokens: 400_000, dollars: 8, wallClockMs: 900_000 },
-    architect: { tokens: 200_000, dollars: 4, wallClockMs: 600_000 },
-    coder: { tokens: 400_000, dollars: 8, wallClockMs: 900_000 },
-    verifier: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
-    reviewer: { tokens: 200_000, dollars: 4, wallClockMs: 600_000 },
-    researcher: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
-    release: { tokens: 80_000, dollars: 2, wallClockMs: 300_000 },
-    devops: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
-    design_qa: { tokens: 150_000, dollars: 3, wallClockMs: 600_000 },
-});
-/**
- * Resolve the effective budget for a dispatch by merging task overrides
- * onto the role default. Caller-supplied limits always tighten, never
- * relax — a missing field falls back to the role default.
- */
-export function budgetForRole(role, override) {
-    const base = DEFAULT_BUDGETS[role];
-    if (!override)
-        return base;
-    return {
-        tokens: override.tokens ?? base.tokens,
-        dollars: override.dollars ?? base.dollars,
-        wallClockMs: override.wallClockMs ?? base.wallClockMs,
-    };
-}
-/* ------------------------------------------------------------------ */
-/* Real-backend lazy import (memoized)                               */
-/* ------------------------------------------------------------------ */
-/**
- * β2a r1 (Backend Architect P1): cached lazy-import of
- * the real dispatch backend. Hoisting the dynamic import to
- * module scope (instead of running it on every dispatch call) means
- * the first agent spawn does not pay 50-200ms cold-start latency.
- *
- * The cache is a Promise so concurrent first-callers share one
- * import; ESM's own module cache also dedups but the Promise wrapper
- * lets `prewarmRealDispatch` kick off the import without awaiting.
- */
-let realDispatchPromise = null;
-function ensureRealDispatch() {
-    if (!realDispatchPromise) {
-        realDispatchPromise = import('./dispatcher-real.js');
-    }
-    return realDispatchPromise;
-}
-/**
- * β2a r1: pre-warm the real dispatcher's module graph. Called by the
- * engine adapter (`NativePugiEngineAdapter`) at construction time
- * when an engine client is wired, so the first `dispatch()` call
- * with `ctx.engineClient` set returns instantly. Safe to call
- * multiple times — subsequent calls hit the cached promise.
- */
-export function prewarmRealDispatch() {
-    return ensureRealDispatch();
-}
-/**
- * Spawn a subagent. Two backends:
- *
- *  - REAL (β2 S1): when `ctx.engineClient` is set, the dispatcher
- *    spawns a genuine child engine loop. See `dispatcher-real.ts`.
- *    The child's tool surface is filtered by the isolation matrix
- *    (β2 S4) so a `researcher` role cannot see `write`/`edit`/`bash`
- *    in its tools schema and the executor refuses if the model
- *    fabricates a call.
- *
- *  - STUB (M1 legacy): when no engine client is supplied, the
- *    dispatcher returns a `shipped` result with zero metrics. This
- *    is the back-compat door for the M1 spec coverage and for
- *    in-memory consumers that only want to assert the dispatcher's
- *    CONTRACT surface (role-to-persona, isolation tier, permission
- *    overrides, event ordering) without standing up Anvil.
- *
- * The function rejects with ZodError when the task fails schema
- * validation. Throwing rather than returning a failed result is the
- * right call here: a malformed dispatch is a caller bug, not a subagent
- * failure, and surfacing it as a thrown error keeps the audit log
- * clean.
- */
-export async function dispatch(task, ctx) {
-    const validated = subagentTaskSchema.parse(task);
-    if (ctx.engineClient) {
-        // β2a r1 (Backend Architect P1): the lazy import
-        // chain (worktree + engine SDK graph) cost 50-200ms on the FIRST
-        // dispatch call. `ensureRealDispatch` memoizes the promise so the
-        // import happens at most once per process; subsequent dispatches
-        // hit the cached promise instantly. Production callers should
-        // prewarm via `prewarmRealDispatch()` at engine adapter init so
-        // the operator never pays cold-start on the first agent call.
-        const { runRealDispatch } = await ensureRealDispatch();
-        const outcome = await runRealDispatch(validated, {
-            sessionId: ctx.sessionId,
-            workspaceRoot: ctx.workspaceRoot,
-            appendEvent: ctx.appendEvent,
-            ...(ctx.now ? { now: ctx.now } : {}),
-            engineClient: ctx.engineClient,
-            ...(ctx.commandKind ? { commandKind: ctx.commandKind } : {}),
-            ...(ctx.useWorktreeIsolation !== undefined
-                ? { useWorktreeIsolation: ctx.useWorktreeIsolation }
-                : {}),
-            ...(ctx.signal ? { signal: ctx.signal } : {}),
-        });
-        return outcome.result;
-    }
-    return runStubDispatch(validated, ctx);
-}
-/**
- * Real-backend variant that also surfaces the optional worktree
- * handle. Callers that need to promote/drop the scratch worktree
- * (e.g. the REPL `/agent` surface, or the Agent tool dispatcher) use
- * this entry point.
- */
-export async function dispatchWithOutcome(task, ctx) {
-    const validated = subagentTaskSchema.parse(task);
-    if (ctx.engineClient) {
-        const { runRealDispatch } = await ensureRealDispatch();
-        return runRealDispatch(validated, {
-            sessionId: ctx.sessionId,
-            workspaceRoot: ctx.workspaceRoot,
-            appendEvent: ctx.appendEvent,
-            ...(ctx.now ? { now: ctx.now } : {}),
-            engineClient: ctx.engineClient,
-            ...(ctx.commandKind ? { commandKind: ctx.commandKind } : {}),
-            ...(ctx.useWorktreeIsolation !== undefined
-                ? { useWorktreeIsolation: ctx.useWorktreeIsolation }
-                : {}),
-            ...(ctx.signal ? { signal: ctx.signal } : {}),
-        });
-    }
-    const result = await runStubDispatch(validated, ctx);
-    return { result };
-}
-async function runStubDispatch(validated, ctx) {
-    const persona = getPersonaForRole(validated.role);
-    const isolation = isolationForRole(validated.role);
-    void budgetForRole(validated.role, validated.budget);
-    void permissionOverridesForRole(validated.role);
-    const now = ctx.now ?? defaultNow;
-    const startedAt = Date.now();
-    ctx.appendEvent({
-        id: randomUUID(),
-        sessionId: ctx.sessionId,
-        timestamp: now(),
-        type: 'subagent.spawned',
-        taskId: validated.id,
-        role: validated.role,
-        personaSlug: persona.slug,
-        parentSessionId: ctx.sessionId,
-        isolation,
-    });
-    const status = 'shipped';
-    const summary = stubSummaryFor(validated.role, persona.name);
-    const result = {
-        taskId: validated.id,
-        role: validated.role,
-        personaSlug: persona.slug,
-        status,
-        summary,
-        filesChanged: [],
-        toolCallCount: 0,
-        tokensIn: 0,
-        tokensOut: 0,
-        durationMs: Date.now() - startedAt,
-    };
-    ctx.appendEvent({
-        id: randomUUID(),
-        sessionId: ctx.sessionId,
-        timestamp: now(),
-        type: 'subagent.completed',
-        taskId: result.taskId,
-        role: result.role,
-        personaSlug: result.personaSlug,
-        toolCallCount: result.toolCallCount,
-        tokensIn: result.tokensIn,
-        tokensOut: result.tokensOut,
-        durationMs: result.durationMs,
-    });
-    return result;
-}
-function stubSummaryFor(role, personaName) {
-    return `${personaName} (${role}) dispatched: in-memory stub backend (no engine client supplied; production callers should pass DispatcherContext.engineClient)`;
-}
-function defaultNow() {
-    return new Date().toISOString();
-}
-/* ------------------------------------------------------------------ */
-/* Convenience helpers                                               */
-/* ------------------------------------------------------------------ */
-/**
- * Build a dispatch context tied to an in-memory event sink. Useful for
- * unit tests that want to assert on emitted events without standing up
- * a real .pugi/ directory. Production callers use spawnSubagent (in
- * sibling spawn.ts), which closes over a real PugiSession.
- */
-export function inMemoryDispatcherContext(input) {
-    return {
-        sessionId: input.sessionId,
-        workspaceRoot: input.workspaceRoot,
-        appendEvent: (event) => input.sink.push(event),
-        now: input.now,
-    };
-}
-//# sourceMappingURL=dispatcher.js.map

package/dist/core/subagents/index.js

@@ -1,39 +0,0 @@
-/**
- * Subagent runtime surface for the Pugi CLI (Sprint a5.4 — M1 gap
- * remediation D).
- *
- * Re-exports the dispatcher + helpers under a single import path so
- * engine adapter code, the REPL, and tests can pull in everything they
- * need with one import statement:
- *
- *  import { dispatch, isolationForRole, ... } from '../core/subagents/index.js';
- *
- * The submodule index does not re-export persona types — those live in
- * @pugi/personas and are pulled in by core/agents/registry.ts. Mixing
- * the persona surface and the dispatcher surface in a single barrel
- * would invite the kind of accidental drift the persona-registry
- * extraction was designed to prevent.
- */
-export { budgetForRole, dispatch, dispatchWithOutcome, inMemoryDispatcherContext, isolationForRole, permissionOverridesForRole, } from './dispatcher.js';
-/**
- * β2 S4: per-role capability matrix. Surfaced via the barrel so
- * engine adapter code, the Agent tool, and tests can introspect a
- * role's allowed tool set without importing the matrix module
- * directly.
- */
-export { allowedToolsForRole, capabilitiesForRole, roleHasToolAccess, ROLE_CAPABILITIES, } from './isolation-matrix.js';
-/**
- * β2 S1: real-backend entry point. Exposed for callers that want to
- * drive the dispatch with the worktree handle in scope (e.g. the
- * Agent tool, the REPL `/agent` surface). Most callers should prefer
- * the `dispatch()` / `dispatchWithOutcome()` helpers above which
- * route to this module when ctx.engineClient is set.
- */
-export { runRealDispatch } from './dispatcher-real.js';
-/**
- * Spawn a subagent from inside the engine adapter loop. Re-exported via
- * the barrel so engine code does not have to import the dispatcher
- * module directly.
- */
-export { spawnSubagent, spawnSubagentWithOutcome } from './spawn.js';
-//# sourceMappingURL=index.js.map

package/dist/core/subagents/isolation-matrix.js

@@ -1,213 +0,0 @@
-const CAP_READ_ONLY = new Set([
-    'read',
-    'task',
-    'skill',
-]);
-const CAP_VERIFIER = new Set([
-    'read',
-    'task',
-    'skill',
-    // β2a r1 (Codex P1): verifier previously got the FULL
-    // `bash` capability. The class-aware bash tool defaults to
-    // permission mode `auto`, which permits `write_workspace` class
-    // commands (e.g. `echo x > src/file.ts`, `sed -i`, `rm`). That
-    // silently bypassed the no-edit/no-write contract — a verifier
-    // could mutate the workspace it was meant to read.
-    //
-    // The fix splits bash into two capabilities:
-    //  - `bash`         → full bash (writers only)
-    //  - `bash_read_only` → bash gate that forces read-only classifier
-    //                       mode regardless of operator settings
-    // verifier needs the read-only flavor so test commands (pnpm test,
-    // jest --listFiles, typecheck) still work but a fabricated
-    // `echo x > file.ts` is refused at the executor layer.
-    'bash_read_only',
-]);
-const CAP_WRITER = new Set([
-    'read',
-    'write',
-    'bash',
-    'task',
-    'skill',
-    'ask_user',
-]);
-const CAP_FULL = new Set([
-    'read',
-    'write',
-    'bash',
-    'task',
-    'skill',
-    'ask_user',
-    'web_fetch',
-    'agent',
-]);
-/**
- * Per-role capability map. Add a new role only when the matching
- * isolation tier classification in dispatcher.ts agrees with the
- * capability set here — drift would let a `coder` role get write
- * privileges with `shared_fs_readonly` isolation, which would mean
- * the dispatcher emits readonly-isolation events while the child
- * actually writes. Always touch both files together.
- */
-export const ROLE_CAPABILITIES = new Map([
-    [
-        'orchestrator',
-        {
-            role: 'orchestrator',
-            capabilities: CAP_FULL,
-            rationale: 'orchestrator (Pugi/Pugi) runs in parent context with full toolset; '
-                + 'parent permissions still gate any actual mutation',
-        },
-    ],
-    [
-        'architect',
-        {
-            role: 'architect',
-            capabilities: CAP_READ_ONLY,
-            rationale: 'architect role is read-only by design (analysis + planning, no mutations)',
-        },
-    ],
-    [
-        'coder',
-        {
-            role: 'coder',
-            capabilities: CAP_WRITER,
-            rationale: 'coder role mutates the workspace via write + edit + bash',
-        },
-    ],
-    [
-        'verifier',
-        {
-            role: 'verifier',
-            capabilities: CAP_VERIFIER,
-            rationale: 'verifier role reads workspace + executes verification commands (tests, typecheck) '
-                + 'but never edits the code it is verifying',
-        },
-    ],
-    [
-        'reviewer',
-        {
-            role: 'reviewer',
-            capabilities: CAP_READ_ONLY,
-            rationale: 'reviewer role is read-only by policy (no edits to code under review); '
-                + 'shell is denied because reviewer should not be re-running tests',
-        },
-    ],
-    [
-        'researcher',
-        {
-            role: 'researcher',
-            capabilities: CAP_READ_ONLY,
-            rationale: 'researcher role is read-only (corpus search + summarization)',
-        },
-    ],
-    [
-        'release',
-        {
-            role: 'release',
-            capabilities: CAP_WRITER,
-            rationale: 'release role needs write + bash for changelog edits + version bumps',
-        },
-    ],
-    [
-        'devops',
-        {
-            role: 'devops',
-            capabilities: CAP_WRITER,
-            rationale: 'devops role needs write + bash for infra config + deploy scripts',
-        },
-    ],
-    [
-        'design_qa',
-        {
-            role: 'design_qa',
-            capabilities: CAP_WRITER,
-            rationale: 'design_qa role needs write + bash for UI tweaks + screenshot scripts',
-        },
-    ],
-]);
-/**
- * Resolve the capability set for a role. Throws when the role is not
- * registered — the closed SubagentRole union prevents that at compile
- * time for typed callers, but the runtime guard catches dynamic dispatch
- * paths (e.g. a tag parsed off Pugi's reply text).
- */
-export function capabilitiesForRole(role) {
-    const entry = ROLE_CAPABILITIES.get(role);
-    if (!entry) {
-        throw new Error(`capabilitiesForRole: unknown role '${role}'`);
-    }
-    return entry;
-}
-/**
- * Map capability classes → concrete tool names (matches tool-bridge.ts
- * WIRED_TOOLS). This is the bridge between the policy layer (this file)
- * and the schema-shaping layer (tool-bridge buildToolsSchema). Keep in
- * lockstep with WIRED_TOOLS — a new tool added to the bridge should
- * be classified here so subagents see (or do not see) it consistently.
- */
-const CAPABILITY_TO_TOOLS = {
-    read: ['read', 'grep', 'glob'],
-    write: ['write', 'edit'],
-    bash: ['bash'],
-    // β2a r1 : `bash_read_only` maps to the same `bash`
-    // tool name so the model sees only one tool surface. The
-    // dispatcher-real executor wraps the verifier's bash calls with a
-    // forced read-only classifier mode (see `gatedExecutor` in
-    // dispatcher-real.ts) so a `write_workspace`-class command is
-    // rejected before the tool runs even though the capability set
-    // appears to advertise `bash`.
-    bash_read_only: ['bash'],
-    task: ['task_create', 'task_get', 'task_list', 'task_update'],
-    skill: ['skill', 'skills_list'],
-    ask_user: ['ask_user_question'],
-    web_fetch: ['web_fetch'],
-    // Agent tool is the subagent spawn primitive itself (S3). Only the
-    // orchestrator role gets it — child agents cannot recursively spawn
-    // grand-children, which keeps the spawn depth bounded at 1 and the
-    // budget rollup tractable.
-    agent: ['agent'],
-};
-/**
- * Return the set of tool names a role is allowed to call. Used by the
- * per-child tool-bridge to shape the OpenAI tools schema AND by the
- * executor refusal gate.
- *
- * The function is pure — same role in, same set out — so the schema
- * builder can call it from inside `buildToolsSchema`.
- */
-export function allowedToolsForRole(role) {
-    const caps = capabilitiesForRole(role);
-    const out = new Set();
-    for (const cap of caps.capabilities) {
-        for (const name of CAPABILITY_TO_TOOLS[cap]) {
-            out.add(name);
-        }
-    }
-    return out;
-}
-/**
- * Predicate: is a tool name reachable by a role under the capability
- * matrix? Used by the executor's pre-dispatch refusal gate.
- *
- * Returns true for orchestrator/full-capability roles and for every
- * specific tool the role's capability set unlocks; false otherwise.
- */
-export function roleHasToolAccess(role, toolName) {
-    return allowedToolsForRole(role).has(toolName);
-}
-/**
- * β2a r1 (Codex P1): predicate identifying roles whose
- * bash access is restricted to read-only classifier mode. Used by
- * dispatcher-real.ts's gatedExecutor to force-flag bash dispatches as
- * read-only regardless of the workspace's permission settings.
- *
- * A role qualifies when it holds `bash_read_only` but NOT the
- * full-power `bash` capability — orchestrators (which inherit both
- * via CAP_FULL) keep full bash access through the regular path.
- */
-export function bashIsReadOnlyForRole(role) {
-    const caps = capabilitiesForRole(role).capabilities;
-    return caps.has('bash_read_only') && !caps.has('bash');
-}
-//# sourceMappingURL=isolation-matrix.js.map