@hachej/boring-agent 0.1.110 → 0.2.0

package/dist/self-evolving.d.ts

@@ -0,0 +1,55 @@
+import type { Extension, PromptSection, Registry } from '@earendil-works/pi-durable';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import type { Context } from '@earendil-works/chord';
+import type { Skill } from './skills.js';
+/** The folder, relative to the environment's working directory. */
+export declare const AGENT_FOLDER = ".agent";
+/** Largest part of `.agent/AGENTS.md` put in the prompt, in characters. */
+export declare const MAX_AGENT_INSTRUCTIONS = 16000;
+export interface SelfEvolutionError {
+    readonly path: string;
+    readonly message: string;
+}
+/** What one scan found and applied. `text` is what the `reload` tool and the person's `/reload` show. */
+export interface SelfEvolutionReport {
+    readonly extension: string;
+    readonly tools: {
+        readonly available: boolean;
+        readonly added: string[];
+        readonly changed: string[];
+        readonly removed: string[];
+        readonly current: string[];
+    };
+    readonly skills: string[];
+    readonly instructions: {
+        readonly present: boolean;
+        readonly characters: number;
+        readonly truncated: boolean;
+    };
+    readonly errors: SelfEvolutionError[];
+    readonly text: string;
+}
+export interface SelfEvolutionOptions {
+    /** The native extension name, one per workspace (`self-evolving:<workspace>`). */
+    readonly name: string;
+    /** The host's skills: listed first; an agent-written skill of the same name is refused. */
+    readonly skills: readonly Skill[];
+    /** Tool names the agent already has from the host; an agent-written tool may not take one. */
+    readonly reserved: readonly string[];
+    readonly parseSkill: (markdown: string) => Skill;
+    readonly skillsExtension: (name: string, skills: readonly Skill[]) => Extension;
+}
+export interface SelfEvolution {
+    /** The extension as it is now (the host's skills, `reload` and the agent-written section before the first scan). */
+    readonly current: () => Extension;
+    /** Skills now offered: the host's, then the agent's. */
+    readonly skills: () => readonly Skill[];
+    /** Install the current extension and keep the registry for later reloads. */
+    readonly install: (registry: Registry) => void;
+    /** Rescan `.agent/` through `env` and replace the extension in every registry it was installed in. */
+    readonly reload: (env: ExecutionEnv | undefined, context: Context) => Promise<SelfEvolutionReport>;
+}
+/** The labelled agent-written section: rendered on every request from `.agent/AGENTS.md`, after the host's instructions. */
+export declare function agentInstructionsSection(): PromptSection;
+export declare function createSelfEvolution(options: SelfEvolutionOptions): SelfEvolution;
+//# sourceMappingURL=self-evolving.d.ts.map

package/dist/self-evolving.js

