pi-advisor-flow 0.2.4 → 0.2.6

package/src/git.ts

@@ -0,0 +1,190 @@
+import { execFileSync } from "node:child_process";
+
+/** How much repository change context may leave the machine. */
+export type GitContextLevel = "off" | "summary" | "full";
+
+export const GIT_CONTEXT_LEVELS: GitContextLevel[] = ["off", "summary", "full"];
+
+export const isValidGitContextLevel = (
+  value: unknown
+): value is GitContextLevel =>
+  GIT_CONTEXT_LEVELS.includes(value as GitContextLevel);
+
+const LEVEL_RANK: Record<GitContextLevel, number> = {
+  full: 2,
+  off: 0,
+  summary: 1,
+};
+
+/**
+ * The Executor may request no more repository context than the user configured.
+ * A model cannot widen its own disclosure allowance.
+ */
+export const clampGitContextLevel = (
+  requested: GitContextLevel,
+  allowed: GitContextLevel
+): GitContextLevel =>
+  LEVEL_RANK[requested] <= LEVEL_RANK[allowed] ? requested : allowed;
+
+export type GitContextStatus =
+  | "disabled"
+  | "no-changes"
+  | "collected"
+  | "not-a-repository"
+  | "failed";
+
+export interface GitContextResult {
+  /** Why collection produced nothing, for diagnostics. Never sent verbatim. */
+  detail?: string;
+  /** The level actually collected after clamping. */
+  level: GitContextLevel;
+  status: GitContextStatus;
+  /** Collected context, not yet escaped or capped. Empty when nothing is disclosed. */
+  text: string;
+}
+
+/**
+ * Repository text is attacker-influenced and is embedded in a tagged region.
+ * A path can reproduce a closing tag verbatim: a directory named `x<` holding a
+ * file named `repository_changes>` prints as `x</repository_changes>`, which
+ * would end the region early and promote the remainder to trusted instructions.
+ */
+export const escapeRepositoryText = (value: string) =>
+  value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const TRUNCATION_NOTICE =
+  "\n[Repository context truncated: it exceeded the configured limit.]";
+
+/** Caps the fully rendered region and states plainly that content was dropped. */
+export const capRepositoryContext = (value: string, maxChars: number) => {
+  if (value.length <= maxChars) {
+    return { text: value, truncated: false };
+  }
+  return {
+    text: `${value.slice(0, Math.max(0, maxChars - TRUNCATION_NOTICE.length))}${TRUNCATION_NOTICE}`,
+    truncated: true,
+  };
+};
+
+// git's own empty-tree object, used to diff a repository with no commits yet.
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const GIT_TOTAL_TIMEOUT_MS = 5000;
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+
+export type GitRunner = (args: string[], cwd: string) => string;
+
+/**
+ * Collection runs several git commands. A per-command timeout alone would let a
+ * pathological repository block for the sum of them, so the budget is shared:
+ * each command may use only the time remaining before the overall deadline.
+ */
+const deadlineRunner = (): GitRunner => {
+  const expiresAt = Date.now() + GIT_TOTAL_TIMEOUT_MS;
+  return (args, cwd) => {
+    const remaining = expiresAt - Date.now();
+    if (remaining <= 0) {
+      throw new Error("Git context collection exceeded its time budget.");
+    }
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: GIT_MAX_BUFFER,
+      // Never use a shell: arguments are fixed and must not be re-parsed.
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: remaining,
+      windowsHide: true,
+    });
+  };
+};
+
+/** Resolves the base revision, falling back to the empty tree before any commit. */
+const diffBase = (run: GitRunner, cwd: string): string => {
+  try {
+    run(["rev-parse", "--verify", "--quiet", "HEAD"], cwd);
+    return "HEAD";
+  } catch {
+    return EMPTY_TREE;
+  }
+};
+
+/**
+ * Collects working-tree changes relative to HEAD, covering staged and unstaged
+ * work. Untracked files are reported by name only and never by content.
+ *
+ * `summary` discloses file names, change status, and line counts. It must not
+ * include diff hunk headers: git derives those from surrounding file content,
+ * so they can reproduce a secret from a line the change never touched.
+ */
+export const collectGitContext = (
+  cwd: string,
+  level: GitContextLevel,
+  maxChars: number,
+  redact: (value: string) => string = (value) => value,
+  run: GitRunner = deadlineRunner()
+): GitContextResult => {
+  if (level === "off" || maxChars <= 0) {
+    return { level: "off", status: "disabled", text: "" };
+  }
+  try {
+    run(["rev-parse", "--is-inside-work-tree"], cwd);
+  } catch (error) {
+    return {
+      detail: error instanceof Error ? error.message : String(error),
+      level,
+      status: "not-a-repository",
+      text: "",
+    };
+  }
+
+  try {
+    const base = diffBase(run, cwd);
+    const nameStatus = run(["diff", "--name-status", base], cwd).trim();
+    const shortstat = run(["diff", "--shortstat", base], cwd).trim();
+    const untracked = run(
+      ["ls-files", "--others", "--exclude-standard"],
+      cwd
+    ).trim();
+
+    if (!(nameStatus || untracked)) {
+      return { level, status: "no-changes", text: "" };
+    }
+
+    const sections = [
+      "Working-tree changes against the last commit (staged and unstaged).",
+      nameStatus ? `Changed files:\n${nameStatus}` : "",
+      shortstat ? `Totals: ${shortstat}` : "",
+      untracked
+        ? `Untracked files (names only, contents withheld):\n${untracked}`
+        : "",
+    ];
+
+    if (level === "full") {
+      const patch = run(["diff", base], cwd);
+      sections.push(
+        patch.trim()
+          ? `Patch:\n${patch}`
+          : "Patch: (no tracked-file content changes)"
+      );
+    } else {
+      sections.push(
+        "Full patch withheld by configuration; file contents were not disclosed."
+      );
+    }
+
+    // Redaction runs before the caller caps the region, so a limit can never
+    // split a secret and leave a readable fragment behind.
+    return {
+      level,
+      status: "collected",
+      text: redact(sections.filter(Boolean).join("\n\n")),
+    };
+  } catch (error) {
+    return {
+      detail: error instanceof Error ? error.message : String(error),
+      level,
+      status: "failed",
+      text: "",
+    };
+  }
+};

