---

summary: "Overview and quickstart for the pi-agent-vent package." read_when:

• "Starting work in this package workspace."
• "Installing or using the agent_vent tool." system4d: container: "Local pi extension for agent frustration capture." compass: "Surface recurring agent friction while preserving authority boundaries and privacy." engine: "Install package -> record minimized vents -> inspect recurrence summary -> human decides escalation." fog: "Vents can be mistaken for canonical incidents, tasks, or telemetry."

---

@tryinget/pi-agent-vent

pi-agent-vent gives Pi agents a local agent_vent tool for recording and reviewing recurring frustrations they notice while working: long-lived bugs, repeated tool/runtime failures, brittle workflows, context-loss patterns, missing affordances, and documentation gaps.

It is intentionally local-first and advisory. It does not create AK tasks, GitHub issues, canonical evidence, external telemetry, ASC/self state, or real incidents.

• Workspace path: packages/pi-agent-vent
• Release component key: pi-agent-vent
• Package command: /agent_vent
• LLM tool: agent_vent
• Toolbox bundle id: agent_vent

Why this exists

Agents often encounter the same friction repeatedly but have no durable low-cost place to say “this keeps hurting.” This package captures those observations as small local JSONL records, groups them by recurrence key, and lets a human mark local review state before deciding whether any owner surface should act.

Install and activate

From this package directory:

npm install
npm run check
pi install /absolute/path/to/your/monorepo/packages/pi-agent-vent

Then in Pi:

/reload
/agent_vent help

Tool behavior

agent_vent supports fourteen actions:

Action	Purpose
record	Append a minimized vent record. Requires summary.
summary	Show recurrence groups and advisory candidate incidents.
list	Show recent local records.
path	Show the store path and boundary contract.
review	Show recurrence groups as a local operator review queue; optionally filter by local category/tag/tool/package facets; include a recurrence key to inspect bounded representative samples.
outcomes	Show read-only local follow-up grouped by review outcome state, including exact local next commands without owner-system mutation.
compare	Compare local review-state buckets before export, retention planning, or draft-only handoff without emitting archive/restore tokens.
facets	Show read-only local category/tag/tool/package facet counts for triage.
set_review	Set local review state for a recurrence group.
curate	Append local recurrence merge/rename projection events without rewriting raw vents.
draft	Generate draft-only owner-surface text for a recurrence group.
stats	Show local store counts, byte sizes, malformed-line counts, curation counts, and review-state totals.
export	Produce a bounded local diagnostic projection in markdown or JSON, optionally focused by local category/tag/tool/package facets.
retention	List read-only reviewed archive candidates and receipt history, preview, confirmation-gate, archive, and restore reviewed local diagnostic records with local backups/receipts.

The tool prompt tells the agent to avoid ordinary status updates, raw logs, secrets, and private user payloads.

Human command

/agent_vent help
/agent_vent summary
/agent_vent list 20
/agent_vent facets
/agent_vent review
/agent_vent review new 20 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
/agent_vent review show bug:reload-tools
/agent_vent review set acknowledged bug:reload-tools "seen locally"
/agent_vent outcomes all 10 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
# outcomes and compare limits are per review-state bucket, not a global row cap
/agent_vent compare 10 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
/agent_vent retention candidates reviewed 20 category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
/agent_vent retention history 20
/agent_vent curate merge bug:reload-tool-a bug:reload-tools "same local pattern"
/agent_vent curate remove bug:reload-tool-a "undo local merge"
/agent_vent draft github_issue bug:reload-tools
/agent_vent stats
/agent_vent export markdown acknowledged category=tool_failure tag=reload tool=pi-reload package=tryinget-pi-agent-vent
/agent_vent retention preview bug:reload-tools
/agent_vent retention archive bug:reload-tools archive:<token> "reviewed locally"
/agent_vent retention restore /path/to/backups/<backup>.agent-vent-backup.json restore:<token>
/agent_vent path

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

pi-agent-vent is a companion to pi-autonomous-session-control, not part of it. ASC/self remains the execution and operational-mirror owner; this package owns only local vent diagnostics.

When pi-toolbox-discovery is installed, it exposes the agent_vent bundle so agents can discover or activate the same-named agent_vent tool on demand:

toolbox({ action: "search", query: "vent" })
toolbox({ action: "activate", bundle: "agent_vent" })

The owner extension must still be installed/reloaded so the agent_vent tool is registered before toolbox can activate it.

Local data contract

Default store:

~/.pi/agent/agent-vent/vents.jsonl
~/.pi/agent/agent-vent/review-events.jsonl
~/.pi/agent/agent-vent/curation-events.jsonl
~/.pi/agent/agent-vent/retention-events.jsonl
~/.pi/agent/agent-vent/backups/

Override:

PI_AGENT_VENT_DIR=/path/to/private/dir pi

