@howaboua/pi-notes-compaction 0.0.14 → 0.0.16

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 (83) hide show
  1. package/CHANGELOG.md +21 -1
  2. package/LICENSE +21 -0
  3. package/README.md +8 -3
  4. package/index.ts +8 -0
  5. package/package.json +16 -11
  6. package/src/board/context-briefing.ts +245 -0
  7. package/src/board/delivery.ts +85 -0
  8. package/src/guidance.ts +121 -0
  9. package/src/notes/AGENTS.md +27 -0
  10. package/src/{activation.ts → notes/activation.ts} +8 -10
  11. package/src/{attachment-sharing.ts → notes/attachment-sharing.ts} +1 -1
  12. package/src/{attachment-snapshot.ts → notes/attachment-snapshot.ts} +33 -20
  13. package/src/{bridge.ts → notes/bridge.ts} +1 -0
  14. package/src/{context-sharing.ts → notes/context-sharing.ts} +22 -2
  15. package/src/{extension-hooks.ts → notes/extension-hooks.ts} +1 -12
  16. package/src/{extension-sharing.ts → notes/extension-sharing.ts} +2 -1
  17. package/src/notes/feature.ts +168 -0
  18. package/src/{history-windows.ts → notes/history-windows.ts} +10 -22
  19. package/src/{history.ts → notes/history.ts} +6 -5
  20. package/src/{index.ts → notes/index.ts} +20 -11
  21. package/src/{integrations.ts → notes/integrations.ts} +19 -3
  22. package/src/{lifecycle.ts → notes/lifecycle.ts} +0 -2
  23. package/src/{note-query.ts → notes/note-query.ts} +3 -5
  24. package/src/notes/note-result.ts +119 -0
  25. package/src/{note-save-marker.ts → notes/note-save-marker.ts} +3 -1
  26. package/src/{query-executor.ts → notes/query-executor.ts} +34 -9
  27. package/src/{query-input.ts → notes/query-input.ts} +1 -0
  28. package/src/{remote.ts → notes/remote.ts} +1 -1
  29. package/src/notes/saved-session-access.ts +121 -0
  30. package/src/notes/saved-session-index.mjs +83 -0
  31. package/src/notes/saved-session.mjs +241 -0
  32. package/src/notes/saved-session.ts +67 -0
  33. package/src/notes/saved-sharing-records.ts +170 -0
  34. package/src/{session-pruning.ts → notes/session-pruning.ts} +5 -5
  35. package/src/{settings-command.ts → notes/settings-command.ts} +29 -42
  36. package/src/{settings-controls.ts → notes/settings-controls.ts} +62 -72
  37. package/src/{settings-screen.ts → notes/settings-screen.ts} +25 -7
  38. package/src/{settings.ts → notes/settings.ts} +37 -6
  39. package/src/notes/shared-notes.ts +419 -0
  40. package/src/{shared-session-reader.ts → notes/shared-session-reader.ts} +35 -26
  41. package/src/{sharing-service.ts → notes/sharing-service.ts} +32 -1
  42. package/src/{store.ts → notes/store.ts} +10 -0
  43. package/src/{tool-contracts.ts → notes/tool-contracts.ts} +71 -44
  44. package/src/{tools.ts → notes/tools.ts} +2 -2
  45. package/src/notes/tree-archive-manifest.mjs +27 -0
  46. package/src/{tree-archive.ts → notes/tree-archive.ts} +6 -26
  47. package/src/{tree-handoff-read.ts → notes/tree-handoff-read.ts} +47 -32
  48. package/src/{window-message.ts → notes/window-message.ts} +15 -20
  49. package/src/settings-navigation.ts +11 -0
  50. package/src/timestamps.ts +3 -0
  51. package/tsconfig.json +9 -0
  52. package/src/note-result.ts +0 -70
  53. package/src/saved-session.ts +0 -169
  54. package/src/saved-sharing-records.ts +0 -112
  55. package/src/shared-notes.ts +0 -290
  56. /package/src/{agent-identity.ts → notes/agent-identity.ts} +0 -0
  57. /package/src/{binding-startup.ts → notes/binding-startup.ts} +0 -0
  58. /package/src/{compaction-projection.ts → notes/compaction-projection.ts} +0 -0
  59. /package/src/{context-owner.ts → notes/context-owner.ts} +0 -0
  60. /package/src/{fresh-checkpoint.ts → notes/fresh-checkpoint.ts} +0 -0
  61. /package/src/{fresh-notes.ts → notes/fresh-notes.ts} +0 -0
  62. /package/src/{history-search-protocol.ts → notes/history-search-protocol.ts} +0 -0
  63. /package/src/{history-search-pruning.mjs → notes/history-search-pruning.mjs} +0 -0
  64. /package/src/{history-search-worker.mjs → notes/history-search-worker.mjs} +0 -0
  65. /package/src/{history-search.ts → notes/history-search.ts} +0 -0
  66. /package/src/{idle-admission.ts → notes/idle-admission.ts} +0 -0
  67. /package/src/{model-role-config.ts → notes/model-role-config.ts} +0 -0
  68. /package/src/{model-role-screen.ts → notes/model-role-screen.ts} +0 -0
  69. /package/src/{model-roles.ts → notes/model-roles.ts} +0 -0
  70. /package/src/{notes-lookup.ts → notes/notes-lookup.ts} +0 -0
  71. /package/src/{notes.ts → notes/notes.ts} +0 -0
  72. /package/src/{rollover.ts → notes/rollover.ts} +0 -0
  73. /package/src/{session-pruning-content.ts → notes/session-pruning-content.ts} +0 -0
  74. /package/src/{session-pruning-plan.ts → notes/session-pruning-plan.ts} +0 -0
  75. /package/src/{session-pruning-policy.ts → notes/session-pruning-policy.ts} +0 -0
  76. /package/src/{session-pruning-screen.ts → notes/session-pruning-screen.ts} +0 -0
  77. /package/src/{session-pruning-source.ts → notes/session-pruning-source.ts} +0 -0
  78. /package/src/{session-pruning-transaction.ts → notes/session-pruning-transaction.ts} +0 -0
  79. /package/src/{sqlite.mjs → notes/sqlite.mjs} +0 -0
  80. /package/src/{task-boundary.ts → notes/task-boundary.ts} +0 -0
  81. /package/src/{tree-checkpoint.ts → notes/tree-checkpoint.ts} +0 -0
  82. /package/src/{window-checkpoint.ts → notes/window-checkpoint.ts} +0 -0
  83. /package/src/{windows.ts → notes/windows.ts} +0 -0
