@tryinget/pi-agent-vent 0.2.2 → 0.3.0

package/tests/vent-store-lifecycle.test.js

@@ -0,0 +1,245 @@
+/**
+summary: "Vent store lifecycle snapshots, stats, and exports; split from vent-store.test.js."
+read_when:
+  - "You change lifecycle snapshots, stats, and exports behavior."
+*/
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  appendReviewEvent,
+  appendVentRecord,
+  buildLifecycleSnapshot,
+  createReviewEvent,
+  createVentRecord,
+  formatExportJson,
+  formatExportMarkdown,
+  formatLifecycleStats,
+  readReviewEvents,
+  readVentRecords,
+} from "../src/vent-store.js";
+
+test("lifecycle stats and exports are bounded local projections", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-lifecycle-"));
+  const storePath = path.join(dir, "vents.jsonl");
+  const reviewPath = path.join(dir, "review-events.jsonl");
+  const record = createVentRecord(
+    { summary: "Lifecycle export captures recurrence", category: "documentation" },
+    { id: "v1" },
+  );
+  const review = createReviewEvent({
+    recurrenceKey: record.recurrenceKey,
+    state: "escalation_drafted",
+    note: "Draft locally only",
+  });
+  appendVentRecord(storePath, record);
+  appendReviewEvent(reviewPath, review);
+
+  const snapshot = buildLifecycleSnapshot({
+    records: readVentRecords(storePath).records,
+    reviewEvents: readReviewEvents(reviewPath).events,
+    storePath,
+    reviewPath,
+    now: "2026-05-21T00:00:00.000Z",
+  });
+
+  assert.equal(snapshot.counts.vents, 1);
+  assert.equal(snapshot.counts.reviewStates.escalation_drafted, 1);
+  assert.equal(snapshot.files.vents.exists, true);
+  assert.match(formatLifecycleStats(snapshot), /no AK task, GitHub issue, incident, evidence/);
+  const markdown = formatExportMarkdown(snapshot);
+  assert.match(markdown, /# Agent vent local diagnostic export/);
+  assert.match(markdown, /Decision posture: draft_recorded_owner_external/);
+  assert.match(
+    markdown,
+    /not resolution, assignment, evidence, publication, issue status, task truth, or incident state/,
+  );
+  assert.match(markdown, /## Safe local follow-up/);
+  assert.match(markdown, /Optional local retention preview: \/agent_vent retention preview/);
+  assert.match(markdown, /Draft-only handoff:/);
+  assert.match(
+    markdown,
+    /They do not file, create, declare, assign, record evidence, publish, archive, restore/,
+  );
+  const json = JSON.parse(formatExportJson(snapshot));
+  assert.equal(json.counts.vents, 1);
+  assert.equal(json.nextActions[0].decisionPosture.state, "draft_recorded_owner_external");
+  assert.equal(
+    json.nextActions[0].retentionPreviewCommand,
+    `/agent_vent retention preview ${record.recurrenceKey}`,
+  );
+  assert.doesNotMatch(
+    JSON.stringify(json.nextActions),
+    /archive:[a-f0-9]|restore:[a-f0-9]|owner was assigned/,
+  );
+});
+
+test("lifecycle export can preserve facet scope without owner-routing claims", () => {
+  const keep = createVentRecord({
+    summary: "Keep export scoped token=abc123",
+    category: "tool_failure",
+    recurrenceKey: "export-keep",
+    tags: ["Export"],
+    tool: "pi reload",
+    packageName: "@tryinget/pi-agent-vent",
+  });
+  const omit = createVentRecord({
+    summary: "Omit unrelated export group",
+    category: "documentation",
+    recurrenceKey: "export-omit",
+    tags: ["Other"],
+  });
+  const mixedOut = createVentRecord({
+    summary: "Omit mixed-group private payload",
+    category: "tool_failure",
+    recurrenceKey: "export-keep",
+    tags: ["Other"],
+    tool: "pi reload",
+    packageName: "@tryinget/pi-agent-vent",
+  });
+  const review = createReviewEvent({
+    recurrenceKey: keep.recurrenceKey,
+    state: "acknowledged",
+    note: "review token=abc123 locally",
+  });
+
+  const snapshot = buildLifecycleSnapshot({
+    records: [keep, omit, mixedOut],
+    reviewEvents: [review],
+    filters: { tags: ["export"], tool: "pi reload", packageName: "@tryinget/pi-agent-vent" },
+    state: "acknowledged",
+    limit: 10,
+    now: "2026-05-22T00:00:00.000Z",
+  });
+
+  assert.equal(snapshot.scope.hasFilters, true);
+  assert.equal(snapshot.scope.matchingGroups, 1);
+  assert.equal(snapshot.counts.vents, 1);
+  assert.equal(snapshot.counts.reviewStates.acknowledged, 1);
+  assert.equal(snapshot.reviewQueue.items.length, 1);
+  assert.equal(snapshot.reviewQueue.items[0].recurrenceKey, keep.recurrenceKey);
+  assert.equal(snapshot.summary.groups[0].recurrenceKey, keep.recurrenceKey);
+  const markdown = formatExportMarkdown(snapshot);
+  assert.match(markdown, /Filters: tool=pi-reload; package=tryinget-pi-agent-vent; tags=export/);
+  assert.match(markdown, /not owner routing or owner assignment/);
+  assert.match(markdown, /token=\[REDACTED\]/);
+  assert.match(markdown, /Safe local follow-up/);
+  assert.match(
+    markdown,
+    /Optional local retention preview: \/agent_vent retention preview tool_failure:export-keep/,
+  );
+  assert.doesNotMatch(
+    markdown,
+    /Omit unrelated export group|Omit mixed-group private payload|owner was assigned|archive:[a-f0-9]/,
+  );
+  const json = JSON.parse(formatExportJson(snapshot));
+  assert.equal(json.scope.filters.tool, "pi-reload");
+  assert.equal(json.counts.vents, 1);
+  assert.equal(
+    json.nextActions[0].exportBucketCommand,
+    "/agent_vent export markdown acknowledged tool=pi-reload package=tryinget-pi-agent-vent tag=export",
+  );
+});
+
+test("lifecycle export state scope constrains counts and summaries", () => {
+  const acknowledged = createVentRecord({
+    summary: "Acknowledged export group",
+    category: "bug",
+    recurrenceKey: "ack-export",
+    tags: ["export-state"],
+  });
+  const fresh = createVentRecord({
+    summary: "Fresh export group should not appear",
+    category: "bug",
+    recurrenceKey: "fresh-export",
+    tags: ["export-state"],
+  });
+  const review = createReviewEvent({
+    recurrenceKey: acknowledged.recurrenceKey,
+    state: "acknowledged",
+  });
+
+  const snapshot = buildLifecycleSnapshot({
+    records: [acknowledged, fresh],
+    reviewEvents: [review],
+    filters: { tags: ["export-state"] },
+    state: "acknowledged",
+    limit: 10,
+  });
+
+  assert.equal(snapshot.scope.stateFilter, "acknowledged");
+  assert.equal(snapshot.scope.facetMatchingGroups, 2);
+  assert.equal(snapshot.scope.matchingGroups, 1);
+  assert.equal(snapshot.counts.vents, 1);
+  assert.equal(snapshot.counts.reviewStates.new, 0);
+  assert.equal(snapshot.counts.reviewStates.acknowledged, 1);
+  assert.equal(snapshot.summary.groups.length, 1);
+  assert.equal(snapshot.reviewQueue.items.length, 1);
+  const markdown = formatExportMarkdown(snapshot);
+  assert.match(markdown, /Acknowledged export group/);
+  assert.doesNotMatch(markdown, /Fresh export group should not appear/);
+});
+
+test("lifecycle export follow-up commands quote legacy keys without authority claims", () => {
+  const legacy = {
+    ...createVentRecord({ summary: "Legacy export key", category: "bug" }),
+    recurrenceKey: 'bug:legacy key "quoted"',
+  };
+  const snapshot = buildLifecycleSnapshot({ records: [legacy], reviewEvents: [], limit: 5 });
+  const markdown = formatExportMarkdown(snapshot);
+  const json = JSON.parse(formatExportJson(snapshot));
+
+  assert.match(markdown, /\/agent_vent review show "bug:legacy key \\"quoted\\""/);
+  assert.match(markdown, /Choose local review state:/);
+  assert.doesNotMatch(markdown, /retention preview "bug:legacy key/);
+  assert.match(markdown, /draft commands only generate local text|local diagnostics\/drafts only/);
+  assert.equal(json.nextActions[0].reviewCommands.length, 3);
+  assert.equal(json.nextActions[0].retentionPreviewCommand, undefined);
+  assert.doesNotMatch(
+    JSON.stringify(json.nextActions),
+    /archive:[a-f0-9]|restore:[a-f0-9]|filed|owner was assigned/,
+  );
+});
+
+test("lifecycle export rejects empty facet filters", () => {
+  assert.throws(
+    () => buildLifecycleSnapshot({ records: [], filters: { tags: [""] } }),
+    /invalid agent_vent review filter tag: empty value/,
+  );
+  assert.throws(
+    () => buildLifecycleSnapshot({ records: [], filters: { tool: "" } }),
+    /invalid agent_vent review filter tool: empty value/,
+  );
+});
+
+test("lifecycle stats report missing stores without creating files", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-lifecycle-missing-"));
+  const storePath = path.join(dir, "vents.jsonl");
+  const reviewPath = path.join(dir, "review-events.jsonl");
+  const snapshot = buildLifecycleSnapshot({ storePath, reviewPath });
+
+  assert.equal(snapshot.files.vents.exists, false);
+  assert.equal(snapshot.files.reviewEvents.sizeBytes, 0);
+  assert.equal(fs.existsSync(storePath), false);
+  assert.match(formatLifecycleStats(snapshot), /vents: 0 record/);
+});
+
+test("lifecycle stats count more groups than the display limit", () => {
+  const records = Array.from({ length: 125 }, (_, index) =>
+    createVentRecord(
+      {
+        summary: `Distinct lifecycle group ${index}`,
+        category: "workflow",
+        recurrenceKey: `distinct-${index}`,
+      },
+      { id: `v-${index}` },
+    ),
+  );
+  const snapshot = buildLifecycleSnapshot({ records, limit: 5 });
+
+  assert.equal(snapshot.counts.recurrenceGroups, 125);
+  assert.equal(snapshot.summary.groups.length, 5);
+  assert.equal(snapshot.reviewQueue.items.length, 5);
+});

package/tests/vent-store-records.test.js

@@ -0,0 +1,304 @@
+/**
+summary: "Vent store record creation, redaction, JSONL append/read, review queue, and store safety; split from vent-store.test.js."
+read_when:
+  - "You change record creation, redaction, JSONL append/read, review queue, and store safety behavior."
+*/
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  appendReviewEvent,
+  appendVentRecord,
+  buildRecurrenceKey,
+  createReviewEvent,
+  createVentRecord,
+  defaultBackupDir,
+  defaultCurationPath,
+  defaultRetentionPath,
+  defaultReviewPath,
+  defaultStorePath,
+  formatReviewQueue,
+  formatSummary,
+  readReviewEvents,
+  readVentRecords,
+  redactSensitiveText,
+  summarizeRecords,
+  summarizeReviewQueue,
+} from "../src/vent-store.js";
+
+test("default store and lifecycle paths honor PI_AGENT_VENT_DIR", () => {
+  assert.equal(
+    defaultStorePath({ PI_AGENT_VENT_DIR: "/tmp/private-vents" }),
+    "/tmp/private-vents/vents.jsonl",
+  );
+  assert.equal(
+    defaultReviewPath({ PI_AGENT_VENT_DIR: "/tmp/private-vents" }),
+    "/tmp/private-vents/review-events.jsonl",
+  );
+  assert.equal(
+    defaultCurationPath({ PI_AGENT_VENT_DIR: "/tmp/private-vents" }),
+    "/tmp/private-vents/curation-events.jsonl",
+  );
+  assert.equal(
+    defaultRetentionPath({ PI_AGENT_VENT_DIR: "/tmp/private-vents" }),
+    "/tmp/private-vents/retention-events.jsonl",
+  );
+  assert.equal(
+    defaultBackupDir({ PI_AGENT_VENT_DIR: "/tmp/private-vents" }),
+    "/tmp/private-vents/backups",
+  );
+});
+
+test("createVentRecord minimizes, redacts, and derives recurrence key", () => {
+  const record = createVentRecord(
+    {
+      category: "tool-failure",
+      severity: "high",
+      summary: "Bash retry keeps failing with token=abc123",
+      frustration: "Same brittle flow; Authorization: Bearer abcdefghijklmnop should not leak.",
+      tags: ["Tool Failure", "runtime"],
+      tool: "bash token=abc123",
+      packageName: "@tryinget/pi-agent-vent secret=hidden",
+    },
+    { id: "vent-1", now: "2026-05-21T00:00:00.000Z", cwd: "/repo", sessionFile: "session.jsonl" },
+  );
+
+  assert.equal(record.schemaVersion, 1);
+  assert.equal(record.category, "tool_failure");
+  assert.equal(record.severity, "high");
+  assert.equal(record.recurrenceKey, "tool_failure:bash-retry-keeps-failing-with-token-redacted");
+  assert.equal(record.tool, "bash-token-redacted");
+  assert.equal(record.packageName, "tryinget-pi-agent-vent-secret-redacted");
+  assert.equal(record.privacy.redacted, true);
+  assert.match(record.summary, /token=\[REDACTED\]/);
+  assert.match(record.frustration, /Bearer \[REDACTED\]/);
+  assert.deepEqual(record.tags, ["tool-failure", "runtime"]);
+
+  const tagOnlySecret = createVentRecord({
+    summary: "Tag-only secret must update privacy metadata",
+    tags: ["token=abc123"],
+  });
+  assert.deepEqual(tagOnlySecret.tags, ["token-redacted"]);
+  assert.equal(tagOnlySecret.privacy.redacted, true);
+  assert.deepEqual(tagOnlySecret.privacy.redactionPatterns, ["assigned_secret"]);
+});
+
+test("category aliases normalize at record and review-filter boundaries", () => {
+  const workflow = createVentRecord({
+    summary: "Workflow alias should not degrade",
+    category: "workflow_friction",
+    recurrenceKey: "workflow alias",
+  });
+  const missing = createVentRecord({
+    summary: "Missing affordance alias should preserve meaning",
+    category: "missing_affordance",
+  });
+  const alignment = createVentRecord({
+    summary: "Context alignment candidate should remain callable",
+    category: "context_alignment",
+  });
+
+  assert.equal(workflow.category, "workflow");
+  assert.equal(workflow.recurrenceKey, "workflow:workflow-alias");
+  assert.equal(missing.category, "missing_capability");
+  assert.match(missing.recurrenceKey, /^missing_capability:/);
+  assert.equal(alignment.category, "other");
+  assert.match(alignment.recurrenceKey, /^other:/);
+
+  const queue = summarizeReviewQueue([workflow, missing, alignment], [], {
+    filters: { category: "workflow_friction" },
+  });
+  assert.equal(queue.filters.category, "workflow");
+  assert.equal(queue.matchingGroupCount, 1);
+  assert.equal(queue.items[0].recurrenceKey, workflow.recurrenceKey);
+
+  const alignmentQueue = summarizeReviewQueue([workflow, missing, alignment], [], {
+    filters: { category: "context_alignment" },
+  });
+  assert.equal(alignmentQueue.filters.category, "other");
+  assert.equal(alignmentQueue.matchingGroupCount, 1);
+  assert.equal(alignmentQueue.items[0].recurrenceKey, alignment.recurrenceKey);
+});
+
+test("explicit recurrence keys are redacted before slugging", () => {
+  const record = createVentRecord({
+    summary: "Explicit key should not leak",
+    category: "bug",
+    recurrenceKey: "reload token=abc123",
+  });
+
+  assert.equal(record.recurrenceKey, "bug:reload-token-redacted");
+  assert.doesNotMatch(record.recurrenceKey, /abc123/);
+});
+
+test("redactSensitiveText catches common secret shapes", () => {
+  const result = redactSensitiveText(
+    "api_key=secret sk-abcdefghijklmnopqrstuvwxyz ghp_abcdefghijklmnopqrstuvwxyz",
+  );
+  assert.equal(result.redacted, true);
+  assert.match(result.text, /api_key=\[REDACTED\]/);
+  assert.match(result.text, /sk-\[REDACTED\]/);
+  assert.match(result.text, /gh\*_REDACTED/);
+});
+
+test("append/read JSONL tolerates malformed old lines", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-"));
+  const filePath = path.join(dir, "vents.jsonl");
+  fs.writeFileSync(filePath, "{not-json}\n", "utf8");
+  const record = createVentRecord(
+    { summary: "Repeated docs mismatch", category: "documentation" },
+    { id: "v1" },
+  );
+  appendVentRecord(filePath, record);
+
+  const result = readVentRecords(filePath);
+  assert.equal(result.malformedLines, 1);
+  assert.equal(result.records.length, 1);
+  assert.equal(result.records[0].id, "v1");
+});
+
+test("summary groups recurrence candidates without declaring incidents", () => {
+  const records = [
+    createVentRecord(
+      {
+        summary: "Reload drops registered tool",
+        category: "bug",
+        severity: "medium",
+        recurrenceKey: "reload-tools",
+      },
+      { id: "a", now: "2026-05-21T00:00:00.000Z" },
+    ),
+    createVentRecord(
+      {
+        summary: "Reload drops registered tool again",
+        category: "bug",
+        severity: "high",
+        recurrenceKey: "reload-tools",
+      },
+      { id: "b", now: "2026-05-21T00:01:00.000Z" },
+    ),
+  ];
+
+  assert.equal(
+    buildRecurrenceKey({ category: "bug", recurrenceKey: "reload-tools" }),
+    "bug:reload-tools",
+  );
+  const summary = summarizeRecords(records);
+  assert.equal(summary.totalRecords, 2);
+  assert.equal(summary.candidateIncidentCount, 1);
+  assert.equal(summary.groups[0].candidateIncident, true);
+  assert.match(formatSummary(summary), /candidate incident/);
+});
+
+test("review events are append-only local state projections", () => {
+  const records = [
+    createVentRecord(
+      {
+        summary: "Reload drops registered tool",
+        category: "bug",
+        severity: "high",
+        recurrenceKey: "reload-tools",
+      },
+      { id: "a", now: "2026-05-21T00:00:00.000Z" },
+    ),
+  ];
+  const acknowledged = createReviewEvent(
+    {
+      recurrenceKey: "bug:reload-tools",
+      state: "acknowledged",
+      note: "Operator saw token=abc123 and will inspect later",
+    },
+    { id: "r1", now: "2026-05-21T00:02:00.000Z" },
+  );
+  const reset = createReviewEvent(
+    { recurrenceKey: "bug:reload-tools", state: "new" },
+    { id: "r2", now: "2026-05-21T00:03:00.000Z" },
+  );
+
+  assert.equal(acknowledged.privacy.redacted, true);
+  assert.match(acknowledged.note, /token=\[REDACTED\]/);
+
+  const queue = summarizeReviewQueue(records, [acknowledged, reset]);
+  assert.equal(queue.queueCount, 1);
+  assert.equal(queue.items[0].reviewState, "new");
+  assert.match(formatReviewQueue(queue), /local diagnostic state only/);
+});
+
+test("review events fail closed on invalid state and clamp huge notes", () => {
+  assert.throws(
+    () => createReviewEvent({ recurrenceKey: "bug:bad-state", state: "resolved" }),
+    /invalid agent_vent review state/,
+  );
+
+  const event = createReviewEvent({
+    recurrenceKey: "bug:huge-note",
+    state: "acknowledged",
+    note: "x".repeat(5000),
+  });
+  assert.equal(event.note.length, 1200);
+  assert.match(event.note, /…$/);
+});
+
+test("dismissed recurrence groups leave the default active review queue", () => {
+  const records = [
+    createVentRecord(
+      { summary: "Noisy one-off", category: "workflow", recurrenceKey: "noisy-one-off" },
+      { id: "v1" },
+    ),
+  ];
+  const event = createReviewEvent({ recurrenceKey: "workflow:noisy-one-off", state: "dismissed" });
+
+  assert.equal(summarizeReviewQueue(records, [event]).queueCount, 0);
+  assert.equal(summarizeReviewQueue(records, [event], { state: "dismissed" }).queueCount, 1);
+  assert.equal(summarizeReviewQueue(records, [event], { state: "all" }).queueCount, 1);
+});
+
+test("review JSONL tolerates malformed lines and records latest state", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-review-"));
+  const filePath = path.join(dir, "review-events.jsonl");
+  fs.writeFileSync(filePath, "{not-json}\n", "utf8");
+  appendReviewEvent(
+    filePath,
+    createReviewEvent({ recurrenceKey: "bug:reload-tools", state: "acknowledged" }, { id: "r1" }),
+  );
+
+  const result = readReviewEvents(filePath);
+  assert.equal(result.malformedLines, 1);
+  assert.equal(result.events.length, 1);
+  assert.equal(result.events[0].state, "acknowledged");
+});
+
+test("JSONL store files fail closed when replaced by symlinks", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-symlink-"));
+  const target = path.join(dir, "target.jsonl");
+  const link = path.join(dir, "vents.jsonl");
+  fs.writeFileSync(target, "", "utf8");
+  fs.symlinkSync(target, link);
+
+  assert.throws(
+    () => appendVentRecord(link, createVentRecord({ summary: "Symlink escape", category: "bug" })),
+    /must not be a symlink/,
+  );
+  assert.throws(() => readVentRecords(link), /must not be a symlink|ELOOP/);
+});
+
+test("JSONL write permission failures propagate instead of pretending success", (context) => {
+  if (process.getuid?.() === 0) {
+    context.skip("root can bypass directory write permissions");
+    return;
+  }
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-vent-permission-"));
+  const filePath = path.join(dir, "vents.jsonl");
+  fs.chmodSync(dir, 0o500);
+  try {
+    assert.throws(
+      () => appendVentRecord(filePath, createVentRecord({ summary: "Permission failure" })),
+      /EACCES|EPERM/,
+    );
+  } finally {
+    fs.chmodSync(dir, 0o700);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});