@tryinget/pi-agent-vent 0.1.0 → 0.1.2

package/README.md

@@ -18,8 +18,9 @@ It is intentionally local-first and advisory. It does **not** create AK tasks, G
 
 - Workspace path: `packages/pi-agent-vent`
 - Release component key: `pi-agent-vent`
-- Package command: `/agent_vent` (`/agent-vent` remains a compatibility alias)
+- Package command: `/agent_vent`
 - LLM tool: `agent_vent`
+- Toolbox bundle id: `agent_vent`
 
 ## Why this exists
 
@@ -92,7 +93,7 @@ The tool prompt tells the agent to avoid ordinary status updates, raw logs, secr
 /agent_vent path
 ```
 
-`/agent-vent` remains a compatibility alias for users who prefer kebab-case slash commands. Review queue, outcome, compare, retention-candidate, retention-history, export, and detail output include advisory human-review hints, explicit local decision-posture projections, exact local next-action commands for review state, draft-only handoff targets, export prompts, retention preview eligibility, and rollback-candidate commands from archive receipts; generated commands quote dynamic recurrence keys/paths so legacy keys remain copyable. Decision posture is derived local diagnostic wording only: it is not resolution, assignment, issue status, task truth, incident state, evidence, or publication. Filtered compare follow-up commands preserve supported category/tag/tool/package filters for `outcomes`, `retention candidates`, and `export`. Export filters are local diagnostic focus aids only, not evidence scoping, publication, owner routing, or owner assignment; export applies review-state and facet scope before counts, summaries, display rows, and safe local follow-up commands. Outcome and compare limits are explicit per review-state bucket so `outcomes all 1` can show one `new`, one `acknowledged`, one `dismissed`, and one `escalation_drafted` group, while `compare 1` shows at most one group per state. Review/outcome/compare/export/retention-candidate/history command syntax fails closed before store reads for unknown filters, empty filter values such as `owner=` or `tag=`, invalid states/arguments, invalid category values, or invalid retention-history arguments. These surfaces are guidance only and do not route, file, create, declare, assign, record evidence, publish, archive, restore, or mutate owner systems.
+The runtime-facing name is intentionally singular: use `agent_vent` for the LLM tool, `/agent_vent` for the command, and `agent_vent` for the toolbox bundle id. Review queue, outcome, compare, retention-candidate, retention-history, export, and detail output include advisory human-review hints, explicit local decision-posture projections, exact local next-action commands for review state, draft-only handoff targets, export prompts, retention preview eligibility, and rollback-candidate commands from archive receipts; generated commands quote dynamic recurrence keys/paths so legacy keys remain copyable. Decision posture is derived local diagnostic wording only: it is not resolution, assignment, issue status, task truth, incident state, evidence, or publication. Filtered compare follow-up commands preserve supported category/tag/tool/package filters for `outcomes`, `retention candidates`, and `export`. Export filters are local diagnostic focus aids only, not evidence scoping, publication, owner routing, or owner assignment; export applies review-state and facet scope before counts, summaries, display rows, and safe local follow-up commands. Outcome and compare limits are explicit per review-state bucket so `outcomes all 1` can show one `new`, one `acknowledged`, one `dismissed`, and one `escalation_drafted` group, while `compare 1` shows at most one group per state. Review/outcome/compare/export/retention-candidate/history command syntax fails closed before store reads for unknown filters, empty filter values such as `owner=` or `tag=`, invalid states/arguments, invalid category values, or invalid retention-history arguments. These surfaces are guidance only and do not route, file, create, declare, assign, record evidence, publish, archive, restore, or mutate owner systems.
 
 ## Deeper Pi integration
 

package/docs/project/2026-05-21-agent-vent-design.md

@@ -129,7 +129,7 @@ Important behavior:
 
 ### `/agent_vent`
 
-Human/operator command for lightweight inspection. `/agent-vent` remains a compatibility alias.
+Human/operator command for lightweight inspection. The command name is intentionally singular: `/agent_vent`.
 
 - `/agent_vent help`
 - `/agent_vent summary`
@@ -168,7 +168,7 @@ This heuristic intentionally errs toward surfacing review candidates, not assert
 
 - ASC/`self` owns operational introspection, subagent/runtime control, and mirror-only handoff/progress summaries.
 - `pi-agent-vent` owns local diagnostic vent records, redaction, recurrence grouping, and advisory candidate-incident heuristics.
-- `pi-toolbox-discovery` owns discovery/activation of the already-registered `agent_vent` tool through the same-named `agent_vent` bundle.
+- `pi-toolbox-discovery` owns discovery/activation of the already-registered `agent_vent` tool through the same-named `agent_vent` bundle; `agent-vent` is not a runtime alias.
 
 This keeps vent persistence from becoming hidden ASC state while still making the capability discoverable during autonomous work.
 

package/docs/project/2026-05-21-agent-vent-implementation-plan.md

@@ -19,7 +19,7 @@ Create a new simple-package monorepo package from `pi-extensions-template` and r
 
 - Package exists at `packages/pi-agent-vent` with tracked `.copier-answers.yml` and template-aligned metadata.
 - `agent_vent` custom tool supports `record`, `summary`, `list`, and `path` actions.
-- `/agent_vent` command supports human-readable `help`, `summary`, `list`, and `path` inspection, with `/agent-vent` retained as a compatibility alias.
+- `/agent_vent` command supports human-readable `help`, `summary`, `list`, and `path` inspection, with no `/agent-vent` runtime alias.
 - Durable data is append-only JSONL at `~/.pi/agent/agent-vent/vents.jsonl` or `PI_AGENT_VENT_DIR`.
 - Records are minimized, schema-versioned, and redacted for common secret patterns.
 - Recurrence grouping and candidate-incident heuristics are implemented in testable core code.
@@ -38,7 +38,7 @@ Create a new simple-package monorepo package from `pi-extensions-template` and r
    - grouping, candidate-incident, and formatting helpers.
 3. Replace `extensions/agent-vent.ts` scaffold command:
    - register `agent_vent` custom tool with clear prompt guidelines;
-   - register `/agent_vent` inspection command plus `/agent-vent` compatibility alias;
+   - register `/agent_vent` inspection command only; do not add `/agent-vent` as a runtime alias;
    - keep all storage local; avoid network and owner-surface writes.
 4. Add `tests/vent-store.test.js` for redaction, record creation, JSONL round-trip, and summary grouping.
 5. Update package metadata and docs:

package/docs/project/product-posture.md

@@ -51,7 +51,7 @@ When an agent keeps hitting the same bug, missing affordance, brittle workflow,
 
 - maturity: `local diagnostic alpha, review-and-retention safety hardened; privacy, review-command, outcome-follow-up, review-filter, review-compare, follow-up-scope, export-scope, export-follow-up, review-decision-legibility, destructive-selection, retention-history, public-contract parity, unpacked-artifact contract, installed-command smoke, installed shadow registered-tool smoke, and release-metadata alignment membranes verified`
 - current capability baseline: local append-only vent capture with optional local tool/package facets, recurrence grouping, local facet summary, local operator review queue with fail-closed-before-store-read command syntax and read-only category/tag/tool/package facet filters, read-only per-state review outcome follow-up buckets, read-only cross-state review comparison without archive/restore tokens, explicit derived local decision-posture projections, curation-aware recurrence resolution for review-state commands and record feedback, filter-preserving supported follow-up commands including record/state-scoped facet export, export-local-follow-up guidance without archive/restore tokens, read-only reviewed-group retention candidate planning without archive tokens, read-only retention receipt history with rollback-candidate restore command reconstruction, advisory human-review hints, quoted state-aware local next-action guidance that round-trips legacy recurrence keys, bounded representative-sample detail, review-state events, append-only recurrence curation projections with remove/undo events, diagnostic-state load membrane with privacy metadata recomputation, facet-aware draft-only owner-surface text generation, lifecycle stats/export projections, lock/hash-guarded confirmation-gated retention archive/restore with duplicate-id-safe record selection, local backup receipts, and rollback safeguards, advisory candidate-incident heuristic, redaction/minimization, `/agent_vent` inspection command, toolbox discovery, ASC/self companion routing, self-contained public-artifact validation for advertised package scripts/docs, no-auth installed-artifact shadow registered-tool `agent_vent path` release smoke with isolated npm prefix/cache and vent storage, installed-tarball local-path package-discovery `/agent_vent path` release smoke with isolated Pi settings, npm prefix/cache, and vent store, explicit local `npm:<tarball>` install-source validation, and package-local release metadata alignment checks for `repository.directory`, `x-pi-template.workspacePath`, and `x-pi-template.releaseComponent`
-- release posture: first publishable package release at `0.1.0`; npm package not yet published at time of first release checks; unpacked tarball contract has artifact-local `npm install && npm run check` proof, artifact-only quick release checks now install the packed tarball into an isolated npm prefix and execute the installed artifact's registered `agent_vent` tool `action=path` through a shadow import against isolated vent storage without Pi auth, full release checks additionally validate local `npm:<tarball>` as the install source and smoke the installed packed artifact through local-path Pi package discovery by running `/agent_vent path` with isolated Pi settings, isolated npm prefix/cache, and isolated vent storage, and package-local structure validation now fails closed on release metadata drift against `.copier-answers.yml`; the remaining release gap is real npm/GitHub provenance publication, not local artifact/package-loading confidence
+- release posture: first published package release is `0.1.0` on npm; `0.1.1` removed the `/agent-vent` command alias and kept runtime-facing naming singularly `agent_vent`; source/package version `0.1.2` hardens extension load against stale review-state imports during reload; unpacked tarball contract has artifact-local `npm install && npm run check` proof, artifact-only quick release checks install the packed tarball into an isolated npm prefix and execute the installed artifact's registered `agent_vent` tool `action=path` through a shadow import against isolated vent storage without Pi auth, full release checks additionally validate local `npm:<tarball>` as the install source and smoke the installed packed artifact through local-path Pi package discovery by running `/agent_vent path` with isolated Pi settings, isolated npm prefix/cache, and isolated vent storage, and package-local structure validation fails closed on release metadata drift against `.copier-answers.yml`; post-publication registry smoke installed `@tryinget/pi-agent-vent@0.1.0` into an isolated npm prefix and verified the installed artifact and shadow registered-tool `path` behavior
 - current strategic line: harden the local review workflow before adding owner-surface escalation adapters
 
 ## Product success criteria
@@ -71,7 +71,7 @@ The package is product-healthy when:
 The package currently owns:
 
 - `agent_vent` tool with `record`, `summary`, `list`, `path`, `facets`, `review`, `outcomes`, `compare`, `set_review`, `curate`, `draft`, `stats`, `export`, and `retention` actions, including read-only local facet filters for review queues, outcome follow-up, cross-state comparison, retention-candidate planning, and read-only retention receipt history;
-- `/agent_vent` command for local inspection and recurrence review, with `/agent-vent` retained as a compatibility alias;
+- `/agent_vent` command for local inspection and recurrence review, with no `/agent-vent` runtime alias;
 - schema-versioned local JSONL storage at `~/.pi/agent/agent-vent/vents.jsonl`, local review events at `~/.pi/agent/agent-vent/review-events.jsonl`, local curation events at `~/.pi/agent/agent-vent/curation-events.jsonl`, local retention receipts at `~/.pi/agent/agent-vent/retention-events.jsonl`, and retention backups under `~/.pi/agent/agent-vent/backups/`, overridable via `PI_AGENT_VENT_DIR`;
 - conservative redaction for common secret/token/password shapes;
 - recurrence key derivation and grouping;
@@ -168,7 +168,7 @@ These drafts do not submit automatically. The package prepares local text, local
 
 ## Next frontier guidance
 
-The next highest-leverage slice should assume the facets/review/outcomes/compare/filter/hint/detail/draft/curation/retention-candidate/retention-history/retention-archive/export/export-follow-up/review-decision-posture and public-runtime-artifact smoke membranes are the baseline and should not broaden authority. Retention now has transaction-oriented safeguards (store/review/curation-hash tokens, append/archive locking, duplicate-id-safe selected-record removal, stale-lock cleanup, receipt-failure rollback, derived restore tokens, realpath backup containment, quoted rollback commands, retention-history receipt rediscovery, and stale-restore checks) plus read-only reviewed-candidate, receipt-history, export follow-up, decision-posture, and cross-state comparison surfaces that preserve supported follow-up scope without owner-surface mutation. Local facet labels, filters, curation aliases, outcome states, comparison buckets, hints, generated commands, export snapshots, history receipts, decision posture, and draft text are diagnostic projections only; filtered export is record/state-scoped and is not evidence, publication, owner routing, or owner assignment. The clarified source-owner seam is that export/history/review scope may focus local diagnostic data but cannot make that data canonical evidence or publication, and curation-aware recurrence keys are local projection identity rather than owner-system identity; local release smoke and release metadata checks may prove package-loading and repo-local metadata alignment but cannot prove npm publication/provenance; Prompt Vault, AK, GitHub, incident, evidence, ROCS, ASC/self, toolbox surfaces, and npm publication/provenance remain separate owners. The latest contract-parity frontier is maintaining source checkout versus public runtime artifact proof together: `npm pack` contents, README/package scripts, packaged docs, release checks, installed package settings, isolated npm installation state, no-auth installed shadow registered-tool smoke, installed command smoke, local tarball install-source validation, local-path Pi package-discovery smoke, and release metadata alignment must be validated as consumed, not only from the monorepo checkout. Discovery showed local `npm:<tarball>` is useful as a Pi install input but is not a documented runtime package-discovery source like `npm:@scope/pkg@1.2.3`; the package now fails closed against falsely claiming that proof. The remaining release frontier is the external publish/provenance workflow, not more unlabeled local package smoke. npm publish, AK/GitHub/incident/evidence creation, and hard-delete remain out of scope unless explicitly authorized. Preserve the contract-parity lesson from this iteration: command grammar, LLM tool schema, README examples, posture docs, package `files[]`, release checks, artifact-local scripts, smoke scripts, and tests must change together; unknown syntax must fail closed before store reads even when values are empty. Do not spend the next slice on hard-delete unless a new decision explicitly supersedes [ADR 2026-05-22](../adr/2026-05-22-agent-vent-retention-delete-policy.md).
+The next highest-leverage slice should assume the facets/review/outcomes/compare/filter/hint/detail/draft/curation/retention-candidate/retention-history/retention-archive/export/export-follow-up/review-decision-posture and public-runtime-artifact smoke membranes are the baseline and should not broaden authority. Retention now has transaction-oriented safeguards (store/review/curation-hash tokens, append/archive locking, duplicate-id-safe selected-record removal, stale-lock cleanup, receipt-failure rollback, derived restore tokens, realpath backup containment, quoted rollback commands, retention-history receipt rediscovery, and stale-restore checks) plus read-only reviewed-candidate, receipt-history, export follow-up, decision-posture, and cross-state comparison surfaces that preserve supported follow-up scope without owner-surface mutation. Local facet labels, filters, curation aliases, outcome states, comparison buckets, hints, generated commands, export snapshots, history receipts, decision posture, and draft text are diagnostic projections only; filtered export is record/state-scoped and is not evidence, publication, owner routing, or owner assignment. The clarified source-owner seam is that export/history/review scope may focus local diagnostic data but cannot make that data canonical evidence or publication, and curation-aware recurrence keys are local projection identity rather than owner-system identity; local release smoke and release metadata checks may prove package-loading and repo-local metadata alignment but cannot prove npm publication/provenance; Prompt Vault, AK, GitHub, incident, evidence, ROCS, ASC/self, toolbox surfaces, and npm publication/provenance remain separate owners. The latest contract-parity frontier is maintaining source checkout versus public runtime artifact proof together: `npm pack` contents, README/package scripts, packaged docs, release checks, installed package settings, isolated npm installation state, no-auth installed shadow registered-tool smoke, installed command smoke, local tarball install-source validation, local-path Pi package-discovery smoke, and release metadata alignment must be validated as consumed, not only from the monorepo checkout. Discovery showed local `npm:<tarball>` is useful as a Pi install input but is not a documented runtime package-discovery source like `npm:@scope/pkg@1.2.3`; the package now fails closed against falsely claiming that proof. The remaining release frontier is ongoing provenance/release-process evidence for future versions, not more unlabeled local package smoke for `0.1.0`. npm publish, AK/GitHub/incident/evidence creation, and hard-delete remain out of scope unless explicitly authorized. Preserve the contract-parity lesson from this iteration: command grammar, LLM tool schema, README examples, posture docs, package `files[]`, release checks, artifact-local scripts, smoke scripts, and tests must change together; unknown syntax must fail closed before store reads even when values are empty. Do not spend the next slice on hard-delete unless a new decision explicitly supersedes [ADR 2026-05-22](../adr/2026-05-22-agent-vent-retention-delete-policy.md).
 
 ## Ownership map
 

package/extensions/agent-vent.ts

@@ -48,11 +48,11 @@ import {
   normalizeRetentionAction,
   normalizeReviewState,
   RETENTION_ACTIONS,
-  REVIEW_STATES,
   readRetentionEvents,
   resolveRecurrenceGroup,
   restoreRetentionBackup,
   SEVERITIES,
+  REVIEW_STATES as STORE_REVIEW_STATES,
   summarizeRecords,
   summarizeReviewQueue,
 } from "../src/vent-store.js";
@@ -74,6 +74,10 @@ const ACTIONS = [
   "retention",
 ] as const;
 const EXPORT_FORMATS = ["markdown", "json"] as const;
+const FALLBACK_REVIEW_STATES = ["new", "acknowledged", "dismissed", "escalation_drafted"] as const;
+const REVIEW_STATES = Array.isArray(STORE_REVIEW_STATES)
+  ? STORE_REVIEW_STATES
+  : FALLBACK_REVIEW_STATES;
 const RETENTION_CANDIDATE_STATES = ["reviewed", "all", ...REVIEW_STATES] as const;
 
 const AgentVentParams = Type.Object({
@@ -724,12 +728,7 @@ export default function agentVentExtension(pi: ExtensionAPI) {
   registerAgentVentCommand(
     pi,
     "agent_vent",
-    "Inspect local agent vent records: /agent_vent [help|summary|list|facets|review|outcomes|compare|curate|draft|retention|stats|export|path]",
-  );
-  registerAgentVentCommand(
-    pi,
-    "agent-vent",
-    "Alias for /agent_vent [help|summary|list|facets|review|outcomes|compare|curate|draft|retention|stats|export|path]",
+    "Inspect local agent_vent records: /agent_vent [help|summary|list|facets|review|outcomes|compare|curate|draft|retention|stats|export|path]",
   );
 }
 
@@ -787,7 +786,6 @@ function handleCommand(args: string) {
       "  /agent_vent export [markdown|json] [state|all] [limit] [category=bug] [tag=reload] [tool=pi-reload] [package=tryinget-pi-agent-vent]",
       "                                                        Export a bounded local diagnostic projection, optionally facet-filtered.",
       "  /agent_vent path                                     Show local JSONL store paths.",
-      "  /agent-vent ...                                      Backward-compatible alias.",
       "",
       "LLM tool: agent_vent can record minimized frustration events, local review states, local recurrence curation projections, and read-only review comparisons.",
       "Boundary: local diagnostics only; no AK tasks, GitHub issues, incidents, evidence, telemetry, or ASC/self state are created.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryinget/pi-agent-vent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local pi tool for agents to record recurring frustrations, bugs, and workflow friction without creating incidents or external telemetry",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/tests/agent-vent-extension.test.js

@@ -23,13 +23,13 @@ function createMockPi() {
   };
 }
 
-test("extension registers agent_vent tool and command aliases", () => {
+test("extension registers only the canonical agent_vent tool and command", () => {
   const pi = createMockPi();
   agentVentExtension(pi.api);
 
   assert.equal(pi.tools.has("agent_vent"), true);
   assert.equal(pi.commands.has("agent_vent"), true);
-  assert.equal(pi.commands.has("agent-vent"), true);
+  assert.equal(pi.commands.has("agent-vent"), false);
   assert.match(pi.tools.get("agent_vent").description, /frustration/i);
 });