@yagni-app/code 0.2.1 → 0.3.0

package/dist/extension/guardian.js

@@ -0,0 +1,213 @@
+/**
+ * The Guardian — LLM auto-review of prompt-band bash commands (YAG-504).
+ *
+ * Pure half: verdict types, state tracking, circuit breaker, JSON parsing.
+ * I/O half: reviewCommand spawns a locked-down child pi (same runStage seam
+ * the advisor uses) on the efficient tier with read-only tools and a risk
+ * policy persona. The child returns a JSON verdict; the gate acts on it.
+ *
+ * Same pure/IO split as advisor.ts (decideConsult pure, askAdvisorTool I/O)
+ * and permission.ts (decideGate pure, registerPermissionGate I/O), for the
+ * same reason: the rules are what need exhaustive tests, and they must not
+ * require a child process to exercise.
+ *
+ * Trigger: the exec policy classifies a bash command as "prompt" (not clearly
+ * safe, not clearly forbidden). The Guardian reviews it instead of interrupting
+ * the user. On allow, the command runs. On ask (YAG-510), the user arbitrates:
+ * the gate shows the Guardian's question-rationale and the user approves or
+ * declines. On deny, the agent sees the rationale and is told to find a safer
+ * alternative or ask the user. On timeout/error, auto mode falls back to an
+ * ask when a UI exists, else fails closed; review mode falls back to the
+ * ordinary user confirm.
+ *
+ * Circuit breaker: 3 consecutive denials within one user prompt → escalation
+ * (ask the user once) or, headless, interruption. Denial streaks reset on
+ * `before_agent_start`, which fires once per USER PROMPT (not per LLM turn).
+ * An `ask` outcome leaves the streak untouched — neither a denial nor an
+ * exoneration — so an ask-preferring model cannot disarm the breaker by
+ * alternating deny/ask.
+ */
+import { runStage as defaultRunStage } from "./pipeline/runner.js";
+export const DEFAULT_GUARDIAN_LIMITS = {
+    maxReviews: 30,
+    maxConsecutiveDenials: 3,
+    timeoutMs: 15_000,
+};
+/**
+ * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
+ * overrides the session review cap; anything non-numeric or < 1 falls back to
+ * the default (a bad value must never zero out the cap and lock the session).
+ */
+export function resolveGuardianLimits(env = process.env) {
+    const raw = env.YAGNI_GUARDIAN_MAX_REVIEWS?.trim();
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    const maxReviews = Number.isFinite(parsed) && parsed >= 1 ? parsed : DEFAULT_GUARDIAN_LIMITS.maxReviews;
+    return { ...DEFAULT_GUARDIAN_LIMITS, maxReviews };
+}
+/** The model tier the Guardian runs on. Configurable via YAGNI_GUARDIAN_TIER. */
+export const GUARDIAN_MODEL_TIER = "efficient";
+/** Read-only tools — the Guardian can read files for context but cannot write or execute. */
+export const GUARDIAN_TOOLS = ["read"];
+export function makeGuardianState() {
+    const state = { reviews: 0, consecutiveDenials: 0 };
+    return {
+        read: () => ({ ...state }),
+        recordReview(outcome) {
+            state.reviews += 1;
+            if (outcome === "deny") {
+                state.consecutiveDenials += 1;
+            }
+            else if (outcome === "allow") {
+                state.consecutiveDenials = 0;
+            }
+            // "ask" leaves the denial streak UNCHANGED: it is neither a denial nor
+            // an exoneration. If it reset the streak, deny/ask/deny/ask would never
+            // trip the breaker (round-2 review blocker).
+            return { ...state };
+        },
+        resetTurn() {
+            state.consecutiveDenials = 0;
+        },
+    };
+}
+export function checkCircuitBreaker(state, limits) {
+    if (state.consecutiveDenials >= limits.maxConsecutiveDenials) {
+        return {
+            tripped: true,
+            reason: `Guardian denied ${state.consecutiveDenials} consecutive actions this turn. Pausing for human review.`,
+        };
+    }
+    return { tripped: false };
+}
+// --- Verdict parsing (fail closed on malformed) ---
+export function parseVerdict(raw) {
+    try {
+        // Efficient-tier models may wrap JSON in markdown fences despite
+        // instructions to output raw JSON. Extract the first {...} block.
+        const jsonMatch = raw.match(/\{[\s\S]*\}/);
+        const jsonStr = jsonMatch ? jsonMatch[0] : raw;
+        const parsed = JSON.parse(jsonStr);
+        const outcome = parsed?.outcome;
+        if (outcome !== "allow" && outcome !== "ask" && outcome !== "deny")
+            return null;
+        const riskLevel = parsed.riskLevel;
+        const validLevels = ["low", "medium", "high", "critical"];
+        return {
+            outcome,
+            riskLevel: typeof riskLevel === "string" && validLevels.includes(riskLevel)
+                ? riskLevel
+                : "medium",
+            rationale: typeof parsed.rationale === "string" && parsed.rationale.trim().length > 0
+                ? parsed.rationale.trim()
+                : "No rationale provided.",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// --- /cost subtotal ---
+export function formatGuardianSubtotal(state, limits) {
+    if (state.reviews === 0)
+        return "";
+    const plural = state.reviews === 1 ? "review" : "reviews";
+    return `Guardian: ${state.reviews} ${plural}.`;
+}
+/**
+ * The synthetic stage a Guardian consult runs as. Borrows the `plan` StageId
+ * (same pattern as the advisor) so it doesn't ripple into feed/reducers. The
+ * agent name selects the guardian persona from PERSONA_BODIES.
+ */
+export function guardianStage(modelTier = GUARDIAN_MODEL_TIER) {
+    return {
+        id: "plan",
+        agent: "guardian",
+        model: modelTier,
+        tools: GUARDIAN_TOOLS,
+        taskTemplate: "{ticket}",
+    };
+}
+/**
+ * Run a Guardian consult: spawn a locked-down child pi with the risk policy
+ * persona and the command as the task. Parse the JSON verdict from the output.
+ * Returns { verdict, cost } on success, { verdict: null, error, cost } on failure.
+ */
+export async function reviewCommand(command, deps) {
+    const runStage = deps.runStage ?? defaultRunStage;
+    const stage = guardianStage(deps.modelTier);
+    // Build the abort signal with the Guardian timeout (injectable — the gate
+    // threads guardianLimits.timeoutMs through).
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_GUARDIAN_LIMITS.timeoutMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    // Chain with the caller's signal if present.
+    if (deps.signal) {
+        if (deps.signal.aborted)
+            controller.abort();
+        else
+            deps.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    try {
+        const justificationLine = deps.execJustification
+            ? `\n\nWhy this command was routed to you (static policy): ${deps.execJustification}`
+            : "";
+        const result = await runStage(stage, { ticket: `Review this shell command for safety. Output only the JSON verdict.${justificationLine}\n\nCommand:\n${command}` }, {
+            cwd: deps.cwd,
+            signal: controller.signal,
+            callerLabel: "guardian",
+        });
+        const cost = result.usage?.cost ?? 0;
+        const output = result.finalOutput.trim();
+        // An aborted child often RESOLVES with empty/partial output instead of
+        // throwing (observed live: ESC → 433ms "empty"). Any result produced
+        // while the caller's signal is aborted is an abort, not an outage — the
+        // gate must not warn or fall back to an ask on it.
+        if (deps.signal?.aborted) {
+            return { verdict: null, error: "aborted", cost };
+        }
+        if (!output) {
+            return { verdict: null, error: "empty", cost };
+        }
+        const verdict = parseVerdict(output);
+        if (!verdict) {
+            return { verdict: null, error: "malformed", cost };
+        }
+        return { verdict, cost };
+    }
+    catch (err) {
+        // Distinguish the caller aborting (user hit ESC — must NOT be treated as
+        // an outage, or the fallback ask would pop a dialog on an aborted turn),
+        // our own timeout, and real network/process errors.
+        if (deps.signal?.aborted) {
+            return { verdict: null, error: "aborted", cost: 0 };
+        }
+        if (controller.signal.aborted) {
+            return { verdict: null, error: "timeout", cost: 0 };
+        }
+        return { verdict: null, error: "network", cost: 0 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Create a sanitized diagnostic event. Never includes the raw command text
+ * (could contain secrets). YAGNI_DEBUG=1 adds rationale and a command hash.
+ */
+export function buildDiagnosticEvent(outcome, opts) {
+    const ev = {
+        event: "guardian_review",
+        outcome,
+        ...(opts.durationMs !== undefined ? { durationMs: opts.durationMs } : {}),
+        ...(opts.tier !== undefined ? { tier: opts.tier } : {}),
+    };
+    if (opts.debug) {
+        if (opts.rationale)
+            ev.rationale = opts.rationale;
+        if (opts.commandHash)
+            ev.commandHash = opts.commandHash;
+    }
+    return ev;
+}
+//# sourceMappingURL=guardian.js.map

package/dist/extension/index.d.ts

@@ -4,7 +4,7 @@ import { runInitPass as defaultRunInitPass } from "./initPass.js";
 import { fetchMcpServers as defaultFetchMcpServers } from "./mcpTools.js";
 import { type FlushOutcome, type SpoolClientOpts } from "./spool.js";
 import { type TokenProvider } from "./tokenProvider.js";
-import { type ContextBrief, type ModelEntry } from "./config.js";
+import { type CatalogResult, type ContextBrief } from "./config.js";
 /**
  * YAGNI Code extension entry point.
  *
@@ -31,7 +31,7 @@ export interface RegisterYagniDeps {
         baseUrl: string;
         getToken: () => string | undefined;
         fetchImpl?: typeof fetch;
-    }) => Promise<ModelEntry[]>;
+    }) => Promise<CatalogResult>;
     fetchContextBrief?: (opts: {
         baseUrl: string;
         getToken: () => string | undefined;
@@ -63,6 +63,12 @@ export interface RegisterYagniDeps {
     tokenProvider?: TokenProvider;
     /** The spool flush (R4 write half), injectable so tests never touch disk. */
     flushSpool?: (opts: SpoolClientOpts) => Promise<FlushOutcome>;
+    /**
+     * Non-fatal auth-event reporter (YAG-500 Fix E). Defaults to
+     * `makeCrashReporter` gated on `!evalMode`; inject a spy in tests to assert
+     * the report is fired with `context: "auth-failure"` and the refresh outcome.
+     */
+    authReporter?: (error: unknown, context?: string) => Promise<void>;
     env?: NodeJS.ProcessEnv;
 }
 /**
@@ -97,8 +103,11 @@ export declare function parseSpendResponse(data: unknown): SpendResponse | null;
 export declare function registerYagni(pi: ExtensionAPI, deps?: RegisterYagniDeps): Promise<void>;
 export default function (pi: ExtensionAPI): Promise<void>;
 export { makeAskYagniTool } from "./askYagniTool.js";
+export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
+export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, } from "./guardian.js";
+export type { GuardianOutcome, GuardianVerdict, GuardianState, GuardianStateHandle, GuardianLimits, ReviewResult, ReviewCommandDeps, } from "./guardian.js";
 export type { Citation, MakeAskYagniToolOptions } from "./askYagniTool.js";
 export { makeReviewBusinessMatchTool } from "./reviewTool.js";
 export type { MakeReviewToolOptions } from "./reviewTool.js";
@@ -115,7 +124,7 @@ export type { RunInitPassDeps, InitPassOutcome, RunTeamSetupDeps, TeamSetupOutco
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, BRAND_NAME } from "./branding.js";
 export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";
-export type { FetchCatalogOptions, ModelEntry } from "./config.js";
+export type { CatalogResult, FetchCatalogOptions, ModelEntry } from "./config.js";
 export { buildYagniProvider } from "./provider.js";
 export { registerGoCommand } from "./pipeline/goCommand.js";
 export type { RegisterGoDeps } from "./pipeline/goCommand.js";
@@ -134,7 +143,9 @@ export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkd
 export type { SubagentDef, SubagentSource } from "./subagents.js";
 export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, todoSummary, TODO_TOOL_NAME, MAX_TODOS, } from "./todos.js";
 export type { TodoItem, TodoStatus, TodoTheme } from "./todos.js";
-export { decideGate, registerPermissionGate, filterStalePlanContext, DEFAULT_PERMISSION_POLICY, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission.js";
+export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission.js";
+export { classifyCommand, DEFAULT_EXEC_POLICY, } from "./execPolicy.js";
+export type { ExecDecision, ExecPolicy, PrefixRule, ExecClassification, } from "./execPolicy.js";
 export type { PermissionMode, PermissionPolicy, GateDecision, RegisterPermissionDeps, BlessRememberInfo, } from "./permission.js";
 export { makeBlessStore, blessPath } from "./bless.js";
 export type { BlessStore, BlessRule } from "./bless.js";