Records are append-only JSONL with schemaVersion: 1. Optional tool and packageName record fields are local diagnostic facets only, not owner-routing truth. Review state changes are append-only local events in review-events.jsonl; recurrence curation changes are append-only local events in curation-events.jsonl. Retention lifecycle receipts are append-only local events in retention-events.jsonl; archive rollback artifacts are package-created local files under backups/. Recurrence review state, review outcome follow-up, and merged/renamed groups are projections from the latest local events; local review-state commands and record feedback resolve curated source keys to the active projected group. Raw vent records are not rewritten except by explicit, confirmation-gated local retention archive/restore operations.

Reads tolerate malformed old lines, oversized lines, invalid records, and semantic curation corruption by reporting ignored/quarantined counts. JSONL store files fail closed when replaced by symlinks or when a store exceeds the package file-size guard. facets, review, outcomes, compare, curate, draft, stats, export, and retention are local diagnostic surfaces, not evidence, owner routing, tasks, issues, incidents, publication, telemetry, or ASC/self state. Draft outputs are paste-ready text only; the owner system still decides acceptance, lifecycle, evidence, and publication.

Retention archive is intentionally destructive to the active local vents store, so it is confirmation-gated: use retention candidates for a read-only reviewed-group planning view that emits no archive tokens, preview a reviewed recurrence group first, copy the exact archive:<token>, then archive. The token includes the active store hash, archive and record append share a local lock, archive creates a backup before rewriting vents.jsonl, and receipt failures roll the active store back when the archive rewrite can still be identified. retention history is a read-only receipt projection that can rediscover recent archive/restore receipts and reconstruct rollback-candidate restore commands from archive receipts; those commands still fail closed during actual restore if the backup is stale, moved, symlink-escaped, missing, or outside the real backup directory. Restore requires the package-created backup path, exact derived restore:<token>, real backup-directory containment, and a current-store hash match so stale backups fail closed. The package intentionally has no hard-delete command in v0.1; permanent removal is operator-owned filesystem/data-lifecycle control, not evidence/task/incident lifecycle.

All display/export/draft/review-detail paths pass loaded records through a diagnostic-state membrane that normalizes schema, re-applies redaction on read, recomputes privacy metadata for loaded records, quarantines curation cycles, and keeps exact recurrence lookup separate from display limits. Review queue and export filters can use local category/tag/tool/package labels, but those filters are diagnostic focus aids only, not owner routing, owner assignment, evidence scoping, or publication. Filtered export is record/state scoped so mixed recurrence groups do not broaden exported counts, summaries, rows, or generated follow-up commands. Export follow-up commands are local diagnostic or draft-only next steps and intentionally include no archive/restore tokens. Drafts include local diagnostic facets when present, but those facets are hints for human review rather than owner-routing truth.

The package applies conservative redaction heuristics for common token/password/API-key shapes, including review notes, but callers must still avoid submitting secrets.

Data classification: local diagnostic user data. No network calls are made by this package.

Candidate incidents are not incidents

A recurrence group is flagged as a candidateIncident when it is repeated or high severity. That flag means “worth human review,” not “incident declared.” Escalation belongs to the appropriate owner surface.

Engineering-core alignment

This package follows engineering-core lane pi-ts:

uv tool -n run --from ~/ai-society/core/engineering-core engineering-core show pi-ts --prefer-repo

Package-specific selected disciplines are documented in docs/engineering.local.md, including local-first-data, data-governance, domain-modeling, and observability because this package owns durable local diagnostic records.

Product docs:

• Vision
• Product posture
• Agent vent design
• Implementation plan

Package checks

Run from package directory:

npm install
npm run check

For release confidence, npm run release:check packs the package, verifies packaged docs/scripts, runs the packaged fallback gate, installs the tarball into an isolated npm prefix for a no-auth shadow registered-tool agent_vent path smoke, then installs the tarball with isolated Pi settings and npm prefix/cache, validates that local npm:<tarball> is being used only as the install source, and smokes the installed artifact through local-path Pi package discovery with /agent_vent path. Use npm run release:check:quick for artifact-only checks when live Pi smoke is not available; quick checks still include the no-auth installed shadow registered-tool smoke. These smokes prove artifact/package-loading behavior only, not npm/GitHub publication or provenance.

Run from monorepo root through the canonical package gate:

bash ./scripts/package-quality-gate.sh ci packages/pi-agent-vent

AK task/work-item operations

This package is a monorepo member, not a git root. Use plain installed ak from the monorepo root or this package directory; repo identity still belongs to the monorepo root. Do not invent package-local AK wrappers.

Release metadata

• npm package name: @tryinget/pi-agent-vent
• release component/tag stem: pi-agent-vent (for example pi-agent-vent-vX.Y.Z)
• release config mode: component

Keep .copier-answers.yml tracked and do not edit it manually.