@opencode/codemode 2.2.6 → 2.3.0

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 (197) hide show
  1. package/README.md +115 -29
  2. package/dist/{vm/async.d.ts → async.d.ts} +1 -1
  3. package/dist/codemode.d.ts +13 -22
  4. package/dist/codemode.js +18 -39
  5. package/dist/data.d.ts +4 -19
  6. package/dist/data.js +1 -82
  7. package/dist/extension.d.ts +20 -1
  8. package/dist/extension.js +14 -1
  9. package/dist/{vm/host.d.ts → host.d.ts} +5 -2
  10. package/dist/{vm/host.js → host.js} +9 -4
  11. package/dist/index.d.ts +1 -1
  12. package/dist/{vm/opcodes.d.ts → opcodes.d.ts} +1 -1
  13. package/dist/{vm/prelude → prelude}/helpers.js +1 -1
  14. package/dist/{vm/runtime → runtime}/driver.d.ts +18 -8
  15. package/dist/{vm/runtime → runtime}/driver.js +90 -20
  16. package/dist/{vm/runtime → runtime}/errors.js +2 -2
  17. package/dist/{vm/runtime → runtime}/execute.d.ts +18 -9
  18. package/dist/{vm/runtime → runtime}/execute.js +45 -15
  19. package/dist/{vm/runtime → runtime}/extensions.d.ts +2 -2
  20. package/dist/{vm/runtime → runtime}/extensions.js +121 -19
  21. package/dist/{vm/runtime → runtime}/globals.js +1 -1
  22. package/dist/{vm/runtime → runtime}/interpreter.d.ts +4 -1
  23. package/dist/{vm/runtime → runtime}/interpreter.js +2 -0
  24. package/dist/{vm/runtime → runtime}/model.d.ts +1 -1
  25. package/dist/{vm/runtime → runtime}/objects.d.ts +1 -1
  26. package/dist/{vm/runtime → runtime}/objects.js +1 -1
  27. package/dist/{vm/runtime → runtime}/operations.d.ts +1 -1
  28. package/dist/{vm/runtime → runtime}/operations.js +1 -1
  29. package/dist/scan.js +2 -2
  30. package/dist/{vm/scheduler.d.ts → scheduler.d.ts} +16 -4
  31. package/dist/{vm/scheduler.js → scheduler.js} +13 -2
  32. package/dist/{vm/snapshot → snapshot}/codec.d.ts +37 -6
  33. package/dist/{vm/snapshot → snapshot}/codec.js +112 -8
  34. package/dist/{vm/snapshot → snapshot}/snapshot.d.ts +13 -6
  35. package/dist/{vm/snapshot → snapshot}/snapshot.js +19 -4
  36. package/dist/{vm/snapshot.js → snapshot.js} +5 -2
  37. package/dist/stdlib/array.d.ts +14 -9
  38. package/dist/stdlib/array.js +89 -276
  39. package/dist/stdlib/bytes.d.ts +11 -7
  40. package/dist/stdlib/bytes.js +112 -79
  41. package/dist/stdlib/collections.d.ts +7 -7
  42. package/dist/stdlib/collections.js +30 -339
  43. package/dist/stdlib/console.d.ts +2 -2
  44. package/dist/stdlib/console.js +3 -3
  45. package/dist/stdlib/date.d.ts +2 -2
  46. package/dist/stdlib/date.js +21 -30
  47. package/dist/stdlib/headers.d.ts +2 -2
  48. package/dist/stdlib/headers.js +15 -33
  49. package/dist/stdlib/iterator.d.ts +2 -2
  50. package/dist/stdlib/iterator.js +10 -303
  51. package/dist/stdlib/json.d.ts +2 -2
  52. package/dist/stdlib/json.js +15 -31
  53. package/dist/stdlib/math.d.ts +2 -7
  54. package/dist/stdlib/math.js +6 -30
  55. package/dist/stdlib/number.d.ts +3 -3
  56. package/dist/stdlib/number.js +8 -8
  57. package/dist/stdlib/object.d.ts +4 -4
  58. package/dist/stdlib/object.js +12 -30
  59. package/dist/stdlib/regexp.d.ts +6 -5
  60. package/dist/stdlib/regexp.js +18 -13
  61. package/dist/stdlib/string.d.ts +2 -2
  62. package/dist/stdlib/string.js +53 -53
  63. package/dist/stdlib/url.d.ts +21 -9
  64. package/dist/stdlib/url.js +55 -55
  65. package/dist/stdlib/value.d.ts +3 -4
  66. package/dist/stdlib/value.js +5 -6
  67. package/dist/stdlib/web.d.ts +4 -4
  68. package/dist/stdlib/web.js +7 -7
  69. package/dist/tool-runtime.d.ts +34 -12
  70. package/dist/tool-runtime.js +350 -68
  71. package/dist/tool-schema.d.ts +5 -0
  72. package/dist/tool-schema.js +36 -16
  73. package/dist/tool.d.ts +60 -2
  74. package/dist/tool.js +17 -1
  75. package/dist/{vm/vm.d.ts → vm.d.ts} +4 -3
  76. package/dist/{vm/vm.js → vm.js} +1 -1
  77. package/package.json +5 -7
  78. package/dist/interpreter/callback.d.ts +0 -24
  79. package/dist/interpreter/callback.js +0 -86
  80. package/dist/interpreter/errors.js +0 -173
  81. package/dist/interpreter/execute.d.ts +0 -14
  82. package/dist/interpreter/execute.js +0 -207
  83. package/dist/interpreter/extensions.d.ts +0 -9
  84. package/dist/interpreter/extensions.js +0 -248
  85. package/dist/interpreter/generators.d.ts +0 -3
  86. package/dist/interpreter/generators.js +0 -168
  87. package/dist/interpreter/globals.js +0 -144
  88. package/dist/interpreter/interpreter.d.ts +0 -48
  89. package/dist/interpreter/interpreter.js +0 -2253
  90. package/dist/interpreter/intrinsics.d.ts +0 -15
  91. package/dist/interpreter/intrinsics.js +0 -105
  92. package/dist/interpreter/model.d.ts +0 -68
  93. package/dist/interpreter/model.js +0 -54
  94. package/dist/interpreter/native.d.ts +0 -17
  95. package/dist/interpreter/native.js +0 -35
  96. package/dist/interpreter/objects.d.ts +0 -301
  97. package/dist/interpreter/objects.js +0 -592
  98. package/dist/interpreter/promises.d.ts +0 -18
  99. package/dist/interpreter/promises.js +0 -292
  100. package/dist/interpreter/runner.d.ts +0 -188
  101. package/dist/interpreter/runner.js +0 -492
  102. package/dist/interpreter/scope.d.ts +0 -16
  103. package/dist/interpreter/scope.js +0 -79
  104. package/dist/suspend-error.d.ts +0 -23
  105. package/dist/suspend-error.js +0 -25
  106. package/dist/vm/data.d.ts +0 -7
  107. package/dist/vm/data.js +0 -13
  108. package/dist/vm/index.d.ts +0 -6
  109. package/dist/vm/index.js +0 -6
  110. package/dist/vm/runtime/errors.d.ts +0 -23
  111. package/dist/vm/runtime/globals.d.ts +0 -6
  112. package/dist/vm/runtime/limits.d.ts +0 -10
  113. package/dist/vm/runtime/limits.js +0 -19
  114. package/dist/vm/runtime/modules.d.ts +0 -4
  115. package/dist/vm/runtime/modules.js +0 -33
  116. package/dist/vm/runtime/references.d.ts +0 -8
  117. package/dist/vm/runtime/references.js +0 -51
  118. package/dist/vm/stdlib/array.d.ts +0 -16
  119. package/dist/vm/stdlib/array.js +0 -311
  120. package/dist/vm/stdlib/bytes.d.ts +0 -11
  121. package/dist/vm/stdlib/bytes.js +0 -222
  122. package/dist/vm/stdlib/collections.d.ts +0 -7
  123. package/dist/vm/stdlib/collections.js +0 -188
  124. package/dist/vm/stdlib/console.d.ts +0 -6
  125. package/dist/vm/stdlib/console.js +0 -93
  126. package/dist/vm/stdlib/date.d.ts +0 -2
  127. package/dist/vm/stdlib/date.js +0 -123
  128. package/dist/vm/stdlib/headers.d.ts +0 -2
  129. package/dist/vm/stdlib/headers.js +0 -92
  130. package/dist/vm/stdlib/iterator.d.ts +0 -2
  131. package/dist/vm/stdlib/iterator.js +0 -30
  132. package/dist/vm/stdlib/json.d.ts +0 -3
  133. package/dist/vm/stdlib/json.js +0 -42
  134. package/dist/vm/stdlib/math.d.ts +0 -3
  135. package/dist/vm/stdlib/math.js +0 -73
  136. package/dist/vm/stdlib/number.d.ts +0 -3
  137. package/dist/vm/stdlib/number.js +0 -72
  138. package/dist/vm/stdlib/object.d.ts +0 -6
  139. package/dist/vm/stdlib/object.js +0 -201
  140. package/dist/vm/stdlib/regexp.d.ts +0 -8
  141. package/dist/vm/stdlib/regexp.js +0 -119
  142. package/dist/vm/stdlib/string.d.ts +0 -2
  143. package/dist/vm/stdlib/string.js +0 -272
  144. package/dist/vm/stdlib/url.d.ts +0 -25
  145. package/dist/vm/stdlib/url.js +0 -255
  146. package/dist/vm/stdlib/value.d.ts +0 -6
  147. package/dist/vm/stdlib/value.js +0 -32
  148. package/dist/vm/stdlib/web.d.ts +0 -5
  149. package/dist/vm/stdlib/web.js +0 -97
  150. /package/dist/{vm/async.js → async.js} +0 -0
  151. /package/dist/{vm/code.d.ts → code.d.ts} +0 -0
  152. /package/dist/{vm/code.js → code.js} +0 -0
  153. /package/dist/{vm/compiler → compiler}/compile.d.ts +0 -0
  154. /package/dist/{vm/compiler → compiler}/compile.js +0 -0
  155. /package/dist/{vm/compiler → compiler}/scope.d.ts +0 -0
  156. /package/dist/{vm/compiler → compiler}/scope.js +0 -0
  157. /package/dist/{vm/generators.d.ts → generators.d.ts} +0 -0
  158. /package/dist/{vm/generators.js → generators.js} +0 -0
  159. /package/dist/{vm/internal-prelude.d.ts → internal-prelude.d.ts} +0 -0
  160. /package/dist/{vm/internal-prelude.js → internal-prelude.js} +0 -0
  161. /package/dist/{vm/opcodes.js → opcodes.js} +0 -0
  162. /package/dist/{vm/prelude → prelude}/bytecode.d.ts +0 -0
  163. /package/dist/{vm/prelude → prelude}/bytecode.js +0 -0
  164. /package/dist/{vm/prelude → prelude}/bytecode.json +0 -0
  165. /package/dist/{vm/prelude → prelude}/helpers.d.ts +0 -0
  166. /package/dist/{vm/prelude → prelude}/prelude.d.ts +0 -0
  167. /package/dist/{vm/prelude → prelude}/prelude.js +0 -0
  168. /package/dist/{vm/prelude → prelude}/source.d.ts +0 -0
  169. /package/dist/{vm/prelude → prelude}/source.js +0 -0
  170. /package/dist/{vm/runtime → runtime}/callback.d.ts +0 -0
  171. /package/dist/{vm/runtime → runtime}/callback.js +0 -0
  172. /package/dist/{interpreter → runtime}/errors.d.ts +0 -0
  173. /package/dist/{vm/runtime → runtime}/generators.d.ts +0 -0
  174. /package/dist/{vm/runtime → runtime}/generators.js +0 -0
  175. /package/dist/{interpreter → runtime}/globals.d.ts +0 -0
  176. /package/dist/{vm/runtime → runtime}/intrinsic-names.d.ts +0 -0
  177. /package/dist/{vm/runtime → runtime}/intrinsic-names.js +0 -0
  178. /package/dist/{vm/runtime → runtime}/intrinsics.d.ts +0 -0
  179. /package/dist/{vm/runtime → runtime}/intrinsics.js +0 -0
  180. /package/dist/{interpreter → runtime}/limits.d.ts +0 -0
  181. /package/dist/{interpreter → runtime}/limits.js +0 -0
  182. /package/dist/{vm/runtime → runtime}/model.js +0 -0
  183. /package/dist/{interpreter → runtime}/modules.d.ts +0 -0
  184. /package/dist/{interpreter → runtime}/modules.js +0 -0
  185. /package/dist/{vm/runtime → runtime}/native.d.ts +0 -0
  186. /package/dist/{vm/runtime → runtime}/native.js +0 -0
  187. /package/dist/{vm/runtime → runtime}/promises.d.ts +0 -0
  188. /package/dist/{vm/runtime → runtime}/promises.js +0 -0
  189. /package/dist/{interpreter → runtime}/references.d.ts +0 -0
  190. /package/dist/{interpreter → runtime}/references.js +0 -0
  191. /package/dist/{vm/runtime → runtime}/signals.d.ts +0 -0
  192. /package/dist/{vm/runtime → runtime}/signals.js +0 -0
  193. /package/dist/{vm/runtime → runtime}/source.d.ts +0 -0
  194. /package/dist/{vm/runtime → runtime}/source.js +0 -0
  195. /package/dist/{vm/runtime → runtime}/table.d.ts +0 -0
  196. /package/dist/{vm/runtime → runtime}/table.js +0 -0
  197. /package/dist/{vm/snapshot.d.ts → snapshot.d.ts} +0 -0
