pi-dent-agent 0.2.3 → 0.2.5

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 (55) hide show
  1. package/index.ts +5 -1
  2. package/lib/config.ts +59 -0
  3. package/lib/engine.ts +6 -1
  4. package/lib/script-render.ts +1 -1
  5. package/lib/script-runner.ts +82 -4
  6. package/lib/script-tool-calls.ts +116 -0
  7. package/lib/script-tool-log.ts +143 -0
  8. package/lib/script-tool-types.ts +258 -0
  9. package/lib/script-tool.ts +103 -9
  10. package/lib/script-worker.ts +92 -1
  11. package/lib/search-tool.ts +1 -1
  12. package/lib/tools.ts +13 -5
  13. package/node_modules/express-rate-limit/dist/index.cjs +6 -4
  14. package/node_modules/express-rate-limit/dist/index.mjs +6 -4
  15. package/node_modules/express-rate-limit/package.json +1 -1
  16. package/node_modules/jose/dist/webapi/jwks/remote.js +2 -2
  17. package/node_modules/jose/dist/webapi/jwt/encrypt.js +5 -8
  18. package/node_modules/jose/dist/webapi/lib/jwe_decrypt.js +1 -1
  19. package/node_modules/jose/dist/webapi/lib/jwe_encrypt.js +2 -2
  20. package/node_modules/jose/dist/webapi/lib/jwt_claims_set.js +1 -1
  21. package/node_modules/jose/dist/webapi/lib/key.js +2 -0
  22. package/node_modules/jose/package.json +1 -1
  23. package/node_modules/object-inspect/CHANGELOG.md +31 -0
  24. package/node_modules/object-inspect/index.js +326 -24
  25. package/node_modules/object-inspect/package.json +22 -13
  26. package/node_modules/object-inspect/readme.markdown +4 -1
  27. package/node_modules/object-inspect/stringWidth.js +68 -0
  28. package/node_modules/object-inspect/stringWidthRanges.js +38 -0
  29. package/package.json +1 -1
  30. package/node_modules/object-inspect/.eslintrc +0 -53
  31. package/node_modules/object-inspect/.nycrc +0 -13
  32. package/node_modules/object-inspect/example/all.js +0 -23
  33. package/node_modules/object-inspect/example/circular.js +0 -6
  34. package/node_modules/object-inspect/example/fn.js +0 -5
  35. package/node_modules/object-inspect/example/inspect.js +0 -10
  36. package/node_modules/object-inspect/test/bigint.js +0 -58
  37. package/node_modules/object-inspect/test/browser/dom.js +0 -15
  38. package/node_modules/object-inspect/test/circular.js +0 -16
  39. package/node_modules/object-inspect/test/deep.js +0 -12
  40. package/node_modules/object-inspect/test/element.js +0 -53
  41. package/node_modules/object-inspect/test/err.js +0 -48
  42. package/node_modules/object-inspect/test/fakes.js +0 -29
  43. package/node_modules/object-inspect/test/fn.js +0 -76
  44. package/node_modules/object-inspect/test/global.js +0 -17
  45. package/node_modules/object-inspect/test/has.js +0 -15
  46. package/node_modules/object-inspect/test/holes.js +0 -15
  47. package/node_modules/object-inspect/test/indent-option.js +0 -271
  48. package/node_modules/object-inspect/test/inspect.js +0 -139
  49. package/node_modules/object-inspect/test/lowbyte.js +0 -12
  50. package/node_modules/object-inspect/test/number.js +0 -58
  51. package/node_modules/object-inspect/test/quoteStyle.js +0 -26
  52. package/node_modules/object-inspect/test/toStringTag.js +0 -40
  53. package/node_modules/object-inspect/test/undef.js +0 -12
  54. package/node_modules/object-inspect/test/values.js +0 -261
  55. package/node_modules/object-inspect/test-core-js.js +0 -26
