@xingular/harness 1.3.1-unstable.0 → 1.3.1-unstable.2

package/dist/sdk/agents/profiles.d.ts

@@ -5,7 +5,7 @@ export declare const PROFILE_NAME: RegExp;
 export declare const RESERVED_PROFILE_NAMES: readonly string[];
 export declare const PROFILE_COLORS: readonly ["blue", "green", "yellow", "red", "magenta", "cyan", "orange", "purple"];
 export type ProfileColor = (typeof PROFILE_COLORS)[number];
-export type ProfileSource = 'builtin' | 'global' | 'project' | 'variant';
+export type ProfileSource = 'builtin' | 'global' | 'project' | 'variant' | 'plugin';
 /** Where a person's own profile file lives. */
 export type ProfileScope = 'global' | 'project';
 /** Which variant a profile's subagent runs: a scope's head or version, none, or the parent's (null). */
@@ -54,12 +54,21 @@ export declare function formatVariant(variant: ProfileVariant): string | null;
 export declare function parseProfile(text: string, name: string, source: ProfileSource, path: string | null): AgentProfile;
 /** The file text for a profile, as `createProfile` writes it. */
 export declare function profileText(profile: ProfileDefinition): string;
+/**
+ * A profile a package brings. It is named by its frontmatter, since such packages are often written
+ * for other agent harnesses whose files are not named after their agents. What only those
+ * harnesses understand is dropped: their tool names are translated, a model without a provider
+ * (`inherit`, `sonnet`) is left to the parent, and a package never pins a variant or plugins. A
+ * tool list of which nothing translates keeps the subagent read-only rather than widening it.
+ */
+export declare function parsePackageProfile(text: string, path: string): AgentProfile;
 /**
  * Every profile a session in `cwd` can use. An unreadable file is reported in `problems`; it hides
  * nothing, so a broken project file leaves the global or built-in profile of that name in force.
+ * `packageProfiles` are the profile files of the session's switched-on packages.
  */
-export declare function listProfiles(root: string, cwd?: string | null, variantDir?: string | null): ProfileListing;
-export declare function resolveProfile(root: string, cwd: string | null | undefined, name: string, variantDir?: string | null): AgentProfile | null;
+export declare function listProfiles(root: string, cwd?: string | null, variantDir?: string | null, packageProfiles?: readonly string[]): ProfileListing;
+export declare function resolveProfile(root: string, cwd: string | null | undefined, name: string, variantDir?: string | null, packageProfiles?: readonly string[]): AgentProfile | null;
 /** Writes a new profile file from the template, or a copy of `from`. Refuses to overwrite one. */
 export declare function createProfile(root: string, cwd: string | null | undefined, input: {
     name: string;
@@ -74,7 +83,7 @@ export declare function removeProfile(root: string, cwd: string | null | undefin
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export declare const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean, researchContext?: PlanResearchContext): {
+export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean, researchContext?: PlanResearchContext, packageProfiles?: readonly string[]): {
     id: string;
     title: string;
     body: string;

package/dist/sdk/agents/profiles.js

@@ -1,9 +1,10 @@
 // Agent profiles (PROP-0029): named bundles a subagent starts from, with its instructions, colour,
 // tools, plugins, variant, model and effort. They come from four places, later ones winning:
 // built-ins in code, `<data root>/agents/*.md`, `<project>/.xingular/agents/*.md`; a variant's own
-// c5 subagents fill in names nobody else took. Profiles only narrow what the parent has.
+// c5 subagents, then the profiles of switched-on packages, fill in names nobody else took.
+// Profiles only narrow what the parent has.
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { EFFORTS } from "../core/effort.js";
 import { invalid, notFound } from "../core/errors.js";
 import { parse, serialize } from "../core/frontmatter.js";
@@ -139,11 +140,49 @@ function variantDefinitions(variantDir) {
             }];
     });
 }