package/src/outcomes.ts

@@ -0,0 +1,85 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type OutcomeAdoption = "followed" | "not-followed" | "unknown";
+export type OutcomeValidation = "passed" | "failed" | "not-run" | "unknown";
+export type OutcomeTrigger =
+  | "manual"
+  | "executor-requested"
+  | "repeated-tool-call";
+export const ADOPTIONS: OutcomeAdoption[] = [
+  "followed",
+  "not-followed",
+  "unknown",
+];
+export const VALIDATIONS: OutcomeValidation[] = [
+  "passed",
+  "failed",
+  "not-run",
+  "unknown",
+];
+export interface OutcomeRecord {
+  adoption: OutcomeAdoption;
+  adviceHash: string;
+  timestamp: string;
+  trigger: OutcomeTrigger;
+  v: 1;
+  validationStatus: OutcomeValidation;
+}
+const MAX_LOG_BYTES = 1024 * 1024;
+const statePath = () => join(getAgentDir(), "advisor-outcomes-salt");
+export const outcomeLogPath = () =>
+  join(getAgentDir(), "advisor-outcomes.jsonl");
+
+const salt = async () => {
+  const path = statePath();
+  try {
+    return await readFile(path);
+  } catch {
+    await mkdir(getAgentDir(), { mode: 0o700, recursive: true });
+    const value = randomBytes(32);
+    const temporary = `${path}.${process.pid}.${Date.now()}`;
+    await writeFile(temporary, value, { mode: 0o600 });
+    await rename(temporary, path);
+    await chmod(path, 0o600);
+    return value;
+  }
+};
+export const adviceDigest = (advice: string, key: Buffer) =>
+  createHmac("sha256", key).update(advice).digest("hex").slice(0, 16);
+
+/** Best-effort, global-only, minimal persistent telemetry. */
+export const appendOutcome = async (
+  record: Omit<OutcomeRecord, "adviceHash" | "timestamp" | "v"> & {
+    advice: string;
+  }
+) => {
+  const path = outcomeLogPath();
+  await mkdir(getAgentDir(), { mode: 0o700, recursive: true });
+  let previous = "";
+  try {
+    previous = await readFile(path, "utf8");
+  } catch {
+    /* new log */
+  }
+  const next: OutcomeRecord = {
+    adoption: record.adoption,
+    adviceHash: adviceDigest(record.advice, await salt()),
+    timestamp: new Date().toISOString(),
+    trigger: record.trigger,
+    v: 1,
+    validationStatus: record.validationStatus,
+  };
+  const line = `${JSON.stringify(next)}\n`;
+  const retained =
+    Buffer.byteLength(previous) + Buffer.byteLength(line) > MAX_LOG_BYTES
+      ? ""
+      : previous;
+  const temporary = `${path}.${process.pid}.${Date.now()}`;
+  await writeFile(temporary, retained + line, { mode: 0o600 });
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return next;
+};

