@howaboua/pi-agent-comms 0.0.2 → 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.
@@ -22,12 +22,12 @@ export async function registerNotesToolIntegrations(
22
22
  pi: ExtensionAPI,
23
23
  lifecycle: NotesLifecycle,
24
24
  activation: NotesActivation,
25
- tools: ReturnType<typeof createTools>,
25
+ registration: ReturnType<typeof createTools>,
26
26
  ) {
27
+ const { tools, requestContext } = registration;
27
28
  try {
28
- const { registerGptPromptMode } = await import(
29
- "@howaboua/pi-codex-conversion/prompt-mode"
30
- );
29
+ const { registerGptPromptMode } =
30
+ await import("@howaboua/pi-codex-conversion/prompt-mode");
31
31
  const registration = registerGptPromptMode(pi, (active, ctx) => {
32
32
  if (ctx) activation.refreshActivation(ctx);
33
33
  const tool = tools.find((tool) => tool.name === "new_context");
@@ -59,42 +59,82 @@ export async function registerNotesToolIntegrations(
59
59
  try {
60
60
  const { adaptToolForCodeMode, registerCodeModeExtensionTools } =
61
61
  await import("@howaboua/pi-codex-conversion/code-mode");
62
+ const rollover: ReturnType<typeof adaptToolForCodeMode> = {
63
+ name: "new_context",
64
+ topLevelName: "new_context",
65
+ usage: "tools.new_context(args)",
66
+ description: "",
67
+ kind: "function",
68
+ inputOptional: true,
69
+ deferLoading: true,
70
+ discoverWhenDeferred: false,
71
+ propagateTermination: true,
72
+ executionMode: "sequential",
73
+ inputSchema: tools.find((tool) => tool.name === "new_context")!
74
+ .parameters,
75
+ async invoke(input, context, signal) {
76
+ if (
77
+ !context.extensionContext ||
78
+ !context.originalExecCallId ||
79
+ !context.toolCallId
80
+ )
81
+ throw new Error(
82
+ "Context rollover is unavailable in this call. Save notes and call new_context directly.",
83
+ );
84
+ const output = await requestContext(
85
+ context.toolCallId,
86
+ input,
87
+ signal,
88
+ context.extensionContext,
89
+ context.originalExecCallId,
90
+ );
91
+ context.captureResult?.(output);
92
+ const part = output.content[0];
93
+ return part?.type === "text" ? JSON.parse(part.text) : undefined;
94
+ },
95
+ };
62
96
  const registration = registerCodeModeExtensionTools(
63
97
  pi,
64
- () =>
65
- tools
66
- .filter((tool) => tool.name === "notes" || tool.name === "history")
67
- .map((tool) => ({
68
- ...adaptToolForCodeMode(tool, {
69
- discovery: "help",
70
- usage: tool.name === "notes" ? NOTES_USAGE : HISTORY_USAGE,
71
- deferLoading: tool.name !== "notes",
72
- opaqueResult: tool.name === "notes",
73
- ...(tool.name === "history"
74
- ? { resultValue: historyResultValue }
75
- : {}),
76
- }),
77
- // Code checks inputs before Pi can normalise these aliases.
78
- ...(tool.name === "notes"
79
- ? {
80
- inputSchema: {
81
- ...NOTES_SCHEMA,
82
- properties: {
83
- ...noteProperties,
84
- content: noteProperties["text"],
85
- end_line: noteProperties["stop_line"],
98
+ () => {
99
+ rollover.inputSchema = tools.find(
100
+ (tool) => tool.name === "new_context",
101
+ )!.parameters;
102
+ return [
103
+ rollover,
104
+ ...tools
105
+ .filter((tool) => tool.name === "notes" || tool.name === "history")
106
+ .map((tool) => ({
107
+ ...adaptToolForCodeMode(tool, {
108
+ discovery: "help",
109
+ usage: tool.name === "notes" ? NOTES_USAGE : HISTORY_USAGE,
110
+ deferLoading: tool.name !== "notes",
111
+ opaqueResult: tool.name === "notes",
112
+ ...(tool.name === "history"
113
+ ? { resultValue: historyResultValue }
114
+ : {}),
115
+ }),
116
+ // Code checks inputs before Pi can normalise these aliases.
117
+ ...(tool.name === "notes"
118
+ ? {
119
+ inputSchema: {
120
+ ...NOTES_SCHEMA,
121
+ properties: {
122
+ ...noteProperties,
123
+ content: noteProperties["text"],
124
+ end_line: noteProperties["stop_line"],
125
+ },
86
126
  },
87
- },
88
- }
89
- : {}),
90
- })),
127
+ }
128
+ : {}),
129
+ })),
130
+ ];
131
+ },
91
132
  { isActive: () => lifecycle.active },
92
133
  );
93
134
  refreshNested = registration.refresh;
94
135
  pi.on("session_shutdown", () => registration.unregister());
95
- const { withCodexDeveloperMessageDetails } = await import(
96
- "@howaboua/pi-codex-conversion/developer-messages"
97
- );
136
+ const { withCodexDeveloperMessageDetails } =
137
+ await import("@howaboua/pi-codex-conversion/developer-messages");
98
138
  lifecycle.prepareReminder = withCodexDeveloperMessageDetails;
99
139
  } catch (error) {
100
140
  if (!optionalPccMissing(error)) throw error;
@@ -138,19 +178,17 @@ export async function registerNotesCompactionIntegration(
138
178
  } = await import("@howaboua/pi-codex-conversion/compaction");
139
179
  prepareProviderWindow = (ctx) => prepareContextWindow(pi, ctx);
140
180
  const registration = registerCompactionPreparation(pi, prepareCompaction);
141
- const stopProjection = registerContextBranchProjection(
142
- pi,
143
- (entries, ctx) =>
144
- activation.available
145
- ? projectTreeHandoffBranch(
146
- lifecycle.windows.projectBranch(
147
- projectTreeCheckpointBranch(
148
- entries,
149
- ctx.sessionManager.getEntries(),
150
- ),
181
+ const stopProjection = registerContextBranchProjection(pi, (entries, ctx) =>
182
+ activation.available
183
+ ? projectTreeHandoffBranch(
184
+ lifecycle.windows.projectBranch(
185
+ projectTreeCheckpointBranch(
186
+ entries,
187
+ ctx.sessionManager.getEntries(),
151
188
  ),
152
- )
153
- : entries,
189
+ ),
190
+ )
191
+ : entries,
154
192
  );
155
193
  pi.on("session_shutdown", stopProjection);
156
194
  pi.on("session_before_compact", registration.prepare);
@@ -40,6 +40,7 @@ export class NotesLifecycle {
40
40
  active = false;
41
41
  normalCompaction = false;
42
42
  newWindowRequests: NewWindowRequests = "unrestricted";
43
+ taskCompletionRollover = false;
43
44
  idleMinutes: IdleMinutes = 0;
44
45
  taskBoundaryReminder = 0;
45
46
  bridge: NotesBridge | undefined;
@@ -170,11 +171,17 @@ export class NotesLifecycle {
170
171
  ctx: ExtensionContext,
171
172
  callId: string,
172
173
  handoff?: ModelRoleHandoff,
174
+ resume = true,
175
+ parentCallId?: string,
173
176
  ): boolean {
174
177
  if (this.newWindowRequests === "off")
175
178
  throw new Error(
176
179
  "New window requests are disabled. Continue in the current window.",
177
180
  );
181
+ if (!resume && !this.taskCompletionRollover)
182
+ throw new Error(
183
+ "Task-completion rollover is disabled. Continue here, or use new_context without resume: false.",
184
+ );
178
185
  if (this.checkpoint.pending || this.admission.pending) return false;
179
186
  if (this.requests.pending) return false;
180
187
  if (
@@ -183,12 +190,13 @@ export class NotesLifecycle {
183
190
  this.windows.current?.currentWindowId,
184
191
  this.runId,
185
192
  callId,
193
+ parentCallId,
186
194
  )
187
195
  )
188
196
  throw new Error(
189
197
  "Save your progress in your own notes using a relative path, wait for the write to succeed, then call new_context next. Writing another agent's notes does not save your checkpoint.",
190
198
  );
191
- this.requests.schedule(ctx, handoff);
199
+ this.requests.schedule(ctx, handoff, resume);
192
200
  return true;
193
201
  }
194
202
  private async openWindow(
@@ -237,6 +245,7 @@ export class NotesLifecycle {
237
245
  }
238
246
  outcome(outcome: "completed" | "aborted" | "error"): void {
239
247
  this.checkpoint.outcome(outcome);
248
+ this.requests.outcome(outcome);
240
249
  }
241
250
  input(
242
251
  event: InputEvent,
@@ -302,7 +311,7 @@ export class NotesLifecycle {
302
311
  return;
303
312
  }
304
313
  if (this.admission.drain()) return;
305
- const rollover = this.requests.settled(ctx);
314
+ const rollover = this.requests.settled(ctx, event.aborted);
306
315
  if (rollover) await rollover;
307
316
  }
308
317
  }
@@ -77,8 +77,8 @@ export function createModelRoles(
77
77
  ? [
78
78
  `Current role: ${currentRole}`,
79
79
  lifecycle.gptPromptMode()
80
- ? 'Roles=user preferences, not capability limits. Switch for clear, sustained task/scope change, not one specialised prompt. Any role can do general work. Bounded specialist detour→consider subagent. Save notes→new_context({role: "name"}); omit role→keep role.'
81
- : 'Roles are user preferences, not capability limits. Switch for clear, sustained change of task or scope, not single specialised prompt. Any role can do general work. Consider subagents for a bounded specialist detour. Save notes, then call new_context({role: "name"}); omit role to keep the current role.',
80
+ ? 'Roles=user-configured model+reasoning presets, not capabilities/permissions. Each agent, including workers, chooses its own role autonomously; NO parent/user approval needed. Main work enters substantial new phase→reassess descriptions, switch for sustained better fit. Single specialised question/brief detour≠switch; any role can do general work. Change your own role, not delegate just to access one. Save notes→new_context({role: "name"})→fresh window, same session; omit role→keep preset.'
81
+ : 'Roles select user-configured model and reasoning presets, not capabilities or permissions. Each agent, including workers, chooses its own role autonomously; no parent or user approval needed. Reassess the descriptions when your main work enters a substantial new phase, and switch for a sustained better fit, not a single specialised question or brief detour. Any role can do general work. Change your own role rather than delegating just to access one. Save notes, then call new_context({role: "name"}) to open a fresh window in this session; omit role to keep the current preset.',
82
82
  ...config.roles.map((role) => `- ${role.id}: ${role.description}`),
83
83
  ].join("\n")
84
84
  : "No model roles available. Call new_context without role.";
@@ -7,6 +7,7 @@ import type {
7
7
  import { prepareCompactionProjection } from "./compaction-projection.js";
8
8
  import type { NotesLifecycle } from "./lifecycle.js";
9
9
  import type { ModelRoleHandoff } from "./model-roles.js";
10
+ import type { NewWindowRequests } from "./settings.js";
10
11
 
11
12
  type Rollover = {
12
13
  sessionId: string;
@@ -67,24 +68,45 @@ export class RolloverRequests {
67
68
  clear(): void {
68
69
  this.rollover = undefined;
69
70
  }
70
- schedule(ctx: ExtensionContext, handoff?: ModelRoleHandoff): void {
71
+ schedule(
72
+ ctx: ExtensionContext,
73
+ handoff?: ModelRoleHandoff,
74
+ resume = true,
75
+ ): void {
71
76
  this.rollover = {
72
77
  sessionId: ctx.sessionManager.getSessionId(),
73
78
  windowId: this.host.windows.current?.currentWindowId,
74
79
  phase: "scheduled",
75
- triggerTurn: true,
80
+ triggerTurn: resume,
76
81
  ...(handoff ? { handoff } : {}),
77
82
  };
78
83
  }
79
- settled(ctx: ExtensionContext): Promise<void> | undefined {
84
+ outcome(outcome: "completed" | "aborted" | "error"): void {
85
+ if (
86
+ this.rollover?.phase === "scheduled" &&
87
+ !this.rollover.triggerTurn &&
88
+ outcome !== "completed"
89
+ )
90
+ this.clear();
91
+ }
92
+ settled(ctx: ExtensionContext, aborted = false): Promise<void> | undefined {
80
93
  const rollover = this.rollover;
94
+ if (rollover?.phase === "scheduled" && !rollover.triggerTurn && aborted) {
95
+ this.clear();
96
+ return;
97
+ }
81
98
  if (
82
99
  rollover?.phase === "scheduled" &&
83
100
  rollover.sessionId === ctx.sessionManager.getSessionId() &&
84
101
  rollover.windowId === this.host.windows.current?.currentWindowId
85
102
  ) {
86
103
  this.rollover = undefined;
87
- return this.roll(ctx, rollover.triggerTurn, rollover.handoff);
104
+ return this.roll(
105
+ ctx,
106
+ rollover.triggerTurn,
107
+ rollover.handoff,
108
+ this.host.newWindowRequests,
109
+ );
88
110
  }
89
111
  }
90
112
 
@@ -92,8 +114,10 @@ export class RolloverRequests {
92
114
  ctx: ExtensionContext,
93
115
  triggerTurn: boolean,
94
116
  handoff?: ModelRoleHandoff,
117
+ policy: NewWindowRequests | undefined = triggerTurn
118
+ ? this.host.newWindowRequests
119
+ : undefined,
95
120
  ): Promise<void> {
96
- const policy = triggerTurn ? this.host.newWindowRequests : undefined;
97
121
  const checkOnly = !this.host.normalCompaction && policy === "pi-limits";
98
122
  if (!this.host.normalCompaction && !checkOnly) {
99
123
  await this.openWindow(ctx, triggerTurn, true, handoff);
@@ -151,6 +175,11 @@ export class RolloverRequests {
151
175
  }
152
176
  this.rollover = undefined;
153
177
  try {
178
+ if (!triggerTurn && policy !== undefined)
179
+ ctx.ui.notify(
180
+ "New context was not opened: Pi has no eligible history to compact. The current context remains.",
181
+ "warning",
182
+ );
154
183
  if (triggerTurn)
155
184
  this.sendMessage(
156
185
  {
@@ -155,6 +155,7 @@ export async function cleanSparseSession(file, sessionId, checkOwners) {
155
155
  try {
156
156
  unlinkSync(temp);
157
157
  } catch (error) {
158
+ // oxlint-disable-next-line no-unsafe-finally -- Cleanup failure must remain visible, even when the primary operation failed.
158
159
  if (!vanished(error)) throw error;
159
160
  } finally {
160
161
  releaseLock?.();
@@ -135,6 +135,7 @@ export async function commitSessionPruning(
135
135
  try {
136
136
  unlinkSync(temp);
137
137
  } catch (error) {
138
+ // oxlint-disable-next-line no-unsafe-finally -- Cleanup failure must remain visible, even when the primary operation failed.
138
139
  if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
139
140
  }
140
141
  }
@@ -99,6 +99,14 @@ export function createNotesSettingsControls(
99
99
  currentValue: settings.newWindowRequests,
100
100
  values: [...NEW_WINDOW_REQUESTS],
101
101
  },
102
+ {
103
+ id: "taskCompletionRollover",
104
+ label: "Task-completion rollover",
105
+ description:
106
+ "Allow new_context({resume: false}) when a task is complete: finish the reply, then wait in fresh context. Off keeps immediate continuation only.",
107
+ currentValue: settings.taskCompletionRollover ? "on" : "off",
108
+ values: ["off", "on"],
109
+ },
102
110
  {
103
111
  id: "taskBoundaryReminder",
104
112
  label: "Task-boundary reminder",
@@ -167,6 +175,8 @@ export function createNotesSettingsControls(
167
175
  save({ ...current, rankedHistorySearch: value === "on" });
168
176
  else if (id === "compact")
169
177
  save({ ...current, normalCompaction: value === "on" });
178
+ else if (id === "taskCompletionRollover")
179
+ save({ ...current, taskCompletionRollover: value === "on" });
170
180
  else if (id === "newWindowRequests") {
171
181
  const newWindowRequests = NEW_WINDOW_REQUESTS.find(
172
182
  (mode) => mode === value,
@@ -15,12 +15,7 @@ export const NEW_WINDOW_REQUESTS = [
15
15
  "unrestricted",
16
16
  ] as const;
17
17
  export type NewWindowRequests = (typeof NEW_WINDOW_REQUESTS)[number];
18
- const DEFAULT_MODEL_WHITELIST = [
19
- "gpt-6-astra",
20
- "gpt-6-sol",
21
- "gpt-6-luna",
22
- "gpt-6.1-sol",
23
- ];
18
+ const DEFAULT_MODEL_WHITELIST = ["gpt-6.2-astra", "gpt-6.2-sol", "gpt-6-luna"];
24
19
  export interface NotesSettings {
25
20
  active: "all" | "whitelist" | "off";
26
21
  modelWhitelist: string[];
@@ -29,6 +24,7 @@ export interface NotesSettings {
29
24
  rankedHistorySearch: boolean;
30
25
  shareSubagentContext: boolean;
31
26
  newWindowRequests: NewWindowRequests;
27
+ taskCompletionRollover: boolean;
32
28
  idleMinutes: IdleMinutes;
33
29
  taskBoundaryReminder: number;
34
30
  }
@@ -79,6 +75,7 @@ function readSettings(
79
75
  noteSaveMarkers: preferences().noteSaveMarkers,
80
76
  shareSubagentContext: false,
81
77
  newWindowRequests: "unrestricted",
78
+ taskCompletionRollover: false,
82
79
  idleMinutes: 0,
83
80
  taskBoundaryReminder: 0,
84
81
  }
@@ -129,6 +126,14 @@ function readSettings(
129
126
  );
130
127
  const taskBoundaryReminder =
131
128
  "taskBoundaryReminder" in settings ? settings.taskBoundaryReminder : 0;
129
+ const taskCompletionRollover =
130
+ "taskCompletionRollover" in settings
131
+ ? settings.taskCompletionRollover
132
+ : false;
133
+ if (typeof taskCompletionRollover !== "boolean")
134
+ throw new Error(
135
+ "Invalid task-completion rollover setting. Choose on or off in /notes.",
136
+ );
132
137
  if (
133
138
  typeof taskBoundaryReminder !== "number" ||
134
139
  !Number.isSafeInteger(taskBoundaryReminder) ||
@@ -159,6 +164,7 @@ function readSettings(
159
164
  ? settings.shareSubagentContext === true
160
165
  : preferences().compaction["shareSubagentContext"] === true,
161
166
  newWindowRequests: newWindowRequests as NewWindowRequests,
167
+ taskCompletionRollover,
162
168
  idleMinutes: idleMinutes as IdleMinutes,
163
169
  taskBoundaryReminder,
164
170
  };
@@ -208,6 +214,7 @@ function readLegacySettings(
208
214
  newWindowRequests: NEW_WINDOW_REQUESTS.some((item) => item === requests)
209
215
  ? (requests as NewWindowRequests)
210
216
  : "unrestricted",
217
+ taskCompletionRollover: false,
211
218
  idleMinutes: [...IDLE_MINUTES, 5, 15].some((item) => item === idle)
212
219
  ? (idle as IdleMinutes)
213
220
  : 0,
@@ -160,7 +160,6 @@ async function readSharedSession(
160
160
  const { containingMachine, locator, load, indexed, find } =
161
161
  createSavedSessionAccess(store, namespace, loader, signal);
162
162
  let unavailable: unknown;
163
- let targetReached = false;
164
163
  async function exploratoryLoad(location: Parameters<typeof load>[0]) {
165
164
  try {
166
165
  return await load(location);
@@ -181,6 +180,31 @@ async function readSharedSession(
181
180
  resolve,
182
181
  sharedNotesUnavailable,
183
182
  );
183
+ async function discover(
184
+ target: string,
185
+ ): Promise<SavedNotesSession | undefined> {
186
+ const family = savedFamilyIdentity(current);
187
+ if (!family) return;
188
+ const candidates: SavedNotesSession[] = [];
189
+ for (const location of await find(target)) {
190
+ const saved = await exploratoryLoad(location);
191
+ if (!saved) continue;
192
+ if (saved.threadId !== target.slice(1))
193
+ throw new Error("Saved session discovery returned a different thread");
194
+ const member = savedFamilyIdentity(saved);
195
+ if (
196
+ member?.storage === "session" &&
197
+ member.sessionId === family.sessionId &&
198
+ member.agentName === target
199
+ )
200
+ candidates.push(saved);
201
+ }
202
+ if (candidates.length > 1)
203
+ throw new Error(
204
+ "Saved shared address is ambiguous across machines. Use a unique attached alias, then retry.",
205
+ );
206
+ return candidates[0];
207
+ }
184
208
  async function resolve(
185
209
  session: SavedNotesSession,
186
210
  destination: string,
@@ -192,7 +216,6 @@ async function readSharedSession(
192
216
  visited.add(key);
193
217
  const identity = savedNotesIdentity(session);
194
218
  if (contextAgentNames(identity).includes(destination)) {
195
- targetReached = true;
196
219
  return read(session, query, destination);
197
220
  }
198
221
  const routes = new Map<string, Static<typeof Route>>();
@@ -216,7 +239,6 @@ async function readSharedSession(
216
239
  "Saved shared address is ambiguous across machines. Use a unique attached alias, then retry.",
217
240
  );
218
241
  for (const route of matching) {
219
- targetReached = true;
220
242
  const link = route.plan.context;
221
243
  if (route.phase !== "ready" || !link) continue;
222
244
  const alias =
@@ -246,7 +268,6 @@ async function readSharedSession(
246
268
  (inside(destination, owner.context.controllerAlias) ||
247
269
  destination === canonicalAgentName(owner.context.controller.threadId))
248
270
  ) {
249
- targetReached = true;
250
271
  const link = owner.context;
251
272
  const alias =
252
273
  destination === canonicalAgentName(link.controller.threadId)
@@ -304,6 +325,33 @@ async function readSharedSession(
304
325
  (member) =>
305
326
  memberValidator.check(member) && member.agentName === destination,
306
327
  );
328
+ if (session === current && !direct.length) {
329
+ // Exact native discovery avoids reading every sibling's conversation.
330
+ // Explicit routes and local hints above retain precedence.
331
+ let saved: SavedNotesSession | undefined;
332
+ try {
333
+ saved = await discover(destination);
334
+ } catch (error) {
335
+ signal?.throwIfAborted();
336
+ if (!sharedNotesUnavailable(error)) throw error;
337
+ unavailable ??= error;
338
+ }
339
+ if (saved) {
340
+ return read(saved, query, destination);
341
+ }
342
+ // Do not crawl an entire family to guess a shortened UUID. A real
343
+ // explicitly named session still works via a route, member or exact hint.
344
+ if (/^\/[a-f0-9]{8}-[a-f0-9]{4}$/i.test(destination))
345
+ throw (
346
+ unavailable ??
347
+ Object.assign(
348
+ new Error(
349
+ "This looks like a shortened agent address. Use the complete agent address from the owner and retry.",
350
+ ),
351
+ { code: "SAVED_SESSION_UNAVAILABLE" },
352
+ )
353
+ );
354
+ }
307
355
  for (const member of direct.length ? direct : members) {
308
356
  if (!memberValidator.check(member)) continue;
309
357
  const location = locator(session, member.machine, member.sessionFile);
@@ -373,32 +421,6 @@ async function readSharedSession(
373
421
  if (!sharedNotesUnavailable(error)) throw error;
374
422
  unavailable ??= error;
375
423
  }
376
- // Legacy remote children may record only a now-dead relay parent. Find the
377
- // requested native thread once, never aliases or intermediate graph nodes.
378
- const family = savedFamilyIdentity(current);
379
- if (!result && !targetReached && family) {
380
- const candidates: SavedNotesSession[] = [];
381
- for (const location of await find(target)) {
382
- const saved = await exploratoryLoad(location);
383
- if (!saved) continue;
384
- if (saved.threadId !== target.slice(1))
385
- throw new Error(
386
- "Saved session discovery returned a different thread",
387
- );
388
- const member = savedFamilyIdentity(saved);
389
- if (
390
- member?.storage === "session" &&
391
- member.sessionId === family.sessionId &&
392
- member.agentName === target
393
- )
394
- candidates.push(saved);
395
- }
396
- if (candidates.length > 1)
397
- throw new Error(
398
- "Saved shared address is ambiguous across machines. Use a unique attached alias, then retry.",
399
- );
400
- if (candidates[0]) result = await read(candidates[0], params, target);
401
- }
402
424
  if (!result && unavailable) throw unavailable;
403
425
  return result;
404
426
  } catch (error) {
@@ -31,8 +31,8 @@ const HISTORY_ACTIONS = [
31
31
  "read",
32
32
  "search",
33
33
  ] as const;
34
- export const NOTES_USAGE = "await tools.notes()";
35
- export const HISTORY_USAGE = "await tools.history()";
34
+ export const NOTES_USAGE = "tools.notes()";
35
+ export const HISTORY_USAGE = "tools.history()";
36
36
  export const NOTES_DESCRIPTION = "Virtual filesystem task checkpoints";
37
37
  export const NOTES_ROUTING_GUIDELINE =
38
38
  "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";
@@ -68,6 +68,7 @@ export const NOTES_SCHEMA = obj(
68
68
  );
69
69
  const NEW_CONTEXT_SCHEMA = obj(
70
70
  {
71
+ resume: opt(bool()),
71
72
  role: opt(
72
73
  str({
73
74
  minLength: 1,
@@ -81,9 +82,27 @@ const NEW_CONTEXT_SCHEMA = obj(
81
82
 
82
83
  const newContextSchemaValidator = compile(NEW_CONTEXT_SCHEMA);
83
84
 
84
- export function newContextSchema(roleIds: string[]) {
85
+ export function newContextSchema(
86
+ roleIds: string[],
87
+ taskCompletionRollover = false,
88
+ ) {
85
89
  return obj(
86
- roleIds.length ? { role: opt({ ...oneOf(roleIds), type: "string" }) } : {},
90
+ {
91
+ ...(roleIds.length
92
+ ? { role: opt({ ...oneOf(roleIds), type: "string" }) }
93
+ : {}),
94
+ ...(taskCompletionRollover
95
+ ? {
96
+ resume: opt(
97
+ bool({
98
+ default: true,
99
+ description:
100
+ "False: task complete; finish reply, then wait in fresh context. True: continue immediately",
101
+ }),
102
+ ),
103
+ }
104
+ : {}),
105
+ },
87
106
  { open: false },
88
107
  );
89
108
  }
@@ -92,7 +111,7 @@ export function prepareNewContextArguments(input: unknown) {
92
111
  const args = input ?? {};
93
112
  if (!newContextSchemaValidator.check(args))
94
113
  throw new Error(
95
- 'Use {} to keep the current model, or {role: "name"} for a configured role.',
114
+ "Use {} to continue in fresh context; optional role selects a configured preset. resume must be true or false.",
96
115
  );
97
116
  return args;
98
117
  }