@pugi/cli 0.1.0-alpha.10

package/dist/core/subagents/dispatcher.js

@@ -0,0 +1,258 @@
+/**
+ * Subagent dispatcher (Sprint a5.4 — M1 gap remediation D).
+ *
+ * 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 M1 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. Runs the dispatch (M1: stub returning shipped immediately so the
+ *      contract surface is exercisable; M2+ swaps the body for
+ *      worktree-isolated execution backed by runEngineLoop).
+ *   6. Emits subagent.completed | blocked | failed into the session
+ *      events log.
+ *   7. Returns the typed SubagentResult.
+ *
+ * Why a stub at M1: the contract surface itself, the event emission, the
+ * isolation classification, and the permission overrides are real
+ * load-bearing pieces — the cabinet UI, audit replay, and triple-review
+ * gating all read these events. The model-driven loop that actually
+ * spawns a separate Anvil session is alpha-5.7 work (REPL-by-default).
+ * The stub returns a shipped result with the correct persona slug + role
+ * pair so downstream consumers can wire against the real shape.
+ *
+ * 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 (ADR-0056 Sprint a5.4 acceptance #2).
+ *
+ * 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 (ADR-0056 Sprint a5.4 acceptance #4):
+ * 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; Mira 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 (ADR-0056 section a5.4 acceptance #4)',
+    },
+    {
+        toolClass: 'write',
+        allowedPaths: Object.freeze([]),
+        reason: 'Vera dispatched as verifier/reviewer (ADR-0056 section a5.4 acceptance #4)',
+    },
+    {
+        toolClass: 'bash',
+        allowedPaths: Object.freeze([]),
+        reason: 'Vera dispatched as verifier/reviewer (ADR-0056 section a5.4 acceptance #4)',
+    },
+]);
+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                                                    */
+/* ------------------------------------------------------------------ */
+const DEFAULT_BUDGETS = Object.freeze({
+    orchestrator: { tokens: 200_000, dollars: 5, wallClockMs: 600_000 },
+    architect: { tokens: 80_000, dollars: 2, wallClockMs: 300_000 },
+    coder: { tokens: 120_000, dollars: 3, wallClockMs: 600_000 },
+    verifier: { tokens: 60_000, dollars: 2, wallClockMs: 300_000 },
+    reviewer: { tokens: 80_000, dollars: 2, wallClockMs: 300_000 },
+    researcher: { tokens: 60_000, dollars: 1.5, wallClockMs: 300_000 },
+    release: { tokens: 40_000, dollars: 1, wallClockMs: 180_000 },
+    devops: { tokens: 60_000, dollars: 2, wallClockMs: 300_000 },
+    design_qa: { tokens: 60_000, dollars: 1.5, wallClockMs: 300_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,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Dispatch                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * Spawn a subagent. M1 implementation is a stub that synchronously
+ * returns a shipped result so the contract surface is exercised by
+ * tests and the cabinet UI. M2+ replaces the body with an Anvil-side
+ * dispatch over a per-task worktree (ADR-0057, deferred).
+ *
+ * The function still emits real subagent.spawned and subagent.completed
+ * events; downstream consumers (audit replay, cabinet activity feed,
+ * eval harness) cannot tell the stub apart from a real dispatch on the
+ * event surface alone, which is the property we want for forward-
+ * compatibility testing.
+ *
+ * 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);
+    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: stub returning shipped (M1 contract surface only; real dispatch in alpha-5.7)`;
+}
+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

@@ -0,0 +1,26 @@
+/**
+ * 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, inMemoryDispatcherContext, isolationForRole, permissionOverridesForRole, } from './dispatcher.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. The actual task_dispatch tool that the model uses
+ * to invoke a subagent lands in alpha-5.7 (REPL); for now the helper
+ * exists so adapter code has a single seam to wire against.
+ */
+export { spawnSubagent } from './spawn.js';
+//# sourceMappingURL=index.js.map

package/dist/core/subagents/spawn.js

@@ -0,0 +1,86 @@
+import { recordSubagentBlocked, recordSubagentCompleted, recordSubagentFailed, recordSubagentSpawned, recordSubagentToolCall, } from '../session.js';
+import { dispatch } from './dispatcher.js';
+/**
+ * Spawn a subagent under an existing PugiSession. Events are routed
+ * through the session module's recorder functions; if the session is
+ * disabled (no .pugi/ directory), the recorders short-circuit and the
+ * dispatch still runs — the contract is "dispatch always works, audit
+ * is best-effort".
+ */
+export async function spawnSubagent(task, session) {
+    const ctx = {
+        sessionId: session.id,
+        workspaceRoot: session.root,
+        appendEvent: (event) => routeEvent(event, session),
+    };
+    return dispatch(task, ctx);
+}
+function routeEvent(event, session) {
+    if (!isRecord(event))
+        return;
+    const type = event['type'];
+    if (typeof type !== 'string')
+        return;
+    switch (type) {
+        case 'subagent.spawned':
+            recordSubagentSpawned(session, {
+                taskId: stringField(event, 'taskId'),
+                role: stringField(event, 'role'),
+                personaSlug: stringField(event, 'personaSlug'),
+                parentSessionId: stringField(event, 'parentSessionId'),
+                isolation: stringField(event, 'isolation'),
+            });
+            return;
+        case 'subagent.tool_call':
+            recordSubagentToolCall(session, {
+                taskId: stringField(event, 'taskId'),
+                role: stringField(event, 'role'),
+                personaSlug: stringField(event, 'personaSlug'),
+                toolName: stringField(event, 'toolName'),
+                toolCallId: stringField(event, 'toolCallId'),
+            });
+            return;
+        case 'subagent.completed':
+            recordSubagentCompleted(session, {
+                taskId: stringField(event, 'taskId'),
+                role: stringField(event, 'role'),
+                personaSlug: stringField(event, 'personaSlug'),
+                toolCallCount: numberField(event, 'toolCallCount'),
+                tokensIn: numberField(event, 'tokensIn'),
+                tokensOut: numberField(event, 'tokensOut'),
+                durationMs: numberField(event, 'durationMs'),
+            });
+            return;
+        case 'subagent.blocked':
+            recordSubagentBlocked(session, {
+                taskId: stringField(event, 'taskId'),
+                role: stringField(event, 'role'),
+                personaSlug: stringField(event, 'personaSlug'),
+                reason: stringField(event, 'reason'),
+                detail: stringField(event, 'detail'),
+            });
+            return;
+        case 'subagent.failed':
+            recordSubagentFailed(session, {
+                taskId: stringField(event, 'taskId'),
+                role: stringField(event, 'role'),
+                personaSlug: stringField(event, 'personaSlug'),
+                error: stringField(event, 'error'),
+            });
+            return;
+        default:
+            return;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringField(event, key) {
+    const v = event[key];
+    return typeof v === 'string' ? v : '';
+}
+function numberField(event, key) {
+    const v = event[key];
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+//# sourceMappingURL=spawn.js.map

package/dist/core/trust.js

@@ -0,0 +1,109 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+/**
+ * Project trust gate for workspace-scoped configs.
+ *
+ * Hooks under `<workspaceRoot>/.pugi/hooks.json` are dangerous: they execute
+ * arbitrary shell commands on every tool event. A malicious repo could ship
+ * a `.pugi/hooks.json` that exfiltrates secrets the first time a user runs
+ * `pugi code` inside it.
+ *
+ * The gate prevents this: project hooks load ONLY when the workspace root
+ * is explicitly trusted by the user. The trust ledger lives in
+ * `~/.pugi/trusted-workspaces.json` and is keyed by absolute path.
+ *
+ * The user-level config at `~/.pugi/hooks.json` is always loaded (the user
+ * authored it themselves on their own machine). Only project-scoped hooks
+ * pass through the gate.
+ *
+ * α5.6 will wire `pugi config trust .` as the user-facing entry point.
+ * For α5.3 the trust ledger primitives ship so the hook registry can gate
+ * on them; manual trust during dev is documented as a one-line script
+ * (see `apps/pugi-cli/scripts/trust-workspace.ts`).
+ */
+const trustEntrySchema = z.object({
+    workspaceRoot: z.string().min(1),
+    trustedAt: z.string().datetime(),
+    trustedBy: z.string().min(1),
+});
+const trustLedgerSchema = z.object({
+    schema: z.number().int().positive().default(1),
+    entries: z.array(trustEntrySchema).default([]),
+});
+const TRUST_LEDGER_FILENAME = 'trusted-workspaces.json';
+/**
+ * Resolve the trust ledger path. The PUGI_HOME env var lets tests redirect
+ * the user-home location without polluting the real `~/.pugi` directory.
+ */
+function trustLedgerPath() {
+    const home = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(home, TRUST_LEDGER_FILENAME);
+}
+function readLedger() {
+    const path = trustLedgerPath();
+    if (!existsSync(path)) {
+        return { schema: 1, entries: [] };
+    }
+    const raw = readFileSync(path, 'utf8');
+    if (raw.trim() === '') {
+        return { schema: 1, entries: [] };
+    }
+    const parsed = JSON.parse(raw);
+    return trustLedgerSchema.parse(parsed);
+}
+function writeLedger(ledger) {
+    const path = trustLedgerPath();
+    mkdirSync(dirname(path), { recursive: true });
+    // Mode 0o600 — only the owning user should read this file. The contents
+    // do not include secrets but they do reveal which directories on the
+    // user's disk are AI-agent workspaces.
+    writeFileSync(path, `${JSON.stringify(ledger, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+function normaliseRoot(root) {
+    // Resolve to drop trailing slashes and `.` segments, then realpath so
+    // the canonical key is the underlying physical path. A user who trusts
+    // `~/projects/foo` (a symlink) trusts whatever foo points to AT TRUST
+    // TIME — `readFileSync` follows symlinks anyway, so the previous
+    // policy of storing the unresolved path created a TOCTOU window: an
+    // attacker who controlled the symlink target after grant could swap
+    // it and have their `.pugi/hooks.json` executed on the next pugi run.
+    // Storing the realpath closes that window. If the path does not
+    // exist yet (e.g. trusting a workspace that will be created later),
+    // fall back to the resolved-but-unrealpath'd form.
+    const resolved = resolve(root);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+export async function isTrustedWorkspace(root) {
+    const key = normaliseRoot(root);
+    const ledger = readLedger();
+    return ledger.entries.some((entry) => entry.workspaceRoot === key);
+}
+export async function trustWorkspace(root, by) {
+    const key = normaliseRoot(root);
+    const ledger = readLedger();
+    const filtered = ledger.entries.filter((entry) => entry.workspaceRoot !== key);
+    filtered.push({
+        workspaceRoot: key,
+        trustedAt: new Date().toISOString(),
+        trustedBy: by,
+    });
+    writeLedger({ schema: ledger.schema, entries: filtered });
+}
+export async function revokeTrust(root) {
+    const key = normaliseRoot(root);
+    const ledger = readLedger();
+    const filtered = ledger.entries.filter((entry) => entry.workspaceRoot !== key);
+    writeLedger({ schema: ledger.schema, entries: filtered });
+}
+export async function listTrusted() {
+    const ledger = readLedger();
+    return [...ledger.entries];
+}
+//# sourceMappingURL=trust.js.map

package/dist/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from './runtime/cli.js';
+runCli(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`pugi: ${message}`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map