@abelxiaoxing/cadence 2.0.40 → 2.0.41

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.
@@ -1,488 +1,55 @@
1
- /** Model-facing observation tools and their worker-local resource lifetime.
2
- * A cursor is one-use navigation, never execution authority or a durable snapshot. */
3
- import { randomUUID } from "node:crypto";
4
- import { Type } from "typebox";
5
- import { RESEARCH_LIMITS as L, ResearchScan } from "./research-scan.mjs";
1
+ /** Pi's standard readonly file tools, at the admitted investigation location.
2
+ * No second file protocol, scanner, cursor registry or model-managed cleanup. */
3
+ import { readFile, stat } from "node:fs/promises";
4
+ import {
5
+ createFindToolDefinition,
6
+ createGrepToolDefinition,
7
+ createLsToolDefinition,
8
+ createReadToolDefinition,
9
+ detectSupportedImageMimeTypeFromFile,
10
+ } from "@earendil-works/pi-coding-agent";
6
11
 
7
- const object = (value, keys) => {
8
- if (
9
- !value ||
10
- typeof value !== "object" ||
11
- Array.isArray(value) ||
12
- Object.keys(value).some((key) => !keys.includes(key))
13
- )
14
- throw new Error("Invalid investigation arguments");
15
- return value;
16
- };
17
- const integer = (value, maximum = Number.MAX_SAFE_INTEGER, minimum = 1) => {
18
- if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
19
- throw new Error("Invalid investigation range or limit");
20
- return value;
21
- };
22
- const string = (value, maximum = 4096) => {
23
- if (
24
- typeof value !== "string" ||
25
- !value ||
26
- value.length > maximum ||
27
- value.includes("\0")
28
- )
29
- throw new Error("Invalid investigation path or pattern");
30
- return value;
31
- };
32
- const array = (value, maximum) => {
33
- if (!Array.isArray(value) || !value.length || value.length > maximum)
34
- throw new Error("Invalid investigation batch");
35
- return value;
36
- };
37
- // Bound expansion work, not ordinary glob syntax. Native matchesGlob supports
38
- // brace alternatives/extglobs; huge ranges/products must not allocate unboundedly.
39
- const GLOB_EXPANSIONS = 4096;
40
- const glob = (value) => {
41
- string(value, 256);
42
- const stack = [{ alternatives: 0, product: 1, start: 0 }];
43
- for (let i = 0; i < value.length; i++) {
44
- if (value[i] === "\\") {
45
- i++;
46
- continue;
47
- }
48
- const current = stack.at(-1);
49
- if (value[i] === "{")
50
- stack.push({ alternatives: 0, product: 1, start: i + 1 });
51
- else if (value[i] === "," && stack.length > 1) {
52
- current.alternatives += current.product;
53
- current.product = 1;
54
- } else if (value[i] === "}" && stack.length > 1) {
55
- stack.pop();
56
- let size = current.alternatives + current.product;
57
- const range =
58
- /^(-?\d+|[a-zA-Z])\.\.(-?\d+|[a-zA-Z])(?:\.\.(-?\d+))?$/.exec(
59
- value.slice(current.start, i),
60
- );
61
- if (range) {
62
- const number = (part) =>
63
- /^-?\d+$/.test(part) ? Number(part) : part.charCodeAt(0);
64
- const step = Math.abs(Number(range[3] ?? 1)) || 1;
65
- size =
66
- Math.floor(Math.abs(number(range[2]) - number(range[1])) / step) + 1;
67
- }
68
- stack.at(-1).product *= size;
69
- }
70
- if (
71
- stack.some(
72
- (entry) =>
73
- !Number.isFinite(entry.product) ||
74
- entry.product + entry.alternatives > GLOB_EXPANSIONS,
75
- )
76
- )
77
- throw new Error(
78
- "Glob expansion is too large; use * or a smaller set of alternatives",
79
- );
80
- }
81
- return value;
82
- };
83
12
  export const RESEARCH_INSTRUCTIONS =