@@ -2,14 +2,11 @@ import { Effect } from "effect";
2
2
  import type { Json } from "./data.js";
3
3
  import type { DiagnosticKind } from "./codemode.js";
4
4
  import { type Namespace } from "./namespace.js";
5
- import { type Tool } from "./tool.js";
5
+ import { type Durable, type Idempotent, type Tool } from "./tool.js";
6
6
  import type { Tools } from "./tools.js";
7
7
  export declare const compareText: (left: string, right: string) => -1 | 0 | 1;
8
8
  export type Services<T> = ServicesOf<T, []>;
9
- type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8 ? never : T extends {
10
- readonly _tag: "CodeModeTool";
11
- readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, infer R>;
12
- } ? R : T extends object ? string extends keyof T ? ServicesOf<T[string], [...Depth, unknown]> : ServicesOf<T[keyof T], [...Depth, unknown]> : never;
9
+ type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8 ? never : T extends Tool<infer R> ? R : T extends object ? string extends keyof T ? ServicesOf<T[string], [...Depth, unknown]> : ServicesOf<T[keyof T], [...Depth, unknown]> : never;
13
10
  export type ToolCall = {
14
11
  readonly name: string;
15
12
  };
@@ -17,6 +14,8 @@ export type ToolCall = {
17
14
  export type ToolInvocation = {
18
15
  readonly name: string;
19
16
  readonly input: unknown;
17
+ /** The call's idempotency key, `<runId>:<callId>`: the same at every hook, and across a suspended run's resumes. */
18
+ readonly key: string;
20
19
  };
21
20
  /**
22
21
  * A call the program is making to an extension global or module function, with its arguments. A module function is
@@ -44,8 +43,8 @@ export type Hooks<R = never> = {
44
43
  readonly "extension.before"?: ((call: ExtensionInvocation) => Effect.Effect<void, unknown, R>) | undefined;
45
44
  readonly "extension.after"?: ((call: ExtensionInvocation, result: CallResult) => Effect.Effect<void, never, R>) | undefined;
46
45
  };
47
- /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */
48
- export declare const hooked: <Call, A, R>(call: Call, before: ((call: Call) => Effect.Effect<void, unknown, R>) | undefined, after: ((call: Call, result: CallResult) => Effect.Effect<void, never, R>) | undefined, run: Effect.Effect<A, unknown, R>) => Effect.Effect<A, unknown, R>;
46
+ /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted (unless `detaching`). */
47
+ export declare const hooked: <Call, A, R>(call: Call, before: ((call: Call) => Effect.Effect<void, unknown, R>) | undefined, after: ((call: Call, result: CallResult) => Effect.Effect<void, never, R>) | undefined, run: Effect.Effect<A, unknown, R>, detaching?: () => boolean) => Effect.Effect<A, unknown, R>;
49
48
  export type ToolDescription = {
50
49
  readonly path: string;
51
50
  readonly description: string;
@@ -69,10 +68,14 @@ export type Prepared<R = never> = {
69
68
  };
70
69
  export type SearchEntry = {
71
70
  readonly description: ToolDescription;
72
- /** The path split into words, so `zones` matches `get_zones` as a word rather than as a substring of `timezones`. */
73
- readonly pathWords: ReadonlyArray<string>;
74
- readonly searchText: string;
71
+ /** Position in the full search index, for scoring through the word index. */
72
+ readonly position: number;
73
+ /** The tool's searchable text by field, read when the word index is built. */
74
+ readonly text: () => Readonly<Record<SearchField, ReadonlyArray<string>>>;
75
+ /** Words in the tool's own name (the last path segment). */
76
+ readonly nameLength: number;
75
77
  };
78
+ type SearchField = "namespace" | "name" | "description" | "parameters" | "namespaceDescription";
76
79
  /** Exact callable signature of the built-in `search` function, for host-owned instructions. */
77
80
  export declare const searchSignature: string;
78
81
  export declare const prepare: <R>(tools: Tools<R>) => Prepared<R>;
@@ -81,13 +84,32 @@ export declare class ToolRuntimeError extends Error {
81
84
  readonly suggestions: ReadonlyArray<string>;
82
85
  constructor(kind: Extract<DiagnosticKind, "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "ToolCallLimitExceeded">, message: string, suggestions?: ReadonlyArray<string>);
83
86
  }
87
+ export type ExecuteCallOptions = {
88
+ readonly key: string;
89
+ readonly admit: (name: string) => void;
90
+ readonly detaching?: (() => boolean) | undefined;
91
+ };
84
92
  /** The tool bridge of one execution. Arguments arrive and results leave as JSON; program values never enter. */
85
93
  export type ToolRuntime<R = never> = {
86
94
  readonly calls: Array<ToolCall>;
87
95
  readonly hooks: Hooks<R>;
88
- readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
89
- readonly search: (args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
96
+ readonly invocations: Map<string, ToolInvocation>;
97
+ readonly record: (name: string) => void;
98
+ readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>, options: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
99
+ readonly search: (args: Array<Json | undefined>, options: ExecuteCallOptions) => Effect.Effect<Json | undefined, unknown, R>;
90
100
  readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>;
101
+ /** How the tool at `path` executes on suspend (`undefined` when unknown or plain). */
102
+ readonly mode: (path: ReadonlyArray<string>) => Idempotent<unknown, unknown, R> | Durable<unknown, unknown, R> | undefined;
103
+ /** Admits a call to a durable tool, runs `tool.before`, and starts its work under `key`: its JSON data. */
104
+ readonly start: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, admit: (name: string) => void) => Effect.Effect<Json, unknown, R>;
105
+ /**
106
+ * Waits for a durable tool's running work: its output, as `execute` gives it. `detaching` says whether an
107
+ * interruption detaches to suspend the run, which `tool.after` doesn't see, or ends the call, which it sees as
108
+ * interrupted.
109
+ */
110
+ readonly wait: (path: ReadonlyArray<string>, args: Array<Json | undefined>, key: string, data: Json, detaching: () => boolean) => Effect.Effect<Json | undefined, unknown, R>;
111
+ /** Cancels a durable tool's started work when the run is interrupted or ends. */
112
+ readonly cancel: (path: ReadonlyArray<string>, data: Json) => Effect.Effect<void, unknown, R>;
91
113
  };
92
114
  /** Per-execution call state over tools prepared once for the runtime. */
93
115
  export declare const make: <R>(prepared: Prepared<R>, maxToolCalls: number | undefined, hooks?: Hooks<R>) => ToolRuntime<R>;
@@ -1,14 +1,16 @@
1
1
  import { Cause, Effect, Exit, Formatter, Schema } from "effect";
2
2
  import { toolError } from "./tool-error.js";
3
- import { decodeInput as decodeToolInput, decodeOutput as decodeToolOutput, identifierSegment, inputProperties, inputTypeScript, isEmptyInput, outputTypeScript, } from "./tool-schema.js";
3
+ import { decodeInput as decodeToolInput, decodeOutput as decodeToolOutput, identifierSegment, inputProperties, inputTypeScript, isEmptyInput, outputTypeScript, stringParameter, } from "./tool-schema.js";
4
4
  import { isNamespace } from "./namespace.js";
5
5
  import { isTool } from "./tool.js";
6
6
  export const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
7
- /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */
8
- export const hooked = (call, before, after, run) => {
7
+ /** Runs `before`, then `run`, then `after` with how it ended, including when interrupted (unless `detaching`). */
8
+ export const hooked = (call, before, after, run, detaching) => {
9
9
  const observed = after === undefined
10
10
  ? run
11
11
  : Effect.onExit(run, (exit) => {
12
+ if (detaching?.())
13
+ return Effect.void;
12
14
  if (Exit.isSuccess(exit))
13
15
  return after(call, { status: "success", value: exit.value });
14
16
  if (Cause.hasInterruptsOnly(exit.cause))
@@ -90,40 +92,210 @@ const describeTool = (visible) => {
90
92
  // Joining the final fragments avoids retaining the rendering's intermediate string ropes in JSC.
91
93
  return (signature ??= [
92
94
  toolExpression(visible.path),
93
- isEmptyInput(visible.tool) ? "()" : `(${inputTypeScript(visible.tool, true)})`,
95
+ stringParameter(visible.tool)?.signature ??
96
+ (isEmptyInput(visible.tool) ? "()" : `(${inputTypeScript(visible.tool, true)})`),
94
97
  `: Promise<${outputTypeScript(visible.tool, true)}>`,
95
98
  ].join(""));
96
99
  },
97
100
  };
98
101
  };
99
- const tokenize = (query) => query
102
+ // Standard field-weighted BM25 (k1 1.2, b 0.75) plus a preference for short names. Compared against other rankers on
103
+ // model-written and real search queries over an ~11k-tool catalog (anomalyco/evals, dumber/evals/tool-search).
104
+ const fieldWeights = {
105
+ name: 3,
106
+ namespace: 2,
107
+ description: 1,
108
+ namespaceDescription: 0.4,
109
+ parameters: 0.3,
110
+ };
111
+ const searchFields = Object.keys(fieldWeights);
112
+ const k1 = 1.2;
113
+ const lengthNormalization = 0.75;
114
+ /** score × (1 + brevityBoost / words in the tool name): "users" prefers `list_users` over `list_user_groups`. */
115
+ const brevityBoost = 0.5;
116
+ /** A query word of 4+ letters also matches longer words it starts with, at this weight: `term` → `terminal`. */
117
+ const prefixWeight = 0.3;
118
+ /** Words split at case changes and non-alphanumerics: `listUserGroups` → list, user, groups. */
119
+ const splitWords = (text) => text
100
120
  .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
101
121
  .toLowerCase()
102
122
  .split(/[^a-z0-9]+/)
103
- .filter((term) => term.length > 0 && term !== "*");
104
- const termForms = (term) => {
105
- const forms = [term];
106
- if (term.endsWith("es") && term.length > 3)
107
- forms.push(term.slice(0, -2));
108
- if (term.endsWith("s") && term.length > 2)
109
- forms.push(term.slice(0, -1));
110
- return forms;
123
+ .filter((word) => word.length > 0);
124
+ /** Plural endings only, applied the same everywhere: `settings` → `setting`, `statuses` → `status`, `vms` → `vm`. */
125
+ const stem = (word) => {
126
+ if (word.length > 4 && word.endsWith("ies"))
127
+ return word.slice(0, -3) + "y";
128
+ if (word.length > 4 && /(?:ss|sh|ch|x|z|us)es$/.test(word))
129
+ return word.slice(0, -2);
130
+ if (word.length > 2 && word.endsWith("s") && !/(?:ss|us|is)$/.test(word))
131
+ return word.slice(0, -1);
132
+ return word;
133
+ };
134
+ /** Searchable words of a text: its split words, plus each camelCase word whole (`CronJob` → cron, job, cronjob). */
135
+ const searchWords = (text) => splitWords(text)
136
+ .concat((text.match(/[A-Za-z0-9]*[a-z0-9][A-Z][A-Za-z0-9]*/g) ?? []).map((word) => word.toLowerCase()))
137
+ .map(stem);
138
+ const fieldWords = (text, cache) => {
139
+ const cached = cache.get(text);
140
+ if (cached)
141
+ return cached;
142
+ const words = searchWords(text);
143
+ cache.set(text, words);
144
+ return words;
145
+ };
146
+ // Built once per search index on the first query.
147
+ const wordIndexes = new WeakMap();
148
+ // Locations with the same tools (global MCP servers) share one word index, keyed by a hash of the indexed text. An
149
+ // index lives while some search index uses it; once none does it can be collected and its key is removed. A hash
150
+ // collision (about 1 in 37 trillion with 1,000 distinct catalogs alive) would only misrank results: they still come
151
+ // from the caller's own tools, and the tool count in the key keeps positions in range.
152
+ const shared = typeof WeakRef === "undefined" || typeof FinalizationRegistry === "undefined"
153
+ ? undefined
154
+ : {
155
+ indexes: new Map(),
156
+ cleanup: new FinalizationRegistry(({ key, ref }) => {
157
+ // A newer index may have been stored under the same key since this one was dropped.
158
+ if (shared?.indexes.get(key) === ref)
159
+ shared.indexes.delete(key);
160
+ }),
161
+ };
162
+ const wordIndexFor = (index) => {
163
+ const cached = wordIndexes.get(index);
164
+ if (cached)
165
+ return cached;
166
+ const texts = index.map((entry) => entry.text());
167
+ const key = shared ? textKey(texts) : undefined;
168
+ const reused = key === undefined ? undefined : shared?.indexes.get(key)?.deref();
169
+ if (reused) {
170
+ wordIndexes.set(index, reused);
171
+ return reused;
172
+ }
173
+ const built = buildWordIndex(texts);
174
+ wordIndexes.set(index, built);
175
+ if (shared && key !== undefined) {
176
+ const ref = new WeakRef(built);
177
+ shared.indexes.set(key, ref);
178
+ shared.cleanup.register(built, { key, ref });
179
+ }
180
+ return built;
181
+ };
182
+ /** Tool count plus two independent 32-bit FNV-1a hashes of every indexed field, in index order. */
183
+ const textKey = (texts) => {
184
+ let first = 0x811c9dc5;
185
+ let second = 0x9e3779b9;
186
+ const add = (text) => {
187
+ for (let i = 0; i < text.length; i++) {
188
+ const code = text.charCodeAt(i);
189
+ first = Math.imul(first ^ code, 0x01000193);
190
+ second = Math.imul(second ^ code, 0x5bd1e995);
191
+ second ^= second >>> 15;
192
+ }
193
+ // Separators keep field boundaries distinct: ["ab", "c"] and ["a", "bc"] hash differently.
194
+ first = Math.imul(first ^ 0x1f, 0x01000193);
195
+ second = Math.imul(second ^ 0x1f, 0x5bd1e995);
196
+ };
197
+ for (const text of texts)
198
+ for (const field of searchFields) {
199
+ for (const part of text[field])
200
+ add(part);
201
+ add("\u0000");
202
+ }
203
+ return `${texts.length}:${(first >>> 0).toString(36)}:${(second >>> 0).toString(36)}`;
204
+ };
205
+ const buildWordIndex = (texts) => {
206
+ // Field texts are split once here and dropped afterwards; descriptions repeat across tools, so each text is split
207
+ // once and shared while building.
208
+ const cache = new Map();
209
+ const words = (texts) => texts.flatMap((text) => fieldWords(text, cache));
210
+ const fields = texts.map((text) => {
211
+ return {
212
+ namespace: words(text.namespace),
213
+ name: words(text.name),
214
+ description: words(text.description),
215
+ parameters: words(text.parameters),
216
+ namespaceDescription: words(text.namespaceDescription),
217
+ };
218
+ });
219
+ const averageLength = Object.fromEntries(searchFields.map((field) => [
220
+ field,
221
+ fields.reduce((sum, entry) => sum + entry[field].length, 0) / texts.length || 1,
222
+ ]));
223
+ const building = new Map();
224
+ const weights = new Map();
225
+ fields.forEach((entry, position) => {
226
+ weights.clear();
227
+ for (const field of searchFields) {
228
+ const weight = fieldWeights[field] /
229
+ (1 - lengthNormalization + (lengthNormalization * entry[field].length) / averageLength[field]);
230
+ for (const word of entry[field])
231
+ weights.set(word, (weights.get(word) ?? 0) + weight);
232
+ }
233
+ for (const [word, weight] of weights) {
234
+ let posting = building.get(word);
235
+ if (!posting)
236
+ building.set(word, (posting = { positions: [], weights: [] }));
237
+ posting.positions.push(position);
238
+ posting.weights.push(weight);
239
+ }
240
+ });
241
+ const postings = new Map([...building].map(([word, posting]) => [
242
+ word,
243
+ { positions: Int32Array.from(posting.positions), weights: Float32Array.from(posting.weights) },
244
+ ]));
245
+ return { postings, documents: texts.length, words: [...postings.keys()].sort() };
111
246
  };
112
- const rank = (entries, query) => {
113
- const terms = tokenize(query).map(termForms);
114
- return entries
115
- .map((entry) => {
116
- const path = entry.description.path.toLowerCase();
117
- const description = entry.description.description.toLowerCase();
118
- const score = terms.reduce((total, forms) => total +
119
- (forms.some((form) => path === form || path.endsWith(`.${form}`)) ? 20 : 0) +
120
- (forms.some((form) => entry.pathWords.includes(form)) ? 12 : 0) +
121
- (forms.some((form) => path.includes(form)) ? 8 : 0) +
122
- (forms.some((form) => description.includes(form)) ? 4 : 0) +
123
- (forms.some((form) => entry.searchText.includes(form)) ? 2 : 0), 0);
124
- return { entry, score };
125
- })
126
- .filter(({ score }) => terms.length === 0 || score > 0)
247
+ /** Indexed words longer than a 4+ letter query word that start with it. */
248
+ const prefixMatches = (words, term) => {
249
+ if (term.length < 4)
250
+ return [];
251
+ let low = 0;
252
+ let high = words.words.length;
253
+ while (low < high) {
254
+ const middle = (low + high) >> 1;
255
+ if (words.words[middle] < term)
256
+ low = middle + 1;
257
+ else
258
+ high = middle;
259
+ }
260
+ const matches = [];
261
+ for (let i = low; i < words.words.length && words.words[i].startsWith(term); i++)
262
+ if (words.words[i] !== term)
263
+ matches.push([words.words[i], prefixWeight]);
264
+ return matches;
265
+ };
266
+ const rank = (entries, query, index) => {
267
+ const terms = searchWords(query);
268
+ if (terms.length === 0)
269
+ return [...entries].sort((left, right) => compareText(left.description.path, right.description.path));
270
+ const words = wordIndexFor(index);
271
+ const allowed = entries === index ? undefined : new Set(entries.map((entry) => entry.position));
272
+ const scores = new Map();
273
+ for (const term of terms) {
274
+ // Each tool counts a query word once, through its best-scoring match.
275
+ const best = new Map();
276
+ for (const [word, factor] of [[term, 1], ...prefixMatches(words, term)]) {
277
+ const posting = words.postings.get(word);
278
+ if (!posting)
279
+ continue;
280
+ const idf = Math.log(1 + (words.documents - posting.positions.length + 0.5) / (posting.positions.length + 0.5));
281
+ for (let i = 0; i < posting.positions.length; i++) {
282
+ const position = posting.positions[i];
283
+ if (allowed && !allowed.has(position))
284
+ continue;
285
+ const weight = posting.weights[i];
286
+ const score = (factor * idf * weight * (k1 + 1)) / (weight + k1);
287
+ if (score > (best.get(position) ?? 0))
288
+ best.set(position, score);
289
+ }
290
+ }
291
+ for (const [position, score] of best)
292
+ scores.set(position, (scores.get(position) ?? 0) + score);
293
+ }
294
+ return [...scores]
295
+ .map(([position, score]) => ({
296
+ entry: index[position],
297
+ score: score * (1 + brevityBoost / Math.max(1, index[position].nameLength)),
298
+ }))
127
299
  .sort((left, right) => right.score - left.score || compareText(left.entry.description.path, right.entry.description.path))
128
300
  .map(({ entry }) => entry);
129
301
  };
@@ -151,7 +323,7 @@ const makeSearchTool = (searchIndex) => ({
151
323
  const exact = pathQuery === ""
152
324
  ? undefined
153
325
  : scoped.find((entry) => entry.description.path === pathQuery || toolExpression(entry.description.path) === trimmed);
154
- const ranked = exact !== undefined ? [exact] : rank(scoped, query);
326
+ const ranked = exact !== undefined ? [exact] : rank(scoped, pathQuery, searchIndex);
155
327
  const items = ranked.slice(offset, offset + (request.limit ?? defaultSearchLimit)).map(({ description }) => ({
156
328
  ...description,
157
329
  path: toolExpression(description.path),
@@ -169,18 +341,23 @@ export const searchSignature = (() => {
169
341
  const tool = makeSearchTool([]);
170
342
  return `search(${inputTypeScript(tool, true)}): ${outputTypeScript(tool, true)}`;
171
343
  })();
172
- const toSearchEntry = (visible) => ({
173
- description: describeTool(visible),
174
- pathWords: tokenize(visible.path),
175
- searchText: [
176
- visible.path,
177
- visible.tool.description,
178
- ...visible.namespaces.flatMap((namespace) => (namespace.description === undefined ? [] : [namespace.description])),
179
- ...inputProperties(visible.tool).flatMap(({ name, description: property }) => property === undefined ? [name] : [name, property]),
180
- ]
181
- .join("\n")
182
- .toLowerCase(),
183
- });
344
+ const toSearchEntry = (visible, position) => {
345
+ const segments = visible.path.split(".");
346
+ const name = segments.at(-1) ?? "";
347
+ return {
348
+ description: describeTool(visible),
349
+ position,
350
+ text: () => ({
351
+ namespace: segments.slice(0, -1),
352
+ name: [name],
353
+ description: [visible.tool.description],
354
+ // Parameter names only: their descriptions are half of all words and didn't improve ranking.
355
+ parameters: inputProperties(visible.tool).map((property) => property.name),
356
+ namespaceDescription: visible.namespaces.map((namespace) => namespace.description ?? ""),
357
+ }),
358
+ nameLength: splitWords(name).length,
359
+ };
360
+ };
184
361
  export const prepare = (tools) => {
185
362
  const root = toolTrie(tools);
186
363
  let searchIndex;
@@ -214,13 +391,26 @@ const resolve = (root, path, index) => {
214
391
  if (node === undefined) {
215
392
  const name = segments.join(".");
216
393
  const ns = segments.length > 1 && root.children.has(segments[0]) ? segments[0] : undefined;
217
- const closest = rank(ns ? index.filter((entry) => entry.description.path.startsWith(`${ns}.`)) : index, ns ? segments.slice(1).join(" ") : name)[0];
394
+ const closest = rank(ns ? index.filter((entry) => entry.description.path.startsWith(`${ns}.`)) : index, ns ? segments.slice(1).join(" ") : name, index)[0];
218
395
  throw new ToolRuntimeError("UnknownTool", closest
219
396
  ? `Unknown tool '${name}'. Did you mean ${toolExpression(closest.description.path)}?`
220
397
  : `Unknown tool '${name}'.`, ["Use search to find available tools."]);
221
398
  }
222
399
  if (node.tool === undefined) {
223
- throw new ToolRuntimeError("UnknownTool", `Tool '${segments.join(".")}' is not callable.`);
400
+ const name = segments.join(".");
401
+ const under = index.filter((entry) => entry.description.path.startsWith(`${name}.`));
402
+ const ranked = rank(under, segments.at(-1) ?? "", index);
403
+ const shown = [...ranked, ...under.filter((entry) => !ranked.includes(entry))]
404
+ .slice(0, 3)
405
+ .map((entry) => toolExpression(entry.description.path));
406
+ const more = under.length - shown.length;
407
+ throw new ToolRuntimeError("UnknownTool", shown.length === 0
408
+ ? `Tool '${name}' is not callable.`
409
+ : `Tool '${name}' is not callable, it is a namespace. Did you mean ${new Intl.ListFormat("en", { type: "disjunction" }).format(shown)}?`, [
410
+ more > 0
411
+ ? `${more} more under '${name}'. Use search({ namespace: ${JSON.stringify(name)} }) to list them.`
412
+ : "Use search to find available tools.",
413
+ ]);
224
414
  }
225
415
  return node.tool;
226
416
  };
@@ -237,6 +427,7 @@ export class ToolRuntimeError extends Error {
237
427
  /** Per-execution call state over tools prepared once for the runtime. */
238
428
  export const make = (prepared, maxToolCalls, hooks = {}) => {
239
429
  const calls = [];
430
+ const invocations = new Map();
240
431
  const root = prepared.root;
241
432
  const recordCall = (call) => {
242
433
  if (maxToolCalls !== undefined && calls.length >= maxToolCalls) {
@@ -244,44 +435,135 @@ export const make = (prepared, maxToolCalls, hooks = {}) => {
244
435
  }
245
436
  calls.push(call);
246
437
  };
247
- const executeTool = (name, tool, args) => Effect.gen(function* () {
438
+ const decode = (name, tool, args) => Effect.gen(function* () {
248
439
  const normalized = args.length === 0 ? [{}] : args;
249
440
  if (normalized.length !== 1)
250
441
  throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects at most one input object.`);
251
- const input = yield* Effect.try({
252
- try: () => decodeToolInput(tool, normalized[0]),
442
+ const input = normalized[0];
443
+ const field = typeof input === "string" ? stringParameter(tool)?.name : undefined;
444
+ return yield* Effect.try({
445
+ try: () => decodeToolInput(tool, field === undefined ? input : { [field]: input }),
253
446
  catch: (cause) => new ToolRuntimeError("InvalidToolInput", `Invalid input for tool '${name}': ${String(cause)}`, name === "search" ? [] : ["The signature may have changed. Use search to get the current signature."]),
254
447
  });
255
- yield* Effect.sync(() => recordCall({ name }));
256
- return yield* hooked({ name, input }, hooks["tool.before"], hooks["tool.after"], Effect.gen(function* () {
257
- const raw = yield* Effect.suspend(() => tool.execute(input)).pipe(Effect.catchCause((cause) => {
258
- if (Cause.hasInterruptsOnly(cause))
259
- return Effect.interrupt;
260
- return Effect.fail(toolError(Cause.prettyErrors(cause)
261
- .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name))
262
- .join("\n")));
263
- }));
264
- // The same round trip a tool result would take through text: exact JSON.stringify semantics.
265
- return yield* Effect.try({
266
- try: () => {
267
- const text = JSON.stringify(decodeToolOutput(tool, raw));
268
- return text === undefined ? undefined : JSON.parse(text);
269
- },
270
- catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
271
- });
272
- }));
273
448
  });
449
+ // A tool's own failure becomes a ToolError; interruption passes through.
450
+ const failure = (effect) => effect.pipe(Effect.catchCause((cause) => {
451
+ if (Cause.hasInterruptsOnly(cause))
452
+ return Effect.interrupt;
453
+ return Effect.fail(toolError(Cause.prettyErrors(cause)
454
+ .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name))
455
+ .join("\n")));
456
+ }));
457
+ // The same round trip a tool result would take through text: exact JSON.stringify semantics.
458
+ const output = (name, tool, raw) => Effect.try({
459
+ try: () => {
460
+ const text = JSON.stringify(decodeToolOutput(tool, raw));
461
+ return text === undefined ? undefined : JSON.parse(text);
462
+ },
463
+ catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
464
+ });
465
+ const executeTool = (name, tool, args, options) => Effect.gen(function* () {
466
+ if ("_tag" in tool.execute && tool.execute._tag === "CodeModeDurable") {
467
+ throw new TypeError(`Tool '${name}' is a durable tool; start it with ToolRuntime.start.`);
468
+ }
469
+ const run = "_tag" in tool.execute ? tool.execute.execute : tool.execute;
470
+ const key = options.key;
471
+ const input = yield* decode(name, tool, args);
472
+ yield* Effect.sync(() => options.admit(name));
473
+ return yield* hooked({ name, input, key }, hooks["tool.before"], hooks["tool.after"], Effect.gen(function* () {
474
+ const raw = yield* failure(Effect.suspend(() => run(input, { key })));
475
+ return yield* output(name, tool, raw);
476
+ }), options.detaching);
477
+ });
478
+ const durableTool = (path) => {
479
+ const segments = canonicalSegments(path);
480
+ const name = segments.join(".");
481
+ const tool = lookup(root, segments)?.tool;
482
+ if (tool === undefined || !("_tag" in tool.execute) || tool.execute._tag !== "CodeModeDurable") {
483
+ throw new TypeError(`Tool '${name}' is not a durable tool.`);
484
+ }
485
+ return { name, tool, durable: tool.execute };
486
+ };
274
487
  return {
275
488
  calls,
276
489
  hooks,
490
+ invocations,
491
+ record: (name) => recordCall({ name }),
277
492
  keys: (path) => namespaceKeys(root, path),
278
- search: (args) => Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args)),
279
- execute: (path, args) => Effect.suspend(() => {
493
+ search: (args, options) => Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args, options)),
494
+ execute: (path, args, options) => Effect.suspend(() => {
280
495
  const segments = canonicalSegments(path);
281
496
  // Models often write `tools.search(...)` for the bare `search(...)`; honor it unless a tool owns that path.
282
497
  if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined)
283
- return executeTool("search", makeSearchTool(prepared.searchIndex), args);
284
- return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args);
498
+ return executeTool("search", makeSearchTool(prepared.searchIndex), args, options);
499
+ return executeTool(segments.join("."), resolve(root, path, prepared.searchIndex), args, options);
500
+ }),
501
+ mode: (path) => {
502
+ const segments = canonicalSegments(path);
503
+ if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined)
504
+ return undefined;
505
+ const execute = lookup(root, segments)?.tool?.execute;
506
+ return execute !== undefined && "_tag" in execute ? execute : undefined;
507
+ },
508
+ start: (path, args, key, admit) => Effect.suspend(() => {
509
+ const found = durableTool(path);
510
+ return Effect.gen(function* () {
511
+ const input = yield* decode(found.name, found.tool, args);
512
+ yield* Effect.sync(() => admit(found.name));
513
+ const invocation = { name: found.name, input, key };
514
+ invocations.set(key, invocation);
515
+ const before = hooks["tool.before"];
516
+ const after = hooks["tool.after"];
517
+ const run = failure(Effect.suspend(() => found.durable.start(input, { key }))).pipe(Effect.flatMap((raw) => Effect.try({
518
+ try: () => {
519
+ const text = JSON.stringify(raw);
520
+ return text === undefined ? null : JSON.parse(text);
521
+ },
522
+ catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid start data from tool '${found.name}': ${cause}`),
523
+ })));
524
+ const observed = after === undefined
525
+ ? run
526
+ : Effect.onError(run, (cause) => {
527
+ invocations.delete(key);
528
+ if (Cause.hasInterruptsOnly(cause))
529
+ return after(invocation, { status: "interrupted" });
530
+ return after(invocation, { status: "failure", error: Cause.squash(cause) });
531
+ });
532
+ return yield* before === undefined ? observed : Effect.andThen(before(invocation), observed);
533
+ });
534
+ }),
535
+ wait: (path, args, key, data, detaching) => Effect.suspend(() => {
536
+ const found = durableTool(path);
537
+ const wait = found.durable.wait;
538
+ const after = hooks["tool.after"];
539
+ const run = Effect.gen(function* () {
540
+ const raw = yield* failure(Effect.suspend(() => wait(data, { key })));
541
+ return yield* output(found.name, found.tool, raw);
542
+ });
543
+ if (after === undefined)
544
+ return run;
545
+ const known = invocations.get(key);
546
+ const callEffect = known !== undefined
547
+ ? Effect.succeed(known)
548
+ : Effect.map(decode(found.name, found.tool, args), (input) => ({
549
+ name: found.name,
550
+ input,
551
+ key,
552
+ }));
553
+ return Effect.flatMap(callEffect, (call) => Effect.onExit(run, (exit) => {
554
+ if (detaching())
555
+ return Effect.void;
556
+ invocations.delete(key);
557
+ if (Exit.isSuccess(exit))
558
+ return after(call, { status: "success", value: exit.value });
559
+ if (Cause.hasInterruptsOnly(exit.cause))
560
+ return after(call, { status: "interrupted" });
561
+ return after(call, { status: "failure", error: Cause.squash(exit.cause) });
562
+ }));
563
+ }),
564
+ cancel: (path, data) => Effect.suspend(() => {
565
+ const cancel = durableTool(path).durable.cancel;
566
+ return failure(cancel(data));
285
567
  }),
286
568
  };
287
569
  };
@@ -9,6 +9,11 @@ export type InputProperty = {
9
9
  readonly required: boolean;
10
10
  };
11
11
  export declare const inputProperties: <R>(tool: Tool<R>) => Array<InputProperty>;
12
+ /** A freeform tool whose input is one required string field takes that string directly: `tools.patch(patchText: string)`. */
13
+ export declare const stringParameter: <R>(tool: Tool<R>) => {
14
+ name: string;
15
+ signature: string;
16
+ } | undefined;
12
17
  export declare const inputTypeScript: <R>(tool: Tool<R>, pretty?: boolean) => string;
13
18
  export declare const isEmptyInput: <R>(tool: Tool<R>) => boolean;
14
19
  export declare const outputTypeScript: <R>(tool: Tool<R>, pretty?: boolean) => string;