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
14 changes: 8 additions & 6 deletions packages/harness/src/context/assemble.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@ import { DateTime, Effect, Schema } from "effect";
import { optional } from "../schema.ts";
import { SessionSchema } from "../session/schema.ts";
import type { Thread } from "../thread/thread.ts";
import { decodeMessage, decodeSyntheticMessage, type ContextMessage } from "./codec.ts";
import { decodeMessage, decodeSyntheticMessage } from "./codec.ts";
import { ContextDecodeError } from "./errors.ts";

export interface Snapshot {
readonly threadId: string;
readonly leafEntryId: string | null;
readonly messages: ReadonlyArray<ContextMessage>;
readonly messages: ReadonlyArray<Message.Message>;
readonly lastAssistant?: {
readonly entryId: string;
readonly message: Message.AssistantMessage;
Expand Down Expand Up @@ -64,7 +64,7 @@ const wrapperMessage = (entry: Thread.HydratedEntry, text: string): Message.User
/**
* Builds a thread's LLM context from its line (own entries, then inherited ones, in seq order).
* Only committed entries count, and the context starts at the newest `reset` or `compaction`.
* Entries that are not messages (system, custom) stay in the transcript, out of the context.
* `system` entries become transcript system messages; `custom` entries stay out of the context.
*/
export const assembleLine = Effect.fn("Context.assembleLine")(function* (
threadId: string,
Expand All @@ -78,7 +78,7 @@ export const assembleLine = Effect.fn("Context.assembleLine")(function* (
| { readonly index: number; readonly handoff: string | undefined }
| undefined;

const messagesByEntry = new Map<string, ContextMessage>();
const messagesByEntry = new Map<string, Message.Message>();
const compactions = new Map<string, SessionSchema.CompactionData>();
const handoffs = new Map<string, string>();

Expand Down Expand Up @@ -126,8 +126,10 @@ export const assembleLine = Effect.fn("Context.assembleLine")(function* (
latestStart = { index, handoff: data.handoff };
break;
}
case "system":
case "system": {
messagesByEntry.set(entry.id, yield* decodeMessage(hydrated));
break;
}
case "custom": {
yield* decodeCustomData(entry.data).pipe(Effect.mapError(decodeFailure(hydrated)));
break;
Expand Down Expand Up @@ -156,7 +158,7 @@ export const assembleLine = Effect.fn("Context.assembleLine")(function* (
effectivePath = [committedPath[index]!, ...kept, ...committedPath.slice(index + 1)];
}

const messages: ContextMessage[] = [];
const messages: Message.Message[] = [];
for (const hydrated of effectivePath) {
const { entry } = hydrated;
const message = messagesByEntry.get(entry.id);
Expand Down
52 changes: 49 additions & 3 deletions packages/harness/src/context/codec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ export interface EncodedMessage {

type AikitPart = Message.AssistantMessage["parts"][number] | Message.UserMessage["parts"][number];

/** A message the session stores as an entry. Transcript system messages are not stored yet. */
/** A message the session stores as a user or assistant entry. System messages have `system` entries. */
export type ContextMessage = Message.UserMessage | Message.AssistantMessage;

const reasonOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
Expand Down Expand Up @@ -199,15 +199,61 @@ export const decodeSyntheticMessage = Effect.fn("Context.decodeSyntheticMessage"
);
});

/** The transcript system message of a tool change; empty sides are left out. */
export const systemMessage = <T>(
messageId: string,
created: number,
changes: {
readonly toolsAdded: ReadonlyArray<T>;
readonly toolsRemoved: ReadonlyArray<Message.ToolReference>;
},
) => ({
messageId,
role: "system" as const,
time: { created },
...(changes.toolsAdded.length === 0 ? {} : { toolsAdded: [...changes.toolsAdded] }),
...(changes.toolsRemoved.length === 0 ? {} : { toolsRemoved: changes.toolsRemoved.map(({ name }) => ({ name })) }),
});

const decodeSystemData = Schema.decodeUnknownEffect(SessionSchema.SystemData);

export const decodeSystemMessage = Effect.fn("Context.decodeSystemMessage")(function* (
hydrated: Thread.HydratedEntry,
): Effect.fn.Return<Message.SystemMessage, ContextDecodeError> {
const { entry } = hydrated;
const data = yield* decodeSystemData(entry.data).pipe(
Effect.mapError(
(cause) => new ContextDecodeError({ entryId: entry.id, type: entry.type, reason: cause.message }),
),
);
const message = yield* Effect.try({
try: () =>
validateAikitMessage(
systemMessage(entry.id, DateTime.toEpochMillis(entry.createdAt), data),
`context entry ${entry.id}`,
),
catch: (cause) => new ContextDecodeError({ entryId: entry.id, type: entry.type, reason: reasonOf(cause) }),
});
if (message.role !== "system") {
return yield* new ContextDecodeError({ entryId: entry.id, type: entry.type, reason: "not a system message" });
}
return message;
});

/** A message's parts; a system message has none. */
export const parts = (message: Message.Message) => (message.role === "system" ? [] : message.parts);

/** The aikit message a `user`, `assistant` or `system` entry stores. */
export const decodeMessage = Effect.fn("Context.decodeMessage")(function* (
hydrated: Thread.HydratedEntry,
): Effect.fn.Return<ContextMessage, ContextDecodeError> {
): Effect.fn.Return<Message.Message, ContextDecodeError> {
const { entry } = hydrated;
if (entry.type === "system") return yield* decodeSystemMessage(hydrated);
if (entry.type !== "user" && entry.type !== "assistant") {
return yield* new ContextDecodeError({
entryId: entry.id,
type: entry.type,
reason: "only user and assistant entries contain complete aikit messages",
reason: "only user, assistant and system entries contain complete aikit messages",
});
}

Expand Down
13 changes: 13 additions & 0 deletions packages/harness/src/event/list.ts
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,17 @@ export const ThreadConfigured = EventSchema.define({
});
export type ThreadConfigured = typeof ThreadConfigured.Type;

/**
* The tools offered to a thread's next request differ from those its transcript declares, such as
* after `toolsearch` loaded some. Appends a `system` entry carrying the change.
*/
export const ToolsChanged = EventSchema.define({
type: "session.thread.tools.changed",
...durableOptions,
schema: { ...baseOptions, messageId: SessionMessageSchema.ID, ...SessionSchema.ToolChanges.fields },
});
export type ToolsChanged = typeof ToolsChanged.Type;

const LLMFields = {
...baseOptions,
messageId: SessionMessageSchema.ID,
Expand Down Expand Up @@ -344,6 +355,7 @@ export const Definitions = EventSchema.inventory(
SessionCreated,
ThreadForked,
ThreadConfigured,
ToolsChanged,
TurnStarted,
TurnEnded,
TurnAborted,
Expand Down Expand Up @@ -379,6 +391,7 @@ export const DurableDefinitions = EventSchema.inventory(
SessionCreated,
ThreadForked,
ThreadConfigured,
ToolsChanged,
TurnEnded,
LLMStarted,
LLMEnded,
Expand Down
4 changes: 3 additions & 1 deletion packages/harness/src/plugin/builtin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,14 @@ import { findPlugin } from "./builtin/tool/find.ts";
import { grepPlugin } from "./builtin/tool/grep.ts";
import { lsPlugin } from "./builtin/tool/ls.ts";
import { readPlugin } from "./builtin/tool/read.ts";
import { toolSearchPlugin } from "./builtin/tool/toolsearch.ts";
import { writePlugin } from "./builtin/tool/write.ts";

/**
* Every plugin the harness ships, and the selection a caller who passes no `plugins` gets. Tool
* contributors come first; within the prompt domain, declaration order is run order. The search
* tools (grep, find, ls) are `optIn` and ship off: settings turn each on with
* `{ "plugin": "codework.tool.grep", "enabled": true }`.
* `{ "plugin": "codework.tool.grep", "enabled": true }`. So is toolsearch, which loads deferred tools.
*/
export const builtins = Object.freeze([
bashPlugin,
Expand All @@ -23,6 +24,7 @@ export const builtins = Object.freeze([
grepPlugin,
findPlugin,
lsPlugin,
toolSearchPlugin,
defaultPromptPlugin,
instructionPlugin,
skillPlugin,
Expand Down
86 changes: 86 additions & 0 deletions packages/harness/src/plugin/builtin/tool/toolsearch.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
import { Effect, Schema } from "effect";
import { ToolOffer } from "../../../tool/offer.ts";
import { ToolSearch } from "../../../tool/search.ts";
import * as Tool from "../../../tool/tool.ts";
import { define } from "../../plugin.ts";

/**
* The built-in toolsearch plugin: the model searches the deferred tools it is not offered yet,
* and the matches are loaded for its next request. Loading writes the thread's `agent`
* `modelTools.add`, so loaded tools stay offered on that line.
*/

export const TOOL_SEARCH_NAME = "toolsearch";
export const DEFAULT_LIMIT = 8;

// Fixed, so it does not change as deferred tools are registered, for example as MCP servers connect.
const DESCRIPTION = `# Tool discovery\n\nSearches over deferred tool metadata with BM25 and exposes matching tools for the next model call.\n\nSome of the tools, such as tools of MCP servers, may not have been provided to you upfront, and you should use this tool (\`${TOOL_SEARCH_NAME}\`) to search for the required tools. For MCP tool discovery, always use \`${TOOL_SEARCH_NAME}\`.`;

const ToolSearchParams = Schema.Struct({
query: Schema.String.annotate({ description: "Search query for deferred tools." }),
limit: Schema.optional(
Schema.Finite.annotate({ description: `Maximum number of tools to return. Defaults to ${DEFAULT_LIMIT}.` }),
),
});

/** The `details` of a completed call: the tools it loaded, best match first. */
export const ToolSearchDetails = Schema.Struct({ loaded: Schema.Array(Schema.String) });
export type ToolSearchDetails = typeof ToolSearchDetails.Type;

const ToolSearchSuccess = Schema.Struct({ text: Schema.String, loaded: Schema.Array(Schema.String) });

export class ToolSearchFailed extends Schema.TaggedError<ToolSearchFailed>()("ToolSearchFailed", {
message: Schema.String,
}) {}

export const toolSearchDef = Tool.define({
name: TOOL_SEARCH_NAME,
label: "toolsearch",
description: DESCRIPTION,
// Searching changes what the model is offered, so only the model calls it.
exposure: "model",
parameters: ToolSearchParams,
success: ToolSearchSuccess,
failure: ToolSearchFailed,
encodeContent: (success) => [{ type: "text", text: success.text }],
encodeFailureContent: (failure) => [{ type: "text", text: failure.message }],
encodeDetails: (success): ToolSearchDetails => ({ loaded: success.loaded }),
});

const fail = (message: string) => Effect.fail(new ToolSearchFailed({ message }));

export const toolSearchHandler: Tool.Handler<
typeof ToolSearchParams,
typeof ToolSearchSuccess,
typeof ToolSearchFailed
> = Effect.fn("ToolSearch.handler")(function* ({ query, limit }) {
if (query.trim() === "") return yield* fail("query must not be empty");
const max = limit ?? DEFAULT_LIMIT;
if (!Number.isInteger(max) || max <= 0) return yield* fail("limit must be a positive integer");
const { deferred } = yield* ToolOffer;
const loaded = ToolSearch.rank(
query,
deferred.map((tool) => ({ name: tool.name, text: ToolSearch.text(tool) })),
max,
);
const listed = loaded.map((name) => {
const description = deferred.find((tool) => tool.name === name)?.description ?? "";
return `- ${name}: ${description.trim().split(/\r?\n/)[0]}`;
});
const text =
loaded.length === 0
? "No matching tools found."
: `Loaded ${loaded.length} tool${loaded.length === 1 ? "" : "s"}. They are available from your next call:\n${listed.join("\n")}`;
return { text, loaded };
});

export const toolSearchTool = Tool.implement(toolSearchDef, toolSearchHandler);

export const toolSearchPlugin = define({
id: "codework.tool.toolsearch",
kind: "tool",
optIn: true,
setup: (ctx) => {
ctx.plugin.tools.add(Tool.register(toolSearchTool));
},
});
4 changes: 3 additions & 1 deletion packages/harness/src/plugin/host.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { Cause, Effect, Schema } from "effect";
import type { Prepared } from "./catalog.ts";
import type { SharedPluginContext } from "./context.ts";
import type { Selection } from "../tool/registry.ts";
import { make } from "./registry.ts";

export class SetupError extends Schema.TaggedError<SetupError>()("Plugin.SetupError", {
Expand All @@ -12,6 +13,7 @@ export class SetupError extends Schema.TaggedError<SetupError>()("Plugin.SetupEr
export const run = Effect.fn("PluginHost.run")(function* (
selection: ReadonlyArray<Prepared>,
input: Omit<SharedPluginContext, "plugin">,
tools?: Selection,
) {
const buckets = make();
const ctx = Object.freeze({ ...input, plugin: buckets.registry });
Expand Down Expand Up @@ -57,7 +59,7 @@ export const run = Effect.fn("PluginHost.run")(function* (
);
}
return yield* Effect.try({
try: () => buckets.freeze(input.location.directory),
try: () => buckets.freeze(input.location.directory, tools),
catch: (cause) =>
new SetupError({
message: `plugin snapshot freeze failed: ${cause instanceof Error ? cause.message : String(cause)}`,
Expand Down
10 changes: 6 additions & 4 deletions packages/harness/src/plugin/registry.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import type { PluginRegistry } from "@codeworksh/plugin/plugin";
import { make as makeCatalog } from "../tool/registry.ts";
import { make as makeCatalog, type Selection } from "../tool/registry.ts";
import { declared } from "../tool/tool.ts";
import { make as makePrompt } from "./prompt/registry.ts";
import { render } from "./prompt/render.ts";
import { make as makeTools } from "./tool/registry.ts";
Expand All @@ -17,12 +18,13 @@ export const make = () => {
return {
registry: Object.freeze<PluginRegistry>({ tools: tools.registry, prompt: prompt.registry }),
close,
freeze: (directory: string) => {
freeze: (directory: string, selection?: Selection) => {
close();
const resolved = makeCatalog(tools.entries()).resolve();
const resolved = makeCatalog(tools.entries()).resolve(selection);
return {
tools: resolved,
systemPrompt: render({ prompt: prompt.snapshot(), tools: resolved.defs, directory }),
// Only declared tools: loading a deferred one must not change the prompt.
systemPrompt: render({ prompt: prompt.snapshot(), tools: resolved.defs.filter(declared), directory }),
};
},
};
Expand Down
Loading
Loading