@@ -132,6 +132,16 @@ export class NotesStore {
132
132
  ?.prepare("UPDATE sessions SET file_path = ? WHERE id = ?")
133
133
  .run(session.file, session.id);
134
134
  }
135
+ /** Exact native thread lookup only. The JSONL header and binding remain authoritative. */
136
+ sessionFile(threadId: string): string | undefined {
137
+ return (
138
+ this.open()
139
+ ?.prepare<[string], { file_path: string | null }>(
140
+ "SELECT file_path FROM sessions WHERE id = ?",
141
+ )
142
+ .get(threadId)?.file_path ?? undefined
143
+ );
144
+ }
135
145
  cache(session: SessionRef, responses: readonly CachedResponse[]): void {
136
146
  if (!responses.length) return;
137
147
  for (const response of responses) {
@@ -1,7 +1,17 @@
1
- import { StringEnum } from "@earendil-works/pi-ai";
2
1
  import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
3
- import { Type } from "typebox";
4
- import { Check } from "typebox/value";
2
+ import {
3
+ bool,
4
+ compile,
5
+ int,
6
+ nul,
7
+ obj,
8
+ oneOf,
9
+ opt,
10
+ type Schema,
11
+ str,
12
+ union,
13
+ type Validator,
14
+ } from "@earendil-works/pi-schema";
5
15
  import type { LookupQuery } from "./bridge.js";
6
16
  import { noteResult } from "./note-result.js";
7
17
  import { internalQueryArguments, normalizeQueryInput } from "./query-input.js";
@@ -29,14 +39,14 @@ export const NOTES_ROUTING_GUIDELINE =
29
39
  export const NEW_CONTEXT_DESCRIPTION =
30
40
  "Start fresh context window. MUST save notes before calling";
31
41
  export const GPT_NEW_CONTEXT_DESCRIPTION = "Save notes→fresh context";
32
- const STRING = Type.Optional(Type.String());
33
- const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
34
- const LINE = Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
35
- export const NOTES_SCHEMA = Type.Object(
42
+ const STRING = opt(str());
43
+ const INTEGER = opt(int({ minimum: 1 }));
44
+ const LINE = opt(union([int(), nul()]));
45
+ export const NOTES_SCHEMA = obj(
36
46
  {
37
- action: Type.Optional(StringEnum(NOTES_ACTIONS)),
38
- path: Type.Optional(
39
- Type.Union([Type.String(), Type.Null()], {
47
+ action: opt({ ...oneOf(NOTES_ACTIONS), type: "string" }),
48
+ path: opt(
49
+ union([str(), nul()], {
40
50
  description:
41
51
  "File for read/write/append; prefix for list/search; virtual filesystem, not files in the project",
42
52
  }),
@@ -47,49 +57,52 @@ export const NOTES_SCHEMA = Type.Object(
47
57
  stop_line: LINE,
48
58
  limit: INTEGER,
49
59
  max_matches_per_file: INTEGER,
50
- file_order: Type.Optional(StringEnum(["ascending", "descending"])),
51
- file_order_by: Type.Optional(
52
- StringEnum(["name", "created_at", "updated_at"]),
53
- ),
54
- recent_file_first: Type.Optional(Type.Boolean()),
60
+ file_order: opt({ ...oneOf(["ascending", "descending"]), type: "string" }),
61
+ file_order_by: opt({
62
+ ...oneOf(["name", "created_at", "updated_at"]),
63
+ type: "string",
64
+ }),
65
+ recent_file_first: opt(bool()),
55
66
  },
56
- { additionalProperties: false },
67
+ { open: false },
57
68
  );
58
- const NEW_CONTEXT_SCHEMA = Type.Object(
69
+ const NEW_CONTEXT_SCHEMA = obj(
59
70
  {
60
- role: Type.Optional(
61
- Type.String({
71
+ role: opt(
72
+ str({
62
73
  minLength: 1,
63
74
  description:
64
75
  "Configured model-role ID, not an agent name or handoff text",
65
76
  }),
66
77
  ),
67
78
  },
68
- { additionalProperties: false },
79
+ { open: false },
69
80
  );
70
81
 
82
+ const newContextSchemaValidator = compile(NEW_CONTEXT_SCHEMA);
83
+
71
84
  export function newContextSchema(roleIds: string[]) {
72
- return Type.Object(
73
- roleIds.length ? { role: Type.Optional(StringEnum(roleIds)) } : {},
74
- { additionalProperties: false },
85
+ return obj(
86
+ roleIds.length ? { role: opt({ ...oneOf(roleIds), type: "string" }) } : {},
87
+ { open: false },
75
88
  );
76
89
  }
77
90
 
78
91
  export function prepareNewContextArguments(input: unknown) {
79
92
  const args = input ?? {};
80
- if (!Check(NEW_CONTEXT_SCHEMA, args))
93
+ if (!newContextSchemaValidator.check(args))
81
94
  throw new Error(
82
95
  'Use {} to keep the current model, or {role: "name"} for a configured role.',
83
96
  );
84
97
  return args;
85
98
  }
86
- export const HISTORY_SCHEMA = Type.Object(
99
+ export const HISTORY_SCHEMA = obj(
87
100
  {
88
- action: Type.Optional(StringEnum(HISTORY_ACTIONS)),
89
- agent_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
90
- item_id: Type.Optional(Type.String()),
91
- window_id: Type.Optional(
92
- Type.Union([Type.String(), Type.Null()], {
101
+ action: opt({ ...oneOf(HISTORY_ACTIONS), type: "string" }),
102
+ agent_name: opt(union([str(), nul()])),
103
+ item_id: opt(str()),
104
+ window_id: opt(
105
+ union([str(), nul()], {
93
106
  description: "Required with item_id for read",
94
107
  }),
95
108
  ),
@@ -97,18 +110,21 @@ export const HISTORY_SCHEMA = Type.Object(
97
110
  limit: INTEGER,
98
111
  limit_chars: INTEGER,
99
112
  max_chars_per_item: INTEGER,
100
- offset_chars: Type.Optional(Type.Integer({ minimum: 0 })),
101
- recent_first: Type.Optional(Type.Boolean()),
102
- role: Type.Optional(
103
- Type.Union([
104
- StringEnum(["user", "assistant", "tool", "system", "developer"]),
105
- Type.Null(),
113
+ offset_chars: opt(int({ minimum: 0 })),
114
+ recent_first: opt(bool()),
115
+ role: opt(
116
+ union([
117
+ {
118
+ ...oneOf(["user", "assistant", "tool", "system", "developer"]),
119
+ type: "string",
120
+ },
121
+ nul(),
106
122
  ]),
107
123
  ),
108
- tool_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
109
- tool_namespace: Type.Optional(Type.Union([Type.String(), Type.Null()])),
124
+ tool_name: opt(union([str(), nul()])),
125
+ tool_namespace: opt(union([str(), nul()])),
110
126
  },
111
- { additionalProperties: false },
127
+ { open: false },
112
128
  );
113
129
 
114
130
  const FIELDS: Record<string, readonly string[]> = {
@@ -272,25 +288,36 @@ export function queryHelp(
272
288
 
273
289
  export function prepareNotesArguments(args: unknown) {
274
290
  const params = normalizeQueryInput("notes", args);
275
- validateArguments("notes", params, NOTES_SCHEMA);
291
+ validateArguments("notes", params, NOTES_FIELD_VALIDATORS);
276
292
  return params;
277
293
  }
278
294
 
279
295
  export function prepareHistoryArguments(args: unknown) {
280
296
  const params = normalizeQueryInput("history", args);
281
- validateArguments("history", params, HISTORY_SCHEMA);
297
+ validateArguments("history", params, HISTORY_FIELD_VALIDATORS);
282
298
  return params;
283
299
  }
284
300
 
301
+ const NOTES_FIELD_VALIDATORS = fieldValidators(NOTES_SCHEMA);
302
+ const HISTORY_FIELD_VALIDATORS = fieldValidators(HISTORY_SCHEMA);
303
+
304
+ function fieldValidators(schema: Schema): Record<string, Validator> {
305
+ return Object.fromEntries(
306
+ Object.entries(schema["properties"] as Record<string, Schema>).map(
307
+ ([field, property]) => [field, compile(property)],
308
+ ),
309
+ );
310
+ }
311
+
285
312
  function validateArguments(
286
313
  namespace: LookupQuery["namespace"],
287
314
  params: Record<string, unknown>,
288
- schema: import("typebox").TObject,
315
+ validators: Record<string, Validator>,
289
316
  ) {
290
317
  if (!queryHelp(namespace, params)) queryArguments(namespace, params);
291
318
  for (const [field, value] of Object.entries(params)) {
292
- const property = schema.properties[field];
293
- if (!property || !Check(property, value))
319
+ const validator = validators[field];
320
+ if (!validator || !validator.check(value))
294
321
  throw new Error(
295
322
  `Invalid ${namespace} ${field}; use {} for exact arguments`,
296
323
  );
@@ -4,7 +4,7 @@ import type {
4
4
  ExtensionContext,
5
5
  ToolDefinition,
6
6
  } from "@earendil-works/pi-coding-agent";
7
- import { Type } from "typebox";
7
+ import { obj } from "@earendil-works/pi-schema";
8
8
  import type { LookupQuery, SharedNotesDetails } from "./bridge.js";
9
9
  import type { HistorySearch } from "./history-search.js";
10
10
  import type { NotesLifecycle } from "./lifecycle.js";
@@ -123,7 +123,7 @@ export function createTools(
123
123
  name: "get_context_remaining",
124
124
  label: "get_context_remaining",
125
125
  description: "Remaining context tokens",
126
- parameters: Type.Object({}, { additionalProperties: false }),
126
+ parameters: obj({}, { open: false }),
127
127
  async execute(_id, _input, _signal, _update, ctx) {
128
128
  assertActive();
129
129
  const remaining = lifecycle.windows.remaining(ctx);
@@ -0,0 +1,27 @@
1
+ /** @typedef {import("./tree-archive.js").TreeArchiveManifestData} TreeArchiveManifestData */
2
+ export const TREE_ARCHIVE_ENTRY_TYPE = "codex-context-tree-archive";
3
+ const TREE_ARCHIVE_PROTOCOL = 1;
4
+ export const MAX_ARCHIVE_DEPTH = 50_000;
5
+
6
+ /** @param {unknown} value @returns {value is TreeArchiveManifestData} */
7
+ export function isTreeArchiveManifestData(value) {
8
+ if (!value || typeof value !== "object" || Array.isArray(value)) return false;
9
+ const manifest = /** @type {Record<string, unknown>} */ (value);
10
+ return (
11
+ manifest["protocol"] === TREE_ARCHIVE_PROTOCOL &&
12
+ manifest["strategy"] === "codex-context-tree" &&
13
+ nonEmptyString(manifest["windowId"]) &&
14
+ nonEmptyString(manifest["boundaryEntryId"]) &&
15
+ nonEmptyString(manifest["summaryEntryId"]) &&
16
+ nonEmptyString(manifest["archivedLeafId"]) &&
17
+ (manifest["compactionEntryId"] === undefined ||
18
+ nonEmptyString(manifest["compactionEntryId"])) &&
19
+ (manifest["branchBaseId"] === null ||
20
+ nonEmptyString(manifest["branchBaseId"]))
21
+ );
22
+ }
23
+
24
+ /** @param {unknown} value @returns {value is string} */
25
+ function nonEmptyString(value) {
26
+ return typeof value === "string" && value !== "";
27
+ }
@@ -2,11 +2,14 @@ import type {
2
2
  BranchSummaryEntry,
3
3
  SessionEntry,
4
4
  } from "@earendil-works/pi-coding-agent";
5
+ import {
6
+ isTreeArchiveManifestData,
7
+ MAX_ARCHIVE_DEPTH,
8
+ TREE_ARCHIVE_ENTRY_TYPE,
9
+ } from "./tree-archive-manifest.mjs";
5
10
  import { windowDetails } from "./windows.js";
6
11
 
7
- export const TREE_ARCHIVE_ENTRY_TYPE = "codex-context-tree-archive";
8
- const TREE_ARCHIVE_PROTOCOL = 1;
9
- export const MAX_ARCHIVE_DEPTH = 50_000;
12
+ export { TREE_ARCHIVE_ENTRY_TYPE } from "./tree-archive-manifest.mjs";
10
13
 
11
14
  export interface TreeArchiveManifestData {
12
15
  protocol: 1;
@@ -112,29 +115,6 @@ function archivedPath(
112
115
  return reverse.reverse();
113
116
  }
114
117
 
115
- export function isTreeArchiveManifestData(
116
- value: unknown,
117
- ): value is TreeArchiveManifestData {
118
- if (!value || typeof value !== "object" || Array.isArray(value)) return false;
119
- const manifest = value as Record<string, unknown>;
120
- return (
121
- manifest["protocol"] === TREE_ARCHIVE_PROTOCOL &&
122
- manifest["strategy"] === "codex-context-tree" &&
123
- nonEmptyString(manifest["windowId"]) &&
124
- nonEmptyString(manifest["boundaryEntryId"]) &&
125
- nonEmptyString(manifest["summaryEntryId"]) &&
126
- nonEmptyString(manifest["archivedLeafId"]) &&
127
- (manifest["compactionEntryId"] === undefined ||
128
- nonEmptyString(manifest["compactionEntryId"])) &&
129
- (manifest["branchBaseId"] === null ||
130
- nonEmptyString(manifest["branchBaseId"]))
131
- );
132
- }
133
-
134
- function nonEmptyString(value: unknown): value is string {
135
- return typeof value === "string" && value !== "";
136
- }
137
-
138
118
  export function hasTreeArchiveSuccessor(
139
119
  entries: readonly SessionEntry[],
140
120
  windowId: string,
@@ -4,45 +4,60 @@ import {
4
4
  buildSessionProjection,
5
5
  type SessionEntry,
6
6
  } from "@earendil-works/pi-coding-agent";
7
- import { Type } from "typebox";
8
- import { Check } from "typebox/value";
7
+ import {
8
+ arr,
9
+ compile,
10
+ lit,
11
+ num,
12
+ obj,
13
+ opt,
14
+ str,
15
+ union,
16
+ unknown,
17
+ unsafe,
18
+ } from "@earendil-works/pi-schema";
9
19
 
10
20
  const READ_KEY = "codexContextNoteRead";
11
- const READ_SCHEMA = Type.Object(
21
+ const READ_SCHEMA = obj(
12
22
  {
13
- protocol: Type.Literal(1),
14
- origin: Type.Literal("host"),
15
- id: Type.String({ pattern: "^[a-f0-9-]{36}$" }),
16
- path: Type.String({ minLength: 1 }),
17
- namespace: Type.Optional(Type.Literal("notes")),
18
- api: Type.String({ minLength: 1 }),
19
- provider: Type.String({ minLength: 1 }),
20
- model: Type.String({ minLength: 1 }),
21
- timestamp: Type.Number({ minimum: 0 }),
22
- content: Type.Array(
23
- Type.Union([
24
- Type.Object({ type: Type.Literal("text"), text: Type.String() }),
25
- Type.Object({
26
- type: Type.Literal("image"),
27
- data: Type.String(),
28
- mimeType: Type.String(),
29
- detail: Type.Optional(
30
- Type.Union([
31
- Type.Literal("auto"),
32
- Type.Literal("high"),
33
- Type.Literal("original"),
34
- ]),
35
- ),
36
- }),
23
+ protocol: lit(1),
24
+ origin: lit("host"),
25
+ id: str({ pattern: "^[a-f0-9-]{36}$" }),
26
+ path: str({ minLength: 1 }),
27
+ namespace: opt(lit("notes")),
28
+ api: str({ minLength: 1 }),
29
+ provider: str({ minLength: 1 }),
30
+ model: str({ minLength: 1 }),
31
+ timestamp: num({ minimum: 0 }),
32
+ content: arr(
33
+ union([
34
+ obj({ type: lit("text"), text: str() }, { open: true }),
35
+ obj(
36
+ {
37
+ type: lit("image"),
38
+ data: str(),
39
+ mimeType: str(),
40
+ detail: opt(union([lit("auto"), lit("high"), lit("original")])),
41
+ },
42
+ { open: true },
43
+ ),
37
44
  ]),
38
45
  ),
39
- details: Type.Object({
40
- codexHistoryNotes: Type.Record(Type.String(), Type.Unknown()),
41
- }),
46
+ details: obj(
47
+ {
48
+ codexHistoryNotes: unsafe<Record<string, unknown>>({
49
+ type: "object",
50
+ patternProperties: { "^.*$": unknown() },
51
+ }),
52
+ },
53
+ { open: true },
54
+ ),
42
55
  },
43
- { additionalProperties: false },
56
+ { open: false },
44
57
  );
45
58
 
59
+ const readSchemaValidator = compile(READ_SCHEMA);
60
+
46
61
  function callId(id: string): string {
47
62
  const name = "tree_handoff_" + id.replaceAll("-", "");
48
63
  return `${name}|fc_${name}`;
@@ -95,7 +110,7 @@ export function projectTreeHandoffReads(
95
110
  if (!details || typeof details !== "object" || !(READ_KEY in details))
96
111
  return [message];
97
112
  const read = details[READ_KEY];
98
- if (!Check(READ_SCHEMA, read))
113
+ if (!readSchemaValidator.check(read))
99
114
  throw new Error("Invalid persisted tree handoff read");
100
115
  const resultDetails = read.details;
101
116
  if (!isJson(resultDetails))
@@ -15,31 +15,31 @@ export interface WindowDetails {
15
15
  trim: boolean;
16
16
  }
17
17
  const GUIDANCE = `<context_window_guidance>
18
- Notes are recovery state, not diary. They use virtual storage, not disk filesystem. Use relative paths when creating.
18
+ Notes are recovery state, not diary. Storage is virtual, not disk. Create relative paths.
19
19
 
20
- MUST maintain one authoritative checkpoint per task/topic with request, constraints, decision, status, next steps and relevant history IDs.
20
+ MUST maintain one authoritative checkpoint per task/topic: request, constraints, decision, status, next steps and relevant history IDs.
21
21
 
22
- Use the notes tool write action to create or replace the checkpoint at milestones, task switches and completion. Use action append to add to it.
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
23
 
24
- Subagents MUST maintain their own notes and return paths. For subagent handoffs, include the checkpoint path.
24
+ Link existing notes rather than duplicate. Recording does not authorise implementation.
25
25
 
26
- Link existing notes instead of duplicating content. Recording does not authorise implementation.
26
+ Immediately before new_context, MUST save the checkpoint via notes. Save before handoff too. For rollover, call new_context after saving.
27
27
 
28
- Before new_context or a handoff, MUST save the checkpoint with notes. For rollover, call new_context.
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
29
 
30
- After rollover, use notes read action to recover the checkpoint, then read only necessary links. SHOULD NOT reread unchanged notes. Use the history tool for missing details.
31
-
32
- Skill reads do not survive rollover. MUST reread required skills.
30
+ MUST reread required skills after rollover.
33
31
  </context_window_guidance>`;
34
32
 
35
33
  const GPT_GUIDANCE = `<context_window_guidance>
36
- Notes=recovery stateNOTdiary. Virtual Notes storageNOTfilesystem. Create notes with relative paths. One authoritative checkpoint per task/topic→request/constraints/decision/status/next steps/history IDs. Existing notes→linkNOTduplicate. RecordingNOTimplementation permission.
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
37
 
38
- MUST maintain task checkpoint→update@ milestones, task switches + completion. Notes tool: write→create/replace stale checkpoint; append→add content. Not every reply/step. Subagents MUST maintain own notes→return paths.
38
+ Immediately before new_context MUST save checkpoint via notes; before handoff too. Rollover→new_context after save.
39
39
 
40
- Before new_context/handoff: MUST save checkpoint via notes. Rollover→call new_context after save; subagent handoff→include checkpoint path. Post-rollover: notes read→checkpoint→necessary links only. SHOULD NOT reread unchanged notes. Missing details→history tool.
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.
41
41
 
42
- Prior skill reads≠current context. MUST reread required skills after rollover.
42
+ After rollover MUST reread required skills.
43
43
  </context_window_guidance>`;
44
44
 
45
45
  export function registerWindowRenderer(pi: ExtensionAPI): void {
@@ -167,13 +167,8 @@ export function windowMessage(
167
167
  kind: "window" | "identity" = "window",
168
168
  gpt = false,
169
169
  ): CustomMessageEntryDraft {
170
- const lines = [
171
- `Agent name: ${agent}`,
172
- `First context window id: ${ids.firstWindowId}`,
173
- `Current context window id: ${ids.currentWindowId}`,
174
- ];
175
- if (ids.previousWindowId)
176
- lines.push(`Previous context window id: ${ids.previousWindowId}`);
170
+ // History exposes lookup IDs on demand; rollover must not churn this text just for UUIDs.
171
+ const lines = [`Agent name: ${agent}`];
177
172
  if (hint) lines.push(hint);
178
173
  return {
179
174
  type: "custom_message",
@@ -0,0 +1,11 @@
1
+ import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
2
+
3
+ export type SettingsTab = "notes" | "board";
4
+ export type OpenSettings = (
5
+ ctx: ExtensionCommandContext,
6
+ tab: SettingsTab,
7
+ ) => Promise<void>;
8
+
9
+ export interface FeatureSettings {
10
+ openSettings(ctx: ExtensionCommandContext): Promise<SettingsTab | undefined>;
11
+ }
@@ -0,0 +1,3 @@
1
+ export function minuteTimestamp(value: string | number = Date.now()): string {
2
+ return new Date(value).toISOString().slice(0, 16) + "Z";
3
+ }
package/tsconfig.json ADDED
@@ -0,0 +1,9 @@
1
+ {
2
+ "extends": "../../tsconfig.base.json",
3
+ "compilerOptions": {
4
+ "allowJs": true,
5
+ "checkJs": true,
6
+ "allowImportingTsExtensions": true
7
+ },
8
+ "include": ["*.ts", "src/**/*.ts", "src/**/*.mjs"]
9
+ }
@@ -1,70 +0,0 @@
1
- import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
2
- import { Type } from "typebox";
3
- import { Check } from "typebox/value";
4
-
5
- const OPTIONAL_STRING = Type.Optional(Type.String());
6
- const OPTIONAL_BOOLEAN = Type.Optional(Type.Boolean());
7
- const MATCH = Type.Object({ line_number: Type.Integer(), line: Type.String() });
8
-
9
- // Pi codemode needs this declaration to return structuredContent rather than text.
10
- export const NOTES_OUTPUT_SCHEMA = Type.Object(
11
- {},
12
- { additionalProperties: true },
13
- );
14
-
15
- const NOTES_RESULT_SCHEMA = Type.Object(
16
- {
17
- file: Type.Optional(
18
- Type.Union([
19
- Type.Object({
20
- path: Type.String(),
21
- content: OPTIONAL_STRING,
22
- start_line: Type.Optional(Type.Integer()),
23
- stop_line: Type.Optional(Type.Integer()),
24
- total_lines: Type.Optional(Type.Integer()),
25
- append_only: OPTIONAL_BOOLEAN,
26
- }),
27
- Type.Null(),
28
- ]),
29
- ),
30
- files: Type.Optional(
31
- Type.Array(
32
- Type.Object({
33
- path: Type.String(),
34
- updated_at: OPTIONAL_STRING,
35
- created_at: OPTIONAL_STRING,
36
- matches: Type.Optional(Type.Array(MATCH)),
37
- truncated: OPTIONAL_BOOLEAN,
38
- append_only: OPTIONAL_BOOLEAN,
39
- }),
40
- ),
41
- ),
42
- usage: OPTIONAL_STRING,
43
- warnings: Type.Optional(Type.Array(Type.String())),
44
- warning: OPTIONAL_STRING,
45
- truncated: OPTIONAL_BOOLEAN,
46
- read_only: OPTIONAL_BOOLEAN,
47
- saved_at: OPTIONAL_STRING,
48
- captured_at: OPTIONAL_STRING,
49
- results: OPTIONAL_STRING,
50
- actions: Type.Optional(Type.Record(Type.String(), Type.String())),
51
- writes: OPTIONAL_STRING,
52
- paths: OPTIONAL_STRING,
53
- ranges: OPTIONAL_STRING,
54
- defaults: OPTIONAL_STRING,
55
- },
56
- { additionalProperties: false },
57
- );
58
-
59
- /** One canonical payload for native text and every programmatic caller. */
60
- export function noteResult(payload: unknown): AgentToolResult<unknown> {
61
- if (!Check(NOTES_RESULT_SCHEMA, payload))
62
- throw new Error(
63
- "Notes returned invalid data. Read the note before retrying a write.",
64
- );
65
- return {
66
- content: [{ type: "text", text: JSON.stringify(payload) }],
67
- structuredContent: payload,
68
- details: {},
69
- };
70
- }