@@ -0,0 +1,239 @@
+import { defineExtension, defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+import { jsonSchemaTool } from './json-schema-tool.js';
+/*
+ * Self-evolution (docs/architecture/SELF-EVOLUTION.md, laws SELF-1..4 in this package's README): an agent keeps its own standing
+ * instructions, skills and tools in the `.agent/` folder of its workspace and applies them with `reload`. Everything is read through
+ * the conversation's own ExecutionEnv (its FileSystem and, for tools, its `exec`): the host never imports or evaluates what the agent
+ * wrote. The result is one native extension per workspace, replaced in place with the native `registry.install()`.
+ */
+/** The folder, relative to the environment's working directory. */
+export const AGENT_FOLDER = '.agent';
+/** Largest part of `.agent/AGENTS.md` put in the prompt, in characters. */
+export const MAX_AGENT_INSTRUCTIONS = 16_000;
+const INSTRUCTIONS = `${AGENT_FOLDER}/AGENTS.md`, SKILLS = `${AGENT_FOLDER}/skills`, TOOLS = `${AGENT_FOLDER}/tools`;
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const ARGS_END = 'BORING_AGENT_TOOL_ARGS';
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const list = (names) => names.length ? names.join(', ') : 'none';
+const reason = (error) => error instanceof Error ? error.message : String(error);
+/** The labelled agent-written section: rendered on every request from `.agent/AGENTS.md`, after the host's instructions. */
+export function agentInstructionsSection() {
+    return {
+        key: 'agent-written',
+        render: async (input, context) => {
+            if (input.env === undefined)
+                return undefined;
+            const read = await input.env.readTextFile(INSTRUCTIONS, context);
+            if (!read.ok)
+                return undefined;
+            const text = read.value.trim();
+            if (!text)
+                return undefined;
+            const shown = text.length > MAX_AGENT_INSTRUCTIONS
+                ? `${text.slice(0, MAX_AGENT_INSTRUCTIONS)}\n[Truncated: ${INSTRUCTIONS} has ${text.length} characters; only the first ${MAX_AGENT_INSTRUCTIONS} are shown.]`
+                : text;
+            return `Agent-written: standing instructions you wrote for yourself in ${INSTRUCTIONS}. They come after the host's instructions and never override them.\n\n${shown}`;
+        },
+    };
+}
+/** Runs `run` through the conversation's environment with the arguments as one line of JSON on stdin; the output is the result. */
+async function runTool(description, env, args, context) {
+    if (env === undefined || typeof env.exec !== 'function')
+        return { content: [{ type: 'text', text: `${description.name} cannot run: this conversation has no execution environment.` }], isError: true };
+    let output = '';
+    const command = `{ ${description.run}\n} <<'${ARGS_END}'\n${JSON.stringify(args ?? {})}\n${ARGS_END}`;
+    const result = await env.exec(command, { onOutput: text => { output += text; } }, context);
+    if (!result.ok)
+        return { content: [{ type: 'text', text: `${description.name} failed: ${result.error.message}${output ? `\n${output}` : ''}` }], isError: true };
+    const failed = result.value.exitCode !== 0;
+    return { content: [{ type: 'text', text: output || '(no output)' }], ...(failed ? { isError: true, diagnostics: [{ severity: 'error', message: `${description.run} exited with code ${result.value.exitCode}` }] } : {}) };
+}
+/** The Harness validates each call's arguments against the agent-written schema before `run` starts (see `jsonSchemaTool`). */
+function toolOf(description) {
+    return jsonSchemaTool({
+        name: description.name, description: description.description, parameters: description.parameters,
+        execute: (args, api, context) => runTool(description, api.env, args, context),
+    });
+}
+/** Validates one tool description; returns it or a reason. Paths that `run` names under `.agent/` must exist. */
+async function describe(env, path, text, reserved, context) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        return `invalid JSON: ${reason(error)}`;
+    }
+    if (!isObject(value))
+        return 'a tool description is a JSON object { name, description, parameters, run }';
+    const extra = Object.keys(value).filter(key => !['name', 'description', 'parameters', 'run'].includes(key));
+    if (extra.length)
+        return `unknown field ${extra.join(', ')}`;
+    const { name, description, parameters, run } = value;
+    if (typeof name !== 'string' || !TOOL_NAME.test(name))
+        return 'name must be snake_case: a lowercase letter, then lowercase letters, digits or _ (at most 64)';
+    if (reserved.has(name))
+        return `the name ${name} is already a tool of this agent`;
+    if (typeof description !== 'string' || !description.trim() || description.length > 2000)
+        return 'description must be a non-empty string of at most 2000 characters';
+    if (!isObject(parameters) || parameters['type'] !== 'object')
+        return 'parameters must be a JSON Schema object with "type": "object"';
+    if (parameters['properties'] !== undefined && !isObject(parameters['properties']))
+        return 'parameters.properties must be an object';
+    if (parameters['required'] !== undefined && !(Array.isArray(parameters['required']) && parameters['required'].every(item => typeof item === 'string')))
+        return 'parameters.required must be a list of property names';
+    if (typeof run !== 'string' || !run.trim() || run.length > 2000 || /[\r\n\0]/.test(run))
+        return 'run must be one command line (at most 2000 characters)';
+    for (const token of run.split(/\s+/)) {
+        const script = token.replace(/^['"]|['"]$/g, '');
+        if (!script.startsWith(`${AGENT_FOLDER}/`) && !script.startsWith(`./${AGENT_FOLDER}/`))
+            continue;
+        const found = await env.exists(script, context);
+        if (!found.ok || !found.value)
+            return `run names ${script}, which does not exist`;
+    }
+    return { name, description: description.trim(), parameters, run: run.trim(), path };
+}
+/** Files directly in `directory` with `suffix`, sorted; `missing` when the directory does not exist. */
+async function filesIn(env, directory, suffix, context) {
+    const listed = await env.listDir(directory, context);
+    if (!listed.ok)
+        return listed.error.code === 'not_found' ? 'missing' : { error: listed.error.message };
+    return listed.value.filter(entry => entry.kind === 'file' && entry.name.endsWith(suffix)).map(entry => `${directory}/${entry.name}`).sort();
+}
+export function createSelfEvolution(options) {
+    const { name, parseSkill, skillsExtension } = options;
+    const hostSkills = [...options.skills];
+    const registries = new Set();
+    let agentSkills = [];
+    let described = new Map();
+    let queue = Promise.resolve();
+    const reloadTool = defineTool({
+        name: 'reload',
+        description: `Apply the changes you made to your own ${AGENT_FOLDER}/ folder in the workspace, then return what was added, changed and removed and every load error. `
+            + `${INSTRUCTIONS}: standing instructions for yourself, shown after the host's instructions on every request. `
+            + `${SKILLS}/<name>.md: skills (front matter with name and description between --- lines, then the instructions), loaded with load_skill. `
+            + `${TOOLS}/<name>.json: your own tools, {"name": "snake_case", "description": "...", "parameters": {a JSON Schema with "type": "object"}, "run": "a command run in the workspace, for example sh ${TOOLS}/<name>.sh"}; `
+            + 'the arguments arrive as one line of JSON on standard input and the command output is the result. Restore or delete the files and reload to undo a change.',
+        parameters: Type.Object({}, { additionalProperties: false }),
+        replay: 'safe',
+        executionMode: 'sequential',
+        execute: async (_args, api, context) => {
+            const report = await reload(api.env, context);
+            return { content: [{ type: 'text', text: report.text }], details: JSON.parse(JSON.stringify(report)) };
+        },
+    });
+    const section = agentInstructionsSection();
+    function build(tools) {
+        const skills = [...hostSkills, ...agentSkills];
+        const offered = skills.length ? skillsExtension(`${name}.skills`, skills) : undefined;
+        return defineExtension({
+            name,
+            tools: [reloadTool, ...(offered?.tools ?? []), ...tools.map(toolOf)],
+            sections: [...(offered?.sections ?? []), section],
+        });
+    }
+    let current = build([]);
+    async function scan(env, context) {
+        const errors = [];
+        // Instructions are rendered by the section on every request; the scan reports what it will show.
+        let instructions = { present: false, characters: 0, truncated: false };
+        const read = await env.readTextFile(INSTRUCTIONS, context);
+        if (read.ok) {
+            const text = read.value.trim();
+            instructions = { present: text.length > 0, characters: text.length, truncated: text.length > MAX_AGENT_INSTRUCTIONS };
+        }
+        else if (read.error.code !== 'not_found')
+            errors.push({ path: INSTRUCTIONS, message: read.error.message });
+        const skills = [];
+        const skillFiles = await filesIn(env, SKILLS, '.md', context);
+        if (typeof skillFiles === 'object' && !Array.isArray(skillFiles))
+            errors.push({ path: SKILLS, message: skillFiles.error });
+        for (const path of Array.isArray(skillFiles) ? skillFiles : []) {
+            const text = await env.readTextFile(path, context);
+            if (!text.ok) {
+                errors.push({ path, message: text.error.message });
+                continue;
+            }
+            let skill;
+            try {
+                skill = parseSkill(text.value);
+            }
+            catch (error) {
+                errors.push({ path, message: reason(error) });
+                continue;
+            }
+            if ([...hostSkills, ...skills].some(other => other.name === skill.name)) {
+                errors.push({ path, message: `a skill named ${skill.name} already exists` });
+                continue;
+            }
+            skills.push(skill);
+        }
+        const available = typeof env.exec === 'function';
+        const tools = [];
+        const toolFiles = await filesIn(env, TOOLS, '.json', context);
+        if (typeof toolFiles === 'object' && !Array.isArray(toolFiles))
+            errors.push({ path: TOOLS, message: toolFiles.error });
+        const files = Array.isArray(toolFiles) ? toolFiles : [];
+        if (!available && files.length)
+            errors.push({ path: TOOLS, message: `tools are unavailable here: this environment has no exec, so ${files.length} tool description(s) were not loaded` });
+        const reserved = new Set([...options.reserved, 'reload', 'load_skill']);
+        for (const path of available ? files : []) {
+            const text = await env.readTextFile(path, context);
+            if (!text.ok) {
+                errors.push({ path, message: text.error.message });
+                continue;
+            }
+            const result = await describe(env, path, text.value, new Set([...reserved, ...tools.map(tool => tool.name)]), context);
+            if (typeof result === 'string')
+                errors.push({ path, message: result });
+            else
+                tools.push(result);
+        }
+        return { errors, instructions, skills, tools, available };
+    }
+    async function apply(env, context) {
+        if (env === undefined) {
+            const errors = [{ path: AGENT_FOLDER, message: 'this conversation has no execution environment; nothing was changed' }];
+            return report({ available: false, added: [], changed: [], removed: [], current: [...described.keys()] }, agentSkills, { present: false, characters: 0, truncated: false }, errors);
+        }
+        const found = await scan(env, context);
+        const next = new Map(found.tools.map(tool => [tool.name, tool]));
+        const same = (a, b) => JSON.stringify([a.description, a.parameters, a.run]) === JSON.stringify([b.description, b.parameters, b.run]);
+        const added = [...next.keys()].filter(key => !described.has(key));
+        const changed = [...next.keys()].filter(key => described.has(key) && !same(described.get(key), next.get(key)));
+        const removed = [...described.keys()].filter(key => !next.has(key));
+        agentSkills = found.skills;
+        described = next;
+        current = build(found.tools);
+        // Native replacement in place: the next request of every conversation selecting this extension sees the new tools; a call
+        // already running finishes with the registration it started with.
+        for (const registry of registries)
+            registry.install(current);
+        return report({ available: found.available, added, changed, removed, current: [...next.keys()] }, found.skills, found.instructions, found.errors);
+    }
+    function report(tools, skills, instructions, errors) {
+        const lines = [
+            `Reloaded ${AGENT_FOLDER}/ (${name}).`,
+            tools.available
+                ? `Tools added: ${list(tools.added)}. Changed: ${list(tools.changed)}. Removed: ${list(tools.removed)}. Now: ${list(tools.current)}.`
+                : 'Tools: unavailable in this environment (no exec).',
+            `Skills: ${list(skills.map(skill => skill.name))}.`,
+            `Instructions: ${instructions.present ? `${INSTRUCTIONS}, ${instructions.characters} characters${instructions.truncated ? ` (only the first ${MAX_AGENT_INSTRUCTIONS} are shown)` : ''}, after the host's instructions` : 'none'}.`,
+            errors.length ? `Errors (${errors.length}):\n${errors.map(error => `- ${error.path}: ${error.message}`).join('\n')}` : 'Errors: none.',
+        ];
+        return { extension: name, tools, skills: skills.map(skill => skill.name), instructions, errors, text: lines.join('\n') };
+    }
+    const reload = (env, context) => {
+        const run = queue.then(() => apply(env, context));
+        queue = run.catch(() => undefined);
+        return run;
+    };
+    return {
+        current: () => current,
+        skills: () => [...hostSkills, ...agentSkills],
+        install: registry => { registries.add(registry); registry.install(current); },
+        reload,
+    };
+}

package/dist/skills.d.ts

@@ -0,0 +1,15 @@
+import type { Extension } from '@earendil-works/pi-durable';
+/** Names of skills and agents: a lowercase letter or digit, then lowercase letters, digits, `.`, `_` or `-` (at most 64). */
+export declare const NAME: RegExp;
+/** Instructions the agent loads on demand: only name and description occupy the system prompt. */
+export interface Skill {
+    readonly name: string;
+    readonly description: string;
+    readonly body: string;
+}
+/** Parse a `SKILL.md`-style document: `---` front matter with `name` and `description`, then the body. */
+export declare function parseSkill(markdown: string): Skill;
+export declare function validSkill(skill: Skill): Skill;
+/** A prompt section listing the skills and a `load_skill` tool returning one body. Usable without `defineAgent`. */
+export declare function createSkillsExtension(name: string, skills: readonly Skill[]): Extension;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.js

@@ -0,0 +1,51 @@
+import { defineExtension, defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+/** Names of skills and agents: a lowercase letter or digit, then lowercase letters, digits, `.`, `_` or `-` (at most 64). */
+export const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** Parse a `SKILL.md`-style document: `---` front matter with `name` and `description`, then the body. */
+export function parseSkill(markdown) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(markdown);
+    if (!match)
+        throw new TypeError('Skill needs front matter with name and description');
+    const fields = new Map();
+    for (const line of match[1].split(/\r?\n/)) {
+        const separator = line.indexOf(':');
+        if (separator > 0)
+            fields.set(line.slice(0, separator).trim(), line.slice(separator + 1).trim().replace(/^(["'])(.*)\1$/, '$2'));
+    }
+    const name = fields.get('name'), description = fields.get('description');
+    if (!name || !description)
+        throw new TypeError('Skill front matter needs name and description');
+    return validSkill({ name, description, body: match[2].trim() });
+}
+export function validSkill(skill) {
+    if (!NAME.test(skill.name))
+        throw new TypeError(`Invalid skill name: ${skill.name}`);
+    if (!skill.description.trim() || !skill.body.trim())
+        throw new TypeError(`Skill ${skill.name} needs a description and a body`);
+    return Object.freeze({ name: skill.name, description: skill.description.trim(), body: skill.body });
+}
+/** A prompt section listing the skills and a `load_skill` tool returning one body. Usable without `defineAgent`. */
+export function createSkillsExtension(name, skills) {
+    const known = new Map();
+    for (const skill of skills.map(validSkill)) {
+        if (known.has(skill.name))
+            throw new TypeError(`Duplicate skill: ${skill.name}`);
+        known.set(skill.name, skill);
+    }
+    const listing = [...known.values()].map(skill => `- ${skill.name}: ${skill.description}`).join('\n');
+    return defineExtension({
+        name,
+        sections: [{ key: 'skills', render: () => `Before starting a task that matches a skill, call load_skill with its name and follow the returned instructions. A user message that starts with /<skill-name> naming one of these skills is an explicit request: call load_skill for that skill first and follow it for the rest of the message.\n${listing}` }],
+        tools: [defineTool({
+                name: 'load_skill',
+                description: 'Load the full instructions of one listed skill.',
+                parameters: Type.Object({ name: Type.String() }, { additionalProperties: false }),
+                replay: 'safe',
+                execute: async (args) => {
+                    const skill = known.get(args.name);
+                    return { content: [{ type: 'text', text: skill ? skill.body : `Unknown skill "${args.name}". Available: ${[...known.keys()].join(', ')}` }] };
+                },
+            })],
+    });
+}

package/dist/tool-evidence.d.ts

@@ -0,0 +1,14 @@
+import type { ConversationId, EntryId, Harness, TaskId, ToolDiagnostic } from '@earendil-works/pi-durable';
+import type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';
+import type { Context } from '@earendil-works/chord';
+export interface NativeToolEvidence {
+    readonly entryId: EntryId;
+    readonly taskId: TaskId;
+    readonly assistantId: EntryId;
+    readonly conversationId: ConversationId;
+    readonly call: ToolCall;
+    readonly result: ToolResultMessage;
+    readonly diagnostics: readonly ToolDiagnostic[];
+}
+export declare function readToolEvidence(harness: Harness, owner: TaskId, ids: readonly EntryId[], context: Context): Promise<NativeToolEvidence[]>;
+//# sourceMappingURL=tool-evidence.d.ts.map

package/dist/tool-evidence.js

@@ -0,0 +1,54 @@
+import { AssistantEntry, ToolResultEntry, ToolTask } from '@earendil-works/pi-durable';
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function entryId(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+async function ownedBy(tx, id, owner) {
+    const visited = new Set();
+    let current = id;
+    while (current !== undefined && !visited.has(current) && visited.size < 128) {
+        if (current === owner)
+            return (await tx.task(owner)) !== undefined;
+        visited.add(current);
+        const task = await tx.task(current);
+        if (!task)
+            return false;
+        current = task.owner ?? (await tx.conversation(task.conversationId))?.owner?.taskId;
+    }
+    return false;
+}
+export async function readToolEvidence(harness, owner, ids, context) {
+    return harness.commit(async (tx) => {
+        const evidence = [];
+        for (const id of ids) {
+            const entry = await tx.entry(ToolResultEntry, id);
+            if (!entry?.byTaskId || entry.model?.length !== 1)
+                throw new Error('Missing native tool result');
+            const task = await tx.task(entry.byTaskId);
+            if (!task || task.kind !== ToolTask.definition.name || task.version !== ToolTask.definition.version
+                || task.conversationId !== entry.conversationId || task.state.status !== 'terminal'
+                || task.state.outcome.status !== 'completed' || !object(task.state.outcome.result)
+                || task.state.outcome.result.entryId !== id || !object(task.input)
+                || !entryId(task.input.assistant) || typeof task.input.callId !== 'string'
+                || !await ownedBy(tx, task.id, owner))
+                throw new Error('Unbound native tool result');
+            const result = entry.model[0];
+            if (result?.role !== 'toolResult' || result.isError || result.toolCallId !== task.input.callId
+                || entry.data.diagnostics.length !== 0)
+                throw new Error('Unusable native tool result');
+            const assistant = await tx.entry(AssistantEntry, task.input.assistant);
+            if (!assistant || assistant.conversationId !== entry.conversationId || assistant.model?.length !== 1
+                || assistant.model[0]?.role !== 'assistant')
+                throw new Error('Missing native tool call');
+            const calls = assistant.model[0].content.filter(item => item.type === 'toolCall' && item.id === result.toolCallId);
+            const call = calls[0];
+            if (calls.length !== 1 || call?.type !== 'toolCall' || call.name !== result.toolName)
+                throw new Error('Mismatched native tool call');
+            evidence.push(structuredClone({ entryId: id, taskId: task.id, assistantId: assistant.id,
+                conversationId: entry.conversationId, call, result, diagnostics: entry.data.diagnostics }));
+        }
+        return evidence;
+    }, context);
+}

package/dist/validation.d.ts

@@ -0,0 +1,38 @@
+import type { EntryId, Harness, TaskId } from '@earendil-works/pi-durable';
+import type { Context, JsonValue } from '@earendil-works/chord';
+import type { NativeToolEvidence } from './tool-evidence.js';
+export type { NativeToolEvidence } from './tool-evidence.js';
+export type OutputProposal = {
+    readonly text: string;
+    readonly evidence: readonly EntryId[];
+};
+export type ValidationResult<T extends JsonValue> = {
+    kind: 'valid';
+    value: T;
+} | {
+    kind: 'invalid';
+    errors: readonly string[];
+};
+export type OutputValidationResult<T extends JsonValue> = ValidationResult<T> | {
+    kind: 'producer-failed';
+    status: string;
+};
+export interface OutputValidationOptions<T extends JsonValue> {
+    readonly name: string;
+    readonly version: number;
+    readonly harness: () => Harness;
+    readonly authorize: (owner: TaskId, evidence: readonly NativeToolEvidence[], context: Context) => boolean | Promise<boolean>;
+    readonly validate: (text: string, evidence: readonly NativeToolEvidence[], context: Context) => ValidationResult<T> | Promise<ValidationResult<T>>;
+}
+export declare function createOutputValidation<T extends JsonValue>(options: OutputValidationOptions<T>): {
+    task: import("@earendil-works/pi-durable").Task<{
+        producer: TaskId<OutputProposal>;
+    }, {
+        phase: "wait";
+    } | {
+        phase: "validate";
+    }, OutputValidationResult<T>, object>;
+    extension: import("@earendil-works/pi-durable").Extension<import("@earendil-works/pi-durable").ToolRegistration>;
+    check: (proposal: OutputProposal, owner: TaskId, context: Context) => Promise<ValidationResult<T>>;
+};
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.js

@@ -0,0 +1,68 @@
+import { defineExtension, defineTask } from '@earendil-works/pi-durable';
+import { isJsonValue } from '@earendil-works/chord';
+import { readToolEvidence } from './tool-evidence.js';
+export function createOutputValidation(options) {
+    const { name, version, harness, authorize, validate } = options;
+    if (!name || name.startsWith('pi.') || !Number.isSafeInteger(version) || version < 1)
+        throw new TypeError('A host validation name and positive version are required');
+    const invalid = (message) => ({ kind: 'invalid', errors: [message] });
+    async function check(proposal, owner, context) {
+        if (!proposal || typeof proposal.text !== 'string' || !Array.isArray(proposal.evidence) || !proposal.evidence.length || proposal.evidence.length > 64
+            || proposal.evidence.some(id => !Number.isSafeInteger(id) || id <= 0)
+            || new Set(proposal.evidence).size !== proposal.evidence.length)
+            return invalid('Actual distinct tool result references are required');
+        const text = proposal.text;
+        const ids = Array.from(proposal.evidence);
+        try {
+            const evidence = await readToolEvidence(harness(), owner, ids, context);
+            if (await authorize(owner, structuredClone(evidence), context) !== true)
+                return invalid('Tool evidence is not authorized');
+            const returned = await validate(text, structuredClone(evidence), context);
+            let result;
+            if (returned?.kind === 'valid') {
+                const value = returned.value;
+                if (!isJsonValue(value))
+                    return invalid('Validator did not return a JSON value');
+                result = { kind: 'valid', value: structuredClone(value) };
+            }
+            else if (returned?.kind === 'invalid') {
+                const supplied = returned.errors;
+                if (!Array.isArray(supplied))
+                    return invalid('Validator did not return errors');
+                const errors = Array.from(supplied);
+                if (!errors.length || errors.some(error => typeof error !== 'string'))
+                    return invalid('Validator did not return errors');
+                result = { kind: 'invalid', errors };
+            }
+            else
+                return invalid('Validator did not return a valid result');
+            if (await authorize(owner, structuredClone(evidence), context) !== true)
+                return invalid('Tool evidence is no longer authorized');
+            return result;
+        }
+        catch {
+            return invalid('Native tool evidence or validation is unavailable');
+        }
+    }
+    const task = defineTask({
+        name, version, initial: () => ({ phase: 'wait' }),
+        phases: {
+            wait: async (running, runtime, context) => {
+                await runtime.commit(() => ({ status: 'waiting', on: [running.input.producer], policy: 'allSettled', checkpoint: { phase: 'validate' } }), context);
+            },
+            validate: async (running, runtime, context) => {
+                const [outcome] = await runtime.outcomes([running.input.producer], context);
+                if (!outcome)
+                    throw new Error('Native producer outcome is missing');
+                const result = outcome.status === 'completed'
+                    ? await check(outcome.result, running.input.producer, context)
+                    : { kind: 'producer-failed', status: outcome.status };
+                await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'completed', result } }), context);
+            },
+        },
+        abort: async (_running, runtime, context) => {
+            await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'aborted' } }), context);
+        },
+    });
+    return { task, extension: defineExtension({ name, tasks: [task] }), check };
+}