package/src/preferences.ts

@@ -0,0 +1,50 @@
+import { lstat, open, realpath } from "node:fs/promises";
+import { join, relative } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { redactAndCapText } from "./conversation.js";
+
+export const PREFERENCES_MAX_BYTES = 8 * 1024;
+export interface TextAttachment {
+  bytes: number;
+  text: string;
+}
+
+const inside = (root: string, candidate: string) => {
+  const path = relative(root, candidate);
+  return path === "" || !(path.startsWith("..") || path.includes("../"));
+};
+
+/** Reads trusted project preferences without following a file or root escape. */
+export const readProjectPreferences = async (
+  ctx: ExtensionContext,
+  maxBytes = PREFERENCES_MAX_BYTES,
+  redact = true
+): Promise<TextAttachment | undefined> => {
+  if (!ctx.isProjectTrusted()) {
+    return;
+  }
+  try {
+    const root = await realpath(ctx.cwd);
+    const candidate = join(ctx.cwd, ".pi", "advisor-preferences.md");
+    const stats = await lstat(candidate);
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+      return;
+    }
+    const resolved = await realpath(candidate);
+    if (!inside(root, resolved)) {
+      return;
+    }
+    const file = await open(resolved, "r");
+    try {
+      const buffer = Buffer.alloc(maxBytes + 1);
+      const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+      const source = buffer.subarray(0, bytesRead).toString("utf8");
+      const capped = redactAndCapText(source, maxBytes, redact);
+      return { bytes: Buffer.byteLength(capped, "utf8"), text: capped };
+    } finally {
+      await file.close();
+    }
+  } catch {
+    // Missing, unreadable, or unsafe preferences are intentionally withheld.
+  }
+};

package/src/session-state.ts

@@ -112,6 +112,13 @@ export class AdvisorSessionState {
   #invocations: AdvisorInvocationRecord[] = [];
   #loopInterventions = 0;
   #consumedCalls = 0;
+  readonly #issuedAdvice = new Map<
+    string,
+    { advice: string; trigger: ConsultationTrigger }
+  >();
+  readonly #reportedAdvice = new Set<string>();
+  #draftConsultations = 0;
+  #outcomes = 0;
 
   resetTask() {
     this.#previousSignature = undefined;
@@ -120,6 +127,10 @@ export class AdvisorSessionState {
     this.#invocations = [];
     this.#loopInterventions = 0;
     this.#consumedCalls = 0;
+    this.#issuedAdvice.clear();
+    this.#reportedAdvice.clear();
+    this.#draftConsultations = 0;
+    this.#outcomes = 0;
   }
 
   clearBlocked() {
@@ -172,6 +183,29 @@ export class AdvisorSessionState {
   recordInvocation(record: AdvisorInvocationRecord) {
     this.#invocations.push(record);
   }
+  issueAdvice(
+    id: string,
+    advice: string,
+    trigger: ConsultationTrigger,
+    draft = false
+  ) {
+    this.#issuedAdvice.set(id, { advice, trigger });
+    if (draft) {
+      this.#draftConsultations += 1;
+    }
+  }
+  claimAdvice(id: string) {
+    if (this.#reportedAdvice.has(id)) {
+      return;
+    }
+    const advice = this.#issuedAdvice.get(id);
+    if (!advice) {
+      return;
+    }
+    this.#reportedAdvice.add(id);
+    this.#outcomes += 1;
+    return advice;
+  }
 
   summary(limit: number | undefined) {
     if (this.#invocations.length === 0 && this.#loopInterventions === 0) {
@@ -215,7 +249,8 @@ export class AdvisorSessionState {
       `Triggers: ${["manual", "executor-requested", "repeated-tool-call", "completion-review", "custom-rule"].filter((trigger) => countTrigger(trigger as AdvisorTrigger) > 0).join(", ") || "none"}`,
       `Models: ${models}`,
       `Budget: ${budget}`,
-      `Markdown advice: ${markdown.length} responses`,
+      `Markdown advice: ${markdown.length} responses (${this.#draftConsultations} with drafts)`,
+      `Outcome reports: ${this.#outcomes}`,
       `Gate decisions: ${decisions}`,
       `Loop matching: normalized tool signatures; ${this.#loopInterventions} gate intervention${this.#loopInterventions === 1 ? "" : "s"}`,
       `Execution effects: ${effects("tool-blocked")} tool blocked, ${effects("session-blocked")} sessions blocked, ${effects("continued")} continued`,