From 2bc68635cf2b8d0700f463efbaa9cad92953306a Mon Sep 17 00:00:00 2001 From: "exe.dev user" Date: Sat, 7 Nov 2026 00:42:52 +0000 Subject: [PATCH] fix(core): list each Code Mode namespace at the most detail that fits --- packages/codemode/src/tool-runtime.ts | 10 + packages/codemode/test/codemode.test.ts | 4 + packages/codemode/test/signature.test.ts | 28 ++ packages/core/src/codemode/catalog.ts | 81 ++++-- packages/core/src/codemode/instructions.ts | 28 +- packages/core/src/codemode/tool.ts | 11 +- packages/core/test/codemode.test.ts | 6 +- packages/core/test/codemode/catalog.test.ts | 243 +++++++++--------- .../core/test/codemode/instructions.test.ts | 6 +- .../core/test/codemode/parameters.test.ts | 23 +- packages/core/test/session-generate.test.ts | 2 +- packages/core/test/session-runner.test.ts | 9 +- 12 files changed, 269 insertions(+), 182 deletions(-) diff --git a/packages/codemode/src/tool-runtime.ts b/packages/codemode/src/tool-runtime.ts index 8660d4fd630..3545fe42b26 100644 --- a/packages/codemode/src/tool-runtime.ts +++ b/packages/codemode/src/tool-runtime.ts @@ -87,6 +87,8 @@ export type ToolDescription = { readonly path: string readonly description: string readonly signature: string + /** The signature on one line, without doc comments, for listings that need to stay short. */ + readonly compactSignature: string } const defaultSearchLimit = 10 @@ -171,6 +173,7 @@ const flattenTools = ( const describeTool = (visible: VisibleTool): ToolDescription => { let signature: string | undefined + let compact: string | undefined return { path: visible.path, description: visible.tool.description, @@ -183,6 +186,13 @@ const describeTool = (visible: VisibleTool): ToolDescription => { `: Promise<${outputTypeScript(visible.tool, true)}>`, ].join("")) }, + get compactSignature() { + return (compact ??= [ + toolExpression(visible.path), + isEmptyInput(visible.tool) ? "()" : `(${inputTypeScript(visible.tool)})`, + `: Promise<${outputTypeScript(visible.tool)}>`, + ].join("")) + }, } } diff --git a/packages/codemode/test/codemode.test.ts b/packages/codemode/test/codemode.test.ts index 225805e403f..c3680ca0ef2 100644 --- a/packages/codemode/test/codemode.test.ts +++ b/packages/codemode/test/codemode.test.ts @@ -612,6 +612,7 @@ describe("CodeMode schema flexibility", () => { path: "adapter.call", description: "Call an adapter-described tool", signature: "tools.adapter.call({\n id: string,\n count?: number,\n}): Promise", + compactSignature: expect.any(String), }, ]) @@ -695,6 +696,7 @@ describe("CodeMode schema flexibility", () => { path: "users.lookup", description: "Look up a user", signature: "tools.users.lookup({\n login: string,\n}): Promise<{\n login: string,\n id: number,\n}>", + compactSignature: expect.any(String), }, ]) @@ -768,6 +770,7 @@ describe("CodeMode public contract", () => { path: "orders.lookup", description: "Look up an order by ID", signature: "tools.orders.lookup({\n id: string,\n}): Promise<{\n id: string,\n status: string,\n}>", + compactSignature: expect.any(String), }, ]) @@ -822,6 +825,7 @@ describe("CodeMode public contract", () => { path: "context7.resolve-library-id", description: "Resolve a library ID", signature: 'tools.context7["resolve-library-id"]({\n libraryName: string,\n}): Promise', + compactSignature: expect.any(String), }, ]) diff --git a/packages/codemode/test/signature.test.ts b/packages/codemode/test/signature.test.ts index ed41e9b02c2..b4da9b3cd9e 100644 --- a/packages/codemode/test/signature.test.ts +++ b/packages/codemode/test/signature.test.ts @@ -1083,3 +1083,31 @@ describe("non-identifier tool paths", () => { expect(value.items[0]?.signature).toContain('tools.context7["resolve-library-id"]({') }) }) + +describe("compact catalog signature", () => { + test("puts the whole signature on one line without doc comments", () => { + const runtime = CodeMode.make({ + tools: { + orders: { + update: Tool.make({ + description: "Update an order", + input: { + type: "object", + properties: { + id: { type: "string", description: "Order id" }, + patch: { type: "object", properties: { status: { type: "string", enum: ["open", "closed"] } } }, + }, + required: ["id", "patch"], + }, + output: Schema.String, + execute: () => Effect.succeed("ok"), + }), + }, + }, + }) + expect(runtime.catalog[0]?.compactSignature).toBe( + 'tools.orders.update({ id: string; patch: { status?: "open" | "closed" } }): Promise', + ) + expect(runtime.catalog[0]?.signature).toContain("/** Order id */") + }) +}) diff --git a/packages/core/src/codemode/catalog.ts b/packages/core/src/codemode/catalog.ts index 8d38c3f4465..de60af5589e 100644 --- a/packages/core/src/codemode/catalog.ts +++ b/packages/core/src/codemode/catalog.ts @@ -7,11 +7,13 @@ export type Tool = { readonly type: "tool" readonly name: string readonly description: string - /** Read only for pinned tools; listing a tool by name needs no signature. */ + /** Full signature with doc comments. Read only when a namespace is listed at that detail. */ readonly signature: string + /** Signature on one line, without doc comments. Read only when a namespace is listed at that detail. */ + readonly compactSignature?: string readonly pinned?: boolean - /** Required parameter names, then `…` when the tool also takes optional ones. Absent when unknown. */ - readonly parameters?: ReadonlyArray + /** Parameter names. Absent when the input is not a plain object. */ + readonly parameters?: { readonly required: ReadonlyArray; readonly optional: ReadonlyArray } } export type Namespace = { @@ -29,15 +31,16 @@ const Listing = Schema.Struct({ path: Schema.String, line: Schema.String, }) +type Listing = typeof Listing.Type /** One namespace's part of the catalog, built from that namespace's tools alone. */ const Section = Schema.Struct({ name: Schema.String, description: Schema.optionalKey(Schema.String), count: Schema.Number, - /** Pinned tools, with full signatures. */ - pinned: Schema.Array(Listing), - /** The other tools by name and required parameters, in path order, as many as fit the section budget. */ + /** Tools listed one per line with a signature: pinned tools, and every tool when the namespace fits that way. */ + listings: Schema.Array(Listing), + /** The other tools on one line, by name and parameters, in path order, as many as fit. */ names: Schema.Array(Schema.String), }) export type Section = typeof Section.Type @@ -49,18 +52,24 @@ export const Summary = Schema.Struct({ export type Summary = typeof Summary.Type export type Options = { - /** Tokens each namespace may spend on names. */ + /** Tokens each namespace may spend on listing its tools. */ readonly budget?: number } const DESCRIPTION_LIMIT = 120 const CHARACTERS_PER_TOKEN = 4 -// Enough for every tool of a typical MCP server; a larger one lists what fits and the rest is found with search. const SECTION_BUDGET = 1_500 +// A signature costs at least this many tokens, so a namespace with more tools than budget / this cannot list them +// all with signatures and is not rendered at that detail. +const SIGNATURE_FLOOR = 20 const LISTING_PREFIX = " - " +type Entry = { readonly path: string; readonly tool: Tool } + // Each namespace's section depends only on its own tools, so a namespace coming, going or changing leaves the -// others as they were, and a catalog update can restate just the sections that changed. +// others as they were, and a catalog update can restate just the sections that changed. Each namespace is listed at +// the most detail that fits its budget whole: full signatures, then one-line signatures, then names with every +// parameter, then names with required parameters; past that, as many bare names as fit. export function summarize(inventory: Inventory, options: Options = {}): Summary { const budget = options.budget ?? SECTION_BUDGET const flattened = flatten(inventory.tools) @@ -71,31 +80,51 @@ export function summarize(inventory: Inventory, options: Options = {}): Summary .map(([name, tools]) => { const sorted = tools.toSorted((left, right) => compare(left.path, right.path)) const description = flattened.namespaces.get(name)?.description + const pinned = sorted.filter((entry) => entry.tool.pinned).map((entry) => listing(entry, entry.tool.signature)) return { name, ...(description === undefined ? {} : { description }), count: tools.length, - pinned: sorted - .filter((entry) => entry.tool.pinned) - .map((entry) => ({ - path: entry.path, - line: `${LISTING_PREFIX}${entry.tool.signature}${suffix(entry.tool)}`, - })), - names: fit( - sorted - .filter((entry) => !entry.tool.pinned) - .map((entry) => { - // A tool at the namespace's own path, with no namespace or with child tools, has no shorter name. - const short = entry.path === name ? toolExpression(entry.path) : entry.path.slice(name.length + 1) - return entry.tool.parameters ? `${short}(${entry.tool.parameters.join(", ")})` : short - }), + ...detail( + name, + sorted.filter((entry) => !entry.tool.pinned), budget, + pinned, ), } }), } } +function detail(namespace: string, entries: ReadonlyArray, budget: number, pinned: ReadonlyArray) { + const signed = entries.length * SIGNATURE_FLOOR <= budget + for (const signature of signed ? [(tool: Tool) => tool.signature, (tool: Tool) => tool.compactSignature] : []) { + const listings = entries.map((entry) => listing(entry, signature(entry.tool) ?? entry.tool.signature)) + if (listings.reduce((total, item) => total + cost(item.line.length), 0) <= budget) + return { listings: [...pinned, ...listings], names: [] } + } + const short = (entry: Entry) => + entry.path === namespace ? toolExpression(entry.path) : entry.path.slice(namespace.length + 1) + const all = entries.map((entry) => { + const parameters = entry.tool.parameters + if (!parameters) return short(entry) + return `${short(entry)}(${[...parameters.required, ...parameters.optional.map((name) => `${name}?`)].join(", ")})` + }) + const required = entries.map((entry) => { + const parameters = entry.tool.parameters + if (!parameters) return short(entry) + return `${short(entry)}(${[...parameters.required, ...(parameters.optional.length > 0 ? ["…"] : [])].join(", ")})` + }) + const fits = (names: ReadonlyArray) => + names.reduce((total, name) => total + cost(name.length + 2), 0) <= budget + const names = fits(all) ? all : fits(required) ? required : fit(entries.map(short), budget) + return { listings: [...pinned], names } +} + +function listing(entry: Entry, signature: string): Listing { + return { path: entry.path, line: `${LISTING_PREFIX}${signature}${suffix(entry.tool)}` } +} + /** The leading names whose cost fits `budget`. */ function fit(names: ReadonlyArray, budget: number) { const totals: number[] = [] @@ -137,16 +166,16 @@ function flatten(entries: ReadonlyArray, path: ReadonlyArray entry.line), + ...section.listings.map((entry) => entry.line), ...(section.names.length === 0 ? [] : [`${LISTING_PREFIX}${section.names.join(", ")}`]), ].join("\n") } diff --git a/packages/core/src/codemode/instructions.ts b/packages/core/src/codemode/instructions.ts index 33fb8abd629..362fc35b833 100644 --- a/packages/core/src/codemode/instructions.ts +++ b/packages/core/src/codemode/instructions.ts @@ -13,7 +13,7 @@ const prompt = `# Code Mode The tools listed below, and \`search\`, cannot be called directly: they only work as JavaScript inside the \`execute\` tool. Every other tool you have is a normal tool call: call it directly, never inside \`execute\`. -Each namespace lists its tools by name with their required parameters, and \`…\` when a tool also takes optional ones; a tool listed without parentheses takes input the list cannot summarize. Pinned tools show their full signature. Before calling a tool whose signature is not shown, get it with the global \`search(...)\` function, for example \`search({ query: "tools.ns.tool_name" })\`, and return the result; one \`execute\` can search for several tools. For a namespace that lists fewer tools than it has, find the rest the same way. Do not guess tool names or arguments. Each result's \`path\` is the complete call expression: write it out as code, for example \`await tools.ns.tool_name({ ... })\`, and call a name that is not a JavaScript identifier with brackets, as in \`tools.ns["tool-name"]({ ... })\`. Do not use a path as a key such as \`tools[path]\`. +Each namespace lists its tools with as much detail as fits: with their signatures, or by name with their parameters, where \`?\` marks an optional parameter and \`…\` stands for optional ones not shown; a tool listed without parentheses takes input the list cannot summarize. Before calling a tool whose signature is not shown, get it with the global \`search(...)\` function, for example \`search({ query: "tools.ns.tool_name" })\`, and return the result; one \`execute\` can search for several tools. For a namespace that lists fewer tools than it has, find the rest the same way. Do not guess tool names or arguments. Each result's \`path\` is the complete call expression: write it out as code, for example \`await tools.ns.tool_name({ ... })\`, and call a name that is not a JavaScript identifier with brackets, as in \`tools.ns["tool-name"]({ ... })\`. Do not use a path as a key such as \`tools[path]\`. - ${searchSignature} @@ -66,25 +66,26 @@ ${render(current)}` // One namespace's change under its new header: marked lines for the tools new, changed or gone, or its whole listing // when that is shorter. A namespace too large to list in full can drop a name without losing the tool, so it says -// "listed" there; a tool that only moved between pinned and listed by name is not gone. +// "listed" there; a tool that only moved between a signature and a name is not gone. function changes(previous: CodeModeCatalog.Section, current: CodeModeCatalog.Section) { const names = Instructions.diffByKey(previous.names, current.names, toolName, (before, after) => before !== after) - const pinned = Instructions.diffByKey( - previous.pinned, - current.pinned, + const listings = Instructions.diffByKey( + previous.listings, + current.listings, (entry) => entry.path, (before, after) => before.line !== after.line, ) const present = new Set([ ...current.names.map(toolName), - ...current.pinned.map((entry) => pinnedName(current, entry)), + ...current.listings.map((entry) => listingName(current, entry)), ]) - const gone = [...pinned.removed.map((entry) => pinnedName(previous, entry)), ...names.removed.map(toolName)].filter( - (name) => !present.has(name), - ) - const signatures = [...pinned.added, ...pinned.changed.map((change) => change.current)] + const gone = [ + ...listings.removed.map((entry) => listingName(previous, entry)), + ...names.removed.map(toolName), + ].filter((name) => !present.has(name)) + const signatures = [...listings.added, ...listings.changed.map((change) => change.current)] const listed = [...names.added, ...names.changed.map((change) => change.current)] - const capped = current.pinned.length + current.names.length < current.count + const capped = current.listings.length + current.names.length < current.count const marked = [ ...(signatures.length === 0 ? [] : [" - new or changed signatures:", ...signatures.map((entry) => entry.line)]), ...(listed.length === 0 ? [] : [` - new or changed: ${listed.join(", ")}`]), @@ -103,8 +104,9 @@ function toolName(listing: string) { return open === -1 ? listing : listing.slice(0, open) } -// The name a pinned tool would have if it were listed by name, so a tool moving between the two is recognized. -function pinnedName(section: CodeModeCatalog.Section, entry: { readonly path: string }) { +// The name a tool listed with its signature would have if it were listed by name, so a tool moving between the two +// is recognized. +function listingName(section: CodeModeCatalog.Section, entry: { readonly path: string }) { return entry.path === section.name ? toolExpression(entry.path) : entry.path.slice(section.name.length + 1) } diff --git a/packages/core/src/codemode/tool.ts b/packages/core/src/codemode/tool.ts index 399e34be6fd..1c49bd969d0 100644 --- a/packages/core/src/codemode/tool.ts +++ b/packages/core/src/codemode/tool.ts @@ -238,6 +238,9 @@ export const catalog = (inventory: Inventory) => { get signature() { return tool.signature }, + get compactSignature() { + return tool.compactSignature + }, pinned: pinned.has(tool.path), ...(registration === undefined ? {} : { parameters: parameters(described(inventory, registration).inputSchema) }), } @@ -266,7 +269,7 @@ const InputShape = Schema.Struct({ }) const decodeInputShape = Schema.decodeUnknownOption(InputShape) -// Required parameter names, then `…` when the tool also takes optional ones. Undefined unless the input is a plain +// Required and optional parameter names. Undefined unless the input is a plain // object, such as a union or a record, whose parameters a list of names would misstate; it is then listed by name. function parameters(schema: unknown) { const shape = Option.getOrUndefined(decodeInputShape(schema)) @@ -279,8 +282,10 @@ function parameters(schema: unknown) { const open = root.additionalProperties !== undefined && root.additionalProperties !== false if (composed || (root.properties === undefined && (root.type !== "object" || open))) return undefined const names = Object.keys(root.properties ?? {}) - const required = names.filter((key) => root.required?.includes(key)) - return required.length < names.length ? [...required, "…"] : required + return { + required: names.filter((key) => root.required?.includes(key)), + optional: names.filter((key) => !root.required?.includes(key)), + } } function renderCatalog(root: CatalogNode): ReadonlyArray { diff --git a/packages/core/test/codemode.test.ts b/packages/core/test/codemode.test.ts index b90e08011d7..111a3e325ec 100644 --- a/packages/core/test/codemode.test.ts +++ b/packages/core/test/codemode.test.ts @@ -43,7 +43,8 @@ describe("CodeMode", () => { description: "Echo text", signature: "tools.echo({\n text: string,\n}): Promise", pinned: true, - parameters: ["text"], + compactSignature: "tools.echo({ text: string }): Promise", + parameters: { required: ["text"], optional: [] }, }, { type: "namespace", @@ -79,7 +80,8 @@ describe("CodeMode", () => { type: "tool", name: "measure", description: "Measure", - parameters: ["ref", "amount", "sentinel"], + parameters: { required: ["ref", "amount", "sentinel"], optional: [] }, + compactSignature: expect.any(String), signature: [ "tools.measure({", " /** Element ref */", diff --git a/packages/core/test/codemode/catalog.test.ts b/packages/core/test/codemode/catalog.test.ts index 64ea5d645ac..ee0d19e5719 100644 --- a/packages/core/test/codemode/catalog.test.ts +++ b/packages/core/test/codemode/catalog.test.ts @@ -9,114 +9,129 @@ const CHANGED = const entry = ( path: string, description: string, - options: { readonly parameters?: ReadonlyArray; readonly pinned?: boolean; readonly signature?: string } = {}, + options: { + readonly required?: ReadonlyArray + readonly optional?: ReadonlyArray + readonly pinned?: boolean + readonly signature?: string + } = {}, ): CodeModeCatalog.Tool => ({ type: "tool", name: path, description, - signature: options.signature ?? `tools.${path}({\n q: string,\n}): Promise`, + signature: options.signature ?? `tools.${path}({\n /** The id. */\n id: string,\n}): Promise`, + compactSignature: `tools.${path}({ id: string }): Promise`, ...(options.pinned === undefined ? {} : { pinned: options.pinned }), - ...(options.parameters === undefined ? {} : { parameters: options.parameters }), + parameters: { required: options.required ?? ["id"], optional: options.optional ?? [] }, }) -const tools = (namespace: string, count: number) => - Array.from({ length: count }, (_, index) => - entry(`${namespace}.tool${index}`, `${namespace} ${index}`, { parameters: ["id"] }), - ) - -// The namespace blocks of an update, after its heading. -const changed = (text: string) => text.slice(text.indexOf(CHANGED) + CHANGED.length) +const tools = (namespace: string, count: number, optional: ReadonlyArray = []) => + Array.from({ length: count }, (_, index) => entry(`${namespace}.tool${index}`, `${namespace} ${index}`, { optional })) const summarize = (inventory: CodeModeCatalog.Inventory["tools"], budget?: number) => CodeModeCatalog.summarize({ tools: inventory }, budget === undefined ? {} : { budget }) -const update = (previous: CodeModeCatalog.Inventory["tools"], current: CodeModeCatalog.Inventory["tools"]) => - CodeModeInstructions.update(summarize(previous), summarize(current)) +const update = ( + previous: CodeModeCatalog.Inventory["tools"], + current: CodeModeCatalog.Inventory["tools"], + budget?: number, +) => CodeModeInstructions.update(summarize(previous, budget), summarize(current, budget)) + +// The namespace blocks of an update, after its heading. +const changed = (text: string) => text.slice(text.indexOf(CHANGED) + CHANGED.length) + +const unread = (path: string): CodeModeCatalog.Tool => ({ + type: "tool", + name: path, + description: path, + get signature(): string { + throw new Error("signature rendered") + }, + get compactSignature(): string { + throw new Error("signature rendered") + }, + parameters: { required: ["id"], optional: [] }, +}) describe("CodeModeCatalog.summarize", () => { - test("lists every tool by name with its required parameters", () => { - const catalog = summarize([ - entry("orders.lookup", "Look up an order", { parameters: ["id"] }), - entry("orders.list", "List orders", { parameters: ["…"] }), - entry("orders.cancel", "Cancel an order", { parameters: ["id", "…"] }), - entry("orders.status", "Service status"), - ]) - expect(catalog).toEqual({ - total: 4, - namespaces: [ + test("lists a namespace with full signatures when they fit", () => { + expect(summarize(tools("orders", 2)).namespaces[0]).toEqual({ + name: "orders", + count: 2, + listings: [ { - name: "orders", - count: 4, - pinned: [], - names: ["cancel(id, …)", "list(…)", "lookup(id)", "status"], + path: "orders.tool0", + line: " - tools.orders.tool0({\n /** The id. */\n id: string,\n}): Promise // orders 0", + }, + { + path: "orders.tool1", + line: " - tools.orders.tool1({\n /** The id. */\n id: string,\n}): Promise // orders 1", }, ], + names: [], }) }) - test("gives pinned tools their full signature and description", () => { - const catalog = summarize([ - entry("notes.echo", "Echo text\nMore detail", { pinned: true }), - entry("notes.list", "List notes", { parameters: [] }), + test("falls back to one-line signatures when full ones do not fit", () => { + const verbose = `tools.orders.tool0({\n /** ${"x".repeat(400)} */\n id: string,\n}): Promise` + const section = summarize([entry("orders.tool0", "x", { signature: verbose }), ...tools("orders", 3).slice(1)], 60) + .namespaces[0]! + expect(section.listings.map((item) => item.line)).toEqual([ + " - tools.orders.tool0({ id: string }): Promise // x", + " - tools.orders.tool1({ id: string }): Promise // orders 1", + " - tools.orders.tool2({ id: string }): Promise // orders 2", ]) - expect(catalog.namespaces[0]).toEqual({ - name: "notes", - count: 2, - pinned: [{ path: "notes.echo", line: " - tools.notes.echo({\n q: string,\n}): Promise // Echo text" }], - names: ["list()"], - }) }) - test("limits inline descriptions to 120 characters", () => { - const line = summarize([entry("notes.echo", "x".repeat(200), { pinned: true })]).namespaces[0]?.pinned[0]?.line - expect(line?.split(" // ")[1]).toBe("x".repeat(117) + "...") + test("lists names with every parameter when no signatures fit", () => { + const section = summarize(tools("bulk", 40, ["page"]), 300).namespaces[0]! + expect(section.listings).toEqual([]) + expect(section.names).toHaveLength(40) + expect(section.names[0]).toBe("tool0(id, page?)") }) - test("never renders the signature of a tool it lists by name", () => { - const unread: CodeModeCatalog.Tool = { - type: "tool", - name: "notes.list", - description: "List notes", - get signature(): string { - throw new Error("signature rendered") - }, - } - expect(summarize([unread]).namespaces[0]?.names).toEqual(["list"]) + test("drops optional parameter names when every parameter does not fit", () => { + const section = summarize(tools("bulk", 40, ["page_cursor", "filter_expression"]), 300).namespaces[0]! + expect(section.names).toHaveLength(40) + expect(section.names[0]).toBe("tool0(id, …)") }) - test("lists the leading names that fit a namespace's budget and keeps its header", () => { - const catalog = summarize(tools("bulk", 1_000), 50) - const section = catalog.namespaces[0]! - expect(section.count).toBe(1_000) + test("lists as many bare names as fit, in path order, when nothing else does", () => { + const section = summarize(tools("bulk", 1_000), 50).namespaces[0]! expect(section.names.length).toBeGreaterThan(0) expect(section.names.length).toBeLessThan(1_000) expect(section.names).toEqual(section.names.toSorted()) + expect(section.names.every((name) => !name.includes("("))).toBe(true) expect(CodeModeCatalog.namespaceLine(section)).toBe( `- bulk (1000 tools, ${section.names.length} listed; search for the rest)`, ) }) - test("names a tool that sits at its namespace's own path in full", () => { - const catalog = summarize([ - entry("deploy", "Deploy", { parameters: ["target"] }), - entry("echo", "Echo", { parameters: ["text"] }), - entry("echo.sub", "Sub", { parameters: ["id"] }), - ]) - expect(catalog.namespaces.map((section) => section.names)).toEqual([ - ["tools.deploy(target)"], - ["tools.echo(text)", "sub(id)"], - ]) + test("never renders signatures for a namespace too large to list them", () => { + const section = summarize(Array.from({ length: 200 }, (_, index) => unread(`big.tool${index}`))).namespaces[0]! + expect(section.names[0]).toBe("tool0(id)") }) - test("keeps every namespace and its description even when nothing else fits", () => { - const catalog = summarize( - [{ type: "namespace", name: "docs", description: "Project docs", tools: tools("x", 3) }, ...tools("alpha", 2)], - 0, - ) - expect(catalog.namespaces.map((section) => CodeModeCatalog.namespaceLine(section))).toEqual([ - "- alpha (2 tools, 0 listed; search for the rest)", - "- docs (3 tools, 0 listed; search for the rest) // Project docs", + test("always lists pinned tools with their full signature", () => { + const section = summarize([entry("big.pinned", "Pinned", { pinned: true }), ...tools("big", 200)]).namespaces[0]! + expect(section.listings).toEqual([ + { + path: "big.pinned", + line: " - tools.big.pinned({\n /** The id. */\n id: string,\n}): Promise // Pinned", + }, ]) + expect(section.names).toHaveLength(200) + }) + + test("names a tool that sits at its namespace's own path in full", () => { + const section = summarize([entry("deploy", "Deploy", { required: ["target"] }), ...tools("deploy", 200)]) + .namespaces[0]! + expect(section.names[0]).toBe("tools.deploy(target)") + }) + + test("limits inline descriptions to 120 characters", () => { + const line = summarize([entry("notes.echo", "x".repeat(200))]).namespaces[0]?.listings[0]?.line + expect(line?.split(" // ")[1]).toBe("x".repeat(117) + "...") }) test("builds each namespace's section from its own tools alone", () => { @@ -134,29 +149,20 @@ describe("CodeModeInstructions.render", () => { }) test("renders the guidance, search and each namespace's section", () => { - const text = CodeModeInstructions.render( - summarize([entry("notes.echo", "Echo text", { pinned: true }), ...tools("orders", 2)]), - ) + const text = CodeModeInstructions.render(summarize([...tools("notes", 1), ...tools("orders", 200)])) expect(text).toContain("they only work as JavaScript inside the `execute` tool") expect(text).toContain("Before calling a tool whose signature is not shown, get it with the global `search(...)`") expect(text).toContain(`- ${searchSignature}`) - expect(text).toEndWith( - [ - "## Code Mode tools (call only inside `execute`)", - "", - "- notes (1 tool)", - " - tools.notes.echo({\n q: string,\n}): Promise // Echo text", - "- orders (2 tools)", - " - tool0(id), tool1(id)", - ].join("\n"), + expect(text).toContain( + "## Code Mode tools (call only inside `execute`)\n\n- notes (1 tool)\n - tools.notes.tool0({\n /** The id. */\n id: string,\n}): Promise // notes 0\n- orders (200 tools)\n - tool0(id), tool1(id),", ) }) }) describe("CodeModeInstructions.update", () => { test("adds a new namespace's section and nothing else", () => { - expect(update(tools("alpha", 3), [...tools("alpha", 3), ...tools("beta", 2)])).toBe( - "The Code Mode tool catalog has changed.\n\nNew tool namespaces are available:\n- beta (2 tools)\n - tool0(id), tool1(id)", + expect(update(tools("alpha", 3), [...tools("alpha", 3), ...tools("beta", 1)])).toBe( + "The Code Mode tool catalog has changed.\n\nNew tool namespaces are available:\n- beta (1 tool)\n - tools.beta.tool0({\n /** The id. */\n id: string,\n}): Promise // beta 0", ) }) @@ -167,68 +173,57 @@ describe("CodeModeInstructions.update", () => { }) test("names the tools that changed in a namespace", () => { - expect(update([...tools("alpha", 3), ...tools("beta", 2)], [...tools("alpha", 4), ...tools("beta", 2)])).toBe( - "The Code Mode tool catalog has changed.\n\n" + - `${CHANGED}\n` + - "- alpha (4 tools)\n - new or changed: tool3(id)", + expect(update(tools("alpha", 200), tools("alpha", 201))).toBe( + `The Code Mode tool catalog has changed.\n\n${CHANGED}\n- alpha (201 tools)\n - new or changed: tool200(id)`, ) - const changed = [entry("alpha.tool0", "x", { parameters: ["id", "…"] }), ...tools("alpha", 3).slice(1)] - expect(update(tools("alpha", 3), changed)).toContain("- alpha (3 tools)\n - new or changed: tool0(id, …)") - expect(update(tools("alpha", 10), tools("alpha", 10).slice(1))).toContain( - "- alpha (9 tools)\n - no longer available: tool0", + expect(changed(update(tools("alpha", 200), tools("alpha", 200).slice(1)))).toBe( + "\n- alpha (199 tools)\n - no longer available: tool0", + ) + }) + + test("marks a signature change so the rest of the namespace stays listed", () => { + const before = tools("ns", 3) + const after = [ + entry("ns.tool0", "ns 0", { signature: "tools.ns.tool0({\n key: string,\n}): Promise" }), + ...before.slice(1), + ] + expect(changed(update(before, after))).toBe( + "\n- ns (3 tools)\n - new or changed signatures:\n - tools.ns.tool0({\n key: string,\n}): Promise // ns 0", ) }) test("says a name is no longer listed when its namespace is too large to list in full", () => { - const before = summarize(tools("bulk", 400), 40) - const after = summarize([entry("bulk.a_first", "First", { parameters: ["id"] }), ...tools("bulk", 400)], 40) - const text = CodeModeInstructions.update(before, after) - expect(text).toContain(" - new or changed: a_first(id)") - expect(text).toMatch(/ {2}- no longer listed: tool\d+/) - expect(text).not.toContain("no longer available") - }) - - test("restates a namespace's whole listing when that is shorter than its changes", () => { - const text = update(tools("alpha", 2), [entry("alpha.renamed", "x", { parameters: ["id"] })]) - expect(changed(text)).toBe("\n- alpha (1 tool)\n - renamed(id)") - }) - - test("marks a pinned signature change so the rest of the namespace stays listed", () => { - const before = [entry("ns.pinned", "Pinned", { pinned: true }), ...tools("ns", 9)] - const after = [ - entry("ns.pinned", "Pinned", { - pinned: true, - signature: "tools.ns.pinned({\n id: string,\n}): Promise", - }), - ...tools("ns", 9), - ] - expect(update(before, after)).toBe( - `The Code Mode tool catalog has changed.\n\n${CHANGED}\n` + - "- ns (10 tools)\n - new or changed signatures:\n - tools.ns.pinned({\n id: string,\n}): Promise // Pinned", - ) + const text = update(tools("bulk", 400), [entry("bulk.a_first", "First"), ...tools("bulk", 400)], 40) + expect(changed(text)).toContain(" - new or changed: a_first") + expect(changed(text)).toMatch(/ {2}- no longer listed: tool\d+/) }) test("says the listed tools are unchanged when only a namespace's header changed", () => { const before = summarize(tools("big", 300), 100) const after = summarize(tools("big", 301), 100) - expect(CodeModeInstructions.update(before, after)).toContain( - `- big (301 tools, ${after.namespaces[0]!.names.length} listed; search for the rest)\n - listed tools unchanged`, + expect(changed(CodeModeInstructions.update(before, after))).toBe( + `\n- big (301 tools, ${after.namespaces[0]!.names.length} listed; search for the rest)\n - listed tools unchanged`, ) }) test("does not report a tool gone when it is only pinned or unpinned", () => { - const listed = tools("ns", 9) - const pinned = [entry("ns.tool0", "ns 0", { pinned: true, parameters: ["id"] }), ...listed.slice(1)] + const listed = tools("ns", 200) + const pinned = [entry("ns.tool0", "ns 0", { pinned: true }), ...listed.slice(1)] expect(changed(update(listed, pinned))).not.toContain("no longer") expect(changed(update(pinned, listed))).not.toContain("no longer") }) + test("restates a namespace's whole listing when that is shorter than its changes", () => { + expect(changed(update(tools("alpha", 2), [entry("alpha.renamed", "x")]))).toBe( + "\n- alpha (1 tool)\n - tools.alpha.renamed({\n /** The id. */\n id: string,\n}): Promise // x", + ) + }) + test("restates a section whose description changed", () => { const text = CodeModeInstructions.update( summarize([{ type: "namespace", name: "notes", description: "Old", tools: tools("x", 1) }]), summarize([{ type: "namespace", name: "notes", description: "New", tools: tools("x", 1) }]), ) - expect(text).toContain("These namespaces changed") expect(text).toContain("- notes (1 tool) // New") expect(text).not.toContain("Old") }) diff --git a/packages/core/test/codemode/instructions.test.ts b/packages/core/test/codemode/instructions.test.ts index dadc2fb9fe9..03aca2b231a 100644 --- a/packages/core/test/codemode/instructions.test.ts +++ b/packages/core/test/codemode/instructions.test.ts @@ -35,7 +35,7 @@ describe("CodeModeInstructions", () => { const added = yield* readUpdate(CodeModeInstructions.make({ tools: [echo] }), initialized) expect(added.text).toContain("This catalog supersedes the previous Code Mode tool catalog.") expect(added.text).toContain("they only work as JavaScript inside the `execute` tool") - expect(added.text).toContain("- notes (1 tool)\n - echo") + expect(added.text).toContain(`- notes (1 tool)\n - ${echo.signature} // Echo text`) expect(yield* readUpdate(CodeModeInstructions.make({ tools: [] }), { values: added.values })).toMatchObject({ text: @@ -52,11 +52,11 @@ describe("CodeModeInstructions", () => { "The tools listed below, and `search`, cannot be called directly: they only work as JavaScript inside the `execute` tool.", ) expect(initialized.text).toContain("## Code Mode tools (call only inside `execute`)") - expect(initialized.text).toContain("- notes (1 tool)\n - echo") + expect(initialized.text).toContain(`- notes (1 tool)\n - ${echo.signature} // Echo text`) const added = yield* readUpdate(CodeModeInstructions.make({ tools: [echo, lookup] }), initialized) expect(added.text).toBe( - "The Code Mode tool catalog has changed.\n\nNew tool namespaces are available:\n- orders (1 tool)\n - lookup", + `The Code Mode tool catalog has changed.\n\nNew tool namespaces are available:\n- orders (1 tool)\n - ${lookup.signature} // Look up an order`, ) const removed = yield* readUpdate(CodeModeInstructions.make({ tools: [echo] }), { values: added.values }) diff --git a/packages/core/test/codemode/parameters.test.ts b/packages/core/test/codemode/parameters.test.ts index 9ae198e44d2..6bd699ffdc0 100644 --- a/packages/core/test/codemode/parameters.test.ts +++ b/packages/core/test/codemode/parameters.test.ts @@ -12,22 +12,31 @@ const listed = (input: Info["input"]) => { } describe("catalog parameters", () => { - test("lists required names, then … for optional ones, from a raw JSON Schema object", () => { + test("reads required and optional names from a raw JSON Schema object", () => { expect( listed({ type: "object", properties: { owner: { type: "string" }, repo: { type: "string" }, page: { type: "number" } }, required: ["owner", "repo"], }), - ).toEqual(["owner", "repo", "…"]) - expect(listed({ type: "object", properties: {} })).toEqual([]) - expect(listed({ type: "object" })).toEqual([]) + ).toEqual({ required: ["owner", "repo"], optional: ["page"] }) + expect(listed({ type: "object", properties: {} })).toEqual({ required: [], optional: [] }) + expect(listed({ type: "object" })).toEqual({ required: [], optional: [] }) }) test("reads Effect and zod objects, including an Effect struct named by an identifier", () => { - expect(listed(Schema.Struct({ id: Schema.String, note: Schema.optionalKey(Schema.String) }))).toEqual(["id", "…"]) - expect(listed(Schema.Struct({ id: Schema.String }).annotate({ identifier: "Lookup" }))).toEqual(["id"]) - expect(listed(z.object({ query: z.string(), limit: z.number().default(10) }))).toEqual(["query", "…"]) + expect(listed(Schema.Struct({ id: Schema.String, note: Schema.optionalKey(Schema.String) }))).toEqual({ + required: ["id"], + optional: ["note"], + }) + expect(listed(Schema.Struct({ id: Schema.String }).annotate({ identifier: "Lookup" }))).toEqual({ + required: ["id"], + optional: [], + }) + expect(listed(z.object({ query: z.string(), limit: z.number().default(10) }))).toEqual({ + required: ["query"], + optional: ["limit"], + }) }) test("leaves inputs that are not plain objects unsummarized rather than claiming they take nothing", () => { diff --git a/packages/core/test/session-generate.test.ts b/packages/core/test/session-generate.test.ts index dd1ee84c3c2..c12ae6e69e2 100644 --- a/packages/core/test/session-generate.test.ts +++ b/packages/core/test/session-generate.test.ts @@ -344,7 +344,7 @@ it.effect( ) expect(instructionUpdates).toHaveLength(1) expect(instructionUpdates?.[0]).toContain("Changed context") - expect(instructionUpdates?.[0]).toContain("- captured (1 tool)\n - lookup") + expect(instructionUpdates?.[0]).toContain("- captured (1 tool)\n - tools.captured.lookup(") expect(userTexts(requests[0])).toEqual(["Existing durable context", "Summarize privately"]) expect( requests[0]?.messages.flatMap((message) => diff --git a/packages/core/test/session-runner.test.ts b/packages/core/test/session-runner.test.ts index a0d1fe809a6..e8890122297 100644 --- a/packages/core/test/session-runner.test.ts +++ b/packages/core/test/session-runner.test.ts @@ -2409,7 +2409,9 @@ describe("SessionRunnerLLM", () => { yield* s.runPrompt("First") const alpha = yield* section("alpha") expect(catalogOf(s.requests.at(-1))).toContain(alpha) - expect(alpha).toContain("alpha_0(id, …)") + expect(alpha).toContain( + " - tools.alpha.alpha_0({\n id: string,\n note?: string,\n}): Promise // alpha tool 0", + ) const beta = yield* register("beta", 5) yield* s.runPrompt("Second") @@ -2434,7 +2436,8 @@ describe("SessionRunnerLLM", () => { expect(updates(s.requests.at(-1)).at(-1)).toBe( "The Code Mode tool catalog has changed.\n\n" + `${CHANGED}\n` + - "- alpha (13 tools)\n - new or changed: alpha_12(id, …)", + "- alpha (13 tools)\n - new or changed signatures:\n" + + " - tools.alpha.alpha_12({\n id: string,\n note?: string,\n}): Promise // alpha tool 12", ) // Compaction restates the stored catalog as the new baseline and has no update to send. @@ -2479,7 +2482,7 @@ describe("SessionRunnerLLM", () => { .find((text) => text.includes("# Code Mode")) ?? "" expect(catalog).toContain("- small (3 tools)\n") expect(catalog).toMatch(/- huge \(800 tools, \d+ listed; search for the rest\)/) - expect(catalog).toContain("small_2_with_a_long_descriptive_name(account, zone, record)") + expect(catalog).toContain(" - tools.small.small_2_with_a_long_descriptive_name({") }) scenario("rebuilds a consistent Code Mode catalog when a revert removes its update", function* (s) {