@howaboua/pi-notes-compaction 0.0.13 → 0.0.14

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.
@@ -58,12 +58,21 @@ export function normalizeQueryInput(
58
58
  if (!input || typeof input !== "object" || Array.isArray(input))
59
59
  throw new Error("Supply an action object; use {} for help");
60
60
  const params = { ...input } as Record<string, unknown>;
61
+ if (
62
+ namespace === "history" &&
63
+ params["action"] === undefined &&
64
+ "query" in params
65
+ )
66
+ params["action"] = "search";
61
67
  const action =
62
68
  ACTIONS[namespace][String(params["action"])] ?? params["action"];
63
69
  if (action !== undefined) params["action"] = action;
64
70
  if (namespace === "notes") {
65
- if (action === "write" || action === "append")
71
+ alias(params, "address", "path");
72
+ if (action === "write" || action === "append") {
66
73
  alias(params, "content", "text");
74
+ alias(params, "body", "text");
75
+ }
67
76
  if (action === "list" || action === "search") {
68
77
  alias(params, "prefix", "path");
69
78
  alias(params, "path_prefix", "path");
@@ -76,6 +85,8 @@ export function normalizeQueryInput(
76
85
  alias(params, "max_results", "limit");
77
86
  }
78
87
  const used = PRESENTATION[`${namespace}:${String(action)}`] ?? [];
88
+ if (namespace === "history" && action !== "read")
89
+ delete params["offset_chars"];
79
90
  for (const hint of HINTS) if (!used.includes(hint)) delete params[hint];
80
91
  return params;
81
92
  }
package/src/remote.ts CHANGED
@@ -12,8 +12,11 @@ import {
12
12
  } from "@howaboua/pi-codex-conversion/code-mode";
13
13
  import {
14
14
  type ContextAgentIdentity,
15
+ canonicalContextIdentity,
15
16
  contextAgentIdentity,
17
+ contextStorageAgentName,
16
18
  contextTargetAgent,
19
+ isContextAgentName,
17
20
  } from "./agent-identity.js";
18
21
  import type { CachedResponse, LookupQuery } from "./bridge.js";
19
22
  import type {
@@ -21,6 +24,7 @@ import type {
21
24
  SharedContextRequest,
22
25
  SharedContextResult,
23
26
  } from "./context-sharing.js";
27
+ import { noteResult } from "./note-result.js";
24
28
 
25
29
  const ENDPOINTS = {
26
30
  list_files_by_prefix: [
@@ -97,7 +101,7 @@ function scope(
97
101
  return JSON.stringify({
98
102
  threadId: identity.threadId,
99
103
  sessionId: identity.sessionId,
100
- agentName: identity.agentName,
104
+ agentName: contextStorageAgentName(identity),
101
105
  accountScope: protectedAccountScope(accountId),
102
106
  baseUrl,
103
107
  });
@@ -154,6 +158,19 @@ async function lookup(
154
158
  target?: RemoteNoteReference,
155
159
  ): Promise<readonly CachedResponse[]> {
156
160
  const { action, args } = readQuery(query);
161
+ if (target) {
162
+ const identity = canonicalContextIdentity(target.identity);
163
+ for (const field of ["path", "prefix", "path_prefix"]) {
164
+ const value = args[field];
165
+ if (
166
+ typeof value === "string" &&
167
+ (value === `${identity.agentName}/notes` ||
168
+ value.startsWith(`${identity.agentName}/notes/`))
169
+ )
170
+ args[field] =
171
+ `${contextStorageAgentName(identity)}${value.slice(identity.agentName.length)}`;
172
+ }
173
+ }
157
174
  const auth = await authenticated(ctx);
158
175
  if (target) checkReference(target, auth.provider);
159
176
  const headers = auth.provider.headers;
@@ -173,8 +190,9 @@ async function lookup(
173
190
  ...args,
174
191
  context: {
175
192
  session_id: target?.identity.sessionId ?? auth.identity.sessionId,
176
- current_agent_name:
177
- target?.identity.agentName ?? auth.identity.agentName,
193
+ current_agent_name: contextStorageAgentName(
194
+ target?.identity ?? auth.identity,
195
+ ),
178
196
  },
179
197
  }),
180
198
  },
@@ -237,10 +255,11 @@ export async function executeRemoteAttachment(
237
255
  throw new Error(
238
256
  "History is unavailable from a saved remote notes attachment. Open its saved Pi JSONL session on this machine, then retry.",
239
257
  );
258
+ const identity = canonicalContextIdentity(reference.identity);
240
259
  if (
241
260
  request.sessionId !== reference.identity.sessionId ||
242
- (request.agentName !== reference.identity.agentName &&
243
- !request.agentName.startsWith(`${reference.identity.agentName}/`)) ||
261
+ (request.agentName !== identity.agentName &&
262
+ request.agentName !== contextStorageAgentName(identity)) ||
244
263
  contextTargetAgent(
245
264
  request.namespace,
246
265
  request.params,
@@ -259,7 +278,7 @@ export async function executeRemoteAttachment(
259
278
  reference,
260
279
  );
261
280
  return {
262
- content: [{ type: "text", text: "Saved remote read completed" }],
281
+ ...noteResult({ usage: "Saved remote read completed" }),
263
282
  details: {
264
283
  codexHistoryNotes: {},
265
284
  externalNotesResponses: responses.map(({ bytes, ...response }) => ({
@@ -303,7 +322,7 @@ async function projectNotesResponses(
303
322
  !provenance.sessionId ||
304
323
  !("agentName" in provenance) ||
305
324
  typeof provenance.agentName !== "string" ||
306
- !/^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(provenance.agentName)
325
+ !isContextAgentName(provenance.agentName)
307
326
  )
308
327
  throw new Error(
309
328
  "Shared protected contents belong to a different account or backend",
@@ -38,6 +38,7 @@ const NOTE_ENTRIES = new Set([
38
38
  ]);
39
39
  const SHARING_ENTRIES = new Set([
40
40
  "codex-context-agent",
41
+ "codex-context-backend",
41
42
  "herdr-context-child",
42
43
  "shepherdr-attachment-route",
43
44
  "shepherdr-attachment-owner",
@@ -1,13 +1,21 @@
1
1
  import { type Static, Type } from "typebox";
2
2
  import { Check } from "typebox/value";
3
+ import {
4
+ CONTEXT_AGENT_PATTERN,
5
+ canonicalAgentName,
6
+ canonicalContextIdentity,
7
+ contextStorageAgentName,
8
+ pinnedContextIdentity,
9
+ } from "./agent-identity.js";
3
10
  import type { SavedNotesSession } from "./saved-session.js";
4
11
 
5
- const Agent = Type.String({ pattern: "^/root(?:/[a-zA-Z0-9_-]+)*$" });
12
+ const Agent = Type.String({ pattern: CONTEXT_AGENT_PATTERN });
6
13
  export const Identity = Type.Object({
7
14
  protocol: Type.Literal(1),
8
15
  sessionId: Type.String(),
9
16
  threadId: Type.String(),
10
17
  agentName: Agent,
18
+ storageAgentName: Type.Optional(Agent),
11
19
  storage: Type.Optional(
12
20
  Type.Union([Type.Literal("session"), Type.Literal("remote")]),
13
21
  ),
@@ -84,13 +92,14 @@ export function savedNotesIdentity(
84
92
  if (found) throw new Error("Conflicting saved notes identities");
85
93
  found = entry.data;
86
94
  }
87
- return (
88
- found ?? {
89
- protocol: 1,
90
- threadId: session.threadId,
91
- sessionId: session.threadId,
92
- agentName: "/root",
93
- }
95
+ return canonicalContextIdentity(
96
+ found ??
97
+ pinnedContextIdentity(session.threadId, session.entries) ?? {
98
+ protocol: 1,
99
+ threadId: session.threadId,
100
+ sessionId: session.threadId,
101
+ agentName: canonicalAgentName(session.threadId),
102
+ },
94
103
  );
95
104
  }
96
105
 
@@ -98,6 +107,6 @@ export function sameOwner(a: Identity, b: Identity): boolean {
98
107
  return (
99
108
  a.threadId === b.threadId &&
100
109
  a.sessionId === b.sessionId &&
101
- a.agentName === b.agentName
110
+ contextStorageAgentName(a) === contextStorageAgentName(b)
102
111
  );
103
112
  }
@@ -2,6 +2,13 @@ import { isDeepStrictEqual } from "node:util";
2
2
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
3
3
  import type { Static } from "typebox";
4
4
  import { Check } from "typebox/value";
5
+ import {
6
+ canonicalAgentName,
7
+ contextAgentNames,
8
+ contextStorageAgentName,
9
+ contextTargetAgent,
10
+ isContextAgentName,
11
+ } from "./agent-identity.js";
5
12
  import type { HistorySearch } from "./history-search.js";
6
13
  import {
7
14
  readSavedNotesSession,
@@ -106,10 +113,14 @@ async function readSharedSession(
106
113
  if (typeof path !== "string" || !path.startsWith("/")) return;
107
114
  const target =
108
115
  namespace === "history"
109
- ? /^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(path)
116
+ ? isContextAgentName(path)
110
117
  ? path
111
118
  : undefined
112
- : /^(\/root(?:\/[a-zA-Z0-9_-]+)*?)\/notes(?:\/|$)/.exec(path)?.[1];
119
+ : contextTargetAgent(
120
+ "notes",
121
+ { path },
122
+ canonicalAgentName(ctx.sessionManager.getSessionId()),
123
+ );
113
124
  if (!target) return;
114
125
  const outputAgent = target;
115
126
  const current: SavedNotesSession = {
@@ -117,7 +128,7 @@ async function readSharedSession(
117
128
  entries: ctx.sessionManager.getEntries(),
118
129
  branch: ctx.sessionManager.getBranch(),
119
130
  };
120
- if (savedNotesIdentity(current).agentName === target) return;
131
+ if (contextAgentNames(savedNotesIdentity(current)).includes(target)) return;
121
132
  const visited = new Set<string>();
122
133
 
123
134
  const { read, reference } = createSharedSessionReader(
@@ -136,7 +147,7 @@ async function readSharedSession(
136
147
  if (visited.has(session.threadId)) return;
137
148
  visited.add(session.threadId);
138
149
  const identity = savedNotesIdentity(session);
139
- if (identity.agentName === destination) {
150
+ if (contextAgentNames(identity).includes(destination)) {
140
151
  if (
141
152
  namespace === "notes" &&
142
153
  identity.storage === "remote" &&
@@ -147,7 +158,7 @@ async function readSharedSession(
147
158
  )
148
159
  )
149
160
  return;
150
- return read(session, query, identity.agentName);
161
+ return read(session, query, destination);
151
162
  }
152
163
  const routes = new Map<string, Static<typeof Route>>();
153
164
  for (const value of records(session, "shepherdr-attachment-route"))
@@ -158,14 +169,18 @@ async function readSharedSession(
158
169
  routes.set(`${value.machine}\0${value.sessionFile}`, value);
159
170
  for (const route of routes.values()) {
160
171
  const link = route.plan.context;
161
- if (route.phase !== "ready" || !link || !inside(destination, link.alias))
162
- continue;
172
+ if (route.phase !== "ready" || !link) continue;
173
+ const alias =
174
+ destination === canonicalAgentName(link.target.threadId)
175
+ ? destination
176
+ : link.alias;
177
+ if (!inside(destination, alias)) continue;
163
178
  if (!sameOwner(identity, link.controller))
164
179
  throw new Error("Saved shared notes identity changed");
165
180
  return reference(
166
181
  link.target,
167
- `${link.target.agentName}${destination.slice(link.alias.length)}`,
168
- remap(query, link.alias, link.target.agentName),
182
+ `${link.target.agentName}${destination.slice(alias.length)}`,
183
+ remap(query, alias, link.target.agentName),
169
184
  route.machine === "local" ? route.sessionFile : undefined,
170
185
  route.detached?.context ?? link.targetNotes,
171
186
  route.detached?.context !== undefined,
@@ -178,9 +193,14 @@ async function readSharedSession(
178
193
  if (
179
194
  Check(Plan, owner) &&
180
195
  owner.context &&
181
- inside(destination, owner.context.controllerAlias)
196
+ (inside(destination, owner.context.controllerAlias) ||
197
+ destination === canonicalAgentName(owner.context.controller.threadId))
182
198
  ) {
183
199
  const link = owner.context;
200
+ const alias =
201
+ destination === canonicalAgentName(link.controller.threadId)
202
+ ? destination
203
+ : link.controllerAlias;
184
204
  if (!sameOwner(identity, link.target))
185
205
  throw new Error("Saved shared notes identity changed");
186
206
  const detached = records(
@@ -195,22 +215,21 @@ async function readSharedSession(
195
215
  : undefined;
196
216
  return reference(
197
217
  link.controller,
198
- `${link.controller.agentName}${destination.slice(link.controllerAlias.length)}`,
199
- remap(query, link.controllerAlias, link.controller.agentName),
218
+ `${link.controller.agentName}${destination.slice(alias.length)}`,
219
+ remap(query, alias, link.controller.agentName),
200
220
  link.controllerFile,
201
221
  snapshot ?? link.controllerNotes,
202
222
  snapshot !== undefined,
203
223
  );
204
224
  }
205
- const member = records(session, "herdr-context-child").findLast(
225
+ const members = records(session, "herdr-context-child").filter(
206
226
  (value) =>
207
227
  Check(Member, value) &&
208
228
  value.threadId === identity.threadId &&
209
- value.sessionId === identity.sessionId &&
210
- inside(destination, value.agentName),
229
+ value.sessionId === identity.sessionId,
211
230
  );
212
- if (Check(Member, member)) {
213
- if (member.machine !== "local") return;
231
+ for (const member of members) {
232
+ if (!Check(Member, member) || member.machine !== "local") continue;
214
233
  const saved = await readSavedNotesSession(
215
234
  member.sessionFile,
216
235
  signal,
@@ -219,12 +238,14 @@ async function readSharedSession(
219
238
  const child = savedNotesIdentity(saved);
220
239
  if (
221
240
  child.sessionId !== identity.sessionId ||
222
- child.agentName !== member.agentName
241
+ (child.agentName !== member.agentName &&
242
+ contextStorageAgentName(child) !== member.agentName)
223
243
  )
224
244
  throw new Error(
225
245
  "Saved shared notes belong to a different agent family",
226
246
  );
227
- return resolve(saved, destination, query);
247
+ const result = await resolve(saved, destination, query);
248
+ if (result) return result;
228
249
  }
229
250
  const routing = identity.routing;
230
251
  const suffix = ".jsonl.shepherdr-context.json";
@@ -237,7 +258,15 @@ async function readSharedSession(
237
258
  const parent = savedNotesIdentity(saved);
238
259
  if (
239
260
  parent.sessionId !== identity.sessionId ||
240
- !identity.agentName.startsWith(`${parent.agentName}/`)
261
+ !records(saved, "herdr-context-child").some(
262
+ (value) =>
263
+ Check(Member, value) &&
264
+ value.threadId === parent.threadId &&
265
+ value.sessionId === parent.sessionId &&
266
+ [identity.agentName, contextStorageAgentName(identity)].includes(
267
+ value.agentName,
268
+ ),
269
+ )
241
270
  )
242
271
  throw new Error("Saved shared notes parent identity changed");
243
272
  return resolve(saved, destination, query);
@@ -1,5 +1,6 @@
1
1
  import type { SessionEntry } from "@earendil-works/pi-coding-agent";
2
2
  import { Check } from "typebox/value";
3
+ import { contextStorageAgentName } from "./agent-identity.js";
3
4
  import { useHistory } from "./history.js";
4
5
  import type { HistorySearch } from "./history-search.js";
5
6
  import { normalizeNoteParams, readNotes } from "./note-query.js";
@@ -99,7 +100,8 @@ export function createSharedSessionReader(
99
100
  }
100
101
  if (
101
102
  namespace === "history" ||
102
- destination !== identity.agentName ||
103
+ (destination !== identity.agentName &&
104
+ destination !== contextStorageAgentName(identity)) ||
103
105
  !Check(Snapshot, retained)
104
106
  )
105
107
  return;
@@ -111,8 +113,10 @@ export function createSharedSessionReader(
111
113
  customType: "codex-context-note-snapshot",
112
114
  data: {
113
115
  ...retained,
114
- files: retained.files.filter((file) =>
115
- file.path.startsWith(`${identity.agentName}/notes/`),
116
+ files: retained.files.filter(
117
+ (file) =>
118
+ file.path.startsWith(`${identity.agentName}/notes/`) ||
119
+ file.path.startsWith(`${contextStorageAgentName(identity)}/notes/`),
116
120
  ),
117
121
  },
118
122
  };
@@ -120,7 +124,7 @@ export function createSharedSessionReader(
120
124
  ...(await read(
121
125
  { threadId: identity.threadId, entries: [], branch: [entry] },
122
126
  query,
123
- identity.agentName,
127
+ destination,
124
128
  )),
125
129
  captured_at: new Date(retained.timestamp).toISOString(),
126
130
  warning: detached
@@ -1,4 +1,3 @@
1
- import { randomUUID } from "node:crypto";
2
1
  import { isDeepStrictEqual } from "node:util";
3
2
  import type {
4
3
  ExtensionAPI,
@@ -6,7 +5,9 @@ import type {
6
5
  } from "@earendil-works/pi-coding-agent";
7
6
  import {
8
7
  CONTEXT_AGENT_ENTRY,
8
+ canonicalAgentName,
9
9
  contextAgentIdentity,
10
+ contextAgentNames,
10
11
  contextTargetAgent,
11
12
  parseContextAgentBinding,
12
13
  } from "./agent-identity.js";
@@ -79,8 +80,14 @@ export function registerContextSharingService(
79
80
  const parent = describe(ctx);
80
81
  if (!parent)
81
82
  throw new Error("Shared context requires notes-based continuity");
82
- if (!/^[a-zA-Z0-9_-]+$/.test(options.name))
83
- throw new Error("Invalid context agent name");
83
+ if (
84
+ options.threadId === parent.threadId ||
85
+ options.threadId === parent.sessionId
86
+ )
87
+ throw new Error(
88
+ "Child Pi session ID conflicts with its controller or family root; start a session with another ID",
89
+ );
90
+ const agentName = canonicalAgentName(options.threadId);
84
91
  if (!router || options.routing === undefined)
85
92
  throw new Error("Local sharing requires a registered context router");
86
93
 
@@ -91,7 +98,7 @@ export function registerContextSharingService(
91
98
  const binding = {
92
99
  protocol: 1 as const,
93
100
  sessionId: parent.sessionId,
94
- agentName: `${parent.agentName}/${options.name}-${randomUUID()}`,
101
+ agentName,
95
102
  storage: "session" as const,
96
103
  ...(parent.accountScope ? { accountScope: parent.accountScope } : {}),
97
104
  ...(parent.backendUrl ? { backendUrl: parent.backendUrl } : {}),
@@ -120,8 +127,18 @@ export function registerContextSharingService(
120
127
  },
121
128
  async bind(ctx, input, options) {
122
129
  const binding = parseContextAgentBinding(input);
123
- if (binding.agentName === "/root")
124
- throw new Error("Shared context binding requires a child agent path");
130
+ if (ctx.sessionManager.getSessionId() === binding.sessionId)
131
+ throw new Error(
132
+ "Child Pi session ID conflicts with its family root; start a session with another ID",
133
+ );
134
+ if (
135
+ binding.agentName !==
136
+ canonicalAgentName(ctx.sessionManager.getSessionId()) ||
137
+ binding.storageAgentName !== undefined
138
+ )
139
+ throw new Error(
140
+ "Shared context binding must use this Pi session identity",
141
+ );
125
142
  const identity = {
126
143
  ...binding,
127
144
  threadId: ctx.sessionManager.getSessionId(),
@@ -176,7 +193,7 @@ export function registerContextSharingService(
176
193
  if (
177
194
  !identity ||
178
195
  identity.sessionId !== request.sessionId ||
179
- identity.agentName !== request.agentName ||
196
+ !contextAgentNames(identity).includes(request.agentName) ||
180
197
  (request.namespace !== "notes" && request.namespace !== "history") ||
181
198
  !request.params ||
182
199
  typeof request.params !== "object" ||
@@ -185,7 +202,7 @@ export function registerContextSharingService(
185
202
  request.namespace,
186
203
  request.params,
187
204
  identity.agentName,
188
- ) !== identity.agentName
205
+ ) !== request.agentName
189
206
  )
190
207
  throw new Error("Shared context request does not belong to this agent");
191
208
  if (request.encryptedArguments)
@@ -6,7 +6,7 @@ export function renderTaskBoundaryReminder(
6
6
  ): string {
7
7
  if (gpt)
8
8
  return `<context_window_reminder>\nSuggested budget reached; ${remainingPercent}% left. Task sequence→finish current task→save notes→new_context before next; otherwise continue here.\n</context_window_reminder>`;
9
- return `<context_window_reminder>\nSuggested context budget reached; ${remainingPercent}% remains. For a sequence of tasks, finish the current task, save notes and call new_context before the next. Otherwise, continue here.\n</context_window_reminder>`;
9
+ return `<context_window_reminder>\nSuggested context budget reached; ${remainingPercent}% remains. For task sequences, finish current task, save notes and call new_context before next task. Otherwise continue here.\n</context_window_reminder>`;
10
10
  }
11
11
 
12
12
  export const TASK_BOUNDARY_PRESETS = [
@@ -3,6 +3,7 @@ import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
3
3
  import { Type } from "typebox";
4
4
  import { Check } from "typebox/value";
5
5
  import type { LookupQuery } from "./bridge.js";
6
+ import { noteResult } from "./note-result.js";
6
7
  import { internalQueryArguments, normalizeQueryInput } from "./query-input.js";
7
8
 
8
9
  const NOTES_ACTIONS = [
@@ -22,14 +23,12 @@ const HISTORY_ACTIONS = [
22
23
  ] as const;
23
24
  export const NOTES_USAGE = "await tools.notes()";
24
25
  export const HISTORY_USAGE = "await tools.history()";
25
- export const NOTES_DESCRIPTION =
26
- "Persistent notes for handing off task state between context windows";
27
- export const GPT_NOTES_DESCRIPTION =
28
- "Persistent notes: task state handoff between context windows";
26
+ export const NOTES_DESCRIPTION = "Virtual filesystem task checkpoints";
27
+ export const NOTES_ROUTING_GUIDELINE =
28
+ "notes: task checkpoints and internal handoffs. MUST revise via write/append actions. Paths are virtual: read/write only through notes, never shell/filesystem tools. MUST NOT store project files or deliverables";
29
29
  export const NEW_CONTEXT_DESCRIPTION =
30
- "Start fresh from saved notes; recover earlier conversation through history";
31
- export const GPT_NEW_CONTEXT_DESCRIPTION =
32
- "Saved notes→fresh context; earlier conversation→history";
30
+ "Start fresh context window. MUST save notes before calling";
31
+ export const GPT_NEW_CONTEXT_DESCRIPTION = "Save notes→fresh context";
33
32
  const STRING = Type.Optional(Type.String());
34
33
  const INTEGER = Type.Optional(Type.Integer({ minimum: 1 }));
35
34
  const LINE = Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
@@ -38,7 +37,8 @@ export const NOTES_SCHEMA = Type.Object(
38
37
  action: Type.Optional(StringEnum(NOTES_ACTIONS)),
39
38
  path: Type.Optional(
40
39
  Type.Union([Type.String(), Type.Null()], {
41
- description: "File for read/write/append; prefix for list/search",
40
+ description:
41
+ "File for read/write/append; prefix for list/search; virtual filesystem, not files in the project",
42
42
  }),
43
43
  ),
44
44
  text: STRING,
@@ -55,11 +55,26 @@ export const NOTES_SCHEMA = Type.Object(
55
55
  },
56
56
  { additionalProperties: false },
57
57
  );
58
- export const NEW_CONTEXT_SCHEMA = Type.Object(
59
- { role: Type.Optional(Type.String({ minLength: 1 })) },
58
+ const NEW_CONTEXT_SCHEMA = Type.Object(
59
+ {
60
+ role: Type.Optional(
61
+ Type.String({
62
+ minLength: 1,
63
+ description:
64
+ "Configured model-role ID, not an agent name or handoff text",
65
+ }),
66
+ ),
67
+ },
60
68
  { additionalProperties: false },
61
69
  );
62
70
 
71
+ export function newContextSchema(roleIds: string[]) {
72
+ return Type.Object(
73
+ roleIds.length ? { role: Type.Optional(StringEnum(roleIds)) } : {},
74
+ { additionalProperties: false },
75
+ );
76
+ }
77
+
63
78
  export function prepareNewContextArguments(input: unknown) {
64
79
  const args = input ?? {};
65
80
  if (!Check(NEW_CONTEXT_SCHEMA, args))
@@ -72,7 +87,7 @@ export const HISTORY_SCHEMA = Type.Object(
72
87
  {
73
88
  action: Type.Optional(StringEnum(HISTORY_ACTIONS)),
74
89
  agent_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
75
- item_id: STRING,
90
+ item_id: Type.Optional(Type.String()),
76
91
  window_id: Type.Optional(
77
92
  Type.Union([Type.String(), Type.Null()], {
78
93
  description: "Required with item_id for read",
@@ -194,7 +209,6 @@ export function result(payload: unknown): AgentToolResult<unknown> {
194
209
  export function queryHelp(
195
210
  namespace: LookupQuery["namespace"],
196
211
  input: unknown,
197
- rankedHistory = false,
198
212
  gpt = false,
199
213
  ): AgentToolResult<unknown> | undefined {
200
214
  const params = input === undefined ? {} : input;
@@ -208,7 +222,10 @@ export function queryHelp(
208
222
  if (entries.some(([key]) => key !== "action"))
209
223
  throw new Error("Help accepts only action: help");
210
224
  const actions = namespace === "notes" ? NOTES_ACTIONS : HISTORY_ACTIONS;
211
- return result({
225
+ return (namespace === "notes" ? noteResult : result)({
226
+ ...(namespace === "notes"
227
+ ? { results: "read: file.content; write/append: file.path" }
228
+ : {}),
212
229
  actions: Object.fromEntries(
213
230
  actions.map((action) => [
214
231
  action,
@@ -230,27 +247,23 @@ export function queryHelp(
230
247
  ? "write=replace; append=add"
231
248
  : "write replaces; append adds",
232
249
  paths: gpt
233
- ? "Relative=current agent; cross-agent=<agent>/notes[/path]"
234
- : "Relative uses current agent; cross-agent uses <agent>/notes[/path]",
235
- usage: '{ "action": "read", "path": "checkpoint" }',
250
+ ? "Virtual≠disk; own list/search→omit path; relative=current agent; absolute=/<session ID>/notes[/path], not the agent ID alone"
251
+ : "Virtual note paths, not disk files. Omit path to list/search your notes. Relative paths use your agent; absolute paths require /<session ID>/notes[/path], not the agent ID alone",
252
+ usage: 'notes: {"action":"read","path":"checkpoint"}',
236
253
  ranges: gpt
237
254
  ? "start_line/stop_line=1-based inclusive; negative=from end; 0/null/omitted=first/last; out-of-range→clamp; reversed→empty"
238
- : "start_line/stop_line inclusive, 1-based; negative counts from end; 0/null/omitted uses first/last line; out-of-range clamps; reversed range returns empty content",
255
+ : "start_line/stop_line inclusive, 1-based; negative from end; 0/null/omitted uses first/last line; out-of-range clamps; reversed returns empty content",
239
256
  defaults: gpt
240
257
  ? "list limit=20; search limit/max_matches_per_file=20; limits clamp 1..100; list/search name ascending; recent_file_first→created_at descending"
241
- : "list limit 20; search limit/max_matches_per_file 20; limits clamp to 1..100; list name ascending; search name ascending, recent_file_first sorts created_at descending",
258
+ : "list limit 20; search limit/max_matches_per_file 20; limits clamp 1..100; list/search name ascending; recent_file_first sorts created_at descending",
242
259
  }
243
260
  : {
244
261
  usage: gpt
245
- ? "Earlierconversation→search≠browse; returned IDs unchanged"
246
- : "Search earlier conversation, don't browse it. Pass returned IDs unchanged",
247
- search: rankedHistory
248
- ? gpt
249
- ? "Own past user/assistant visible text: all keywords, case/accent-insensitive, BM25-ranked. Explicit live/tool/metadata/agent_name scopes→case-sensitive literal substring. list/read=full transcript; recent_first=true→newest first"
250
- : "Own earlier conversation: user/assistant visible text, all keywords, case/accent-insensitive, relevance order. Explicit live/tool/metadata scopes or agent_name: case-sensitive literal substring. list/read retain the full transcript. recent_first=true uses newest first"
251
- : gpt
252
- ? "Case-sensitive literal substring; recent_first=true→newest first"
253
- : "Case-sensitive literal substring. recent_first=true uses newest first",
262
+ ? "query→search default; past chat→search≠browse; returned IDs unchanged"
263
+ : "With query, action defaults to search. Search past chat, don't browse it. Pass returned IDs unchanged",
264
+ search: gpt
265
+ ? "recent_first=true→newest first"
266
+ : "recent_first=true uses newest first",
254
267
  }),
255
268
  });
256
269
  }