// Tool catalog. Harness tools run in the service: block edits on the agent's own records, and // xrpc, which runs a script that calls XRPC methods (src/codemode.ts). Computer tools run on a // runner on one of the owner's computers. // // Computer tools are pi's own built-ins (read, bash, edit, write, grep, find, ls): same names, // descriptions and parameters, plus one optional `computer` argument, so each call can target a // different computer. The runner executes them with pi's implementations (see runner.ts). // // Every tool also takes a required `call_intention`, listed first: a short phrase saying what the // call is for, which clients show as the call's label (the same field Identity uses). It's checked // and removed before the tool runs, so no implementation sees it. import type { Tool } from '@earendil-works/pi-ai' import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from '@earendil-works/pi-coding-agent' import { now, type ToolDefinition } from './records.ts' type Schema = Record const str = (description: string): Schema => ({ type: 'string', description }) const bool = (description: string): Schema => ({ type: 'boolean', description }) const obj = (properties: Record, required: string[]): Schema => ({ type: 'object', properties, required, additionalProperties: false, }) const computerParam = str( 'Computer to run on (a name from ). Omit to use your computer for this session. Calls on different computers run at the same time.', ) /** The field every tool call carries for display. */ export const CALL_INTENTION = 'call_intention' const CALL_INTENTION_GUIDANCE = 'Always give call_intention first: a short phrase, shown to your owner while the call runs, saying what the call does (the action, not your reasoning).' const intentionParam: Schema = { type: 'string', // At least three characters once trimmed (as intentionProblem checks): a pattern, not minLength, // which OpenAI's strict tool schemas don't take. Some providers' constrained decoding matches a // pattern against the whole string (a bare \S would mean one character), so it reads the same // anchored or not. pattern: '[\\s\\S]*\\S[\\s\\S]+\\S[\\s\\S]*', description: "What this call does, for your owner, e.g. 'Check which tests fail'. A few words; write it before the other arguments.", } /** The schema with call_intention as its first, required property. */ function withIntention(schema: Schema): Schema { const { [CALL_INTENTION]: _reserved, ...properties } = (schema.properties ?? {}) as Record const required = ((schema.required ?? []) as string[]).filter((k) => k !== CALL_INTENTION) return { ...schema, properties: { [CALL_INTENTION]: intentionParam, ...properties }, required: [CALL_INTENTION, ...required] } } /** A call's stated intention, trimmed, if it has one. */ export function callIntention(args: unknown): string | undefined { const v = args && typeof args === 'object' && !Array.isArray(args) ? (args as Record)[CALL_INTENTION] : undefined const t = typeof v === 'string' ? v.trim() : '' return t || undefined } /** Why a call's arguments can't run for lack of an intention, if they can't. */ export function intentionProblem(tool: string, args: unknown): string | undefined { if ((callIntention(args)?.length ?? 0) >= 3) return undefined return `${tool} requires call_intention: a short phrase saying what the call does. Nothing was run.` } /** The arguments a tool's implementation gets: everything but call_intention. */ export function withoutIntention(args: T): T { if (!args || typeof args !== 'object' || Array.isArray(args)) return args const { [CALL_INTENTION]: _i, ...rest } = args as Record return rest as T } interface Spec { name: string description: string parameters: Schema executor: 'harness' | 'computer' /** Computer tools that only read are dispatched without asking for approval. */ readOnly?: boolean /** * Harness tools only: false runs the tool without the agent's write lock and alongside other * tools. xrpc takes the lock per write instead, so a slow network read doesn't hold up block edits. */ locks?: boolean } /** Whether a tool runs under the agent's write lock. */ export const takesLock = (spec: Spec) => spec.executor === 'harness' && spec.locks !== false /** How the default system prompt tells the agent to read a block that isn't loaded. */ /** The system prompt's sentences about blocks. Older config records are brought up to date on load (PROMPT_MIGRATIONS). */ export const BLOCKS_INTRO = 'Your pinned blocks appear below in , in full. They are recompiled every turn, so they always show the current value, including edits you made earlier in this conversation. Keep them current: record what you learn about your owner, yourself, and ongoing work using the block tools.' export const BLOCK_READ_HINT = "Blocks listed under are shown by label only. To read one, call block_read (or xrpc getRecord). Pin a block with block_pin only if you need it every turn; reading it once doesn't need pinning. Everything else in your space (threads, messages, tool results) can be looked up with xrpc; see ." /** The system prompt's sentence about computer tools. */ export const COMPUTERS_INTRO = "You can act on your owner's computers (listed in ) with the computer tools." /** Earlier versions of those sentences, and what replaces each. */ export const PROMPT_MIGRATIONS: [string, string][] = [ ['Blocks listed under are not loaded; use block_load to read one.', BLOCK_READ_HINT], [ "Blocks listed under are not loaded; read one with the xrpc tool: `return await tools.com_atproto_repo_getRecord({ collection: 'ai.languid.memory.block', rkey: '