fix(core): list each Code Mode namespace at the most detail that fits

This commit is contained in:
exe.dev user
2026-11-07 00:42:52 +00:00
Unverified
parent 1025eb1af0
commit 2bc68635cf
12 changed files with 269 additions and 182 deletions
+10
View File
@@ -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 = <R>(
const describeTool = <R>(visible: VisibleTool<R>): ToolDescription => {
let signature: string | undefined
let compact: string | undefined
return {
path: visible.path,
description: visible.tool.description,
@@ -183,6 +186,13 @@ const describeTool = <R>(visible: VisibleTool<R>): 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(""))
},
}
}
+4
View File
@@ -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<void>",
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<string>',
compactSignature: expect.any(String),
},
])
+28
View File
@@ -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<string>',
)
expect(runtime.catalog[0]?.signature).toContain("/** Order id */")
})
})
+55 -26
View File
@@ -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<string>
/** Parameter names. Absent when the input is not a plain object. */
readonly parameters?: { readonly required: ReadonlyArray<string>; readonly optional: ReadonlyArray<string> }
}
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<Entry>, budget: number, pinned: ReadonlyArray<Listing>) {
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<string>) =>
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<string>, budget: number) {
const totals: number[] = []
@@ -137,16 +166,16 @@ function flatten(entries: ReadonlyArray<Tool | Namespace>, path: ReadonlyArray<s
/** A section's header: its name, how many tools it has and how many it lists, and its description. */
export function namespaceLine(section: Section) {
const count = section.count === 1 ? "1 tool" : `${section.count} tools`
const listed = section.pinned.length + section.names.length
const listed = section.listings.length + section.names.length
const label = listed === section.count ? count : `${count}, ${listed} listed; search for the rest`
return `- ${section.name} (${label})${section.description === undefined ? "" : ` // ${section.description}`}`
}
/** A section as the model reads it: its header, its pinned signatures, then the other tools' names. */
/** A section as the model reads it: its header, the tools listed with signatures, then the other tools' names. */
export function renderSection(section: Section) {
return [
namespaceLine(section),
...section.pinned.map((entry) => entry.line),
...section.listings.map((entry) => entry.line),
...(section.names.length === 0 ? [] : [`${LISTING_PREFIX}${section.names.join(", ")}`]),
].join("\n")
}
+15 -13
View File
@@ -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)
}
+8 -3
View File
@@ -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<CodeModeCatalog.Tool | CodeModeCatalog.Namespace> {
+4 -2
View File
@@ -43,7 +43,8 @@ describe("CodeMode", () => {
description: "Echo text",
signature: "tools.echo({\n text: string,\n}): Promise<string>",
pinned: true,
parameters: ["text"],
compactSignature: "tools.echo({ text: string }): Promise<string>",
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 */",
+119 -124
View File
@@ -9,114 +9,129 @@ const CHANGED =
const entry = (
path: string,
description: string,
options: { readonly parameters?: ReadonlyArray<string>; readonly pinned?: boolean; readonly signature?: string } = {},
options: {
readonly required?: ReadonlyArray<string>
readonly optional?: ReadonlyArray<string>
readonly pinned?: boolean
readonly signature?: string
} = {},
): CodeModeCatalog.Tool => ({
type: "tool",
name: path,
description,
signature: options.signature ?? `tools.${path}({\n q: string,\n}): Promise<string>`,
signature: options.signature ?? `tools.${path}({\n /** The id. */\n id: string,\n}): Promise<string>`,
compactSignature: `tools.${path}({ id: string }): Promise<string>`,
...(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<string> = []) =>
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<string> // orders 0",
},
{
path: "orders.tool1",
line: " - tools.orders.tool1({\n /** The id. */\n id: string,\n}): Promise<string> // 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<string>`
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<string> // x",
" - tools.orders.tool1({ id: string }): Promise<string> // orders 1",
" - tools.orders.tool2({ id: string }): Promise<string> // orders 2",
])
expect(catalog.namespaces[0]).toEqual({
name: "notes",
count: 2,
pinned: [{ path: "notes.echo", line: " - tools.notes.echo({\n q: string,\n}): Promise<string> // 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<string> // 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<string> // 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<string> // 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<string> // 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<string>" }),
...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<string> // 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<string>",
}),
...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<string> // 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<string> // 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")
})
@@ -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 })
+16 -7
View File
@@ -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", () => {
+1 -1
View File
@@ -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) =>
+6 -3
View File
@@ -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<string> // 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<string> // 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) {