mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 13:05:14 +03:00
fix(core): list each Code Mode namespace at the most detail that fits
This commit is contained in:
@@ -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(""))
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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),
|
||||
},
|
||||
])
|
||||
|
||||
|
||||
@@ -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 */")
|
||||
})
|
||||
})
|
||||
|
||||
@@ -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")
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
|
||||
@@ -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> {
|
||||
|
||||
@@ -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 */",
|
||||
|
||||
@@ -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 })
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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) =>
|
||||
|
||||
@@ -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) {
|
||||
|
||||
Reference in New Issue
Block a user