@@ -0,0 +1,258 @@
1
+ /**
2
+ * The tool functions' pure side (specs/script-tool.md Sections 10.1 and 10.2): which callable
3
+ * tools a call binds, and the TypeScript declarations of the bound tools.
4
+ */
5
+
6
+ /** A callable tool as the host lists it (AgentTool's fields the tool functions read). */
7
+ export interface CallableTool {
8
+ name: string;
9
+ description?: string | undefined;
10
+ parameters: unknown;
11
+ outputSchema?: unknown;
12
+ }
13
+
14
+ export interface ToolSelection<T extends CallableTool> {
15
+ /** Bound tools, in ascending order of name. */
16
+ bound: T[];
17
+ /** Unbindable tools that are not `Script` and match the allow list, in ascending order of name. */
18
+ unbound: T[];
19
+ }
20
+
21
+ /** Default of `script.tools.allow` (Section 8). */
22
+ export const DEFAULT_TOOLS_ALLOW: readonly string[] = ["*"];
23
+
24
+ /** Whether an allow entry admits `name` (Section 10.1): equal, or a `*`-terminated prefix. */
25
+ export function allowMatches(allow: readonly string[], name: string): boolean {
26
+ return allow.some((entry) =>
27
+ entry.endsWith("*") ? name.startsWith(entry.slice(0, -1)) : entry === name,
28
+ );
29
+ }
30
+
31
+ function isObject(value: unknown): value is Record<string, unknown> {
32
+ return typeof value === "object" && value !== null && !Array.isArray(value);
33
+ }
34
+
35
+ /** Whether a tool's `parameters` is an object schema (Section 10.1). */
36
+ function isBindable(tool: CallableTool): boolean {
37
+ return isObject(tool.parameters) && tool.parameters.type === "object";
38
+ }
39
+
40
+ const byName = (a: CallableTool, b: CallableTool): number =>
41
+ a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
42
+
43
+ /** The bound and unbound tools of one reading of the callable tools (Section 10.1). */
44
+ export function selectTools<T extends CallableTool>(
45
+ callable: readonly T[],
46
+ allow: readonly string[],
47
+ ): ToolSelection<T> {
48
+ const bound: T[] = [];
49
+ const unbound: T[] = [];
50
+ for (const tool of callable) {
51
+ if (tool.name === "Script" || !allowMatches(allow, tool.name)) continue;
52
+ (isBindable(tool) ? bound : unbound).push(tool);
53
+ }
54
+ return { bound: bound.toSorted(byName), unbound: unbound.toSorted(byName) };
55
+ }
56
+
57
+ /** A type text and whether it is a union or an intersection at its top level. */
58
+ interface Typed {
59
+ text: string;
60
+ kind: "union" | "intersection" | "atom";
61
+ }
62
+
63
+ const atom = (text: string): Typed => ({ text, kind: "atom" });
64
+
65
+ const UNSUPPORTED_KEYWORDS = [
66
+ "not",
67
+ "if",
68
+ "prefixItems",
69
+ "patternProperties",
70
+ "propertyNames",
71
+ "dependentSchemas",
72
+ "contains",
73
+ "unevaluatedProperties",
74
+ "unevaluatedItems",
75
+ ];
76
+
77
+ const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
78
+
79
+ /** A member or property key (Section 10.2). */
80
+ function keyText(name: string): string {
81
+ return IDENTIFIER.test(name) ? name : JSON.stringify(name);
82
+ }
83
+
84
+ function literal(value: unknown): string {
85
+ return value === null ||
86
+ typeof value === "boolean" ||
87
+ typeof value === "number" ||
88
+ typeof value === "string"
89
+ ? JSON.stringify(value)
90
+ : "Json";
91
+ }
92
+
93
+ /** A union of member texts: duplicates dropped, intersections parenthesized; `never` when empty. */
94
+ function union(members: readonly Typed[]): Typed {
95
+ const kept: Typed[] = [];
96
+ for (const member of members) {
97
+ if (!kept.some((k) => k.text === member.text)) kept.push(member);
98
+ }
99
+ const [only] = kept;
100
+ if (only === undefined) return atom("never");
101
+ if (kept.length === 1) return only;
102
+ const texts = kept.map((m) => (m.kind === "intersection" ? `(${m.text})` : m.text));
103
+ return { text: texts.join(" | "), kind: "union" };
104
+ }
105
+
106
+ function unsupportedSuffix(schema: Record<string, unknown>): string {
107
+ const found = UNSUPPORTED_KEYWORDS.filter((key) => Object.hasOwn(schema, key));
108
+ if (
109
+ isObject(schema.properties) &&
110
+ Object.hasOwn(schema, "additionalProperties") &&
111
+ schema.additionalProperties !== false
112
+ ) {
113
+ found.push("additionalProperties");
114
+ }
115
+ return found.length === 0 ? "" : ` /* unsupported: ${found.join(", ")} */`;
116
+ }
117
+
118
+ const REF = /^#\/(\$defs|definitions)\/(.+)$/;
119
+
120
+ interface TypingContext {
121
+ root: unknown;
122
+ /** Named schemas being typed, against `$ref` cycles. */
123
+ typing: Set<unknown>;
124
+ }
125
+
126
+ function refTarget(ref: unknown, ctx: TypingContext): unknown {
127
+ if (typeof ref !== "string") return undefined;
128
+ const match = REF.exec(ref);
129
+ if (match === null || !isObject(ctx.root)) return undefined;
130
+ const [, section = "", name = ""] = match;
131
+ const defs = ctx.root[section];
132
+ if (!isObject(defs) || !Object.hasOwn(defs, name)) return undefined;
133
+ const target = defs[name];
134
+ return ctx.typing.has(target) ? undefined : target;
135
+ }
136
+
137
+ function arrayOf(schema: Record<string, unknown>, key: string): unknown[] | undefined {
138
+ const value = schema[key];
139
+ return Array.isArray(value) ? value : undefined;
140
+ }
141
+
142
+ /** The type text of a schema without its unsupported-keyword suffix. */
143
+ function baseType(schema: Record<string, unknown>, ctx: TypingContext): Typed {
144
+ if (Object.hasOwn(schema, "$ref")) {
145
+ const target = refTarget(schema.$ref, ctx);
146
+ if (target === undefined) return atom("Json /* unsupported: $ref */");
147
+ ctx.typing.add(target);
148
+ try {
149
+ return typeOf(target, ctx);
150
+ } finally {
151
+ ctx.typing.delete(target);
152
+ }
153
+ }
154
+ if (Object.hasOwn(schema, "const")) return atom(literal(schema.const));
155
+ if (Object.hasOwn(schema, "enum")) {
156
+ return union((arrayOf(schema, "enum") ?? []).map((value) => atom(literal(value))));
157
+ }
158
+ const anyOf = Object.hasOwn(schema, "anyOf") ? "anyOf" : "oneOf";
159
+ if (Object.hasOwn(schema, anyOf)) {
160
+ return union((arrayOf(schema, anyOf) ?? []).map((member) => typeOf(member, ctx)));
161
+ }
162
+ if (Object.hasOwn(schema, "allOf")) {
163
+ const members = (arrayOf(schema, "allOf") ?? []).map((member) => typeOf(member, ctx));
164
+ const [only] = members;
165
+ if (only === undefined) return atom("Json");
166
+ if (members.length === 1) return only;
167
+ const texts = members.map((m) => (m.kind === "union" ? `(${m.text})` : m.text));
168
+ return { text: texts.join(" & "), kind: "intersection" };
169
+ }
170
+ const type = schema.type;
171
+ if (Array.isArray(type)) {
172
+ // Each member is typed without the suffix, which the whole union carries once.
173
+ return union(type.map((entry) => baseType({ ...schema, type: entry }, ctx)));
174
+ }
175
+ if (type === "string" || type === "boolean" || type === "null") return atom(type);
176
+ if (type === "number" || type === "integer") return atom("number");
177
+ if (type === "array") {
178
+ if (!Object.hasOwn(schema, "items")) return atom("Json[]");
179
+ const items = typeOf(schema.items, ctx);
180
+ return atom(items.kind === "atom" ? `${items.text}[]` : `(${items.text})[]`);
181
+ }
182
+ if (type === "object") {
183
+ const properties = schema.properties;
184
+ if (isObject(properties)) {
185
+ const names = Object.keys(properties);
186
+ if (names.length === 0) return atom("{}");
187
+ const required = arrayOf(schema, "required") ?? [];
188
+ const members = names.map(
189
+ (name) =>
190
+ `${keyText(name)}${required.includes(name) ? "" : "?"}: ${typeOf(properties[name], ctx).text}`,
191
+ );
192
+ return atom(`{ ${members.join("; ")} }`);
193
+ }
194
+ const additional = schema.additionalProperties;
195
+ const value =
196
+ additional === false
197
+ ? "never"
198
+ : additional === undefined
199
+ ? "Json"
200
+ : typeOf(additional, ctx).text;
201
+ return atom(`{ [key: string]: ${value} }`);
202
+ }
203
+ return atom("Json");
204
+ }
205
+
206
+ function typeOf(schema: unknown, ctx: TypingContext): Typed {
207
+ if (schema === false) return atom("never");
208
+ if (!isObject(schema)) return atom("Json");
209
+ const base = baseType(schema, ctx);
210
+ return { text: base.text + unsupportedSuffix(schema), kind: base.kind };
211
+ }
212
+
213
+ /** The type text of a root schema: a tool's `parameters` or `outputSchema` (Section 10.2). */
214
+ export function schemaTypeText(schema: unknown): string {
215
+ return typeOf(schema, { root: schema, typing: new Set() }).text;
216
+ }
217
+
218
+ /** A tool's doc text (Section 10.2): first line, trimmed, `*\/` defused, 200 characters. */
219
+ function docText(description: string | undefined): string {
220
+ const first = (description ?? "").split(/\r\n|\r|\n/, 1)[0] ?? "";
221
+ return first.trim().replaceAll("*/", "* /").slice(0, 200);
222
+ }
223
+
224
+ const PREAMBLE = [
225
+ "type Json = null | boolean | number | string | Json[] | { [key: string]: Json };",
226
+ "type ToolContent =",
227
+ ' | { readonly type: "text"; readonly text: string }',
228
+ ' | { readonly type: "image"; readonly data: string; readonly mimeType: string }',
229
+ ' | { readonly type: "other"; readonly kind: string };',
230
+ "type ToolResult<S = undefined> = {",
231
+ " readonly text: string;",
232
+ " readonly content: readonly ToolContent[];",
233
+ " readonly details: Json | undefined;",
234
+ " readonly structured: S;",
235
+ "};",
236
+ "declare const tools: {",
237
+ ];
238
+
239
+ /** The tool declarations of a selection (Section 10.2). */
240
+ export function toolDeclarations(selection: ToolSelection<CallableTool>): string {
241
+ const lines = [...PREAMBLE];
242
+ for (const tool of selection.bound) {
243
+ const doc = docText(tool.description);
244
+ if (doc !== "") lines.push(` /** ${doc} */`);
245
+ const result =
246
+ tool.outputSchema === undefined
247
+ ? "ToolResult"
248
+ : `ToolResult<${schemaTypeText(tool.outputSchema)}>`;
249
+ lines.push(
250
+ ` readonly ${keyText(tool.name)}: (args: ${schemaTypeText(tool.parameters)}) => Promise<${result}>;`,
251
+ );
252
+ }
253
+ lines.push("};");
254
+ for (const tool of selection.unbound) {
255
+ lines.push(`// not bound: ${tool.name}: parameters is not an object schema`);
256
+ }
257
+ return `${lines.join("\n")}\n`;
258
+ }
@@ -1,7 +1,7 @@
1
1
  import { appendFileSync, readFileSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
  import { Type, type Static } from "typebox";
4
- import { defineTool } from "@earendil-works/pi-coding-agent";
4
+ import { defineTool, type ExtensionToolContext } from "@earendil-works/pi-coding-agent";
5
5
  import type { BootSnapshot, ToolResult } from "./engine.ts";
6
6
  import type { HostSession } from "./host.ts";
7
7
  import type { ScriptTaskRow, TaskRegistry } from "./registry.ts";
@@ -9,7 +9,10 @@ import { bundledAliases } from "./bundled.ts";
9
9
  import { resolveCwdParam } from "./cwd-param.ts";
10
10
  import { ensureOutputDir, outputPathsFor } from "./output-file.ts";
11
11
  import { resolvePluginScriptPath } from "./plugins.ts";
12
- import { runScript, type ScriptRunResult } from "./script-runner.ts";
12
+ import { runScript, type ScriptRunHandle, type ScriptRunResult } from "./script-runner.ts";
13
+ import { callBoundTool } from "./script-tool-calls.ts";
14
+ import { ScriptToolLog } from "./script-tool-log.ts";
15
+ import { DEFAULT_TOOLS_ALLOW, selectTools, toolDeclarations } from "./script-tool-types.ts";
13
16
  import { type ReturnValueRender } from "./script-render.ts";
14
17
  import { renderCardCall } from "./tool-card.ts";
15
18
  import {
@@ -25,7 +28,8 @@ import { errorCode, errorMessage } from "./util.ts";
25
28
  /**
26
29
  * The Script tool (specs/script-tool.md): in-process execution of agent-authored
27
30
  * JavaScript or TypeScript, its sources, inputs, results, timeout, and delivery
28
- * modes. Pure compute — no host bridge (Section 7).
31
+ * modes, and the tool functions through which a script calls the session's other tools
32
+ * (Section 10).
29
33
  */
30
34
 
31
35
  export const scriptParameterSchema = Type.Object(
@@ -107,6 +111,8 @@ interface ScriptToolDeps {
107
111
  agentDir: (host: HostSession) => string;
108
112
  /** Extra environment variables for the script worker, merged over process.env (never mutating it). */
109
113
  extraEnv?: () => Record<string, string> | undefined;
114
+ /** `script.tools.allow` (Section 8); absent gives the default. */
115
+ toolsAllow?: () => readonly string[];
110
116
  }
111
117
 
112
118
  interface ResolvedSource {
@@ -204,6 +210,8 @@ function buildBody(opts: {
204
210
  returnJson?: string | undefined;
205
211
  /** The output file path, when the body names the full return value (Section 5). */
206
212
  fullValuePath?: string | undefined;
213
+ /** The `--- tool calls` block's line, when the run made nested calls (Section 6). */
214
+ toolCallsLine?: string | undefined;
207
215
  }): string {
208
216
  let text = opts.stdout;
209
217
  if (opts.stderr !== "") text += `\n--- stderr ---\n${opts.stderr}`;
@@ -213,6 +221,7 @@ function buildBody(opts: {
213
221
  text += `\n--- exited ${opts.exitReason}${opts.exitCode === undefined ? "" : ` code=${opts.exitCode}`} in ${opts.durationMs}ms ---`;
214
222
  // A browser kill names its author in the body the model reads (Section 5).
215
223
  if (opts.browserKill === true) text += "\n--- killed by the user from the task browser ---";
224
+ if (opts.toolCallsLine !== undefined) text += `\n${opts.toolCallsLine}`;
216
225
  if (opts.renderJson !== undefined) text += `\n--- return metadata ---\n${opts.renderJson}`;
217
226
  return text;
218
227
  }
@@ -248,6 +257,7 @@ function thrownText(error: { name: string; message: string; stack: string } | un
248
257
  function formatResult(
249
258
  result: ScriptRunResult,
250
259
  outputPath: string,
260
+ toolCalls: { count: number; logPath: string; createdLogPath: string | undefined; taskId: string },
251
261
  browserKill = false,
252
262
  ): {
253
263
  text: string;
@@ -283,6 +293,10 @@ function formatResult(
283
293
  const clipped =
284
294
  render !== undefined && (render.stringsOverLimit > 0 || render.aggregateTruncated);
285
295
  const returnJson = clipped ? result.json : undefined;
296
+ const toolCallsLine =
297
+ toolCalls.count === 0
298
+ ? undefined
299
+ : `--- tool calls: ${toolCalls.count}; log: ${toolCalls.logPath}; Search it with session ${toolCalls.taskId} ---`;
286
300
  const text = buildBody({
287
301
  stdout: result.stdout,
288
302
  stderr,
@@ -293,6 +307,7 @@ function formatResult(
293
307
  renderJson,
294
308
  browserKill,
295
309
  fullValuePath: returnJson === undefined ? undefined : outputPath,
310
+ toolCallsLine,
296
311
  });
297
312
  const details: Record<string, unknown> = {
298
313
  stdout: result.stdout,
@@ -300,7 +315,9 @@ function formatResult(
300
315
  exitReason: result.exitReason,
301
316
  truncated: result.truncated,
302
317
  durationMs: result.durationMs,
318
+ toolCalls: toolCalls.count,
303
319
  };
320
+ if (toolCalls.createdLogPath !== undefined) details.toolLogPath = toolCalls.createdLogPath;
304
321
  if (returnValue !== undefined) details.returnValue = returnValue;
305
322
  if (render !== undefined) details.returnValueRender = render;
306
323
  if (result.exitCode !== undefined) details.exitCode = result.exitCode;
@@ -314,6 +331,7 @@ function formatResult(
314
331
  renderJson,
315
332
  browserKill,
316
333
  returnJson,
334
+ toolCallsLine,
317
335
  });
318
336
  return { text, details, isError: isErrorExit(result.exitReason), suffix, thrown };
319
337
  }
@@ -323,13 +341,17 @@ export function makeScriptTool(deps: ScriptToolDeps) {
323
341
  name: "Script",
324
342
  label: "Script",
325
343
  description:
326
- "Run one JavaScript or TypeScript program in a fresh worker thread with the caller's privileges and full Node capabilities: ESM, TypeScript syntax, top-level await, no build step, no state kept between calls. Source: inline `code`, or a plugin script (`plugin` + `path`). Imports: node:* builtins and the bundled cheerio, csv-parse, csv-stringify, fast-xml-parser, file-type, glob, gray-matter, ini, js-yaml, jsonc-parser, jszip, semver, smol-toml; any other package resolves from `cwd`, or for a plugin script from its own location. fetch and the other web globals are available; console output is captured. Child processes: use async `spawn`, `exec`, or `execFile` with `await`; `spawnSync`, `execSync`, and `execFileSync` throw. Every settled run terminates every process it spawned, so start a process that must outlive the run with `Bash` `background: true`. No agent dispatch, skills, or MCP tools. `background: true` returns a task ID at once, with a completion notification.",
344
+ "Run one JavaScript or TypeScript program in a fresh worker thread with the caller's privileges and full Node capabilities: ESM, TypeScript syntax, top-level await, no build step, no state kept between calls. Source: inline `code`, or a plugin script (`plugin` + `path`). Imports: node:* builtins and the bundled cheerio, csv-parse, csv-stringify, fast-xml-parser, file-type, glob, gray-matter, ini, js-yaml, jsonc-parser, jszip, semver, smol-toml; any other package resolves from `cwd`, or for a plugin script from its own location. fetch and the other web globals are available; console output is captured. Child processes: use async `spawn`, `exec`, or `execFile` with `await`; `spawnSync`, `execSync`, and `execFileSync` throw. Every settled run terminates every process it spawned, so start a process that must outlive the run with `Bash` `background: true`. `tools.<Name>(args)` calls another tool of the session, MCP tools included, and resolves to `{ text, content, details, structured }` or rejects with the tool's error; `dent.toolTypes()` returns their TypeScript declarations. Tool calls are logged to a session file that `Search` reads by the run's task ID. `background: true` returns a task ID at once, with a completion notification.",
327
345
  promptSnippet: "Run an in-process JavaScript or TypeScript program",
328
346
  parameters: scriptParameterSchema,
347
+ // Section 10.1: a call can reach every callable tool.
348
+ reachesTools: () => "all",
329
349
  async execute(
330
350
  toolCallId: string,
331
351
  params: ScriptToolParams,
332
352
  signal: AbortSignal | undefined,
353
+ _onUpdate: unknown,
354
+ ctx: ExtensionToolContext | undefined,
333
355
  ): Promise<ToolResult> {
334
356
  const registry = deps.registry();
335
357
  // Section 2: the source shape is checked before the row is registered,
@@ -403,6 +425,25 @@ export function makeScriptTool(deps: ScriptToolDeps) {
403
425
  const failRun = (error: unknown): ToolResult =>
404
426
  reject(`Script error: ${errorMessage(error)}`);
405
427
 
428
+ // Section 10.4: the tool log, created at the run's first nested call.
429
+ let runHandle: ScriptRunHandle | undefined;
430
+ const toolLog = new ScriptToolLog({
431
+ agentDir,
432
+ taskId: row.taskId,
433
+ cwd,
434
+ source: source.code,
435
+ runStart: () => runHandle?.startedAt() ?? Date.now(),
436
+ // Writes happen only while a nested call is open, and every open call is logged
437
+ // when the run settles, before its result is built: the line always lands.
438
+ reportFailure: (line) => void runHandle?.stderrLine(line),
439
+ });
440
+ const toolCallsOf = () => ({
441
+ count: toolLog.calls,
442
+ logPath: toolLog.path,
443
+ createdLogPath: toolLog.createdPath,
444
+ taskId: row.taskId,
445
+ });
446
+
406
447
  try {
407
448
  ensureOutputDir(agentDir);
408
449
  const request: Parameters<typeof runScript>[0] = {
@@ -414,6 +455,47 @@ export function makeScriptTool(deps: ScriptToolDeps) {
414
455
  };
415
456
  if (timeoutMs !== undefined) request.timeoutMs = timeoutMs;
416
457
  if (!background && signal !== undefined) request.signal = signal;
458
+ // Section 10.1: the callable tools are read once, after the checks of Section 2.
459
+ const selection = selectTools(ctx?.tools ?? [], deps.toolsAllow?.() ?? DEFAULT_TOOLS_ALLOW);
460
+ request.tools = {
461
+ names: selection.bound.map((tool) => tool.name),
462
+ declarations: toolDeclarations(selection),
463
+ call: async (name, args, callSignal) => {
464
+ const tool = selection.bound.find((candidate) => candidate.name === name);
465
+ if (tool === undefined || ctx === undefined)
466
+ throw new Error(`tool ${name} is not bound`);
467
+ const callId = toolLog.start(name, args);
468
+ // The run's settlement aborts the call: it is logged as aborted at that moment.
469
+ const onAbort = (): void => toolLog.abort(callId);
470
+ callSignal.addEventListener("abort", onAbort, { once: true });
471
+ try {
472
+ return await callBoundTool(
473
+ tool,
474
+ args,
475
+ async (toolName, toolArgs, options) => {
476
+ try {
477
+ const outcome = await ctx.executeTool(toolName, toolArgs, options);
478
+ toolLog.settle(callId, {
479
+ content: outcome.result.content,
480
+ details: outcome.result.details,
481
+ isError: outcome.isError,
482
+ });
483
+ return outcome;
484
+ } catch (error) {
485
+ toolLog.settle(callId, {
486
+ content: [{ type: "text", text: errorMessage(error) }],
487
+ isError: true,
488
+ });
489
+ throw error;
490
+ }
491
+ },
492
+ callSignal,
493
+ );
494
+ } finally {
495
+ callSignal.removeEventListener("abort", onAbort);
496
+ }
497
+ },
498
+ };
417
499
  const extra = deps.extraEnv?.();
418
500
  if (extra !== undefined && Object.keys(extra).length > 0) request.extraEnv = extra;
419
501
  // The run's chunks feed the row's progress projection line by line, in
@@ -444,9 +526,15 @@ export function makeScriptTool(deps: ScriptToolDeps) {
444
526
  if (thrown !== "") request.onOutput?.("stderr", thrown);
445
527
  flushProgress();
446
528
  };
447
- const handle = killedBeforeRun
448
- ? { promise: Promise.resolve(notRun), cancel: (): void => {} }
529
+ const handle: ScriptRunHandle = killedBeforeRun
530
+ ? {
531
+ promise: Promise.resolve(notRun),
532
+ cancel: (): void => {},
533
+ startedAt: (): undefined => {},
534
+ stderrLine: () => false,
535
+ }
449
536
  : runScript(request);
537
+ runHandle = handle;
450
538
 
451
539
  // Task-based cancellation (Section 6) applies to foreground rows too:
452
540
  // hard-terminating the worker settles the run with exitReason "killed".
@@ -454,7 +542,7 @@ export function makeScriptTool(deps: ScriptToolDeps) {
454
542
 
455
543
  if (!background) {
456
544
  const result = await handle.promise;
457
- const formatted = formatResult(result, outputPath, row.browserKill);
545
+ const formatted = formatResult(result, outputPath, toolCallsOf(), row.browserKill);
458
546
  emitThrown(formatted.thrown);
459
547
  appendOutput(formatted.suffix);
460
548
  registry.settle(row, {
@@ -471,7 +559,7 @@ export function makeScriptTool(deps: ScriptToolDeps) {
471
559
 
472
560
  void handle.promise
473
561
  .then((result) => {
474
- const formatted = formatResult(result, outputPath, row.browserKill);
562
+ const formatted = formatResult(result, outputPath, toolCallsOf(), row.browserKill);
475
563
  emitThrown(formatted.thrown);
476
564
  appendOutput(formatted.suffix);
477
565
  registry.settle(row, {
@@ -485,7 +573,12 @@ export function makeScriptTool(deps: ScriptToolDeps) {
485
573
  settleBackgroundFailure(registry, row, "Script", error);
486
574
  });
487
575
  return {
488
- content: [{ type: "text", text: `Script started in background (taskId ${row.taskId}).` }],
576
+ content: [
577
+ {
578
+ type: "text",
579
+ text: `Script started in background (taskId ${row.taskId}).\nTool calls, if the script makes any: ${toolLog.path}`,
580
+ },
581
+ ],
489
582
  details: {
490
583
  taskId: row.taskId,
491
584
  outputPath,
@@ -495,6 +588,7 @@ export function makeScriptTool(deps: ScriptToolDeps) {
495
588
  stderr: "",
496
589
  truncated: { stdout: false, stderr: false },
497
590
  durationMs: 0,
591
+ toolCalls: 0,
498
592
  },
499
593
  };
500
594
  } catch (error) {
@@ -5,7 +5,7 @@ import { dirname, isAbsolute, resolve } from "node:path";
5
5
  import { ChildProcess } from "node:child_process";
6
6
  import * as vm from "node:vm";
7
7
  import { Writable } from "node:stream";
8
- import { renderReturn } from "./script-render.ts";
8
+ import { isJsonCompatible, renderReturn } from "./script-render.ts";
9
9
  import { TEMP_VARIABLES } from "./session-tmp.ts";
10
10
  import { parentPort, workerData } from "node:worker_threads";
11
11
  import { createJiti } from "jiti";
@@ -26,6 +26,10 @@ interface ScriptWorkerData {
26
26
  input: unknown;
27
27
  /** Package name -> absolute directory, for jiti's `alias` (bundled packages). */
28
28
  aliases: Record<string, string>;
29
+ /** Bound tool names, in declaration order (Section 10.3). */
30
+ toolNames: string[];
31
+ /** The tool declarations (Section 10.2). */
32
+ toolTypes: string;
29
33
  }
30
34
 
31
35
  const port = parentPort;
@@ -132,6 +136,91 @@ process.on("uncaughtException", (thrown: unknown) => {
132
136
  reportError(thrown instanceof Error ? thrown : new Error(String(thrown)));
133
137
  });
134
138
 
139
+ // --- tool functions and dent (Sections 4 and 10.3) ----------------------------
140
+ // A nested call is one `tool-call` message; the runner answers with `tool-result`. The port is
141
+ // referenced only while a call is pending, so a script awaiting nothing else still ends as before.
142
+ interface PendingCall {
143
+ resolve: (value: unknown) => void;
144
+ reject: (error: Error) => void;
145
+ }
146
+ const pendingCalls = new Map<number, PendingCall>();
147
+ let nextCallId = 0;
148
+ let listening = false;
149
+
150
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
151
+ typeof value === "object" && value !== null;
152
+
153
+ const freezeResult = (value: unknown): unknown => {
154
+ if (!isRecord(value)) return value;
155
+ const content = Array.isArray(value.content)
156
+ ? Object.freeze(value.content.map((part: unknown) => Object.freeze(part)))
157
+ : value.content;
158
+ return Object.freeze({
159
+ text: value.text,
160
+ content,
161
+ details: value.details,
162
+ structured: value.structured,
163
+ });
164
+ };
165
+
166
+ const onToolResult = (message: unknown): void => {
167
+ if (!isRecord(message) || message.type !== "tool-result" || typeof message.id !== "number") {
168
+ return;
169
+ }
170
+ const call = pendingCalls.get(message.id);
171
+ if (call === undefined) return;
172
+ pendingCalls.delete(message.id);
173
+ if (pendingCalls.size === 0) port.unref();
174
+ // No code of the script runs after process.exit (Section 3).
175
+ if (exitCalled) return;
176
+ const reply = message.reply;
177
+ if (isRecord(reply) && reply.ok === true) {
178
+ call.resolve(freezeResult(reply.value));
179
+ return;
180
+ }
181
+ const failure = isRecord(reply) && isRecord(reply.error) ? reply.error : {};
182
+ const error = new Error(String(failure.message ?? "tool call failed"));
183
+ if (typeof failure.name === "string" && failure.name !== "Error") error.name = failure.name;
184
+ call.reject(error);
185
+ };
186
+
187
+ const toolFunction =
188
+ (name: string) =>
189
+ (args: unknown): Promise<unknown> => {
190
+ const plain =
191
+ isRecord(args) &&
192
+ !Array.isArray(args) &&
193
+ [Object.prototype, null].includes(Object.getPrototypeOf(args));
194
+ if (!plain || !isJsonCompatible(args)) {
195
+ return Promise.reject(new Error(`tools.${name} args must be a JSON-compatible object`));
196
+ }
197
+ return new Promise((resolveCall, rejectCall) => {
198
+ const id = nextCallId++;
199
+ port.postMessage({ type: "tool-call", id, name, args });
200
+ pendingCalls.set(id, { resolve: resolveCall, reject: rejectCall });
201
+ if (!listening) {
202
+ listening = true;
203
+ port.on("message", onToolResult);
204
+ }
205
+ port.ref();
206
+ });
207
+ };
208
+
209
+ const scriptTools: Record<string, unknown> = Object.freeze(
210
+ Object.fromEntries(data.toolNames.map((name) => [name, toolFunction(name)])),
211
+ );
212
+ const scriptDent = Object.freeze({ toolTypes: (): string => data.toolTypes });
213
+ Object.defineProperty(globalThis, "tools", {
214
+ value: scriptTools,
215
+ writable: true,
216
+ configurable: true,
217
+ });
218
+ Object.defineProperty(globalThis, "dent", {
219
+ value: scriptDent,
220
+ writable: true,
221
+ configurable: true,
222
+ });
223
+
135
224
  // --- cwd-observing process proxy --------------------------------------------
136
225
  let cwd = data.cwd;
137
226
  // Node's chdir rejects a missing directory (ENOENT, from statSync) and a non-
@@ -865,6 +954,8 @@ void (async () => {
865
954
  __filename: data.filename,
866
955
  __dirname: dirname(data.filename),
867
956
  input: data.input,
957
+ tools: scriptTools,
958
+ dent: scriptDent,
868
959
  Buffer,
869
960
  process: scriptProcess,
870
961
  console: scriptConsole,
@@ -168,7 +168,7 @@ export const SEARCH_PARAMETER_DESCRIPTIONS = {
168
168
  until:
169
169
  "Upper time bound, exclusive: an RFC 3339 date-time with a time-zone offset, or an age such as 90s, 15m, 2h, or 7d. For sessions it bounds when the session was last written.",
170
170
  session:
171
- "For find and sessions: the session to search or list: self (default), the task ID of an Agent call of this session, a session key as shown before the colon of a hit address or at the start of a sessions line, or a session file path.",
171
+ "For find and sessions: the session to search or list: self (default), the task ID of an Agent or Script call of this session, a session key as shown before the colon of a hit address or at the start of a sessions line, or a session file path.",
172
172
  scope:
173
173
  "How far to reach: session (one session; default for find), tree (it and the child sessions beneath it; default for sessions), project (this main session and the other sessions of its project), project-trees (those and all their child sessions). sessions takes tree or project only.",
174
174
  branches: "For find: true also searches the entries of abandoned branches. Default false.",
package/lib/tools.ts CHANGED
@@ -382,15 +382,23 @@ function isOwnHeaderLine(line: string, resultPath: string): boolean {
382
382
  return HEADER_FORMS.some((form) => form.test(head));
383
383
  }
384
384
 
385
+ /** Whether `line` is exactly a `--- tool calls` line of a `script` row for `taskId` (script-tool.md Section 6). */
386
+ function isOwnToolCallsLine(line: string, taskId: string): boolean {
387
+ const tail = `; Search it with session ${taskId} ---`;
388
+ return /^--- tool calls: \d+; log: ./.test(line) && line.endsWith(tail);
389
+ }
390
+
385
391
  /**
386
392
  * The preview of a settled result that spilled (task-tool.md Section 2.1): each line cut
387
- * to 120 characters, but a `bash` row's own header line kept whole, and no `Full output:`
388
- * line when the preview already carries that header line.
393
+ * to 120 characters, but a `bash` row's own header line and a `script` row's own tool-calls
394
+ * line kept whole, and no `Full output:` line when the preview already carries that header line.
389
395
  */
390
- function previewSpill(text: string, kind: TaskKind, resultPath: string): string {
396
+ function previewSpill(text: string, kind: TaskKind, resultPath: string, taskId: string): string {
391
397
  const header = (line: string) => kind === "bash" && isOwnHeaderLine(line, resultPath);
398
+ const whole = (line: string) =>
399
+ header(line) || (kind === "script" && isOwnToolCallsLine(line, taskId));
392
400
  const truncate = (line: string) =>
393
- line.length > 120 && !header(line) ? line.slice(0, 120) : line;
401
+ line.length > 120 && !whole(line) ? line.slice(0, 120) : line;
394
402
  const lines = text.split("\n");
395
403
  const shown =
396
404
  lines.length <= 20
@@ -435,7 +443,7 @@ function taskRead(registry: TaskRegistry, row: TaskRow): ToolResult {
435
443
  if ("error" in spill) {
436
444
  return textError(`cannot read the result file ${row.resultPath}: ${spill.error}`);
437
445
  }
438
- text = previewSpill(spill.text, row.kind, row.resultPath);
446
+ text = previewSpill(spill.text, row.kind, row.resultPath, row.taskId);
439
447
  } else {
440
448
  // A rebuilt settled row keeps no result (task-record.md Section 3).
441
449
  text = row.result ?? `(result not retained; resume with Agent resume=${row.taskId})`;