@yagni-app/code 0.2.1 → 0.3.1

package/dist/extension/mineBeat.js

@@ -0,0 +1,193 @@
+/**
+ * The opt-in repo seeding beat (org plane, Run 7).
+ *
+ * On the first interactive session in a repo whose repo-scoped decision
+ * ledger is empty (`/context?repo=` reports `repoDecisionCount: 0`), YAGNI
+ * Code offers — once — to read the repo's own decision record and seed the
+ * ledger: "Read this repo's ADRs and docs and seed the decision ledger?".
+ * One keystroke, then the backend extracts, dedupes, and banks at most 12
+ * `repo_mined` asserted rows, and the beat prints the banked count plus the
+ * Library review deep link.
+ *
+ * Never automatic, never a nag: a decline writes a per-repo marker so the
+ * beat does not recur; an accepted pass marks the repo only after the server
+ * confirms (a transport failure leaves the offer available next session).
+ * The corpus is collected at git HEAD (same echo-chamber guard as
+ * repoDocs.ts) — ADR directories, agent-instruction root docs, top-level
+ * docs/*.md, and recent merge subjects — bounded client-side to the same
+ * limits the backend enforces.
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import { dirname, join } from "node:path";
+import { METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+/**
+ * Client-side bounds on the mining corpus — mirror of the backend's
+ * MINE_INPUT_LIMITS so nothing is silently truncated server-side.
+ */
+export const MINE_BEAT_LIMITS = {
+    maxDocs: 40,
+    maxPathChars: 300,
+    maxExcerptChars: 8_000,
+    maxCommitSubjects: 200,
+    maxSubjectChars: 200,
+};
+const GIT_OPTS = {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"],
+};
+function git(cwd, args) {
+    try {
+        return execFileSync("git", args, { cwd, ...GIT_OPTS });
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse `owner/name` from an origin remote URL (ssh or https). */
+export function parseRepoFullName(remote) {
+    if (!remote)
+        return undefined;
+    const m = remote.trim().match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
+    return m ? m[1] : undefined;
+}
+export const defaultMineBeatGit = {
+    repoFullName: (cwd) => parseRepoFullName(git(cwd, ["config", "--get", "remote.origin.url"])),
+    listAtHead: (cwd) => {
+        const out = git(cwd, ["ls-tree", "-r", "--name-only", "HEAD"]);
+        return out === null ? null : out.split("\n").filter(Boolean);
+    },
+    readAtHead: (cwd, rel) => git(cwd, ["show", `HEAD:${rel}`]),
+    mergeSubjects: (cwd, max) => {
+        const merges = git(cwd, ["log", "--merges", `-n`, String(max), "--pretty=%s"]);
+        const chosen = merges && merges.trim().length > 0
+            ? merges
+            : // Squash-merge repos have no merge commits; plain subjects still
+                // carry the shipped-work trail. No further heuristics (spec flag).
+                git(cwd, ["log", `-n`, String(max), "--pretty=%s"]);
+        return (chosen ?? "").split("\n").map((s) => s.trim()).filter(Boolean).slice(0, max);
+    },
+};
+/** Is this HEAD-tracked path part of the repo's decision record? */
+export function isMineCandidate(rel) {
+    if (/^(?:docs\/)?adrs?\/[^/]+\.md$/i.test(rel))
+        return true;
+    if (/^(?:AGENTS|CLAUDE|CONTRIBUTING|CONTEXT|ARCHITECTURE)\.md$/i.test(rel))
+        return true;
+    if (/^docs\/[^/]+\.md$/i.test(rel))
+        return true;
+    return false;
+}
+/** Collect the HEAD-era mining corpus, bounded to MINE_BEAT_LIMITS. */
+export function collectMineCorpus(cwd, gitImpl = defaultMineBeatGit) {
+    const tracked = gitImpl.listAtHead(cwd);
+    if (tracked === null)
+        return { docs: [], commitSubjects: [] };
+    const docs = [];
+    for (const rel of tracked) {
+        if (docs.length >= MINE_BEAT_LIMITS.maxDocs)
+            break;
+        if (rel.length > MINE_BEAT_LIMITS.maxPathChars)
+            continue;
+        if (!isMineCandidate(rel))
+            continue;
+        const body = gitImpl.readAtHead(cwd, rel);
+        if (body === null || body.trim().length === 0)
+            continue;
+        docs.push({ path: rel, excerpt: body.trim().slice(0, MINE_BEAT_LIMITS.maxExcerptChars) });
+    }
+    const commitSubjects = gitImpl
+        .mergeSubjects(cwd, MINE_BEAT_LIMITS.maxCommitSubjects)
+        .map((s) => s.slice(0, MINE_BEAT_LIMITS.maxSubjectChars));
+    return { docs, commitSubjects };
+}
+/** Filesystem path of one repo's beat marker under the state home. */
+export function mineMarkerPath(stateHome, repoFullName) {
+    return join(stateHome, "mine-beat", `${repoFullName.replace(/[/\\]/g, "__")}.json`);
+}
+export function fileMineBeatMarkers(stateHome) {
+    return {
+        has: (repo) => {
+            try {
+                return fs.existsSync(mineMarkerPath(stateHome, repo));
+            }
+            catch {
+                return false;
+            }
+        },
+        write: (repo, status) => {
+            try {
+                const p = mineMarkerPath(stateHome, repo);
+                fs.mkdirSync(dirname(p), { recursive: true });
+                fs.writeFileSync(p, JSON.stringify({ status, at: new Date().toISOString() }), "utf8");
+            }
+            catch {
+                // A marker failure must never break the session; worst case the beat
+                // asks once more next launch.
+            }
+        },
+    };
+}
+/**
+ * Offer (once per repo) and, on yes, run the seeding pass. Fail-soft
+ * throughout: any error surfaces as a notify at most, never a broken session.
+ */
+export async function maybeOfferMiningBeat(ctx, opts) {
+    const { repoFullName } = opts;
+    // Only an EXPLICIT zero fires the beat: an absent count means an older
+    // backend or a count failure, and a nag on either would be wrong.
+    if (!repoFullName || opts.repoDecisionCount !== 0)
+        return { offered: false };
+    if (opts.markers.has(repoFullName))
+        return { offered: false };
+    if (!ctx.hasUI || typeof ctx.ui.confirm !== "function")
+        return { offered: false };
+    const collect = opts.collect ?? collectMineCorpus;
+    const corpus = collect(opts.cwd, opts.gitImpl ?? defaultMineBeatGit);
+    // Nothing to mine yet: skip WITHOUT a marker, so a later checkout that
+    // gains docs still gets its one offer.
+    if (corpus.docs.length === 0 && corpus.commitSubjects.length === 0) {
+        return { offered: false };
+    }
+    const accepted = await ctx.ui.confirm("Seed the decision ledger?", `Read this repo's ADRs and docs and bank up to 12 candidate decisions for ${repoFullName}? You review every one in the Library before it counts as confirmed.`);
+    if (!accepted) {
+        opts.markers.write(repoFullName, "declined");
+        return { offered: true, accepted: false };
+    }
+    try {
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/decisions/mine`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                repo: repoFullName,
+                docs: corpus.docs,
+                commitSubjects: corpus.commitSubjects,
+                // Stable per repo: the write-spool replay contract makes a retry of
+                // the same pass idempotent server-side.
+                idempotencyKey: `mine:${repoFullName}`,
+            }),
+        }, { fetchImpl: opts.fetchImpl, policy: METERED_POST_FETCH_POLICY });
+        if (!res.ok) {
+            // No marker: the offer stays available next session.
+            ctx.ui.notify("Seeding the decision ledger failed; YAGNI Code will offer again next session.", "error");
+            return { offered: true, accepted: true };
+        }
+        const body = (await res.json());
+        opts.markers.write(repoFullName, "seeded");
+        if (body.alreadyMined)
+            return { offered: true, accepted: true, banked: 0 };
+        const banked = typeof body.banked === "number" ? body.banked : 0;
+        const noun = banked === 1 ? "decision" : "decisions";
+        ctx.ui.notify(`Banked ${banked} ${noun} read from this repo's docs. Review them: ${opts.baseUrl}/knowledge/decisions`, "info");
+        return { offered: true, accepted: true, banked };
+    }
+    catch {
+        ctx.ui.notify("Seeding the decision ledger failed; YAGNI Code will offer again next session.", "error");
+        return { offered: true, accepted: true };
+    }
+}
+//# sourceMappingURL=mineBeat.js.map

package/dist/extension/permission.d.ts

@@ -4,7 +4,8 @@
  * YAGNI Code registers no tool_call handler today, so the interactive session has
  * no plan/approval surface. P3 adds one on pi's documented `tool_call` block seam
  * plus a `/mode` command:
- *   - auto   (default): never blocks. Byte-identical to today, so this is additive.
+ *   - auto   (default): ordinary coding tools run directly; external tracker
+ *              changes still require fresh human confirmation.
  *   - plan   : blocks write/edit/bash so the agent can explore + propose without
  *              touching the tree.
  *   - review : surfaces a three-way ctx.ui.select before a write/edit/bash; a
@@ -14,7 +15,7 @@
  *              adds a session-scoped bless rule AND drafts a decision capture.
  *
  * `decideGate` is PURE; the live wiring holds the mode in a small closure (no
- * module-global state). The default auto mode remains fail-open, but stricter
+ * module-global state). The default auto mode remains direct for coding tools, but stricter
  * modes fail closed for side-effect tools if the gate itself errors. Bless rules
  * are session-scoped, path-prefix-bound, never persisted, and never consulted in
  * plan mode (plan blocks outright before isBlessed is reached).
@@ -26,20 +27,43 @@
  * the context so the model doesn't keep believing it is restricted.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ApprovedPrefixGrant } from "./approvedPrefixes.js";
 import { type BlessStore } from "./bless.js";
+import { type ExecPolicy } from "./execPolicy.js";
+import { type GuardianError, type GuardianRiskLevel } from "./guardian.js";
 export type PermissionMode = "auto" | "plan" | "review";
+/**
+ * A shared, mutable holder for the current permission mode. Both
+ * `registerPermissionGate` (which writes on /mode) and the footer factory
+ * (which reads on every render) hold a reference, so mode changes appear
+ * immediately in the footer's line 2.
+ */
+export interface ModeHolder {
+    get(): PermissionMode;
+    set(m: PermissionMode): void;
+    onSet(fn: (m: PermissionMode) => void): void;
+}
+export declare function createModeHolder(initial?: PermissionMode): ModeHolder;
 /** Which tools each tier acts on, plus the optional grounding-bless predicate. */
 export interface PermissionPolicy {
     /** Tools blocked outright in plan mode (write/exec). */
     planBlockTools: string[];
     /** Tools that prompt for confirmation in review mode. */
     reviewConfirmTools: string[];
+    /** Consequential external writes that require fresh consent in every mode. */
+    alwaysConfirmTools?: string[];
     /**
      * Optional: a recorded decision already blesses this action, so it auto-runs in
      * review mode instead of prompting. The hook for tying the gate to captured
      * judgment; default undefined (nothing pre-blessed).
      */
     isBlessed?: (toolName: string, params: Record<string, unknown>) => boolean;
+    /**
+     * Exec policy for bash command classification. When present, bash commands are
+     * classified by the exec policy engine before the tool-granular logic runs.
+     * Defaults to DEFAULT_EXEC_POLICY when absent.
+     */
+    execPolicy?: ExecPolicy;
 }
 export declare const DEFAULT_PERMISSION_POLICY: PermissionPolicy;
 /** A pure gate verdict: block outright, ask to confirm, or allow. */
@@ -48,13 +72,55 @@ export interface GateDecision {
     reason?: string;
     /** review mode only: the caller should ctx.ui.confirm before allowing. */
     confirm?: boolean;
+    /**
+     * Exec policy classification result for bash commands. When present, the
+     * tool_call handler should run the Guardian for "prompt" before falling
+     * through to the user confirm. Absent for non-bash tools or when no
+     * command string is available.
+     */
+    classify?: "allow" | "prompt" | "forbidden";
+    /**
+     * The exec policy's justification for a "prompt" classification — why the
+     * command was routed to the Guardian. Threaded into the consult prompt and
+     * the storage event (it is the layer-tuning signal, YAG-510).
+     */
+    classifyJustification?: string;
 }
 /**
- * Pure permission decision for one tool call under a mode + policy. auto always
- * allows; plan blocks the write/exec set; review marks writes for confirmation
+ * Pure permission decision for one tool call under a mode + policy. Auto allows
+ * ordinary tools; plan blocks the write/exec set; review marks writes for confirmation
  * unless a recorded decision blesses them.
  */
 export declare function decideGate(toolName: string, params: Record<string, unknown>, mode: PermissionMode, policy: PermissionPolicy): GateDecision;
+/**
+ * Terminal outcome of one prompt-band decision (YAG-510). One storage event
+ * is emitted per terminal outcome; `consulted` says whether a Guardian LLM
+ * call actually happened (grants/cache hits skip it).
+ */
+export type GuardianGateOutcome = "prefix_allow" | "cached_allow" | "allow" | "deny" | "ask_approved" | "ask_approved_remembered" | "ask_denied" | "ask_headless_blocked" | "breaker_ask_approved" | "breaker_blocked" | GuardianError;
+/**
+ * Rich per-decision event for opt-in storage (YAG-510). Carries the RAW
+ * command — the wiring layer (index.ts) hashes/redacts per the workspace's
+ * storage tier before anything leaves the machine. Distinct from the
+ * sanitized GuardianDiagnosticEvent (local debug log), which never carries
+ * the command.
+ */
+export interface GuardianGateEvent {
+    command: string;
+    outcome: GuardianGateOutcome;
+    /** Why the exec policy routed this command to the Guardian. */
+    execJustification?: string;
+    riskLevel?: GuardianRiskLevel;
+    rationale?: string;
+    mode: PermissionMode;
+    tier?: string;
+    durationMs?: number;
+    /** Whether a Guardian LLM consult actually ran for this decision. */
+    consulted: boolean;
+    /** Present when the terminal outcome followed a Guardian error (e.g. an
+     * error-fallback ask that the user then approved). */
+    guardianError?: GuardianError;
+}
 /** What was blessed with "don't ask again", handed to the capture hook. */
 export interface BlessRememberInfo {
     tool: string;
@@ -73,16 +139,64 @@ export interface RegisterPermissionDeps {
      * never blocks the approved tool call.
      */
     onBlessRemember?: (ctx: ExtensionContext, info: BlessRememberInfo) => void | Promise<void>;
+    /** Shared holder so the footer can read the live mode on every render. */
+    modeHolder?: ModeHolder;
+    /**
+     * Guardian state handle for the session. When present, prompt-band bash
+     * commands are auto-reviewed by the Guardian LLM instead of interrupting
+     * the user. When absent, prompt-band commands fall through to the existing
+     * tool-granular behavior (review: user prompt, auto: allow).
+     */
+    guardianState?: import("./guardian.js").GuardianStateHandle;
+    /** Guardian limits (timeouts, circuit breaker). Defaults to DEFAULT_GUARDIAN_LIMITS. */
+    guardianLimits?: import("./guardian.js").GuardianLimits;
+    /** Override the Guardian model tier (default: efficient). */
+    guardianTier?: string;
+    /** Injectable Guardian review function (tests pass a stub). */
+    guardianReview?: (command: string, deps: import("./guardian.js").ReviewCommandDeps) => Promise<import("./guardian.js").ReviewResult>;
+    /**
+     * Called (fire-and-forget) after each Guardian review with a sanitized
+     * diagnostic event. Fail-soft; never blocks.
+     */
+    onGuardianReview?: (event: import("./guardian.js").GuardianDiagnosticEvent) => void;
+    /** Disable the Guardian entirely (env var YAGNI_DISABLE_GUARDIAN). */
+    guardianDisabled?: boolean;
+    /**
+     * Persisted "don't ask again" grants for this session's repo (YAG-510).
+     * Consulted ONLY after the exec policy classified a command as "prompt" —
+     * a grant can never override the forbidden band. Suppressed in review mode.
+     */
+    grants?: readonly ApprovedPrefixGrant[];
+    /** Resolve the grant scope key for a cwd (git remote origin URL fallback
+     * realpath). Lazily invoked on the first prompt-band bash call. */
+    resolveRepoKey?: (cwd: string) => string;
+    /** Persist a new grant (fire-and-forget; the in-memory list is updated
+     * either way). index.ts wires approvedPrefixes.appendGrant. */
+    persistGrant?: (grant: ApprovedPrefixGrant) => void;
+    /**
+     * Called (fire-and-forget) at every terminal prompt-band outcome with the
+     * rich storage event (raw command — the wiring layer redacts/hashes).
+     * Fail-soft; never blocks.
+     */
+    onGuardianEvent?: (event: GuardianGateEvent) => void;
 }
-/** The customType tag on injected plan-mode context (filterable later). */
-export declare const PLAN_CONTEXT_TYPE = "yagni-plan-context";
+/** The customType tag on injected mode-context messages (filterable later). */
+export declare const MODE_CONTEXT_TYPE = "yagni-mode-context";
+/** Legacy alias — the original plan-mode tag, kept for backward compat. */
+export declare const PLAN_CONTEXT_TYPE = "yagni-mode-context";
 export declare const PLAN_CONTEXT_MESSAGE = "[PLAN MODE ACTIVE]\nYou are in plan mode: explore and design, change nothing.\n- write, edit, and bash are held by the permission gate; do not attempt them.\n- Read, search, and ask_yagni freely to ground the plan in how this company works.\n- Produce a concrete numbered plan of the steps you would take, with the files involved.\n- End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.\n- Once executing, track the plan's steps with todo_write.";
+/** Build the mode-awareness context message for the current permission mode. */
+export declare function buildModeContextMessage(mode: PermissionMode): string;
 /**
- * Drop previously injected plan-mode context once plan mode is off, so the
- * model stops believing writes are held. Pure; returns the SAME array when
- * nothing needs filtering so callers can cheaply detect a no-op.
+ * Drop previously injected mode-context messages from a DIFFERENT mode so the
+ * model does not keep believing it is in a prior mode. Messages matching the
+ * current mode are kept (the fresh injection from before_agent_start should
+ * survive). Pure; returns the SAME array when nothing needs filtering so callers
+ * can cheaply detect a no-op.
  */
-export declare function filterStalePlanContext<T>(messages: T[]): T[];
+export declare function filterStaleModeContext<T>(messages: T[], currentMode?: PermissionMode): T[];
+/** Legacy alias — the original plan-mode filter name. */
+export declare const filterStalePlanContext: typeof filterStaleModeContext;
 /**
  * Wire the tool_call gate + the /mode command onto a shared mode holder. Default
  * auto, so absent any /mode this is a no-op over today's behavior.