@hachej/boring-agent 0.4.35 → 0.4.36

package/dist/agents.d.ts

@@ -3,9 +3,10 @@ import type { Context } from '@earendil-works/chord';
 import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
 import type { SelfEvolutionReport } from './self-evolving.js';
 import type { DelegateOptions } from './delegate.js';
+import type { StruggleOptions } from './struggle.js';
 import type { Skill, SkillSource } from './skills.js';
 export type { SelfEvolutionError, SelfEvolutionReport } from './self-evolving.js';
-export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, staticSkills } from './skills.js';
+export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, skillInFolder, staticSkills } from './skills.js';
 export type { LiveSkills, LiveSkillsOptions, Skill, SkillError, SkillFileSystem, SkillListing, SkillSource, SkillsOptions, SkillVersions } from './skills.js';
 export { jsonSchemaTool } from './json-schema-tool.js';
 export type { JsonObjectSchema, JsonSchemaToolOptions } from './json-schema-tool.js';
@@ -41,6 +42,11 @@ export interface AgentSpec {
      * (docs/architecture/SELF-EVOLUTION.md). Off by default: without it nothing reads `.agent/` (SELF-1).
      */
     readonly selfEvolving?: boolean;
+    /**
+     * The agent reports its own failures (`@hachej/boring-agent/struggle`): the `report_bug` tool and content-free automatic events, on by
+     * default. `{ sink, sinkTimeoutMs, agentText }` tune it (default sink: `setStruggleSink`, else one log line); `false` turns it off.
+     */
+    readonly struggle?: false | Pick<StruggleOptions, 'sink' | 'sinkTimeoutMs' | 'agentText'>;
     /**
      * The workspace instance this agent works in; names the per-workspace extension `self-evolving:<workspace>`. With `selfEvolving` and
      * no `workspace`, the agent works in a workspace per conversation: `inWorkspace(name)` gives the agent of one workspace.

package/dist/agents.js

@@ -3,7 +3,8 @@ import { AgentDoc, defineExtension } from '@earendil-works/pi-durable';
 import { createSelfEvolution } from './self-evolving.js';
 import { NAME, isSkillArray, liveSkills, staticSkills, validSkill } from './skills.js';
 import { createDelegateTool } from './delegate.js';
-export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, staticSkills } from './skills.js';
+import { REPORT_BUG_TOOL, createStruggleExtension } from './struggle.js';
+export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, skillInFolder, staticSkills } from './skills.js';
 export { jsonSchemaTool } from './json-schema-tool.js';
 export { createDelegateTool, DELEGATE_DETAILS_KIND, DELEGATE_TOOL } from './delegate.js';
 /** Turn an agent described as data into native extensions and a native agent configuration. */
@@ -31,7 +32,12 @@ export function defineAgent(spec) {
         ? (spec.skills.length ? [staticSkills(spec.skills, { name: skillsName }).extension] : [])
         : [liveSkills(spec.skills, { name: skillsName }).extension];
     const listed = (skills) => Object.freeze(skills.map(skill => Object.freeze({ name: skill.name, description: skill.description.trim() })));
-    const reserved = [...tools, ...(spec.extensions ?? []).flatMap(extension => extension.tools ?? [])].map(tool => tool.name);
+    const hostTools = [...tools, ...(spec.extensions ?? []).flatMap(extension => extension.tools ?? [])].map(tool => tool.name);
+    const reports = spec.struggle !== false;
+    // A self-evolving agent may already keep its own `.agent/tools/report_bug.json`: it gets the automatic events and no tool of ours.
+    if (reports)
+        own.push(createStruggleExtension({ ...(spec.struggle || {}), agent: spec.id, tool: !spec.selfEvolving && !hostTools.includes(REPORT_BUG_TOOL) }));
+    const reserved = hostTools;
     /** The agent as one native configuration: its own extensions, the host's, and with `evolution` the per-workspace one last. */
     function assemble(selected, evolution, inWorkspace) {
         const initial = evolution?.current();

package/dist/audit.d.ts

@@ -0,0 +1,31 @@
+import type { Extension } from '@earendil-works/pi-durable';
+import type { JsonValue } from '@earendil-works/chord';
+/** One finished tool call. `id` is stable for the call: a call replayed by recovery reports the same `id`, so the sink can drop it. */
+export interface AuditRecord {
+    readonly id: string;
+    /** Milliseconds since the epoch. */
+    readonly at: number;
+    readonly user: string;
+    readonly conversationId: number;
+    readonly tool: string;
+    readonly isError: boolean;
+    /** What `redact` kept of the call's arguments. Absent without `redact`, or when it threw. */
+    readonly arguments?: JsonValue;
+    /** What `redact` kept of the result's text. Absent without `redact`, or when it threw. */
+    readonly output?: JsonValue;
+    /** `redact` threw: the values were dropped, the call is still recorded. */
+    readonly redactionFailed?: true;
+}
+export interface AuditExtensionOptions {
+    /** The host's audit store. The tool's result waits for it; a sink that fails never fails the tool. */
+    readonly sink: (record: AuditRecord) => void | Promise<void>;
+    /** Who acts: a fixed id, or read per conversation for a harness shared by several people. */
+    readonly user: string | ((conversationId: number) => string);
+    /** Called once for the arguments and once for the output. Without it no value is recorded, only which tool ran and how it ended. */
+    readonly redact?: (value: JsonValue, field: 'arguments' | 'output', tool: string) => JsonValue;
+    /** The extension's native name. Default `boring.audit`. */
+    readonly name?: string;
+}
+/** An opt-in native extension: select it in an agent's `extensions` or with `conversation.configure`. It brings no tools and changes no result. */
+export declare function createAuditExtension(options: AuditExtensionOptions): Extension;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.js

@@ -0,0 +1,32 @@
+// @hachej/boring-agent/audit: a record of what an agent's tools did, for the host's own audit store. The host owns the store (`sink`), who
+// acted (`user`) and what may be kept (`redact`); this module only observes native tool calls through the `afterTool` hook.
+import { ToolTask, defineExtension, hook } from '@earendil-works/pi-durable';
+const outputText = (result) => (result.output ?? []).map(part => part.type === 'text' ? part.text : '').join('');
+/** An opt-in native extension: select it in an agent's `extensions` or with `conversation.configure`. It brings no tools and changes no result. */
+export function createAuditExtension(options) {
+    const { sink, user, redact } = options;
+    return defineExtension({
+        name: options.name ?? 'boring.audit',
+        hooks: [hook(ToolTask, {
+                afterTool: async (call, result, api) => {
+                    const conversationId = Number(api.conversationId);
+                    let values = {};
+                    if (redact) {
+                        try {
+                            values = { arguments: redact(call.arguments, 'arguments', call.name), output: redact(outputText(result), 'output', call.name) };
+                        }
+                        catch {
+                            values = { redactionFailed: true };
+                        }
+                    }
+                    try {
+                        await sink({ id: `${conversationId}:${String(api.taskId)}:${call.id}`, at: Date.now(), user: typeof user === 'string' ? user : user(conversationId), conversationId, tool: call.name, isError: result.isError === true, ...values });
+                    }
+                    catch (error) {
+                        console.error(JSON.stringify({ level: 'error', event: 'audit-sink-failed', tool: call.name, name: error instanceof Error ? error.name : 'Error' }));
+                    }
+                    return undefined;
+                },
+            })],
+    });
+}

package/dist/delegate.d.ts

@@ -1,4 +1,4 @@
-import type { AgentChange, ConversationId, EntryId, ToolRegistration, Tx } from '@earendil-works/pi-durable';
+import type { AgentChange, ConversationId, EntryId, TaskId, ToolRegistration, Tx } from '@earendil-works/pi-durable';
 import type { Usage } from '@earendil-works/pi-ai';
 export declare const DELEGATE_TOOL = "delegate";
 /** `DelegateDetails.kind`: how a UI recognises a sub-agent call's details, whatever the tool is named. */
@@ -76,6 +76,12 @@ export interface DelegateMeter {
     /** Called once, after the last `record`, when the call ends. A throw is ignored. */
     readonly close: (end: DelegateEnd) => void | Promise<void>;
 }
+/** Which call made a child, for the host's log lines: the parent's tool call and task, and the request id of the child's input. */
+export interface DelegateCallIds {
+    readonly callId: string;
+    readonly taskId: TaskId;
+    readonly requestId: string;
+}
 export interface DelegateOptions {
     /**
      * The child agent, usually a `defineAgent` result (its `id` and native `agent` change). The child conversation selects exactly its
@@ -93,7 +99,7 @@ export interface DelegateOptions {
      * configured: the host copies what the child must carry from the parent (user, workspace binding, permissions) with `tx`.
      * It runs once per child (never on a replay that finds the existing child); a throw aborts the commit, so no child exists.
      */
-    readonly onChild?: (parent: ConversationId, child: ConversationId, tx: Tx) => void | Promise<void>;
+    readonly onChild?: (parent: ConversationId, child: ConversationId, tx: Tx, ids: DelegateCallIds) => void | Promise<void>;
     /** Concurrency, rate, task size and timeout limits (`DelegateLimits`). */
     readonly limits?: DelegateLimits;
     /**
@@ -102,7 +108,7 @@ export interface DelegateOptions {
      * The tool sends the handle each child model response (`DelegateModelEvent`) and closes it when the call ends. A throw fails
      * the call. The kit keeps no log.
      */
-    readonly meter?: (parent: ConversationId, child: ConversationId) => DelegateMeter | Promise<DelegateMeter>;
+    readonly meter?: (parent: ConversationId, child: ConversationId, ids: DelegateCallIds) => DelegateMeter | Promise<DelegateMeter>;
     /**
      * Names of the tools a child may have: its enabled tools become the intersection of this list with what it would otherwise
      * get, written as Pi's own tool filter (`pi.agent` `tools`) in the commit that creates it. Unset: no restriction.

package/dist/delegate.js

@@ -34,6 +34,7 @@ export function createDelegateTool(options) {
             const inherited = (await api.agent(context)).extensions.filter(isGuard);
             const agent = withGuards(child, inherited);
             const parent = api.conversationId, ledger = limits === undefined ? undefined : ledgerOf(limits);
+            const ids = { callId: api.callId, taskId: api.taskId, requestId: `${name}:${api.taskId}` };
             let opened;
             try {
                 opened = await api.commit(async (tx) => {
@@ -49,7 +50,7 @@ export function createDelegateTool(options) {
                     await configure(tx, created.id, agent);
                     if (options.childTools !== undefined)
                         await allowTools(tx, created.id, options.childTools, api);
-                    await options.onChild?.(parent, created.id, tx);
+                    await options.onChild?.(parent, created.id, tx, ids);
                     return { id: created.id };
                 }, context);
             }
@@ -64,7 +65,7 @@ export function createDelegateTool(options) {
             // `end` is set where the call's outcome is known; a throw ends `cancelled` only when the call itself was aborted.
             let meter, end = 'failed', timer;
             try {
-                meter = await options.meter?.(parent, childId);
+                meter = await options.meter?.(parent, childId, ids);
                 const startedAt = await api.memo('delegate.startedAt', Date.now(), context);
                 const progress = childProgress(api, childId, meter);
                 const details = (status, counts, error) => ({
@@ -76,7 +77,7 @@ export function createDelegateTool(options) {
                 const conversation = await api.conversation(childId, context);
                 if (conversation === undefined)
                     throw new Error(`Delegate conversation ${childId} is missing`);
-                const submission = await conversation.submit({ type: 'input', content: args.task, requestId: `${name}:${api.taskId}` }, context);
+                const submission = await conversation.submit({ type: 'input', content: args.task, requestId: ids.requestId }, context);
                 // The timeout reuses the cancel path: aborting the child settles its submission `aborted`, reported below as a timeout.
                 let timedOut = false;
                 if (limits?.timeoutMs !== undefined)

package/dist/metering.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from '@earendil-works/chord';
-import type { Conversation, Harness } from '@earendil-works/pi-durable';
+import type { Conversation, ConversationId, Harness } from '@earendil-works/pi-durable';
 import type { Models, Usage } from '@earendil-works/pi-ai';
 import { type SqliteConnection, type SqliteSettings } from '@hachej/boring-files/sqlite';
 /** Small flat JSON-safe values the host passes through untouched (a plan, a tenant): at most 16 keys, strings of at most 256 characters. */
@@ -129,6 +129,32 @@ export interface Meter {
 }
 /** The longest `message` preview a reservation carries. */
 export declare const MESSAGE_PREVIEW_LENGTH = 280;
+/** Which delegate call made a child (`DelegateCallIds`; this module stays free of the delegate tool). */
+export interface ChildCallIds {
+    readonly callId: string;
+    readonly taskId: number;
+    readonly requestId: string;
+}
+/** A `DelegateMeter`: pass the function `meterFromSink` returns as `DelegateOptions.meter`. */
+export interface ChildMeter {
+    readonly record: (event: {
+        readonly entryId: number;
+        readonly provider: string;
+        readonly model: string;
+        readonly usage: Usage;
+    }) => void | Promise<void>;
+    readonly close: (end: 'done' | 'failed' | 'cancelled' | 'timeout') => void | Promise<void>;
+}
+export interface MeterFromSinkOptions extends Pick<MeterOptions, 'sink' | 'price' | 'models' | 'markup' | 'onError'> {
+    /** Who pays for the child, usually read from the parent's identity. */
+    readonly scope: MeteringScope | ((parent: ConversationId, child: ConversationId, ids: ChildCallIds) => MeteringScope | Promise<MeteringScope>);
+}
+/**
+ * `DelegateOptions.meter` over a `MeteringSink`: a child's spend goes to the same ledger as its parent's, as one run of the child under the
+ * call's request id. A refused reservation throws, which fails the delegate call before the child runs. A rerun reattaching to the child
+ * reserves and reports again: the sink is idempotent on `runId` and `usageId`.
+ */
+export declare function meterFromSink(options: MeterFromSinkOptions): (parent: ConversationId, child: ConversationId, ids: ChildCallIds) => Promise<ChildMeter>;
 /** Meter submissions of native conversations into the host's `sink`. */
 export declare function createMeter(options: MeterOptions): Meter;
 /**

package/dist/metering.js

@@ -20,6 +20,63 @@ export class MeteringRefused extends Error {
 const runIdOf = (conversationId, requestId) => `run:${conversationId}:${requestId}`;
 /** The longest `message` preview a reservation carries. */
 export const MESSAGE_PREVIEW_LENGTH = 280;
+/**
+ * `DelegateOptions.meter` over a `MeteringSink`: a child's spend goes to the same ledger as its parent's, as one run of the child under the
+ * call's request id. A refused reservation throws, which fails the delegate call before the child runs. A rerun reattaching to the child
+ * reserves and reports again: the sink is idempotent on `runId` and `usageId`.
+ */
+export function meterFromSink(options) {
+    const { sink, onError } = options;
+    const price = options.price ?? catalogPrice(options.models);
+    const markup = options.markup ?? 1;
+    if (!(markup > 0))
+        throw new TypeError('markup must be a positive number');
+    return async (parent, child, ids) => {
+        if (sink.isEnabled?.() === false)
+            return { record: () => undefined, close: () => undefined };
+        const scope = typeof options.scope === 'function' ? await options.scope(parent, child, ids) : options.scope;
+        const run = { ...scope, conversationId: Number(child), requestId: ids.requestId, runId: runIdOf(Number(child), ids.requestId) };
+        const reserved = await sink.reserveRun({ ...run, kind: 'input', message: '', content: '' });
+        if ('kind' in reserved)
+            throw new MeteringRefused(reserved.reason);
+        const reservation = reserved.reservationId ? { reservationId: reserved.reservationId } : {};
+        // A rerun after a crash reattaches here. A run the ledger already finished must not take the replayed usage on top of a charged hold.
+        if (sink.openRuns && !(await sink.openRuns()).some(open => open.runId === run.runId))
+            return { record: () => undefined, close: () => undefined };
+        let recorded = 0, lost = false, unpriced = false;
+        return {
+            record: async (event) => {
+                const model = { provider: event.provider, id: event.model };
+                try {
+                    const { billedMicros } = await sink.recordUsage({ ...run, ...reservation, usageId: `entry:${child}:${event.entryId}`, model, bucket: `model:${event.provider}/${event.model}`, usage: event.usage, amountMicros: Math.ceil(Math.max(0, price(event.usage, model)) * markup) });
+                    recorded++;
+                    if (billedMicros === 0 && !isZero(event.usage))
+                        unpriced = true;
+                }
+                catch (error) {
+                    lost = true;
+                    onError?.(`recordUsage failed (${run.runId})`, error);
+                }
+            },
+            close: async (end) => {
+                try {
+                    if (lost)
+                        await sink.releaseRun({ ...run, ...reservation, reason: 'usage-write-failed' });
+                    // Tokens that priced to nothing are work it cannot account for, as in `createMeter`: the hold is charged, not settled as free.
+                    else if (unpriced)
+                        await sink.releaseRun({ ...run, ...reservation, reason: 'fallback-charge' });
+                    else if (end === 'done' || recorded > 0)
+                        await sink.settleRun({ ...run, ...reservation, status: end === 'done' ? 'done' : 'unanswered' });
+                    else
+                        await sink.releaseRun({ ...run, ...reservation, reason: end === 'failed' ? 'error-before-usage' : 'cancelled' });
+                }
+                catch (error) {
+                    onError?.(`closing the child's run failed (${run.runId})`, error);
+                }
+            },
+        };
+    };
+}
 function previewOf(content) {
     const parts = typeof content === 'string' ? [content] : Array.isArray(content)
         ? content.map(part => part?.type === 'text' && typeof part.text === 'string' ? part.text : part?.type === 'image' ? '[image]' : '') : [];

package/dist/skills.d.ts

@@ -9,6 +9,7 @@ export interface Skill {
     readonly description: string;
     readonly body: string;
 }
+/** Say which folder a skill's relative paths start from, for a skill built without a directory source. `load_skill` names it to the agent. */
 export declare function skillInFolder(skill: Skill, folder: string): Skill;
 /** Parse a `SKILL.md`-style document: `---` front matter with `name` and `description`, then the body. */
 export declare function parseSkill(markdown: string): Skill;
@@ -79,6 +80,12 @@ export interface SkillsOptions {
      * a skill that could not be read also answers as unknown (its reason still goes to `onDiagnostics`).
      */
     readonly visible?: (conversationId: ConversationId, skills: readonly Skill[]) => readonly Skill[] | Promise<readonly Skill[]>;
+    /**
+     * A `load_skill` call for a name this conversation does not see: the host may answer with a skill it keeps out of the listing, or
+     * undefined for an unknown name. It wins over `visible`, so it is the host's own permission check. Called only with a valid skill name.
+     * A skill of another name, an invalid one or a throw answers as unknown.
+     */
+    readonly loadUnlisted?: (conversationId: ConversationId, name: string) => Skill | undefined | Promise<Skill | undefined>;
     /** The listing section's text before the `- name: description` lines. Default: call load_skill first, `/<skill-name>` is explicit. */
     readonly intro?: string;
 }

package/dist/skills.js

@@ -3,6 +3,7 @@ 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}$/;
 const skillFolders = new WeakMap();
+/** Say which folder a skill's relative paths start from, for a skill built without a directory source. `load_skill` names it to the agent. */
 export function skillInFolder(skill, folder) {
     skillFolders.set(skill, folder);
     return skill;
@@ -413,6 +414,17 @@ function skillsExtension(live, options, fs) {
         const names = new Set((await visible(at(), all)).map(skill => skill.name));
         return all.filter(skill => names.has(skill.name));
     }
+    async function unlisted(conversationId, name) {
+        if (!options.loadUnlisted || !NAME.test(name))
+            return undefined;
+        try {
+            const found = await options.loadUnlisted(conversationId, name);
+            return found?.name === name ? validSkill(found) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     const parameters = fs
         ? Type.Object({ name: Type.String(), path: Type.Optional(Type.String({ description: 'A companion file of the skill, relative to its folder.' })) }, { additionalProperties: false })
         : Type.Object({ name: Type.String() }, { additionalProperties: false });
@@ -437,7 +449,7 @@ function skillsExtension(live, options, fs) {
                         ({ known, errors } = await live.miss(context));
                         shown = await seen(known, () => api.conversationId);
                     }
-                    const skill = shown.find(candidate => candidate.name === args.name);
+                    const skill = shown.find(candidate => candidate.name === args.name) ?? await unlisted(api?.conversationId, args.name);
                     if (!skill) {
                         const failed = visible ? undefined : errors.find(error => error.name === args.name);
                         return text(failed ? `Skill "${args.name}" could not be loaded (${failed.path}): ${failed.message}` : `Unknown skill "${args.name}". Available: ${shown.map(entry => entry.name).join(', ')}`);

package/dist/struggle.d.ts

@@ -0,0 +1,55 @@
+import type { Extension } from '@earendil-works/pi-durable';
+export declare const REPORT_BUG_TOOL = "report_bug";
+/**
+ * `tool_error`: a tool answered with an error. `tool_retry`: since the person's last message, one tool ran 3 times with the same arguments,
+ * or failed 3 times. `rephrase`: the message shares at least 75% of its words with one of the person's 2 previous messages (3 words or more).
+ * `correction`: the message opens by saying the agent is wrong; a bare « non » answering a question does not count. `abandoned`: the person
+ * stopped a run mid-task, seen when the attempt ends or at the next request. `report_bug`: the agent called the tool.
+ */
+export type StruggleKind = 'tool_error' | 'tool_retry' | 'rephrase' | 'correction' | 'abandoned' | 'report_bug';
+export declare const BUG_CATEGORIES: readonly ["tool_failed", "impossible", "person_says_wrong"];
+export type BugCategory = (typeof BUG_CATEGORIES)[number];
+/** Content-free: never the person's words, and no text a model wrote unless the host turned on `agentText`. */
+export interface AgentStruggle {
+    readonly event: 'agent.struggle';
+    readonly kind: StruggleKind;
+    readonly agent: string;
+    /** Stable for one agent, kind and tool: the host files one task per fingerprint. */
+    readonly fingerprint: string;
+    readonly conversationId: number;
+    readonly taskId: number;
+    readonly tool?: string;
+    /** On `report_bug`: which of `BUG_CATEGORIES` the agent chose. */
+    readonly category?: BugCategory;
+    /** Never set here: a host that knows the request adds it in its sink. */
+    readonly req_id?: string;
+    /** With `agentText` only. */
+    readonly summary?: string;
+    readonly tried?: string;
+}
+export type StruggleSink = (struggle: AgentStruggle) => void | Promise<void>;
+/**
+ * The host's sink for every agent of this process that names none: the agent home calls it once, so apps write no code. One sink per
+ * process: a process serving several tenants gives each agent its own through `defineAgent({ struggle: { sink } })`.
+ */
+export declare function setStruggleSink(sink: StruggleSink | undefined): void;
+export interface StruggleOptions {
+    /** The agent's id, in the fingerprint. */
+    readonly agent: string;
+    /** Default: the sink of `setStruggleSink`, else one log line. A throw is ignored: reporting never fails the agent. */
+    readonly sink?: StruggleSink;
+    /** How long the agent waits for the sink, in milliseconds. Default 2000; a late sink keeps running unwatched. */
+    readonly sinkTimeoutMs?: number;
+    /**
+     * Let `report_bug` ask for the agent's own `summary` and `tried`, scrubbed of emails and long numbers. Off by default: free text a model
+     * writes can carry a name or a diagnosis no scrub catches, so turn it on only where such text may reach the sink.
+     */
+    readonly agentText?: boolean;
+    /** False when the agent already has a tool named `report_bug`. Default true. */
+    readonly tool?: boolean;
+    /** Default `agent.<agent>.struggle`. */
+    readonly name?: string;
+}
+/** The S6 extension: the `report_bug` tool and the automatic events. It changes no result and no request. */
+export declare function createStruggleExtension(options: StruggleOptions): Extension;
+//# sourceMappingURL=struggle.d.ts.map

package/dist/struggle.js

@@ -0,0 +1,130 @@
+// @hachej/boring-agent/struggle: an app's agent reports its own failures (fleet standard S6), so the fleet can fix them without a person
+// noticing. `defineAgent` selects this extension by default. It reads run events through native hooks and sends only kinds, tool names and
+// ids to the host's sink: the person's words are read to classify them and never leave this module.
+import { createHash } from 'node:crypto';
+import { GenerationTask, ToolTask, defineExtension, hook } from '@earendil-works/pi-durable';
+import { jsonSchemaTool } from './json-schema-tool.js';
+export const REPORT_BUG_TOOL = 'report_bug';
+export const BUG_CATEGORIES = ['tool_failed', 'impossible', 'person_says_wrong'];
+/** Without a host sink an event is one structured log line, so nothing is lost before a host wires one. */
+const logLine = struggle => { console.log(JSON.stringify({ level: 'warn', ...struggle })); };
+let hostSink;
+/**
+ * The host's sink for every agent of this process that names none: the agent home calls it once, so apps write no code. One sink per
+ * process: a process serving several tenants gives each agent its own through `defineAgent({ struggle: { sink } })`.
+ */
+export function setStruggleSink(sink) { hostSink = sink; }
+const MAX_TEXT = 200, MAX_SEEN = 500, SINK_TIMEOUT_MS = 2000;
+const scrub = (text) => text.replace(/\S+@\S+/g, '[email]').replace(/\d[\d\s.-]{2,}\d/g, '[number]').slice(0, MAX_TEXT);
+const userText = (message) => message.role !== 'user' ? '' : typeof message.content === 'string' ? message.content
+    : message.content.map(part => part.type === 'text' ? part.text : '').join(' ');
+const asked = (message) => message?.role === 'assistant'
+    && message.content.map(part => part.type === 'text' ? part.text : '').join('').trim().endsWith('?');
+/** The person's words only: the block a point-and-speak message or a mention adds is not what they said. */
+const words = (text) => new Set(text.replace(/^<target>.*?<\/target>/s, '').replace(/<file[\s\S]*?<\/file>/g, '').toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []);
+function rephrased(text, earlier) {
+    const said = words(text);
+    if (said.size < 3)
+        return false;
+    return earlier.some(other => {
+        const before = words(other);
+        const shared = [...said].filter(word => before.has(word)).length;
+        return shared / new Set([...said, ...before]).size >= 0.75;
+    });
+}
+const WRONG = /^\s*((no|non)[,.! ]+)?(c['’]est faux|c['’]est pas (ça|ca)|ce n['’]est pas (ça|ca)|tu te trompes|vous vous trompez|faux\b|that['’]s wrong|you['’]re wrong|wrong\b|incorrect\b|not what i asked)/i;
+const BARE_NO = /^\s*(no|non)\s*[.!]*\s*$/i;
+/** The S6 extension: the `report_bug` tool and the automatic events. It changes no result and no request. */
+export function createStruggleExtension(options) {
+    const seen = new Set();
+    const emit = async (once, ids, kind, fields = {}) => {
+        const key = `${String(ids.conversationId)}:${once}`;
+        if (seen.has(key))
+            return;
+        if (seen.size >= MAX_SEEN)
+            seen.delete(seen.values().next().value);
+        seen.add(key);
+        const fingerprint = createHash('sha256').update(JSON.stringify([options.agent, kind, fields.tool ?? null])).digest('hex').slice(0, 16);
+        // Hooks run before the result commits: a sink that hangs must not hold the agent.
+        let timer;
+        try {
+            await Promise.race([
+                (options.sink ?? hostSink ?? logLine)({ event: 'agent.struggle', kind, agent: options.agent, fingerprint, conversationId: Number(ids.conversationId), taskId: Number(ids.taskId), ...fields }),
+                new Promise(resolve => { timer = setTimeout(resolve, options.sinkTimeoutMs ?? SINK_TIMEOUT_MS); }),
+            ]);
+        }
+        catch { /* the host's sink owns its failures */ }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const tool = jsonSchemaTool({
+        name: REPORT_BUG_TOOL,
+        description: "Tell the app's team that something is broken: a tool failed, something you should be able to do is impossible, or the person says you are wrong.",
+        parameters: { type: 'object', properties: {
+                category: { type: 'string', enum: BUG_CATEGORIES },
+                tool: { type: 'string', description: 'The name of the tool involved, if any.' },
+                ...(options.agentText ? {
+                    summary: { type: 'string', description: "What is broken, in one short general sentence: never the person's words, name, health, money or any personal value." },
+                    tried: { type: 'string', description: 'What you tried, in general terms, with no personal value.' },
+                } : {}),
+            }, required: ['category'] },
+        execute: async (args, api, context) => {
+            // The model writes these: only a tool the agent really has, and an enum, may leave. A name it made up could carry anything.
+            const known = (await api.agent(context)).extensions.some(extension => extension.tools?.some(each => each.name === args.tool));
+            await emit(`bug:${api.callId}`, api, 'report_bug', {
+                ...(BUG_CATEGORIES.includes(args.category) ? { category: args.category } : {}),
+                ...(args.tool && known ? { tool: args.tool } : {}),
+                ...(options.agentText && args.summary ? { summary: scrub(args.summary) } : {}),
+                ...(options.agentText && args.tried ? { tried: scrub(args.tried) } : {}),
+            });
+            return { output: [{ type: 'text', text: 'Reported to the team. Carry on with the person.' }] };
+        },
+    });
+    return defineExtension({
+        name: options.name ?? `agent.${options.agent}.struggle`,
+        tools: options.tool === false ? [] : [tool],
+        hooks: [
+            hook(ToolTask, {
+                afterTool: async (call, result, api) => {
+                    if (result.isError === true && call.name !== REPORT_BUG_TOOL)
+                        await emit(`error:${call.id}`, api, 'tool_error', { tool: call.name });
+                    return undefined;
+                },
+            }),
+            hook(GenerationTask, {
+                afterResponse: async (message, api) => { if (message.stopReason === 'aborted')
+                    await emit(`stop:${String(api.taskId)}`, api, 'abandoned'); },
+                beforeRequest: async ({ messages }, api) => {
+                    const users = messages.flatMap((message, index) => message.role === 'user' ? [index] : []);
+                    const last = users.at(-1);
+                    if (last === undefined)
+                        return undefined;
+                    if (last === messages.length - 1) {
+                        const text = userText(messages[last]);
+                        const previous = messages[last - 1];
+                        if (WRONG.test(text) || (BARE_NO.test(text) && !asked(previous)))
+                            await emit(`wrong:${last}`, api, 'correction');
+                        if (rephrased(text, users.slice(-3, -1).map(index => userText(messages[index]))))
+                            await emit(`rephrase:${last}`, api, 'rephrase');
+                        if (previous?.role === 'assistant' && previous.stopReason === 'aborted')
+                            await emit(`stopped:${last}`, api, 'abandoned');
+                        return undefined;
+                    }
+                    const same = new Map(), failed = new Map();
+                    const bump = (counts, key) => { const count = (counts.get(key) ?? 0) + 1; counts.set(key, count); return count; };
+                    for (const message of messages.slice(last + 1)) {
+                        if (message.role === 'assistant') {
+                            for (const part of message.content)
+                                if (part.type === 'toolCall' && bump(same, JSON.stringify([part.name, part.arguments])) === 3)
+                                    await emit(`retry:${last}:${part.name}`, api, 'tool_retry', { tool: part.name });
+                        }
+                        else if (message.role === 'toolResult' && message.isError && bump(failed, message.toolName) === 3)
+                            await emit(`retry:${last}:${message.toolName}`, api, 'tool_retry', { tool: message.toolName });
+                    }
+                    return undefined;
+                },
+            }),
+        ],
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.4.35",
+  "version": "0.4.36",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -69,6 +69,14 @@
       "types": "./dist/file-types.d.ts",
       "import": "./dist/file-types.js"
     },
+    "./audit": {
+      "types": "./dist/audit.d.ts",
+      "import": "./dist/audit.js"
+    },
+    "./struggle": {
+      "types": "./dist/struggle.d.ts",
+      "import": "./dist/struggle.js"
+    },
     "./ask-user": {
       "types": "./dist/ask-user.d.ts",
       "import": "./dist/ask-user.js"
@@ -180,8 +188,8 @@
     "@earendil-works/pi-durable": "~1.4.0",
     "@earendil-works/pi-ai": "~1.4.0",
     "@earendil-works/chord": "~1.4.0",
-    "@hachej/boring-files": "^0.4.35",
-    "@hachej/boring-ui-kit": "^0.4.35",
+    "@hachej/boring-files": "^0.4.36",
+    "@hachej/boring-ui-kit": "^0.4.36",
     "typebox": "1.3.27",
     "xlsx": "^0.20.3"
   },