84
- "Readonly investigation: use read, grep, find/glob and ls directly, not shell command strings. Explicit absolute paths (including installed packages outside the checkout) and symlinks are readable; roots only choose the default search location. grep accepts regular expressions by default; use literal:true for exact text. find/glob accept brace alternatives and extglobs. There is no bash, write or edit tool in this readonly role: use ls for listing, read for file contents, grep for matching and find/glob for file discovery. Keep credentials and private session content out of reports. A returned cursor continues the same query; an empty page with a cursor is not absence.";
13
+ "Use Pi's read, grep, find and ls tools directly. read accepts one path with optional offset/limit; follow its next-offset notice for more text. grep accepts one pattern, find accepts a glob, and ls lists a directory. Searches respect .gitignore; use explicit paths and directory listings when investigating ignored dependencies or backups. Explicit absolute paths outside the checkout remain readable. Relative paths use the first investigation root. These are live filesystem reads, not a snapshot: report truncation and unresolved coverage honestly. There is no bash, write or edit tool in this readonly role; shell work belongs to an authorized implementation. Keep credentials and private session content out of reports.";
85
14
 
86
- function query(kind, args) {
87
- const common = ["pageSize", "path"];
88
- object(args, [
89
- ...common,
90
- ...(kind === "read"
91
- ? ["files", "offset", "limit"]
92
- : kind === "grep"
93
- ? ["pattern", "patterns", "glob", "depth", "ignoreCase", "literal"]
94
- : ["find", "glob"].includes(kind)
95
- ? ["pattern", "depth"]
96
- : []),
97
- ]);
98
- const result = {
99
- kind,
100
- pageSize: integer(args.pageSize ?? L.results, L.results),
101
- };
102
- if (kind === "read") {
103
- if (
104
- args.files !== undefined &&
105
- ["path", "offset", "limit"].some((key) => args[key] !== undefined)
106
- )
107
- throw new Error("Select either one file or a file batch");
108
- const offset = integer(args.offset ?? 1);
109
- const end =
110
- args.limit === undefined
111
- ? Number.MAX_SAFE_INTEGER
112
- : integer(offset + integer(args.limit) - 1);
113
- const files =
114
- args.files === undefined
115
- ? [{ path: string(args.path), ranges: [{ start: offset, end }] }]
116
- : array(args.files, L.files);
117
- let count = 0;
118
- result.files = files.map((entry) => {
119
- object(entry, ["path", "ranges"]);
120
- const ranges = entry.ranges ?? [
121
- { start: 1, end: Number.MAX_SAFE_INTEGER },
122
- ];
123
- return {
124
- path: string(entry.path),
125
- ranges: array(ranges, L.ranges).map((range) => {
126
- object(range, ["start", "end"]);
127
- if (++count > L.ranges)
128
- throw new Error("Too many requested line ranges");
129
- const start = integer(range.start);
130
- return {
131
- start,
132
- end: integer(range.end, Number.MAX_SAFE_INTEGER, start),
133
- };
134
- }),
135
- };
136
- });
137
- } else {
138
- result.path = args.path === undefined ? undefined : string(args.path);
139
- result.depth = integer(args.depth ?? L.depth, Number.MAX_SAFE_INTEGER, 0);
140
- if (["find", "glob"].includes(kind)) result.glob = glob(args.pattern);
141
- if (kind === "grep") {
142
- if (args.literal !== undefined && typeof args.literal !== "boolean")
143
- throw new Error("Invalid literal selection");
144
- result.literal = args.literal === true;
145
- if (args.ignoreCase !== undefined && typeof args.ignoreCase !== "boolean")
146
- throw new Error("Invalid case selection");
147
- if ((args.pattern === undefined) === (args.patterns === undefined))
148
- throw new Error("Supply one pattern or a patterns array");
149
- result.ignoreCase = args.ignoreCase === true;
150
- result.patterns = array(args.patterns ?? [args.pattern], L.patterns).map(
151
- (pattern) => {
152
- const text = string(pattern, 256);
153
- return result.literal && result.ignoreCase
154
- ? text.toLowerCase()
155
- : text;
15
+ export function createResearchTools(workspace) {
16
+ const cwd = workspace.roots[0];
17
+ const definitions = [
18
+ createReadToolDefinition(cwd, {
19
+ operations: {
20
+ readFile,
21
+ detectImageMimeType: detectSupportedImageMimeTypeFromFile,
22
+ async access(path) {
23
+ // Pi resolves paths first. Follow regular-file aliases, but never
24
+ // intentionally open a device, socket, pipe or directory for reading.
25
+ if (!(await stat(path)).isFile())
26
+ throw new Error("Only regular files can be read");
156
27
  },
157
- );
158
- if (!result.literal) {
159
- try {
160
- result.regex = result.patterns.map(
161
- (pattern) => new RegExp(pattern, result.ignoreCase ? "iu" : "u"),
162
- );
163
- } catch {
164
- throw new Error(
165
- "Invalid regular expression; use literal:true for exact text",
166
- );
167
- }
168
- }
169
- if (args.glob !== undefined) result.glob = glob(args.glob);
170
- }
171
- }
172
- return result;
173
- }
174
-
175
- const path = Type.Optional(
176
- Type.String({
177
- minLength: 1,
178
- maxLength: 4096,
179
- description:
180
- "An explicit host path, including outside the checkout. Relative paths use the first search root; ~ uses this account's home.",
181
- }),
182
- );
183
- const pageSize = Type.Optional(
184
- Type.Integer({ minimum: 1, maximum: L.results }),
185
- );
186
- const depth = Type.Optional(
187
- Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
188
- );
189
- const pattern = Type.String({ minLength: 1, maxLength: 256 });
190
- // Provider function schemas require an object root, not a union of objects.
191
- // Initial-query versus continuation exclusivity is checked before admission;
192
- // every field is optional here because a continuation carries no query fields.
193
- const parameters = (shape) =>
194
- Type.Partial(
195
- Type.Object({
196
- ...shape,
197
- cursor: Type.String({ minLength: 1, maxLength: 128 }),
198
- close: Type.Literal(true),
199
- }),
200
- { additionalProperties: false },
201
- );
202
- const definitions = [
203
- {
204
- name: "read",
205
- description:
206
- "Read UTF-8 text or a batch of file/line ranges. Use path with optional 1-based offset/limit, or files with ranges {start,end}. Overlapping ranges are merged. pageSize bounds one response, not the requested range. Resume a returned cursor instead of rereading a prefix; {cursor,close:true} releases it. Long/binary/invalid text omissions are explicit.",
207
- parameters: parameters({
208
- path,
209
- offset: Type.Optional(Type.Integer({ minimum: 1 })),
210
- limit: Type.Optional(Type.Integer({ minimum: 1 })),
211
- files: Type.Optional(
212
- Type.Array(
213
- Type.Object(
214
- {
215
- path: Type.String(),
216
- ranges: Type.Optional(
217
- Type.Array(
218
- Type.Object({
219
- start: Type.Integer({ minimum: 1 }),
220
- end: Type.Integer({ minimum: 1 }),
221
- }),
222
- { minItems: 1, maxItems: L.ranges },
223
- ),
224
- ),
225
- },
226
- { additionalProperties: false },
227
- ),
228
- { minItems: 1, maxItems: L.files },
229
- ),
230
- ),
231
- pageSize,
232
- }),
233
- },
234
- {
235
- name: "grep",
236
- description:
237
- "Search regular expressions in one file or a tree; literal:true selects exact text. Supply pattern or patterns (OR; matchedPatterns are zero-based input indexes). Each matching logical path is scanned without replaying its consumed prefix. Optional glob, ignoreCase and depth. Explicit host paths, dependencies and symlinks are supported; .git is skipped during tree traversal, and .gitignore is not interpreted. Empty pages with a cursor are progress, NOT absence. Resume with {cursor}, or release with {cursor,close:true}.",
238
- parameters: parameters({
239
- path,
240
- pattern: Type.Optional(pattern),
241
- patterns: Type.Optional(
242
- Type.Array(pattern, { minItems: 1, maxItems: L.patterns }),
243
- ),
244
- glob: Type.Optional(pattern),
245
- literal: Type.Optional(Type.Boolean()),
246
- ignoreCase: Type.Optional(Type.Boolean()),
247
- depth,
248
- pageSize,
28
+ },
249
29
  }),
250
- },
251
- ...["find", "glob"].map((name) => ({
252
- name,
253
- description:
254
- "Find file paths by glob (*, **, ?, brackets, brace alternatives and extglobs). Explicit host paths, dependencies and symlinks are supported. Traversal defaults to depth 8; set depth explicitly for deeper trees. Symlink cycles and .git traversal are omitted visibly; .gitignore is not interpreted. Resume with this tool's {cursor}; {cursor,close:true} releases it. Coverage/omissions are explicit.",
255
- parameters: parameters({ path, pattern, depth, pageSize }),
256
- })),
257
- {
258
- name: "ls",
259
- description:
260
- "List one directory in filesystem order, including entry kinds. Does not follow symlinks or recurse. Continue with the returned {cursor}, not a repeated initial request; {cursor,close:true} releases it.",
261
- parameters: parameters({ path, pageSize }),
262
- },
263
- ];
264
-
265
- function render(scan, items, state, nextCursor, pausedBy, elapsedMs) {
266
- const omissions = [...scan.omissions].map(([reason, count]) => ({
267
- reason,
268
- count,
269
- }));
270
- const details = {
271
- state,
272
- nextCursor,
273
- pausedBy,
274
- coverage: {
275
- complete: state === "done" && !omissions.length,
276
- consistency: "live-filesystem",
277
- omissions,
278
- },
279
- progress: { ...scan.page, total: { ...scan.total } },
280
- elapsedMs,
281
- ...(state === "more" || omissions.length
282
- ? {
283
- truncation: {
284
- reason: [
285
- ...(pausedBy ? [pausedBy] : []),
286
- ...omissions.map((o) => o.reason),
287
- ],
288
- },
289
- }
290
- : {}),
291
- };
292
- return {
293
- content: [{ type: "text", text: JSON.stringify({ items, ...details }) }],
294
- details,
295
- };
296
- }
297
- const size = (result) => Buffer.byteLength(JSON.stringify(result));
298
-
299
- export function createResearchTools(workspace, now = () => performance.now()) {
300
- const scans = new Set();
301
- const cursors = new Map();
302
- let closing = false,
303
- closingOriginal,
304
- failure;
305
- const finish = (scan) => {
306
- scan.finishing ??= (async () => {
307
- try {
308
- await scan.close();
309
- scans.delete(scan);
310
- } catch {
311
- failure = new Error("Investigation resource closure failed");
312
- throw failure;
313
- }
314
- })();
315
- return scan.finishing;
316
- };
317
- const stop = async (scan) => {
318
- scan.stopping = true;
319
- await scan.active?.catch(() => {});
320
- await finish(scan);
321
- };
322
- const execute = (kind, args, signal) => {
323
- if (closing || failure)
324
- return Promise.reject(failure ?? new Error("Investigation tools closed"));
325
- if (signal?.aborted)
326
- return Promise.reject(new Error("Investigation canceled"));
327
- let scan,
328
- close = false;
329
- try {
330
- if (args?.cursor !== undefined) {
331
- object(args, ["cursor", "close"]);
332
- if (args.close !== undefined && args.close !== true)
333
- throw new Error("Invalid cursor operation");
334
- const token = string(args.cursor, 128);
335
- scan = cursors.get(token);
336
- if (scan && scan.query.kind === kind && now() >= scan.expiresAt) {
337
- cursors.delete(token);
338
- clearTimeout(scan.timer);
339
- void stop(scan).catch(() => {
340
- /* finish retains the closure failure. */
341
- });
342
- throw new Error(
343
- "Investigation cursor expired; start a fresh query explicitly",
344
- );
345
- }
346
- if (!scan || scan.query.kind !== kind)
347
- throw new Error(
348
- "Investigation cursor consumed or foreign; start a fresh query explicitly",
349
- );
350
- cursors.delete(token);
351
- clearTimeout(scan.timer);
352
- close = args.close === true;
353
- } else {
354
- const request = query(kind, args);
355
- if (scans.size >= L.scans)
356
- throw new Error(
357
- "Investigation cursor capacity reached; close an unused cursor",
358
- );
359
- scan = new ResearchScan(workspace, request);
360
- scans.add(scan); // Reserve before the first asynchronous filesystem operation.
361
- }
362
- } catch (error) {
363
- return Promise.reject(error);
364
- }
365
- const original = (async () => {
366
- const startedAt = now();
367
- scan.begin(signal);
368
- const items = [];
369
- const token = randomUUID();
370
- let done = false,
371
- pausedBy = null;
372
- try {
373
- if (close) {
374
- await finish(scan);
375
- return render(
376
- scan,
377
- [],
378
- "closed",
379
- null,
380
- null,
381
- Math.max(0, now() - startedAt),
382
- );
383
- }
384
- await scan.validate();
385
- for (;;) {
386
- scan.check();
387
- if (now() - startedAt >= L.toolMs) {
388
- pausedBy = "cooperative time quantum";
389
- break;
390
- }
391
- const next = scan.pending ?? (await scan.iterator.next());
392
- scan.pending = undefined;
393
- scan.check();
394
- if (next.done) {
395
- done = true;
396
- break;
397
- }
398
- if (!next.value) continue;
399
- if (next.value.pause) {
400
- pausedBy = next.value.pause;
401
- break;
402
- }
403
- const item = next.value.item;
404
- const candidate = render(
405
- scan,
406
- [...items, item],
407
- "more",
408
- token,
409
- "output quantum",
410
- 0,
411
- );
412
- // Reserve bounded metadata growth (counters/omissions/elapsed) while
413
- // charging the entire encoded envelope, not just unescaped line text.
414
- if (size(candidate) > L.outputBytes - 4096) {
415
- if (!items.length) {
416
- scan.omit("oversized result omitted");
417
- continue;
418
- }
419
- scan.pending = next;
420
- pausedBy = "output quantum";
421
- break;
422
- }
423
- if (items.length >= scan.query.pageSize) {
424
- scan.pending = next;
425
- pausedBy = "result quantum";
426
- break;
427
- }
428
- items.push(item);
429
- }
430
- await scan.validate();
431
- scan.check();
432
- if (done) await finish(scan);
433
- const result = render(
434
- scan,
435
- items,
436
- done ? "done" : "more",
437
- done ? null : token,
438
- pausedBy,
439
- Math.max(0, now() - startedAt),
440
- );
441
- if (size(result) > L.outputBytes)
442
- throw new Error("Investigation reply exceeds bound");
443
- if (!done) {
444
- scan.expiresAt = now() + L.idleMs;
445
- cursors.set(token, scan);
446
- scan.timer = setTimeout(() => {
447
- cursors.delete(token);
448
- void stop(scan).catch(() => {
449
- /* finish retains the failure and reservation. */
450
- });
451
- }, L.idleMs);
452
- scan.timer.unref();
453
- }
454
- return result;
455
- } catch (error) {
456
- await finish(scan);
457
- throw error;
458
- }
459
- })();
460
- scan.active = original;
461
- // Return the tracked original. No detached rejecting finally promise.
462
- return original.finally(() => {
463
- if (scan.active === original) scan.active = undefined;
464
- });
465
- };
30
+ createGrepToolDefinition(cwd),
31
+ createFindToolDefinition(cwd),
32
+ createLsToolDefinition(cwd),
33
+ ];
466
34
  return {
467
35
  tools: definitions.map((tool) => ({
468
36
  ...tool,
469
- label: tool.name,
470
- execute: (_id, args, signal) => execute(tool.name, args, signal),
471
- })),
472
- close() {
473
- if (closingOriginal) return closingOriginal;
474
- closing = true;
475
- for (const scan of cursors.values()) clearTimeout(scan.timer);
476
- cursors.clear();
477
- closingOriginal = (async () => {
478
- const outcomes = await Promise.allSettled([...scans].map(stop));
37
+ async execute(id, args, signal, update, context) {
38
+ if (signal?.aborted) throw new Error("Investigation canceled");
39
+ // The worker already enforces offline mode before creating its session.
40
+ // Keep direct uses equally noninstalling without changing ambient env.
479
41
  if (
480
- failure ||
481
- outcomes.some((outcome) => outcome.status === "rejected")
42
+ ["grep", "find"].includes(tool.name) &&
43
+ process.env.PI_OFFLINE !== "1"
482
44
  )
483
- throw failure ?? new Error("Investigation resource closure failed");
484
- })();
485
- return closingOriginal;
486
- },
45
+ throw new Error(
46
+ "Readonly search requires PI_OFFLINE=1; no tools were downloaded",
47
+ );
48
+ const selected = { ...context, cwd };
49
+ // Original-operation accounting and cancellation belong to the toolkit,
50
+ // just as they do for the standard file tools of an editing worker.
51
+ return tool.execute(id, args, signal, update, selected);
52
+ },
53
+ })),
487
54
  };
488
55
  }
@@ -688,7 +688,7 @@ try {
688
688
  publicRequest.context,
689
689
  ...(!conversation && kind !== "code"
690
690
  ? [
691
- `Investigation roots: ${JSON.stringify(workspace.roots)}. Start at these specific paths, not / or their parents. Observation tools support file/range batches, literal multi-pattern searches and one-use continuation cursors; no shell is available. Read their schemas. Continue a cursor to advance actual I/O, including empty progress pages; do not repeat the initial query to paginate. Close unused cursors. Source-changed/expired cursors require an explicit fresh query, never an assumed continuation. Coverage names omissions and live-filesystem observation, not a snapshot. Search filenames and shallow directories before content; do not silently exclude backup trees. Total worker deadline: ${investigation?.timeoutMs ?? LIMITS.workerMs}ms, including model and tool time; activity never extends it. There is no cumulative tool-call quota or early tool cutoff. Use nextCursor when available; for terminal omissions, narrow the scope as needed. Never claim exhaustive absence from a progress page or incomplete coverage. Report retained evidence and unresolved questions honestly.`,
691
+ `Investigation roots: ${JSON.stringify(workspace.roots)}. Relative file-tool paths use the first root; select other roots explicitly. Start with these paths rather than broad parent trees. Total worker deadline: ${investigation?.timeoutMs ?? LIMITS.workerMs}ms, including model and tool time; activity never extends it. Report observed evidence, truncation and unresolved questions honestly.`,
692
692
  ]
693
693
  : []),
694
694
  ...publicRequest.handoff.inputs.map(
@@ -31066,8 +31066,8 @@ function workflowResultDetail(value, secrets) {
31066
31066
 
31067
31067
  // src/service/workflows.ts
31068
31068
  var OWNER_RUNTIME = Object.freeze({
31069
- version: "2.0.40",
31070
- build: "d855120ead3c2b3ebdfb42215818a8a1e42a76007134a38fefb233cfa97645a3",
31069
+ version: "2.0.41",
31070
+ build: "4da1375d7184585ffb2ed6499f1b81ec3b0f8498dc04dfb182f8104e0596e6dc",
31071
31071
  entry: fileURLToPath6(import.meta.url),
31072
31072
  pid: process.pid,
31073
31073
  node: process.versions.node,
@@ -123,10 +123,31 @@ export function createWorkerToolkit(options) {
123
123
  ...tool,
124
124
  execute: (...args) => {
125
125
  if (closed) return Promise.reject(new Error("Worker tools closed"));
126
- const original = Promise.resolve().then(() => {
126
+ const original = Promise.resolve().then(async () => {
127
127
  if (closed) throw new Error("Worker tools closed");
128
- if (args[2]?.aborted) throw new Error("Worker tool canceled");
129
- return tool.execute(...args);
128
+ const signal = args[2];
129
+ if (signal?.aborted) throw new Error("Worker tool canceled");
130
+ const fileTool = [
131
+ "read",
132
+ "grep",
133
+ "find",
134
+ "ls",
135
+ "write",
136
+ "edit",
137
+ ].includes(tool.name);
138
+ // Stock file tools may reject an abort observer before their real
139
+ // I/O finishes. Join this admitted call under the worker deadline,
140
+ // then suppress its result if canceled. Pi grep already waits for
141
+ // child close on abort, so preserve its stop signal like shell and
142
+ // changes; no mutation is replayed.
143
+ const forwarded = [...args];
144
+ if (fileTool && tool.name !== "grep") forwarded[2] = undefined;
145
+ const result = await tool.execute(...forwarded);
146
+ if (fileTool && signal?.aborted)
147
+ throw new Error(
148
+ "Worker tool canceled; its original operation settled and may have completed",
149
+ );
150
+ return result;
130
151
  });
131
152
  const tracked = original.finally(() => originals.delete(tracked));
132
153
  originals.add(tracked);