pi-self-complaint 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,54 @@
1
- # Temporary Holding Version
1
+ # pi-self-complaint
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A Pi extension that, after each agent run, asks the model whether anything about the system annoyed it. If it names a concrete problem, the sentence is appended to `docs/agent-complaints.md` in the project. Off by default.
4
+
5
+ Each enabled run makes one extra model request, so it costs tokens. Turn it on only where you want the feedback.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ pi install npm:pi-self-complaint
11
+ ```
12
+
13
+ For one invocation use `pi -e npm:pi-self-complaint`. Requires Pi `>=0.87.1`, which provides the `agent_before_settle` hook.
14
+
15
+ ## Usage
16
+
17
+ ```
18
+ /complaints on # ask in this project
19
+ /complaints off # stop asking in this project
20
+ /complaints # show status for this project and the log path
21
+ ```
22
+
23
+ The setting is per project directory. It is stored in `~/.pi/agent/self-complaint.json` (or `$PI_CODING_AGENT_DIR/self-complaint.json`) as a map from absolute directory path to `true`. Every new session in an enabled directory asks; other directories are unaffected. The match is exact: subdirectories and moved or renamed folders need `/complaints on` again.
24
+
25
+ ## How it works
26
+
27
+ 1. When a run completes, the extension adds a hidden question (`display: false`) and requests one more model response.
28
+ 2. The model answers with exactly `NO` or `COMPLAINT: <one sentence>`.
29
+ 3. A complaint is appended as a line to `docs/agent-complaints.md`, with the date, session ID, and project name:
30
+
31
+ ```
32
+ # Agent complaints
33
+
34
+ - 2026-11-16 20:40 · session 01a1e0d4 · #my-project · pnpm gate keeps running after the rules step fails
35
+ ```
36
+
37
+ Aborted and errored runs are not asked. Runs that only pause while background work is still going are not asked either: with `pi-background-tasks` a task that will wake the agent (`notifyOnCompletion` and `triggerOnCompletion`), and with `pi-subagents` an async subagent run, count as pending until their completion arrives. The question then comes in the run that the result starts. Without those extensions nothing is tracked and each run is asked as before. Replies that are neither `NO` nor a `COMPLAINT:` line are ignored and logged nothing. The question is asked once per run, so the extension cannot loop.
38
+
39
+ ## Privacy
40
+
41
+ The sentence is written by the model and may contain paths, code fragments, or secrets from the session context. Everything stays local: nothing is sent anywhere except the normal model request Pi already makes. The log lives inside the project, so check `docs/agent-complaints.md` before committing it or add it to `.gitignore`.
42
+
43
+ ## Limits
44
+
45
+ Answers are model self-reports: they can be invented to fit the question or missing when the model is unaware of a problem. Treat them as leads to verify, not as measurements.
46
+
47
+ ## Development checks
48
+
49
+ ```sh
50
+ npm test
51
+ npm run typecheck
52
+ ```
53
+
54
+ Tests use a mocked Pi API and never call a model.
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "pi-self-complaint",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "After each Pi run, ask the agent what annoyed it and log concrete complaints to the project's docs",
5
+ "keywords": ["pi-package"],
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "files": ["src", "README.md"],
9
+ "engines": {
10
+ "node": ">=22.19"
11
+ },
12
+ "scripts": {
13
+ "test": "node --test test/*.test.ts",
14
+ "typecheck": "tsc --noEmit"
15
+ },
16
+ "pi": {
17
+ "extensions": [
18
+ "./src/index.ts"
19
+ ]
20
+ },
21
+ "peerDependencies": {
22
+ "@earendil-works/pi-coding-agent": ">=0.87.1"
23
+ },
24
+ "devDependencies": {
25
+ "@earendil-works/pi-coding-agent": "^1.5.2",
26
+ "@types/node": "^24.0.0",
27
+ "typescript": "^5.9.3"
28
+ }
29
+ }
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Event names published by the background-work extensions. They are plain strings on the shared `pi.events` bus,
3
+ * so this package does not depend on them. Without those extensions nothing is ever published and nothing is tracked.
4
+ */
5
+ export const SUBAGENT_ASYNC_STARTED = "subagent:async-started";
6
+ export const SUBAGENT_ASYNC_COMPLETE = "subagent:async-complete";
7
+ export const BACKGROUND_TERMINAL = "pi-background-tasks:terminal:v1";
8
+
9
+ function idOf(value: unknown): string | undefined {
10
+ if (!value || typeof value !== "object") return undefined;
11
+ const id = (value as { id?: unknown }).id;
12
+ return typeof id === "string" && id !== "" ? id : undefined;
13
+ }
14
+
15
+ /** Id of a background subagent run, from `subagent:async-started` or `subagent:async-complete`. */
16
+ export function subagentRunId(payload: unknown): string | undefined {
17
+ return idOf(payload);
18
+ }
19
+
20
+ /** Id of a finished background shell or agent task, from `pi-background-tasks:terminal:v1`. */
21
+ export function terminalTaskId(payload: unknown): string | undefined {
22
+ if (!payload || typeof payload !== "object") return undefined;
23
+ return idOf((payload as { task?: unknown }).task);
24
+ }
25
+
26
+ /**
27
+ * Id of a background task that was just started by a tool, from the tool result details (`details.task`).
28
+ * Only tasks that wake the parent when they finish count: without notify and trigger the parent never
29
+ * gets a new run for them, so waiting for them would silence complaints for good.
30
+ */
31
+ export function startedBackgroundTaskId(details: unknown): string | undefined {
32
+ if (!details || typeof details !== "object") return undefined;
33
+ const task = (details as { task?: unknown }).task;
34
+ if (!task || typeof task !== "object") return undefined;
35
+ const { status, notifyOnCompletion, triggerOnCompletion } = task as Record<string, unknown>;
36
+ if (status !== "running" || notifyOnCompletion !== true || triggerOnCompletion !== true) return undefined;
37
+ return idOf(task);
38
+ }
@@ -0,0 +1,64 @@
1
+ import { appendFileSync, existsSync, mkdirSync } from "node:fs";
2
+ import { dirname } from "node:path";
3
+
4
+ export const QUESTION_TYPE = "self-complaint-question";
5
+ export const LOG_RELATIVE_PATH = "docs/agent-complaints.md";
6
+ export const MAX_COMPLAINT_CHARS = 500;
7
+
8
+ export const QUESTION = [
9
+ "Before you finish: did anything about the system, its tools, or this workflow annoy you during this run?",
10
+ "Reply with exactly one line and nothing else:",
11
+ "NO",
12
+ "or",
13
+ "COMPLAINT: <one concrete sentence naming the specific tool, step, or behaviour>",
14
+ ].join("\n");
15
+
16
+ export type ParsedAnswer =
17
+ | { type: "complaint"; text: string }
18
+ | { type: "none" }
19
+ | { type: "invalid" };
20
+
21
+ /** Reads the first non-empty line of the reply. Anything else is treated as invalid and logs nothing. */
22
+ export function parseAnswer(text: string): ParsedAnswer {
23
+ const line = text.split(/\r?\n/).map((part) => part.trim()).find((part) => part !== "");
24
+ if (line === undefined) return { type: "invalid" };
25
+ if (/^NO\.?$/i.test(line)) return { type: "none" };
26
+ const match = /^COMPLAINT:\s*(.+)$/i.exec(line);
27
+ const complaint = match?.[1] ? sanitize(match[1]) : "";
28
+ return complaint ? { type: "complaint", text: complaint } : { type: "invalid" };
29
+ }
30
+
31
+ /** Collapses whitespace and caps length so one complaint stays one line in the log. */
32
+ export function sanitize(text: string): string {
33
+ const oneLine = text.replace(/\s+/g, " ").trim();
34
+ return oneLine.length > MAX_COMPLAINT_CHARS ? `${oneLine.slice(0, MAX_COMPLAINT_CHARS - 1)}…` : oneLine;
35
+ }
36
+
37
+ export function formatEntry(when: Date, sessionId: string, project: string, complaint: string): string {
38
+ const pad = (value: number) => String(value).padStart(2, "0");
39
+ const stamp = `${when.getFullYear()}-${pad(when.getMonth() + 1)}-${pad(when.getDate())} ${pad(when.getHours())}:${pad(when.getMinutes())}`;
40
+ return `- ${stamp} · session ${sessionId} · #${project} · ${complaint}`;
41
+ }
42
+
43
+ /** Appends one line, creating the file with a heading the first time. */
44
+ export function appendComplaint(path: string, line: string): void {
45
+ mkdirSync(dirname(path), { recursive: true });
46
+ const header = existsSync(path) ? "" : "# Agent complaints\n\n";
47
+ appendFileSync(path, `${header}${line}\n`, "utf8");
48
+ }
49
+
50
+ /** Returns the text of the most recent assistant message, or "" when there is none. */
51
+ export function lastAssistantText(messages: readonly { role: string; content?: unknown }[]): string {
52
+ for (let index = messages.length - 1; index >= 0; index--) {
53
+ const message = messages[index];
54
+ if (!message || message.role !== "assistant") continue;
55
+ const content = message.content;
56
+ if (typeof content === "string") return content;
57
+ if (!Array.isArray(content)) return "";
58
+ return content
59
+ .filter((part): part is { type: "text"; text: string } => part?.type === "text" && typeof part.text === "string")
60
+ .map((part) => part.text)
61
+ .join("\n");
62
+ }
63
+ return "";
64
+ }
package/src/index.ts ADDED
@@ -0,0 +1,132 @@
1
+ import { basename, join } from "node:path";
2
+ import type { AgentBeforeSettleEventResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
3
+ import {
4
+ LOG_RELATIVE_PATH,
5
+ QUESTION,
6
+ QUESTION_TYPE,
7
+ appendComplaint,
8
+ formatEntry,
9
+ lastAssistantText,
10
+ parseAnswer,
11
+ } from "./complaint.ts";
12
+ import {
13
+ BACKGROUND_TERMINAL,
14
+ SUBAGENT_ASYNC_COMPLETE,
15
+ SUBAGENT_ASYNC_STARTED,
16
+ startedBackgroundTaskId,
17
+ subagentRunId,
18
+ terminalTaskId,
19
+ } from "./background.ts";
20
+ import { defaultStatePath, isEnabled, writeEnabled } from "./state.ts";
21
+
22
+ export default function selfComplaint(pi: ExtensionAPI, statePath = defaultStatePath()): void {
23
+ // True while the one extra "did anything annoy you?" request of the current run is pending.
24
+ let asked = false;
25
+
26
+ // Background runs that will start a new run when they finish. The parent settles while they are still working,
27
+ // so asking then would ask before the work is done. Ids are removed when the matching completion arrives.
28
+ const pendingBackground = new Set<string>();
29
+ const busUnsubscribes = [
30
+ pi.events?.on(SUBAGENT_ASYNC_STARTED, (payload) => {
31
+ const id = subagentRunId(payload);
32
+ if (id) pendingBackground.add(id);
33
+ }),
34
+ pi.events?.on(SUBAGENT_ASYNC_COMPLETE, (payload) => {
35
+ const id = subagentRunId(payload);
36
+ if (id) pendingBackground.delete(id);
37
+ }),
38
+ pi.events?.on(BACKGROUND_TERMINAL, (payload) => {
39
+ const id = terminalTaskId(payload);
40
+ if (id) pendingBackground.delete(id);
41
+ }),
42
+ ];
43
+
44
+ pi.on("session_start", () => {
45
+ asked = false;
46
+ });
47
+ pi.on("session_tree", () => {
48
+ asked = false;
49
+ });
50
+ pi.on("session_shutdown", () => {
51
+ for (const unsubscribe of busUnsubscribes) unsubscribe?.();
52
+ pendingBackground.clear();
53
+ });
54
+
55
+ // Tools that start a background shell or agent task return its snapshot in details.task. Without the bus there is
56
+ // no completion event to remove the id again, so nothing is tracked.
57
+ if (pi.events) {
58
+ pi.on("tool_result", (event) => {
59
+ const id = startedBackgroundTaskId(event.details);
60
+ if (id) pendingBackground.add(id);
61
+ });
62
+ }
63
+
64
+ pi.registerCommand("complaints", {
65
+ description: "Turn agent self-complaints on, off, or show status for this project (on | off | status)",
66
+ handler: async (args, ctx) => {
67
+ const value = args.trim().toLowerCase() || "status";
68
+ if (value !== "on" && value !== "off" && value !== "status") {
69
+ ctx.ui.notify("Usage: /complaints [on | off | status]", "warning");
70
+ return;
71
+ }
72
+ try {
73
+ if (value !== "status") writeEnabled(statePath, ctx.cwd, value === "on");
74
+ const enabled = isEnabled(statePath, ctx.cwd);
75
+ ctx.ui.notify(`Agent complaints for ${ctx.cwd}: ${enabled ? "on" : "off"} (log: ${LOG_RELATIVE_PATH})`, "info");
76
+ } catch (error) {
77
+ ctx.ui.notify(`Could not update agent complaints: ${error instanceof Error ? error.message : String(error)}`, "error");
78
+ }
79
+ },
80
+ });
81
+
82
+ pi.on("agent_before_settle", (event, ctx): AgentBeforeSettleEventResult | undefined => {
83
+ if (event.outcome !== "completed") {
84
+ asked = false;
85
+ return;
86
+ }
87
+ if (!asked) {
88
+ // Disabled projects, and unreadable state, never trigger the extra request.
89
+ let enabled = false;
90
+ try {
91
+ enabled = isEnabled(statePath, ctx.cwd);
92
+ } catch (error) {
93
+ ctx.ui.notify(`Agent complaints disabled: ${error instanceof Error ? error.message : String(error)}`, "error");
94
+ }
95
+ if (!enabled) return;
96
+
97
+ // Background work is still running, so this settle is only a pause. Its completion starts a new run, and
98
+ // the question is asked there, once the work is actually done.
99
+ if (pendingBackground.size > 0) return;
100
+
101
+ // First boundary of the run: ask once and request exactly one more model response.
102
+ asked = true;
103
+ return {
104
+ entries: [
105
+ ...event.entries,
106
+ { type: "custom_message", customType: QUESTION_TYPE, content: QUESTION, display: false },
107
+ ],
108
+ continue: true,
109
+ };
110
+ }
111
+
112
+ // Second boundary: the continuation has run, so the answer is the last assistant message.
113
+ asked = false;
114
+ const answer = parseAnswer(lastAssistantText(event.context.contextMessages));
115
+ if (answer.type !== "complaint") return;
116
+
117
+ try {
118
+ const path = join(ctx.cwd, LOG_RELATIVE_PATH);
119
+ const line = formatEntry(new Date(), ctx.sessionManager.getSessionId(), basename(ctx.cwd), answer.text);
120
+ appendComplaint(path, line);
121
+ ctx.ui.notify(`Agent complaint saved to ${LOG_RELATIVE_PATH}`, "info");
122
+ } catch (error) {
123
+ // Never fail the run because the log could not be written.
124
+ ctx.ui.notify(`Could not save agent complaint: ${error instanceof Error ? error.message : String(error)}`, "error");
125
+ }
126
+ return;
127
+ });
128
+
129
+ pi.on("agent_settled", () => {
130
+ asked = false;
131
+ });
132
+ }
package/src/state.ts ADDED
@@ -0,0 +1,43 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
3
+ import { homedir } from "node:os";
4
+ import { dirname, join } from "node:path";
5
+
6
+ /** Projects where complaints are enabled, keyed by absolute project directory. */
7
+ export type ProjectStates = Record<string, true>;
8
+
9
+ export function defaultStatePath(env: Record<string, string | undefined> = process.env): string {
10
+ return join(env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"), "self-complaint.json");
11
+ }
12
+
13
+ /** Missing file means nothing is enabled. Invalid content throws so it is never overwritten by mistake. */
14
+ export function readStates(path: string): ProjectStates {
15
+ let text: string;
16
+ try {
17
+ text = readFileSync(path, "utf8");
18
+ } catch (error) {
19
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
20
+ throw error;
21
+ }
22
+ const value: unknown = JSON.parse(text);
23
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid self-complaint state file");
24
+ return Object.fromEntries(Object.entries(value).filter(([, on]) => on === true)) as ProjectStates;
25
+ }
26
+
27
+ export function isEnabled(path: string, cwd: string): boolean {
28
+ return readStates(path)[cwd] === true;
29
+ }
30
+
31
+ export function writeEnabled(path: string, cwd: string, enabled: boolean): void {
32
+ const states = readStates(path);
33
+ if (enabled) states[cwd] = true;
34
+ else delete states[cwd];
35
+ mkdirSync(dirname(path), { recursive: true });
36
+ const temporary = `${path}.${randomUUID()}.tmp`;
37
+ try {
38
+ writeFileSync(temporary, `${JSON.stringify(states, null, 2)}\n`, { mode: 0o600, flag: "wx" });
39
+ renameSync(temporary, path);
40
+ } finally {
41
+ rmSync(temporary, { force: true });
42
+ }
43
+ }