+// Tool names that agent plugins written for other harnesses use, as this harness names them.
+const FOREIGN_TOOLS = {
+    Read: 'read', Grep: 'grep', Glob: 'find', LS: 'ls', Edit: 'edit', MultiEdit: 'edit', Write: 'write', Bash: 'bash',
+    WebSearch: 'web_search', WebFetch: 'web_fetch', TodoWrite: 'todo_write'
+};
+const READ_ONLY_TOOLS = ['read', 'grep', 'find', 'ls'];
+/**
+ * A profile a package brings. It is named by its frontmatter, since such packages are often written
+ * for other agent harnesses whose files are not named after their agents. What only those
+ * harnesses understand is dropped: their tool names are translated, a model without a provider
+ * (`inherit`, `sonnet`) is left to the parent, and a package never pins a variant or plugins. A
+ * tool list of which nothing translates keeps the subagent read-only rather than widening it.
+ */
+export function parsePackageProfile(text, path) {
+    const parsed = parse(text);
+    if (!parsed)
+        throw invalid('The profile needs a frontmatter block between --- lines.');
+    const front = parsed.front;
+    const name = optionalText(front.name, 'name');
+    if (!name || !PROFILE_NAME.test(name))
+        throw invalid('A profile name uses lowercase letters, digits, - and _, and starts with a letter or digit.');
+    if (RESERVED_PROFILE_NAMES.includes(name))
+        throw invalid(reservedRefusal(name));
+    const description = optionalText(front.description, 'description');
+    if (!description)
+        throw invalid('The profile needs a description.');
+    const declared = stringList(front.tools, 'tools');
+    const tools = declared ? [...new Set(declared.flatMap((tool) => FOREIGN_TOOLS[tool] ?? (/^[a-z][a-z0-9_]*$/.test(tool) ? [tool] : [])))] : null;
+    const color = typeof front.color === 'string' && PROFILE_COLORS.includes(front.color) ? front.color : 'blue';
+    const model = typeof front.model === 'string' && front.model.includes('/') ? front.model : null;
+    const effort = typeof front.effort === 'string' && EFFORTS.includes(front.effort) ? front.effort : null;
+    return {
+        name, description, color, instructions: parsed.body.trim(),
+        tools: tools && !tools.length ? READ_ONLY_TOOLS : tools, plugins: null, variant: null, model, effort,
+        source: 'plugin', path
+    };
+}
 /**
  * Every profile a session in `cwd` can use. An unreadable file is reported in `problems`; it hides
  * nothing, so a broken project file leaves the global or built-in profile of that name in force.
+ * `packageProfiles` are the profile files of the session's switched-on packages.
  */