package/dist/workspaces.d.ts

@@ -0,0 +1,107 @@
+import type { ConversationId, EnvTarget, Session, ToolExecutionApi } from '@earendil-works/pi-durable';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import type { Context } from '@earendil-works/chord';
+import type { ResourceAccess } from '@hachej/boring-files';
+import type { WorkspaceResourceProvider } from '@hachej/boring-files/workspace';
+import type { GitRepository } from '@hachej/boring-files/git';
+/** One workspace as the tools of a call see it. */
+export interface WorkspaceBinding {
+    /** Stable workspace identity; scopes the guard's per-conversation baselines. Default: the provider id. */
+    readonly id?: string;
+    /** The workspace's single provider (`@hachej/boring-files/workspace`): its queue, reads, history and conditional writes. */
+    readonly files: WorkspaceResourceProvider;
+    /** The workspace root as the call's ExecutionEnv names it (the provider's `fs.cwd`). */
+    readonly root: string;
+    /** The ExecutionEnv Pi uses for this workspace. When present, a call whose `api.env` is another object is refused. */
+    readonly env?: ExecutionEnv;
+    /** The agent's principal in this workspace, chosen by the host when it opened it; tools use it unless they are given `resolveAccess`. */
+    readonly access?: ResourceAccess;
+    /** The workspace's working Git repository (`@hachej/boring-files/git`) over the same files, when it has one; `working_git` uses it. */
+    readonly repository?: GitRepository;
+}
+/** Same shape as `HarnessOptions.env`: the workspace of one call, or `undefined` when the conversation has none. */
+export type WorkspaceResolver = (target: EnvTarget, context: Context) => WorkspaceBinding | undefined | Promise<WorkspaceBinding | undefined>;
+/** What a tool needs a credential for: the tool, and the external server when there is one (an MCP server id). */
+export interface CredentialRequest {
+    readonly tool: string;
+    readonly server?: string;
+}
+/**
+ * The host's per-call credentials: a secret for the person behind the call, or `undefined` when they have none. Tools call it at
+ * execute time and keep the value only in memory: never in conversation state, a tool result or a log.
+ */
+export type CredentialResolver = (target: EnvTarget, context: Context, request: CredentialRequest) => string | undefined | Promise<string | undefined>;
+/** The single-workspace case: every call uses `binding`. */
+export declare function constantWorkspace(binding: WorkspaceBinding): WorkspaceResolver;
+/** A resolver as given, or a binding wrapped as a constant resolver; nothing: the workspace of the call's env (`withWorkspace`). */
+export declare function asWorkspaceResolver(workspace?: WorkspaceResolver | WorkspaceBinding): WorkspaceResolver | undefined;
+/** Mark `view` as a decoration of `env` (the same workspace, for example `confinedEnv`'s): the workspace of `view` is that of `env`. Returns `view`. */
+export declare function decorate<E extends ExecutionEnv>(env: ExecutionEnv, view: E): E;
+/**
+ * Attach `binding` to `env`: the workspace that comes with that env. The host's `HarnessOptions.env(target, context)` returns such an
+ * env, and every tool without its own `workspace` option uses its binding, so one host function resolves both. Returns `env`.
+ */
+export declare function withWorkspace<E extends ExecutionEnv>(env: E, binding: WorkspaceBinding): E;
+/** The workspace attached to `env` (`withWorkspace`, or the env of a `createWorkspaceCache` entry), if any. */
+export declare const workspaceOfEnv: (env: ExecutionEnv | undefined) => WorkspaceBinding | undefined;
+/** The target Pi would pass to `HarnessOptions.env` for this call: its conversation, the agent's `cwd`, committed reads. */
+export declare function callTarget(api: ToolExecutionApi, context: Context): Promise<EnvTarget>;
+/**
+ * Resolve the workspace of a tool call, or the reason it has none: through `resolver` (or one binding), or without either from the env
+ * Pi handed the call (`withWorkspace`).
+ */
+export declare function workspaceFor(resolver: WorkspaceResolver | WorkspaceBinding | undefined, api: ToolExecutionApi, context: Context): Promise<{
+    readonly binding: WorkspaceBinding;
+} | {
+    readonly refused: string;
+}>;
+/**
+ * The conversation whose workspace a conversation uses: itself, or for a conversation a task owns (a subagent's child), the
+ * conversation of that task, transitively. Read-only; the mapping never changes, so a host may memoise it.
+ */
+export declare function rootConversation(session: Pick<Session, 'commit'>, id: ConversationId, context: Context): Promise<ConversationId>;
+/** A workspace the cache opened: a binding with its env, and how to close it. */
+export interface OpenedWorkspace extends WorkspaceBinding {
+    readonly env: ExecutionEnv;
+    readonly close?: () => void | Promise<void>;
+}
+export interface WorkspaceCacheOptions<W extends OpenedWorkspace = OpenedWorkspace> {
+    /** The workspace key of a call (for example the owner of the conversation), or `undefined`: the conversation has no workspace. */
+    readonly key: (target: EnvTarget, context: Context) => string | undefined | Promise<string | undefined>;
+    /** Open the workspace of `key`: one provider instance over one env. Called once per key while it stays open. */
+    readonly open: (key: string, context: Context) => W | Promise<W>;
+    /** A native cwd view over this same workspace. The workspace owner closes any resources it acquires. Other cwd values refuse without this factory. */
+    readonly atCwd?: (workspace: W, cwd: string, context: Context) => W['env'] | Promise<W['env']>;
+    /** Close a workspace this long after its last use, when nothing holds it (default 10 minutes; `Infinity`: never). */
+    readonly idleMs?: number;
+    /**
+     * Whether `key` is still in use beyond what the cache sees, checked before an idle close (for example: the harness has live
+     * tasks). Pi does not report when a call stops using its env, so a host whose tool calls can outlast `idleMs` answers here.
+     */
+    readonly busy?: (key: string) => boolean | Promise<boolean>;
+    /** A close that failed. Must not throw. */
+    readonly onError?: (error: unknown, key: string) => void;
+}
+/** A borrowed workspace: `release` returns the hold and never closes the workspace itself. */
+export interface WorkspaceLease<W extends OpenedWorkspace = OpenedWorkspace> {
+    readonly workspace: W;
+    readonly release: () => void;
+}
+export interface WorkspaceCache<W extends OpenedWorkspace = OpenedWorkspace> {
+    /** `HarnessOptions.env`: the env of the call's workspace. */
+    readonly env: (target: EnvTarget, context: Context) => Promise<ExecutionEnv | undefined>;
+    /** The tools' resolver: the binding of the same workspace instance as `env`. */
+    readonly workspace: (target: EnvTarget, context: Context) => Promise<W | undefined>;
+    /** Borrow the workspace of `key` (a viewer or HTTP route, after authentication): kept open until every lease is released. */
+    readonly acquire: (key: string, context: Context) => Promise<WorkspaceLease<W>>;
+    /** The keys open now. */
+    readonly keys: () => string[];
+    /** Close every workspace (host shutdown). */
+    readonly close: () => Promise<void>;
+}
+/**
+ * One open workspace per key, opened on first use and closed when idle. The cache owns what `open` returns: a lease or a call
+ * borrows it, and only the cache closes it (idle, or `close()`), never a viewer that stops looking.
+ */
+export declare function createWorkspaceCache<W extends OpenedWorkspace = OpenedWorkspace>(options: WorkspaceCacheOptions<W>): WorkspaceCache<W>;
+//# sourceMappingURL=workspaces.d.ts.map