@yagni-app/code 0.2.1 → 0.3.1

package/dist/extension/guardian.js

@@ -0,0 +1,237 @@
+/**
+ * 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: 120,
+    maxConsecutiveDenials: 3,
+    timeoutMs: 15_000,
+};
+/**
+ * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
+ * overrides the sliding-window 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"];
+// --- State ---
+/**
+ * The review-cap window. `reviews` counts consults inside a SLIDING window
+ * rather than for the session's lifetime: a 24/7 session (a fleet operator's
+ * always-on terminal) must regain review capacity as old consults age out,
+ * not hard-block forever after the first N. The cap is a cost/runaway bound,
+ * not a safety bound — safety is the verdicts themselves.
+ */
+export const GUARDIAN_REVIEW_WINDOW_MS = 60 * 60_000;
+export function makeGuardianState(now = Date.now) {
+    const reviewTimes = [];
+    let consecutiveDenials = 0;
+    const prune = () => {
+        const cutoff = now() - GUARDIAN_REVIEW_WINDOW_MS;
+        while (reviewTimes.length > 0 && reviewTimes[0] <= cutoff)
+            reviewTimes.shift();
+    };
+    const snapshot = () => ({
+        reviews: reviewTimes.length,
+        consecutiveDenials,
+    });
+    return {
+        read: () => {
+            prune();
+            return snapshot();
+        },
+        recordReview(outcome) {
+            prune();
+            reviewTimes.push(now());
+            if (outcome === "deny") {
+                consecutiveDenials += 1;
+            }
+            else if (outcome === "allow") {
+                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 snapshot();
+        },
+        resetTurn() {
+            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,8 @@ 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";
+import { maybeOfferMiningBeat as defaultMaybeOfferMiningBeat, type MineBeatMarkers } from "./mineBeat.js";
 /**
  * YAGNI Code extension entry point.
  *
@@ -31,12 +32,26 @@ export interface RegisterYagniDeps {
         baseUrl: string;
         getToken: () => string | undefined;
         fetchImpl?: typeof fetch;
-    }) => Promise<ModelEntry[]>;
+    }) => Promise<CatalogResult>;
     fetchContextBrief?: (opts: {
         baseUrl: string;
         getToken: () => string | undefined;
         fetchImpl?: typeof fetch;
+        repo?: string;
     }) => Promise<ContextBrief | null>;
+    /**
+     * The session repo (`owner/name`), resolved from the origin remote before
+     * the boot brief fetch so `/context` can carry `repoDecisionCount` for the
+     * mining beat. Injectable (no git in tests); undefined outside a repo.
+     */
+    resolveRepoFullName?: (cwd: string) => string | undefined;
+    /**
+     * The opt-in seeding beat itself (Run 7). Injectable so tests assert it
+     * fires only on a startup with an explicitly-zero repo ledger.
+     */
+    offerMiningBeat?: typeof defaultMaybeOfferMiningBeat;
+    /** The beat's once-per-repo marker store. Injectable (no disk in tests). */
+    mineBeatMarkers?: MineBeatMarkers;
     /**
      * Workspace MCP server list seam (YAG-446). The default hits
      * `/api/yagni-code/mcp/servers` and is fail-soft: older backends and
@@ -63,6 +78,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 +118,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";
@@ -113,9 +137,11 @@ export type { RecordDecisionParams } from "./recordDecisionTool.js";
 export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace, readRepoIntake, draftEngineering, summarizeDraft, FRESH_BRIEF_MIN_CHARS, } from "./initPass.js";
 export type { RunInitPassDeps, InitPassOutcome, RunTeamSetupDeps, TeamSetupOutcome, RepoIntake, RepoIntakeFs, EngineeringDraft, DraftTeam, } from "./initPass.js";
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
-export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, BRAND_NAME } from "./branding.js";
+export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA, BRAND_NAME } from "./branding.js";
+export { createUltraHolder, registerUltraCommand } from "./ultra.js";
+export type { UltraHolder } from "./ultra.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";
@@ -130,11 +156,13 @@ export type { VerifyCommand, VerifyOutcome } from "./pipeline/verify.js";
 export { blindStages, reportOnlyStages, makeGroundedVsBlindEval, formatComparisonReport } from "./pipeline/eval.js";
 export type { ComparisonReport, LaneFit, LaneOutcome } from "./pipeline/eval.js";
 export { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
-export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkdown, buildSubagentStage, formatAgentList, mapModelTier, SUBAGENT_TOOL_NAME, GENERAL_AGENT_NAME, MAX_PARALLEL_SUBAGENTS, DEFAULT_SUBAGENT_TOOLS, } from "./subagents.js";
+export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkdown, buildSubagentStage, formatAgentList, mapModelTier, SUBAGENT_TOOL_NAME, GENERAL_AGENT_NAME, MAX_PARALLEL_SUBAGENTS, MAX_PARALLEL_SUBAGENTS_ULTRA, DEFAULT_SUBAGENT_TOOLS, } from "./subagents.js";
 export type { SubagentDef, SubagentSource } from "./subagents.js";
-export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, todoSummary, TODO_TOOL_NAME, MAX_TODOS, } from "./todos.js";
+export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, formatTodoReminder, shouldRemindTodos, todoSummary, TODO_TOOL_NAME, TODO_REMINDER_TURNS, 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";