-export function listProfiles(root, cwd, variantDir) {
+export function listProfiles(root, cwd, variantDir, packageProfiles = []) {
     const profiles = new Map();
     const problems = [];
     for (const definition of BUILTIN_PROFILES)
@@ -154,12 +193,25 @@ export function listProfiles(root, cwd, variantDir) {
     for (const definition of variantDefinitions(variantDir))
         if (!profiles.has(definition.name))
             profiles.set(definition.name, definition);
+    // A package cannot replace a profile a person, the harness or the variant already has.
+    for (const path of packageProfiles) {
+        try {
+            const profile = parsePackageProfile(readFileSync(path, 'utf8'), path);
+            if (!profiles.has(profile.name))
+                profiles.set(profile.name, profile);
+            else
+                problems.push({ name: profile.name, source: 'plugin', path, error: `A ${profiles.get(profile.name).source} profile already has this name, so the package's is not used.` });
+        }
+        catch (error) {
+            problems.push({ name: basename(path, '.md'), source: 'plugin', path, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
     return { profiles: [...profiles.values()].sort((left, right) => left.name.localeCompare(right.name)), problems };
 }
-export function resolveProfile(root, cwd, name, variantDir) {
+export function resolveProfile(root, cwd, name, variantDir, packageProfiles = []) {
     if (!PROFILE_NAME.test(name))
         return null;
-    return listProfiles(root, cwd, variantDir).profiles.find(profile => profile.name === name) ?? null;
+    return listProfiles(root, cwd, variantDir, packageProfiles).profiles.find(profile => profile.name === name) ?? null;
 }
 function scopeDir(root, cwd, scope) {
     const dirs = profileDirs(root, cwd);
@@ -214,8 +266,8 @@ export function removeProfile(root, cwd, input) {
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export function profileSection(root, cwd, variantDir, planResearchOnly = false, researchContext) {
-    const { profiles } = listProfiles(root, cwd, variantDir);
+export function profileSection(root, cwd, variantDir, planResearchOnly = false, researchContext, packageProfiles = []) {
+    const { profiles } = listProfiles(root, cwd, variantDir, packageProfiles);
     const listed = planResearchOnly
         ? profiles.filter(profile => researchContext
             ? planResearchEligibility(profile, researchContext).eligible

package/dist/sdk/annotations/bridge.d.ts

@@ -29,6 +29,8 @@ export declare class NotesBridge {
     private settingsFile;
     /** Starts the bridge (once) on the port and token kept from last time, so the app's snippet stays valid. */
     start(): Promise<BridgeInfo>;
+    /** What a window loads, once the bridge is listening. */
+    current(): BridgeInfo | null;
     private listen;
     list(): BridgeWindow[];
     /** Sends one helper operation to a window and waits for its JSON reply. */

package/dist/sdk/annotations/bridge.js

@@ -71,6 +71,10 @@ export class NotesBridge {
         this.starting ??= this.listen().finally(() => { this.starting = null; });
         return this.starting;
     }
+    /** What a window loads, once the bridge is listening. */
+    current() {
+        return this.info;
+    }
     async listen() {
         const settingsFile = this.settingsFile();
         if (existsSync(settingsFile))

package/dist/sdk/annotations/capture.d.ts

@@ -28,7 +28,7 @@ export interface CaptureWindow {
 /** One comment the person submitted in the inspector's popover. */
 export interface InspectResult extends CaptureEnvelope {
     body: string;
-    action: 'save' | 'queue' | 'send';
+    action: 'save' | 'send';
 }
 export interface InspectState {
     /** False once the person or the page ended it. */
@@ -44,16 +44,43 @@ export interface InspectState {
 }
 /** Opens a DevTools connection to a running app; tests replace it. */
 export type AppConnector = (endpoint: string) => Promise<Browser>;
+/** A desktop app on this computer that answers on a DevTools port. */
+export interface DevToolsApp {
+    endpoint: string;
+    port: number;
+    /** The title of its first window, or what the app calls itself. */
+    name: string;
+    /** What the DevTools port reports, such as `Chrome/126.0` or `Electron/31.0`. */
+    browser: string;
+    electron: boolean;
+    windows: number;
+}
+/** Reads a JSON answer from a loopback DevTools port, or null when nothing answers in time; tests replace it. */
+export type DevToolsFetch = (url: string, timeoutMs: number) => Promise<unknown>;
+/** Starts an app the person named; tests replace it. */
+export type AppSpawner = (command: string, args: string[]) => void;
 export interface AnnotationCaptureOptions {
     stateDir: string;
     launch?: Launcher;
     network?: NetworkPolicy;
     connect?: AppConnector;
     bridge?: NotesBridge;
+    fetchJson?: DevToolsFetch;
+    spawnApp?: AppSpawner;
+    /** A free loopback port for an app started here; tests replace it. */
+    freePort?: () => Promise<number>;
+    /** How long a started app has to open its DevTools port, in milliseconds. */
+    launchTimeoutMs?: number;
 }
+/** Where apps started with `--remote-debugging-port` or `--inspect` usually listen. */
+export declare const DEVTOOLS_PORTS: readonly [9222, 9223, 9224, 9225, 9226, 9227, 9228, 9229, 9230];
+/** The program inside a macOS `.app` bundle, or the path itself. */
+export declare function appExecutable(path: string): string;
 export declare class AnnotationCapture {
     private readonly options;
     private readonly targets;
+    /** Ports the person attached to or started an app on, checked again by `discover`. */
+    private readonly knownPorts;
     private readonly inspecting;
     private readonly network;
     readonly bridge: NotesBridge;
@@ -62,11 +89,14 @@ export declare class AnnotationCapture {
     private target;
     private replace;
     private call;
-    /** What `key` captures in now. */
+    /** What `key` captures in now, with the script to load while it captures a bridge. */
     describe(key: string): {
         kind: CaptureTargetSpec['kind'];
         app: NoteApp | null;
         inspecting: boolean;
+        bridge?: {
+            snippet: string;
+        };
     };
     /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
     attach(key: string, spec: CaptureTargetSpec): Promise<{
@@ -76,6 +106,18 @@ export declare class AnnotationCapture {
         bridge?: BridgeInfo;
     }>;
     windows(key: string): Promise<CaptureWindow[]>;
+    /** Apps on this computer that answer on a DevTools port: the usual ports and any used before. */
+    discover(ports?: readonly number[]): Promise<DevToolsApp[]>;
+    /**
+     * Starts the app the person named with a DevTools port and attaches to its windows. A macOS `.app`
+     * bundle starts its own program. The app keeps running when the capture ends.
+     */
+    launchApp(key: string, path: string, args?: readonly string[]): Promise<{
+        kind: 'cdp';
+        app: NoteApp | null;
+        windows: CaptureWindow[];
+        endpoint: string;
+    }>;
     /** Switches to another window or tab of the target; an inspector there starts again. */
     selectWindow(key: string, id: string): Promise<void>;
     /** Shows the capture window, at `url` when given. Captures in the browser again if an app was attached. */

package/dist/sdk/annotations/capture.js

@@ -5,8 +5,11 @@
 // - `bridge`: app windows that loaded the page bridge script (a macOS web view has no DevTools port).
 // The person selects text, clicks an element, or inspects with the popover; the front end pulls
 // what they did through the page helper.
+import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { join } from 'node:path';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { basename, join } from 'node:path';
 import { readBrowserConfig } from "../browser/config.js";
 import { NetworkPolicy } from "../browser/network.js";
 import { BrowserSession, fileName, launchBrowser } from "../browser/session.js";
@@ -14,6 +17,56 @@ import { NotesBridge } from "./bridge.js";
 import { evaluateIsolated } from "./isolated.js";
 import { pageCall, pageReply } from "./pageScript.js";
 import { validateUrl } from "./store.js";
+/** Where apps started with `--remote-debugging-port` or `--inspect` usually listen. */
+export const DEVTOOLS_PORTS = [9222, 9223, 9224, 9225, 9226, 9227, 9228, 9229, 9230];
+const PROBE_MS = 400;
+const fetchJson = async (url, timeoutMs) => {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        return response.ok ? await response.json() : null;
+    }
+    catch {
+        return null;
+    }
+};
+const spawnApp = (command, args) => {
+    // The app is the person's: it keeps running after the terminal ends.
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => undefined);
+    child.unref();
+};
+const freePort = () => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+        const address = server.address();
+        server.close(() => typeof address === 'object' && address ? resolve(address.port) : reject(new Error('No free port.')));
+    });
+});
+/** The program inside a macOS `.app` bundle, or the path itself. */
+export function appExecutable(path) {
+    if (!/\.app\/?$/.test(path))
+        return path;
+    const folder = join(path, 'Contents', 'MacOS');
+    if (!existsSync(folder))
+        throw new Error(`${path} has no Contents/MacOS folder.`);
+    const programs = readdirSync(folder).filter((name) => !name.startsWith('.') && statSync(join(folder, name)).isFile());
+    const named = basename(path.replace(/\/$/, ''), '.app');
+    const program = programs.find((name) => name === named) ?? programs[0];
+    if (!program)
+        throw new Error(`${path} has no program in Contents/MacOS.`);
+    return join(folder, program);
+}
+function describeApp(port, version, list) {
+    const agent = typeof version['User-Agent'] === 'string' ? version['User-Agent'] : '';
+    const electron = /Electron\/([\d.]+)/.exec(agent);
+    const browser = electron ? `Electron/${electron[1]}` : typeof version.Browser === 'string' ? version.Browser : 'DevTools';
+    const pages = Array.isArray(list) ? list.filter((entry) => !!entry && typeof entry === 'object' && entry.type === 'page' && !/^(?:devtools|chrome-extension):/.test(String(entry.url ?? ''))) : [];
+    const title = pages.map((page) => typeof page.title === 'string' ? page.title.trim() : '').find(Boolean);
+    const product = /\)\s+([A-Za-z][\w .-]*?)\/[\d.]+\s+(?:Chrome|Electron)\//.exec(agent)?.[1];
+    return { endpoint: `http://127.0.0.1:${port}`, port, name: (title || product || browser).slice(0, 120), browser, electron: !!electron, windows: pages.length };
+}
 const IDLE_MS = 60 * 60_000;
 const LOOPBACK = /^(?:https?|wss?):\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/;
 const connectApp = async (endpoint) => {
@@ -130,6 +183,8 @@ class WebTarget {
 export class AnnotationCapture {
     options;
     targets = new Map();
+    /** Ports the person attached to or started an app on, checked again by `discover`. */
+    knownPorts = new Set();
     inspecting = new Map();
     network;
     bridge;
@@ -170,10 +225,11 @@ export class AnnotationCapture {
     async call(key, operation) {
         return pageReply((await this.target(key).evaluate(operation)).reply);
     }
-    /** What `key` captures in now. */
+    /** What `key` captures in now, with the script to load while it captures a bridge. */
     describe(key) {
         const target = this.targets.get(key);
-        return { kind: target?.kind ?? 'web', app: target?.app ?? null, inspecting: this.inspecting.has(key) };
+        const bridge = target?.kind === 'bridge' ? this.bridge.current() : null;
+        return { kind: target?.kind ?? 'web', app: target?.app ?? null, inspecting: this.inspecting.has(key), ...(bridge ? { bridge: { snippet: bridge.snippet } } : {}) };
     }
     /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
     async attach(key, spec) {
@@ -189,6 +245,9 @@ export class AnnotationCapture {
             const name = spec.name?.trim() || `App at ${new URL(spec.endpoint).host}`;
             const target = new CdpTarget(browser, { kind: 'cdp', name: name.slice(0, 200) });
             await this.replace(key, target);
+            const port = Number(new URL(spec.endpoint).port);
+            if (port)
+                this.knownPorts.add(port);
             return { kind: 'cdp', app: target.app, windows: await target.windows() };
         }
         if (spec.kind === 'bridge') {
@@ -202,6 +261,48 @@ export class AnnotationCapture {
     windows(key) {
         return this.target(key).windows();
     }
+    /** Apps on this computer that answer on a DevTools port: the usual ports and any used before. */
+    async discover(ports = []) {
+        const probe = this.options.fetchJson ?? fetchJson;
+        const wanted = [...new Set([...DEVTOOLS_PORTS, ...this.knownPorts, ...ports])].filter((port) => Number.isInteger(port) && port > 0 && port < 65536);
+        const found = await Promise.all(wanted.map(async (port) => {
+            const version = await probe(`http://127.0.0.1:${port}/json/version`, PROBE_MS);
+            if (!version || typeof version !== 'object')
+                return null;
+            // A Node `--inspect` port answers too, but has no windows to annotate.
+            if (typeof version.webSocketDebuggerUrl !== 'string' && typeof version.Browser !== 'string')
+                return null;
+            if (/^node(?:\.js)?\//i.test(String(version.Browser ?? '')))
+                return null;
+            return describeApp(port, version, await probe(`http://127.0.0.1:${port}/json/list`, PROBE_MS));
+        }));
+        return found.filter((app) => app !== null).sort((left, right) => left.port - right.port);
+    }
+    /**
+     * Starts the app the person named with a DevTools port and attaches to its windows. A macOS `.app`
+     * bundle starts its own program. The app keeps running when the capture ends.
+     */
+    async launchApp(key, path, args = []) {
+        const program = appExecutable(path.trim());
+        if (!program)
+            throw new Error('Give the path of the app to start.');
+        const port = await (this.options.freePort ?? freePort)();
+        (this.options.spawnApp ?? spawnApp)(program, [...args, `--remote-debugging-port=${port}`]);
+        this.knownPorts.add(port);
+        const endpoint = `http://127.0.0.1:${port}`;
+        const probe = this.options.fetchJson ?? fetchJson;
+        const deadline = Date.now() + (this.options.launchTimeoutMs ?? 20_000);
+        for (;;) {
+            if (await probe(`${endpoint}/json/version`, PROBE_MS))
+                break;
+            if (Date.now() > deadline)
+                throw new Error(`${basename(path)} did not open a DevTools port. Only Chromium and Electron apps can be inspected this way.`);
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+        const name = basename(path.trim().replace(/\/$/, '')).replace(/\.app$/, '');
+        const attached = await this.attach(key, { kind: 'cdp', endpoint, name });
+        return { kind: 'cdp', app: attached.app, windows: attached.windows, endpoint };
+    }
     /** Switches to another window or tab of the target; an inspector there starts again. */
     async selectWindow(key, id) {
         const inspecting = this.inspecting.has(key);

package/dist/sdk/annotations/delivery.d.ts

@@ -23,27 +23,29 @@ export type SendResult = {
 } | {
     state: 'empty';
     ids: [];
+    unconfirmed: number;
 };
-export type NoteAction = 'save' | 'queue' | 'send';
+export type NoteAction = 'save' | 'send';
 export interface NoteDeliveryOptions {
     root: () => string;
     bus: Bus;
     terminals: () => TerminalSender | null;
+    /** Waits between tries to send notes held back while a run ends; tests shorten it. */
+    retryDelays?: readonly number[];
 }
 export declare class NoteDeliveries {
     private readonly options;
     private readonly sending;
+    private readonly retrying;
+    private readonly again;
     constructor(options: NoteDeliveryOptions);
     private changed;
-    queue(id: string, expectedVersion: number | undefined, sessionId: string, options?: {
-        autoSend?: boolean;
-        confirm?: boolean;
-    }): store.Note;
-    dequeue(id: string, expectedVersion: number | undefined): store.Note;
+    /** Shares a saved note with the session; it waits there, unsent. */
+    share(id: string, expectedVersion: number | undefined, sessionId: string): store.Note;
     /**
-     * Creates a note and acts on it in one step: what the popover's three buttons do. `trusted` is
-     * false when the comment came from a script the page could reach; a send then waits in the queue
-     * for the person to confirm it.
+     * Creates a note and acts on it in one step: what the popover's two buttons do. With a session the
+     * note is always shared with it. `trusted` is false when the comment came from a script the page
+     * could reach; it then waits for the person to confirm it before it is ever sent.
      */
     createAndAct(input: store.NoteInput, action: NoteAction, sessionId: string | null, trusted: boolean): Promise<{
         note: store.Note;
@@ -51,22 +53,27 @@ export declare class NoteDeliveries {
     }>;
     /** The person confirms a note the page could have forged; it is then sent with the next send. */
     confirm(id: string, expectedVersion: number | undefined): store.Note;
-    /** The instruction for the session's queued notes (or the given ones), for a host that runs it itself. */
-    compose(sessionId: string, ids?: string[] | null): {
+    /** Confirms every page-origin note of the session at once; the person checked them in one prompt. */
+    confirmAll(sessionId: string): store.Note[];
+    /** `/annotate:clear`: the session's unsent notes are resolved and stop being shared with it. */
+    clear(sessionId: string): store.Note[];
+    private sendable;
+    /** The message for the session's unsent notes (or the given ones), for a host that runs it itself. */
+    compose(sessionId: string, ids?: string[] | null, prompt?: string | null): {
         text: string;
         ids: string[];
     };
     /** A host started `runId` with composed notes. */
     delivered(ids: string[], sessionId: string, runId: string): store.Note[];
-    /** Sends the session's queued notes (or the given ones) as one run. */
+    /** Sends the session's unsent notes (or the given ones) as one run, with the person's own request when given. */
     send(sessionId: string, filter?: {
         ids?: string[] | null;
         auto?: boolean;
+        prompt?: string | null;
     }): Promise<SendResult>;
-    /** A run of the session ended: notes waiting for it to be idle go out now. */
+    /**
+     * A run of the session ended: notes waiting for it to be idle go out now. The terminal can still
+     * report the turn as active for a moment, so a busy answer is tried again a few times.
+     */
     runEnded(sessionId: string | null | undefined): Promise<void>;
-    markFixed(id: string, caller: {
-        sessionId?: string | null;
-        agentId?: string | null;
-    }, summary: string): store.Note;
 }