@howaboua/pi-agent-comms 0.0.1 → 0.0.3

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.
Files changed (47) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +1 -1
  3. package/dist/viewer/web/app.js +6 -6
  4. package/dist/viewer/web/render.js +2 -2
  5. package/docs/BOARD.md +1 -1
  6. package/docs/NOTES.md +19 -2
  7. package/package.json +75 -74
  8. package/src/board/activity.ts +1 -0
  9. package/src/board/briefing.ts +2 -2
  10. package/src/board/delivery.ts +8 -6
  11. package/src/board/runtime/activation.ts +2 -3
  12. package/src/board/runtime/catchup.ts +1 -1
  13. package/src/board/settings/panel.ts +11 -8
  14. package/src/board/viewer/web/app.js +6 -6
  15. package/src/board/viewer/web/render.js +2 -2
  16. package/src/guidance.ts +14 -14
  17. package/src/notes/AGENTS.md +3 -3
  18. package/src/notes/activation.ts +1 -0
  19. package/src/notes/bridge.ts +4 -2
  20. package/src/notes/context-owner.ts +5 -5
  21. package/src/notes/feature.ts +67 -1
  22. package/src/notes/fresh-notes.ts +46 -5
  23. package/src/notes/history-search-pruning.mjs +110 -76
  24. package/src/notes/history-search-worker.mjs +1 -1
  25. package/src/notes/history-windows.ts +1 -1
  26. package/src/notes/index.ts +9 -3
  27. package/src/notes/integrations.ts +83 -45
  28. package/src/notes/lifecycle.ts +11 -2
  29. package/src/notes/model-roles.ts +2 -2
  30. package/src/notes/notes-lookup.ts +1 -1
  31. package/src/notes/rollover.ts +34 -5
  32. package/src/notes/session-pruning-cleanup.mjs +164 -0
  33. package/src/notes/session-pruning-exit.mjs +312 -0
  34. package/src/notes/session-pruning-screen.ts +1 -1
  35. package/src/notes/session-pruning-sparse.mjs +133 -0
  36. package/src/notes/session-pruning-state.mjs +123 -0
  37. package/src/notes/session-pruning-transaction.ts +1 -0
  38. package/src/notes/session-pruning.ts +34 -1
  39. package/src/notes/settings-controls.ts +23 -17
  40. package/src/notes/settings-screen.ts +2 -6
  41. package/src/notes/settings.ts +13 -6
  42. package/src/notes/shared-notes.ts +52 -30
  43. package/src/notes/tool-contracts.ts +24 -5
  44. package/src/notes/tools.ts +51 -29
  45. package/src/notes/tree-checkpoint.ts +12 -13
  46. package/src/notes/window-message.ts +6 -18
  47. package/src/notes/windows.ts +10 -11
