Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 20 additions & 4 deletions packages/harness/src/mcp/mcp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ import { McpLog } from "./log.ts";
import { McpOAuth } from "./oauth.ts";
import { McpOutput } from "./output.ts";
import { McpResources } from "./resources.ts";
import { McpSection } from "./section.ts";
import { McpTool } from "./tool.ts";
import { McpValue } from "./value.ts";
import { hostPath } from "../host.ts";
Expand Down Expand Up @@ -135,6 +136,8 @@ export interface Reconciled {
* Waits first, within {@link STARTUP_WAIT}, for those servers' connect attempts in progress.
*/
readonly deferred: Effect.Effect<ReadonlyArray<Message.Tool>>;
/** The `mcpservers` prompt section, as the servers stand once the ones with declared tools were waited for. */
readonly section: string | undefined;
}

export interface Interface {
Expand Down Expand Up @@ -186,6 +189,8 @@ interface Server {
skipped: EventList.McpSkipped | undefined;
/** Whether the server offered resources when it last connected. */
resources: boolean;
/** The instructions it sent when it last connected; kept while it is not connected. */
instructions: string | undefined;
/** The credential it was refused with, when it needs sign-in: a new one is worth a retry. */
refused: string | undefined;
live: Live | undefined;
Expand Down Expand Up @@ -605,6 +610,7 @@ export const layer = (options: {
server.live = live;
yield* listed(server, exit.value.listing);
server.resources = exit.value.connection.capabilities?.resources !== undefined;
server.instructions = exit.value.connection.instructions;
yield* setState(server, "connected");
watch(server, live);
yield* Effect.logInfo("mcp connected", { server: server.name, tools: server.tools.length });
Expand Down Expand Up @@ -898,11 +904,12 @@ export const layer = (options: {
return tools;
};

/** The thread's enabled servers configured with `deferred` exposure. */
const deferring = (thread: Thread) =>
[...thread.servers.values()].flatMap(({ config, server }) =>
server !== undefined && hasTools(config, "deferred") ? [server] : [],
/** The thread's enabled servers configured with `deferred` exposure, by name. */
const deferringEntries = (thread: Thread) =>
[...thread.servers].flatMap(([name, { config, server }]) =>
server !== undefined && hasTools(config, "deferred") ? [{ name, config, server }] : [],
);
const deferring = (thread: Thread) => deferringEntries(thread).map(({ server }) => server);

/** Settles when the server's connect attempt in progress, if any, does. */
const attempted = (server: Server) =>
Expand Down Expand Up @@ -1004,6 +1011,7 @@ export const layer = (options: {
tools: [],
skipped: undefined,
resources: false,
instructions: undefined,
refused: undefined,
live: undefined,
attempt: undefined,
Expand Down Expand Up @@ -1076,6 +1084,14 @@ export const layer = (options: {
tools: toolsOf(thread),
defers: deferring(thread).length > 0,
deferred: deferred(thread),
// A server disconnected on request offers no tools to search.
section: McpSection.render(
deferringEntries(thread).flatMap(({ name, config, server }) =>
server.stopped
? []
: [{ name, description: config.description, instructions: server.instructions }],
),
),
} satisfies Reconciled;
});

Expand Down
57 changes: 57 additions & 0 deletions packages/harness/src/mcp/section.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
/**
* The `mcpservers` prompt section: the servers whose tools are not declared to the model, since
* the tool search does not list them. Only `deferred` tools have a way in: a server whose tools are
* all `codemode` is left out until codemode exists, and the section is left out while the tool search
* is not declared.
*/

import { ToolSearch } from "../tool/search.ts";
import { namespace } from "./config.ts";

export const name = "mcpservers";

/** Characters of a server description, as Codex allows for deferred namespaces. */
const MAX_DESCRIPTION_CHARS = 250;
/** Descriptions shrink to fit; when the server lines alone do not, the last servers are counted instead. */
const MAX_SECTION_CHARS = 4096;

const INTRO = `MCP servers whose tools are not declared to you. Load the tools of \`${ToolSearch.name}\` servers with \`${ToolSearch.name}\`.`;

/** An enabled server with deferred tools. */
export interface Listing {
readonly name: string;
readonly description: string | undefined;
/** The server's instructions, once it connected. */
readonly instructions: string | undefined;
}

const truncate = (text: string, max: number) =>
text.length <= max ? text : max <= 1 ? "" : `${text.slice(0, max - 1).trimEnd()}…`;

/** First line of the configured description, or of the server instructions once connected. */
const summary = (server: Listing) => {
const text = server.description?.trim() || server.instructions || "";
return (text.split("\n", 1)[0] ?? "").trim();
};

/** Undefined when there are no servers. */
export const render = (servers: ReadonlyArray<Listing>): string | undefined => {
const listed = [...servers].sort((a, b) => a.name.localeCompare(b.name));
if (listed.length === 0) return undefined;
const heads = listed.map((server) => `- ${namespace(server.name)} (${ToolSearch.name})`);
const omitted = (count: number) =>
count > 0 ? [`- … ${count} more server${count === 1 ? "" : "s"}; find their tools with ${ToolSearch.name}`] : [];
const size = (kept: number) => [INTRO, ...heads.slice(0, kept), ...omitted(listed.length - kept)].join("\n").length;
let kept = listed.length;
while (kept > 0 && size(kept) > MAX_SECTION_CHARS) kept--;
// Each description also takes a ": " separator.
const each =
kept === 0 ? 0 : Math.min(MAX_DESCRIPTION_CHARS, Math.floor((MAX_SECTION_CHARS - size(kept)) / kept) - 2);
const lines = listed.slice(0, kept).map((server, index) => {
const text = each > 0 ? truncate(summary(server), each) : "";
return text ? `${heads[index]}: ${text}` : heads[index];
});
return [INTRO, ...lines, ...omitted(listed.length - kept)].join("\n");
};

export * as McpSection from "./section.ts";
2 changes: 1 addition & 1 deletion packages/harness/src/plugin/builtin/tool/toolsearch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import type { Builtin } from "../../plugin.ts";
* `modelTools.add`, so loaded tools stay offered on that line.
*/

export const TOOL_SEARCH_NAME = "toolsearch";
export const TOOL_SEARCH_NAME = ToolSearch.name;
export const DEFAULT_LIMIT = 8;

// Fixed, so it does not change as deferred tools are registered, for example as MCP servers connect.
Expand Down
4 changes: 2 additions & 2 deletions packages/harness/src/plugin/host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,9 @@ export const run = Effect.fn("PluginHost.run")(function* (
yield* apply(prepared);
}
yield* flush(Infinity);
const { deferred } = yield* settle;
const { deferred, section } = yield* settle;
return yield* Effect.try({
try: () => buckets.freeze(input.location.directory, tools, deferred),
try: () => buckets.freeze(input.location.directory, tools, deferred, section),
catch: (cause) =>
new SetupError({
message: `plugin snapshot freeze failed: ${cause instanceof Error ? cause.message : String(cause)}`,
Expand Down
7 changes: 7 additions & 0 deletions packages/harness/src/plugin/prompt/render.ts
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
// Bodies are never escaped: a plugin may nest its own tags inside an entry.

import * as Section from "@codeworksh/plugin/plugin/section";
import { McpSection } from "../../mcp/section.ts";
import { ToolSearch } from "../../tool/search.ts";
import type { AnyToolDef } from "../../tool/tool.ts";
import { fallback, type Snapshot, type Written } from "./registry.ts";

interface Input {
readonly prompt: Snapshot;
readonly tools: ReadonlyArray<AnyToolDef>;
readonly directory: string;
/** The `mcpservers` section's body, rendered by the `mcp` domain. */
readonly mcpservers: string | undefined;
}

const tag = (name: string, body: string): string => `<${name}>\n${body}\n</${name}>`;
Expand Down Expand Up @@ -64,6 +68,9 @@ export const render = (input: Input): Rendered => {

for (const section of Section.builtins) push(section.name);
sections.cwd = tag("cwd", input.directory);
// The servers are listed only while the tool that reaches them is declared.
if (input.mcpservers !== undefined && input.tools.some((tool) => tool.name === ToolSearch.name))
sections[McpSection.name] = tag(McpSection.name, input.mcpservers);
for (const name of Array.from(written.keys())) push(name);

// A blank foundation would leave the Responses transport without instructions, and it would
Expand Down
14 changes: 11 additions & 3 deletions packages/harness/src/plugin/registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,22 @@ export const make = (servers: ReadonlyArray<McpServer>) => {
/** Close the MCP bucket and return the servers the `mcp` domain settled on. */
settle: mcp.settle,
close,
/** `live` is the MCP servers' deferred tools as they stand when searched; see `Registry.resolve`. */
freeze: (directory: string, selection?: Selection, live?: Effect.Effect<ReadonlyArray<Message.Tool>>) => {
/**
* `live` is the MCP servers' deferred tools as they stand when searched; see `Registry.resolve`.
* `mcpservers` is the body of that prompt section, when there is one.
*/
freeze: (
directory: string,
selection?: Selection,
live?: Effect.Effect<ReadonlyArray<Message.Tool>>,
mcpservers?: string,
) => {
close();
const resolved = makeCatalog(tools.entries()).resolve(selection, live);
return {
tools: resolved,
// Only declared tools: loading a deferred one must not change the prompt.
prompt: render({ prompt: prompt.snapshot(), tools: resolved.defs.filter(declared), directory }),
prompt: render({ prompt: prompt.snapshot(), tools: resolved.defs.filter(declared), directory, mcpservers }),
};
},
};
Expand Down
16 changes: 14 additions & 2 deletions packages/harness/src/runner/loop.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { Context } from "../context/context.ts";
import { Event } from "../event/event.ts";
import { EventList } from "../event/list.ts";
import { Inbox } from "../inbox/inbox.ts";
import { McpSection } from "../mcp/section.ts";
import { SessionMessageSchema } from "../session/message/schema.ts";
import type { ThreadSchema } from "../thread/schema.ts";
import { Thread } from "../thread/thread.ts";
Expand Down Expand Up @@ -86,6 +87,16 @@ const observeTool = (
return Telemetry.record(Telemetry.toolDuration, seconds, labels);
};

/** The `mcpservers` section is the one the run started with: servers that connect mid-run show at the next run. */
const holdServers = (start: State.Snapshot, next: State.Snapshot): State.Snapshot => {
const { [McpSection.name]: _current, ...sections } = next.prompt.sections;
const held = start.prompt.sections[McpSection.name];
return {
...next,
prompt: { ...next.prompt, sections: held === undefined ? sections : { ...sections, [McpSection.name]: held } },
};
};

export const layer = (options: Options = {}) =>
Layer.effect(
Runner.Service,
Expand Down Expand Up @@ -520,7 +531,8 @@ export const layer = (options: Options = {}) =>
});

const drain = Effect.gen(function* () {
let snapshot = yield* state.snapshot(input.threadId);
const start = yield* state.snapshot(input.threadId);
let snapshot = start;
let continuing = input.force;
// Tool results and steers continue first; a follow-up only once both are exhausted.
while (true) {
Expand All @@ -544,7 +556,7 @@ export const layer = (options: Options = {}) =>
if (!continuing && !steer && !followUp) return;
promotion = followUp ? "followUp" : "steer";

const next = yield* state.snapshot(input.threadId);
const next = holdServers(start, yield* state.snapshot(input.threadId));
snapshot = completed === undefined ? next : yield* hooks.prepareNextTurn(completed, next);
}
});
Expand Down
3 changes: 3 additions & 0 deletions packages/harness/src/tool/search.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@ import type { Message } from "@codeworksh/aikit";

/** BM25 ranking over tool metadata: what `toolsearch` loads deferred tools by. */

/** The tool that loads deferred tools. */
export const name = "toolsearch";

export interface Document {
readonly name: string;
readonly text: string;
Expand Down
48 changes: 48 additions & 0 deletions packages/harness/test/__artifacts__/mcp.section.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
{
"systems": [
1,
2,
3,
4
],
"changes": [
{
"sections": [
"tools",
"rules",
"cwd",
"mcpservers"
],
"added": [],
"removed": []
},
{
"sections": [],
"added": [
"mcp__atlas__echo"
],
"removed": []
},
{
"sections": [
"mcpservers"
],
"added": [],
"removed": []
},
{
"sections": [
"mcpservers"
],
"added": [],
"removed": [
"mcp__atlas__echo"
]
}
],
"mcpservers": [
"<mcpservers>\nMCP servers whose tools are not declared to you. Load the tools of `toolsearch` servers with `toolsearch`.\n- mcp__atlas (toolsearch)\n</mcpservers>",
"<mcpservers>\nMCP servers whose tools are not declared to you. Load the tools of `toolsearch` servers with `toolsearch`.\n- mcp__atlas (toolsearch): Tide tables for coastal towns.\n</mcpservers>",
null
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
{
"declared": [
{
"sections": [
"tools",
"rules",
"cwd",
"mcpservers"
],
"mcpservers": "<mcpservers>\nMCP servers whose tools are not declared to you. Load the tools of `toolsearch` servers with `toolsearch`.\n- mcp__atlas (toolsearch): Capital cities of the world.\n</mcpservers>"
},
{
"sections": [
"mcpservers"
],
"mcpservers": "<mcpservers>\nMCP servers whose tools are not declared to you. Load the tools of `toolsearch` servers with `toolsearch`.\n- mcp__atlas (toolsearch): Tide tables for coastal towns.\n</mcpservers>"
}
],
"order": [
"user",
"system",
"assistant",
"user",
"system"
],
"answer": "mcp__atlas"
}
3 changes: 2 additions & 1 deletion packages/harness/test/__artifacts__/mcp.thread.json
Original file line number Diff line number Diff line change
Expand Up @@ -492,7 +492,8 @@
"sections": [
"tools",
"rules",
"cwd"
"cwd",
"mcpservers"
],
"added": [],
"removed": []
Expand Down
Loading
Loading