@@ -57,7 +57,7 @@ export function createTools(
57
57
  lifecycle: NotesLifecycle,
58
58
  search: HistorySearch,
59
59
  roles: ReturnType<typeof createModelRoles>,
60
- ): ToolDefinition[] {
60
+ ) {
61
61
  const assertActive = () => {
62
62
  if (!lifecycle.active)
63
63
  throw new Error(
@@ -65,6 +65,41 @@ export function createTools(
65
65
  );
66
66
  };
67
67
  const queries = createQueryExecutor(pi, store, lifecycle, search);
68
+ const requestContext = async (
69
+ id: string,
70
+ input: unknown,
71
+ signal: AbortSignal | undefined,
72
+ ctx: ExtensionContext,
73
+ parentCallId?: string,
74
+ ) => {
75
+ assertActive();
76
+ if (signal?.aborted) throw new Error("Rollover cancelled");
77
+ const { role, resume = true } = prepareNewContextArguments(input);
78
+ const handoff =
79
+ role === undefined ? undefined : await roles.prepare(role, ctx);
80
+ if (signal?.aborted) throw new Error("Rollover cancelled");
81
+ const started = lifecycle.requestRollover(
82
+ ctx,
83
+ id,
84
+ handoff,
85
+ resume,
86
+ parentCallId,
87
+ );
88
+ if (started && resume) ctx.abort();
89
+ return {
90
+ ...result({
91
+ started,
92
+ message: started
93
+ ? !resume
94
+ ? "Window request queued without continuation. Finish your reply"
95
+ : lifecycle.newWindowRequests === "pi-limits"
96
+ ? "Window request queued"
97
+ : "New window queued"
98
+ : "Checkpoint or rollover is already pending. Save notes and finish your response",
99
+ }),
100
+ ...(started && resume ? { terminate: true } : {}),
101
+ };
102
+ };
68
103
  const tools: ToolDefinition[] = [
69
104
  {
70
105
  name: "notes",
@@ -97,27 +132,8 @@ export function createTools(
97
132
  prepareArguments: prepareNewContextArguments,
98
133
  exposure: "model-only",
99
134
  executionMode: "sequential",
100
- async execute(id, input, signal, _update, ctx) {
101
- assertActive();
102
- if (signal?.aborted) throw new Error("Rollover cancelled");
103
- const { role } = prepareNewContextArguments(input);
104
- const handoff =
105
- role === undefined ? undefined : await roles.prepare(role, ctx);
106
- if (signal?.aborted) throw new Error("Rollover cancelled");
107
- const started = lifecycle.requestRollover(ctx, id, handoff);
108
- if (started) ctx.abort();
109
- return {
110
- ...result({
111
- started,
112
- message: started
113
- ? lifecycle.newWindowRequests === "pi-limits"
114
- ? "Window request queued"
115
- : "New window queued"
116
- : "Checkpoint or rollover is already pending. Save notes and finish your response",
117
- }),
118
- ...(started ? { terminate: true } : {}),
119
- };
120
- },
135
+ execute: (id, input, signal, _update, ctx) =>
136
+ requestContext(id, input, signal, ctx),
121
137
  },
122
138
  {
123
139
  name: "get_context_remaining",
@@ -136,13 +152,19 @@ export function createTools(
136
152
  },
137
153
  ];
138
154
  const newContext = tools.find((tool) => tool.name === "new_context")!;
139
- let advertisedRoles = "[]";
140
- roles.onRoleIdsChanged((ids) => {
141
- const key = JSON.stringify(ids);
142
- if (key === advertisedRoles) return;
143
- advertisedRoles = key;
144
- newContext.parameters = newContextSchema(ids);
155
+ let roleIds: string[] = [];
156
+ let advertised = "";
157
+ const refresh = () => {
158
+ const schema = newContextSchema(roleIds, lifecycle.taskCompletionRollover);
159
+ const key = JSON.stringify(schema);
160
+ if (key === advertised) return;
161
+ advertised = key;
162
+ newContext.parameters = schema;
145
163
  pi.registerTool(newContext);
164
+ };
165
+ roles.onRoleIdsChanged((ids) => {
166
+ roleIds = ids;
167
+ refresh();
146
168
  });
147
- return tools;
169
+ return { tools, refresh, requestContext };
148
170
  }
@@ -95,19 +95,18 @@ function hideArchiveSummaries(
95
95
  hidden: ReadonlySet<string>,
96
96
  ): readonly SessionEntry[] {
97
97
  if (hidden.size === 0) return entries;
98
- return entries.map(
99
- (entry): SessionEntry =>
100
- entry.type === "branch_summary" && hidden.has(entry.id)
101
- ? // Keep entry IDs as replay cut points without sending archive summaries.
102
- {
103
- type: "custom",
104
- id: entry.id,
105
- parentId: entry.parentId,
106
- timestamp: entry.timestamp,
107
- customType: "codex-context-tree-summary",
108
- data: {},
109
- }
110
- : entry,
98
+ return entries.map((entry): SessionEntry =>
99
+ entry.type === "branch_summary" && hidden.has(entry.id)
100
+ ? // Keep entry IDs as replay cut points without sending archive summaries.
101
+ {
102
+ type: "custom",
103
+ id: entry.id,
104
+ parentId: entry.parentId,
105
+ timestamp: entry.timestamp,
106
+ customType: "codex-context-tree-summary",
107
+ data: {},
108
+ }
109
+ : entry,
111
110
  );
112
111
  }
113
112
 
@@ -15,31 +15,19 @@ export interface WindowDetails {
15
15
  trim: boolean;
16
16
  }
17
17
  const GUIDANCE = `<context_window_guidance>
18
- Notes are recovery state, not diary. Storage is virtual, not disk. Create relative paths.
18
+ Notes are short virtual resume points, not working memory. Use task notes and/or checkpoints as needed. Reuse existing notes and avoid duplicating state. Use relative paths. Keep only current goal, task-specific constraints or exceptions, decision/status, next action and evidence/history links. Keep reasoning and intermediate results in context. Omit harness instructions, tool usage and skill-read bookkeeping.
19
19
 
20
- MUST maintain one authoritative checkpoint per task/topic: request, constraints, decision, status, next steps and relevant history IDs.
20
+ Write less: consolidate changed recovery state at substantive turn end, before replying. Skip routine turns and unchanged state unless explicit reminders or earlier handoffs require a save. If a no-action report needs recording, add only its run/report ID and "no owned action". Keep current state first; replace superseded status. Append only while existing state remains accurate. Use history on demand for older decisions and evidence instead of copying them into notes.
21
21
 
22
- Near a substantive turn's end, before replying, consolidate changed recovery state. notes write creates or replaces; append adds. Do not interleave saves with ordinary tool calls. Skip routine turns and unchanged state. Explicit reminders and earlier handoffs still apply.
23
-
24
- Link existing notes rather than duplicate. Recording does not authorise implementation.
25
-
26
- Immediately before new_context, MUST save the checkpoint via notes. Save before handoff too. For rollover, call new_context after saving.
27
-
28
- When recovering context, read the checkpoint and necessary links if available, then retrieve a few relevant user messages with history for intent and communication preferences. Past messages are context, not renewed requests. Current instructions take precedence. Resume the current task; read further history only as needed. Do not reread unchanged notes.
29
-
30
- MUST reread required skills after rollover.
22
+ Save relevant notes before handoff and immediately before new_context. On recovery, read relevant notes, necessary links and a few relevant user messages with history, then resume the current task. Past messages are context, not renewed requests; current instructions win. Avoid unchanged rereads. Reread required skills after rollover. Recording does not authorise implementation.
31
23
  </context_window_guidance>`;
32
24
 
33
25
  const GPT_GUIDANCE = `<context_window_guidance>
34
- Notes=virtual recovery state, NOT disk/diary. Create relative paths. MUST maintain one authoritative checkpoint/task→request/constraints/decision/status/next steps/history IDs. Link existing notes≠duplicate; recording≠implementation permission.
35
-
36
- Near substantive turn end, before reply→consolidate CHANGED recovery. notes write→create/replace; append→add. No saves amid ordinary tool calls; skip routine/unchanged state. Explicit reminders/earlier handoffs still apply.
37
-
38
- Immediately before new_context MUST save checkpoint via notes; before handoff too. Rollover→new_context after save.
26
+ Notes=short virtual resume points, not working memory. Relative paths; task notes and/or checkpoints as needed. Reuse existing notes; avoid duplicate state. Keep only current goal, task constraints/exceptions, decision/status, next action, evidence/history links. Reasoning/intermediate results stay in context. Omit harness/tool instructions and skill-read state.
39
27
 
40
- Context recovery→notes checkpoint/necessary links if available→a few relevant user messages via history for intent/communication preferences→resume current task. Past messages=context≠renewed requests; current instructions win. Further history as needed; no unchanged-note rereads.
28
+ Fewer writes→consolidate changed recovery at substantive turn end BEFORE reply; skip routine/unchanged turns unless explicit reminders/earlier handoffs require saving. No-action report + save needed→add only run/report ID + "no owned action". Current first; replace superseded status. Append only while prior state stays accurate. History→older decisions/evidence on demand, not copied into notes.
41
29
 
42
- After rollover MUST reread required skills.
30
+ Save relevant notes before handoff/immediately before new_context. Recovery→relevant notes, necessary links, a few relevant user messages via history→resume current task. Past messages≠renewed requests; current instructions win. No unchanged rereads. Reread required skills after rollover. Recording≠implementation permission.
43
31
  </context_window_guidance>`;
44
32
 
45
33
  export function registerWindowRenderer(pi: ExtensionAPI): void {
@@ -256,17 +256,16 @@ export class Windows {
256
256
  if (entries[i]!.type === "compaction" && !isWindowCheckpoint(entries[i]!))
257
257
  boundary = -1;
258
258
  }
259
- return entries.slice(Math.max(0, boundary)).map(
260
- (entry): SessionEntry =>
261
- isWindowCheckpoint(entry)
262
- ? {
263
- type: "custom",
264
- id: entry.id,
265
- parentId: entry.parentId,
266
- timestamp: entry.timestamp,
267
- customType: "notes-compaction:window-checkpoint",
268
- }
269
- : entry,
259
+ return entries.slice(Math.max(0, boundary)).map((entry): SessionEntry =>
260
+ isWindowCheckpoint(entry)
261
+ ? {
262
+ type: "custom",
263
+ id: entry.id,
264
+ parentId: entry.parentId,
265
+ timestamp: entry.timestamp,
266
+ customType: "notes-compaction:window-checkpoint",
267
+ }
268
+ : entry,
270
269
  );
271
270
  }
272
271
  }