@hachej/boring-agent 0.4.25 → 0.4.27

package/README.md

@@ -327,6 +327,17 @@ The resource must be UTF-8 `application/json`, optionally with `charset=utf-8`.
 
 Run `node fixtures/agent-definitions.mjs` after building for a fictional definition, explicit native configuration and real document publication. `npm run test:definitions-consumer` installs files/agent archives with pinned registry dependencies, checks strict declarations and repeats exact-read, native publication, reopen and registry-replacement tests. Like the question consumer, this strict fixture explicitly installs the pinned optional model SDK declaration dependencies.
 
+## One-call runs
+
+A run is one agent asked once, in its own native conversation, for a result: the host starts it by a key, the agent answers by calling a result tool (or in text), the host checks the answer, asks for a corrected one while the repair budget lasts, and hands the end to the operation that started the run. Every home needs the same parts, so they are here once. Pi still owns the turns, the transcript and recovery; these read the transcript and submit native follow-up inputs, and the host keeps its data and its budgets.
+
+- `@hachej/boring-agent/run-result` (optional peer `typebox`): `resultConfig` (the card's `result: { schema?, validate?, repairs? }`), `resultParameters`, `resultExecutor` (the result tool's `execute`: checks the call against the schema and the card's validator operation, spends the budget), `settleResult` (wait for the answer, read it, repair it in the run's own conversation with `repair:<conversation>:<n>` inputs, check it once more with `phase: "delivery"`), `runMessage`, `runResult`, `resultState`, `evidenceOf`, `withEvidence`. The validator is an operation the host calls through `invoke(operation, input, key)` as the person whose run it is. `ResultBudget` keeps the stored document shape of the homes that ran this first.
+- `@hachej/boring-agent/runs`: the run ends (`completed`, `invalid_output`, `cancelled`, `interrupted`, `revoked`, `error`), `RunView`, `sumUsage`, `OVER_BUDGET` and `isOverBudget`, and `deliverRunEnd`: bounded attempts under one `deliver:<key>` receipt key, a completed end checked again first and delivered as `invalid_output` when it no longer passes. A delivery that fails is reported, not dropped.
+- `@hachej/boring-agent/run-ledger`: `createRunLedger(sql)` keeps `_host_agent_runs` in the person's own SQLite file; an end happens once (`UPDATE ... RETURNING`), so a cancel and the run's own end can race. `createRunner({ ledger, person, context, has, prepare, invoke, admit?, usage? })` gives `start(agent, input, key, deliverTo)` (the same key is the same run), `status`, `cancel` and `recover`: a run a stopped process left ends `interrupted`, and one that ended without being delivered is delivered. `admit` is the host's spend meter: a refused run is never started and ends `error: over_budget`. The cap, the spend ledger and the prices stay the host's.
+- `@hachej/boring-agent/run-outbox`: `stageStarts(sql, ...)` in the app operation's own transaction, `drainStarts` after the commit. A row is removed only when the run is acknowledged, retried with backoff when it may pass, dropped when it never will.
+
+Stores are a synchronous `SyncSql` function (`node:sqlite` `prepare(sql).all(...params)`, a Durable Object's `sql.exec`); nothing here opens a connection or a transaction. Not here, by design: the card parser and its front matter, the app operations a run calls, the schedule and alarm of a Durable Object home, and anything clinical or app specific.
+
 ## Structured output and native tool evidence
 
 `@hachej/boring-agent/validation` exports `createOutputValidation`. Install its native extension explicitly. A producer returns `{ text, evidence }`, where `evidence` contains retained native tool-result entry IDs. Create the returned validation task with `{ producer }` through ordinary `tx.createTask`; it waits for the producer and returns `valid`, `invalid` or `producer-failed`. Only a `valid` result may feed application delivery. The host supplies a stable task name and definition version; incompatible stored versions require native migration or refusal.
@@ -349,33 +360,34 @@ Each evidence entry must link to a completed native ToolTask, its original assis
 
 `?op=configure` (POST `{ model?: { provider, modelId }, thinkingLevel? }`) changes the conversation's native agent for a model or effort picker. It is gated by `allow('configure')` and delegated to `ChatTransportAccess.configure(change)`; without that function the op answers `not-supported`. The host function applies `conversation.configure(...)` and owns the allow-list: it validates the change against its own models and levels and returns a refusal such as `{ kind: 'refused', reason }` instead of applying it (the handler checks only the request shape). `createRemoteChat().configure(change)` returns whatever the host answered. A change applies from the next model request.
 
-`createSkillsExtension` tells the model that a user message starting with `/<skill-name>` is an explicit request to load that skill first, which is what the chat's `/` menu inserts. `defineAgent(...).skills` lists each skill's name and description for such a menu.
+The skills section (`staticSkills` and `liveSkills`) tells the model that a user message starting with `/<skill-name>` is an explicit request to load that skill first, which is what the chat's `/` menu inserts. `defineAgent(...).skills` lists each skill's name and description for such a menu when the skills are an array.
 
 With self-evolution, workspace skills may be flat `.agent/skills/<name>.md` files or `.agent/skills/<name>/SKILL.md` folders. Only `SKILL.md` defines a skill inside a folder; other Markdown and deeper files are companions, not skills. `load_skill` returns the body followed by “This skill's folder is `.agent/skills/<name>`; paths in it are relative to that folder.” (For flat files the folder is `.agent/skills`.) A skill can say `see portions.md` or `see tables/2026.csv`; the agent reads that path under the returned folder with Pi's native `read`, through the same workspace provider. Scanning and loading do not read the companions. No special companion folder, new file tool or additional access is granted. Host-given `Skill` data stays `{ name, description, body }`: with no source folder, `load_skill` returns its body unchanged.
 
 ## Live skills
 
-`createSkillsExtension(name, skills, options?)` also takes a `SkillSource` instead of an array, so skills added, edited or removed after start reach the agent without rebuilding the extension. A source is `{ list(context), version(context) }`: `list` returns `{ skills, errors }`, `version` a cheap token that changes when the skills do. Two are built in, and both read through the workspace's Pi `FileSystem` (an `ExecutionEnv` is one; pass the workspace provider's instance, never `node:fs`):
+`staticSkills(skills, { name, intro?, visible? })` takes an array and returns `{ extension }`. `liveSkills(source, { name, maxAgeMs?, onDiagnostics?, companionFiles?, onPublish?, intro?, visible? })` takes a `SkillSource` instead, so skills added, edited or removed after start reach the agent without rebuilding the extension; `defineAgent({ skills })` takes either. A source is `{ list(context), version(context) }`: `list` returns `{ skills, errors }`, `version` a cheap token that changes when the skills do. Two are built in, and both read through the workspace's Pi `FileSystem` (an `ExecutionEnv` is one; pass the workspace provider's instance, never `node:fs`):
 
-- `directorySkillSource(fs, 'skills')`: every `skills/<name>/SKILL.md`, its folder passed to `load_skill` as for self-evolution. A missing directory holds no skills; folders without `SKILL.md` are skipped, and companion files are read only with `companionFiles` (below). Its version is the folder names with each `SKILL.md`'s `mtimeMs` and size (one `listDir` and one `fileInfo` per folder).
+- `directorySkillSource(fs, 'skills')`: every `skills/<name>/SKILL.md`, its folder passed to `load_skill` as for self-evolution; `{ flat: true }` adds every `skills/<name>.md` file (self-evolution's `.agent/skills` layout). A missing directory holds no skills; folders without `SKILL.md` are skipped, and companion files are read only with `companionFiles` (below). Its version is each skill file's path with its `mtimeMs` and size (one `listDir` and one `fileInfo` per skill file).
 - `fileSkillSource(fs, 'notes/triage.md')`: one skill file, its folder the file's directory; a missing file holds no skill. Its version is the file's `mtimeMs` and size.
 
-The source is read on first use. After that the listing section and `load_skill` use the cached copy until it is older than `options.maxAgeMs` (default 5000), then ask `version()` and read `list()` again only when it changed. There is no watcher or timer: the check happens on use, and concurrent uses share one read. `load_skill` asked for a name the conversation's listing does not hold makes the same check at once, whatever `maxAgeMs` (see *refresh on miss* below). What a source returns is checked with `validSkill` and the duplicate-name rule (the first skill of a name wins). A skill that fails, or a file that cannot be read or parsed, is left out instead of taking the extension down: `options.onDiagnostics(errors)` receives every `SkillError` (`{ path, name?, message }`) after each read (an empty array once all are fine), and `load_skill` asked for the left-out name answers `Skill "<name>" could not be loaded (<path>): <reason>`. A source whose `list`/`version` throws is a host bug: the section keeps the text already shown (Pi's `renderSections`) and `load_skill` fails. A fixed array works as before: validated once, an invalid or duplicate skill throws. With no skills, the section is omitted.
+The source is read on first use. After that the listing section and `load_skill` use the cached copy until it is older than `maxAgeMs` (default 5000), then ask `version()` and read `list()` again only when it changed. There is no watcher or timer: the check happens on use, and concurrent uses share one read. `load_skill` asked for a name the conversation's listing does not hold makes the same check at once, whatever `maxAgeMs` (see *refresh on miss* below). What a source returns is checked with `validSkill` and the duplicate-name rule (the first skill of a name wins). A skill that fails, or a file that cannot be read or parsed, is left out instead of taking the extension down: `onDiagnostics(errors)` receives every `SkillError` (`{ path, name?, message }`) after each read (an empty array once all are fine), and `load_skill` asked for the left-out name answers `Skill "<name>" could not be loaded (<path>): <reason>`. A source whose `list`/`version` throws is a host bug: the section keeps the text already shown (Pi's `renderSections`) and `load_skill` fails. A fixed array works as before: validated once, an invalid or duplicate skill throws. With no skills, the section is omitted.
 
 Pi renders every extension section before each model request (`PromptSection.render`), so a refreshed listing reaches the next request; Pi's `planSystemEntries` writes nothing when the text is unchanged and a minimal `pi.system` section patch when it changed. Prompt cache: on a model that accepts system messages mid-conversation the patch is appended and the cached prefix stays valid; on one that does not, Pi collapses the system messages into one leading prompt, so every listing change rewrites the start of the prompt and misses the provider's prompt cache once. Keep `maxAgeMs` coarse and edits to skill descriptions deliberate. Pi itself has no skills loader in the packages this one depends on (`pi-durable` and `pi-ai`), so this is a host concern built on its `FileSystem` and section seams.
 
 **Control (all optional; with none set, the extension behaves as above).**
 
-- `visible(conversationId, skills)`: which skills a conversation sees. It is called once per render and once per `load_skill` call (may be async) with the whole current list of valid skills, and returns the subset that conversation sees (matched by name). The id is Pi's own: the section gets it from `PromptInput.conversationId`, the tool from `ToolExecutionApi.conversationId`, so no host bookkeeping is needed. A hidden skill is left out of the listing, and `load_skill` answers for it exactly as for an unknown name (`Unknown skill "<name>". Available: <visible names>`). With a filter, a skill that could not be read also answers as unknown (it is never in the list); its reason still reaches `onDiagnostics`. Works for an array too.
-- `companionFiles: true`: `load_skill`'s answer ends with the files beside the skill's `SKILL.md` (the Agent Skills layout: `references/`, `scripts/`, `assets/`; any depth, name order, at most 200), and `load_skill({ name, path })` returns one of them as text. The files are checked when the listing is read, and a listed file is checked again when the model asks: each one must be a regular file inside the skill's folder that reads as UTF-8 text. A symbolic link, an unreadable or binary file (a NUL byte or invalid UTF-8) and files past the 200th are left out and reported to `onDiagnostics` (`{ path, name: <skill>, message: 'Companion file left out: …' }`). Only a listed path is read, so a path cannot leave the folder (`../`, absolute paths and links are refused with `Skill "<name>" has no companion file "<path>"`). Before returning a listed file, `load_skill` looks at the skill's folder, every folder on the way and the file with `fileInfo` (which does not follow links) and checks the text again: a file or folder swapped for a symbolic link since the listing (the agent may write its own skill folder) answers `Companion file "<path>" of skill "<name>" could not be read: <path> is a symbolic link` and is never followed. The list is kept with the listing: a companion added or removed later shows up on the next read of the source (a `SKILL.md` change or `refresh()`); a listed file's content is read on demand through the source's `fs` (the same workspace `FileSystem`; both built-in sources set `SkillSource.fs`), never cached. A skill file not named `SKILL.md` (a `fileSkillSource` on `notes/triage.md`) has none. An array, or a source without `fs`, throws.
+- `visible(conversationId, skills)`: which skills a conversation sees. It is called once per render and once per `load_skill` call (may be async) with the whole current list of valid skills, and returns the subset that conversation sees (matched by name). The id is Pi's own: the section gets it from `PromptInput.conversationId`, the tool from `ToolExecutionApi.conversationId`, so no host bookkeeping is needed. A hidden skill is left out of the listing, and `load_skill` answers for it exactly as for an unknown name (`Unknown skill "<name>". Available: <visible names>`). With a filter, a skill that could not be read also answers as unknown (it is never in the list); its reason still reaches `onDiagnostics`. Works for `staticSkills` too.
+- `companionFiles: true`: `load_skill`'s answer ends with the files beside the skill's `SKILL.md` (the Agent Skills layout: `references/`, `scripts/`, `assets/`; any depth, name order, at most 200), and `load_skill({ name, path })` returns one of them as text. The files are checked when the listing is read, and a listed file is checked again when the model asks: each one must be a regular file inside the skill's folder that reads as UTF-8 text. A symbolic link, an unreadable or binary file (a NUL byte or invalid UTF-8) and files past the 200th are left out and reported to `onDiagnostics` (`{ path, name: <skill>, message: 'Companion file left out: …' }`). Only a listed path is read, so a path cannot leave the folder (`../`, absolute paths and links are refused with `Skill "<name>" has no companion file "<path>"`). Before returning a listed file, `load_skill` looks at the skill's folder, every folder on the way and the file with `fileInfo` (which does not follow links) and checks the text again: a file or folder swapped for a symbolic link since the listing (the agent may write its own skill folder) answers `Companion file "<path>" of skill "<name>" could not be read: <path> is a symbolic link` and is never followed. The list is kept with the listing: a companion added or removed later shows up on the next read of the source (a `SKILL.md` change or `refresh()`); a listed file's content is read on demand through the source's `fs` (the same workspace `FileSystem`; both built-in sources set `SkillSource.fs`), never cached. A skill file not named `SKILL.md` (a `fileSkillSource` on `notes/triage.md`) has none. A source without `fs` throws.
 - `intro`: the listing section's text before the `- name: description` lines, replacing the default (“Before starting a task that matches a skill, call load_skill …”, with the `/<skill-name>` rule). The skill lines still follow it.
 - `onPublish(next, previous)`: called with both listings' skills before a newly read listing of a source replaces the current one (may be async). Return a reason, or throw, to refuse it: the current listing stays and `onDiagnostics` gets that listing's errors followed by `{ path: '', message: 'Listing refused by onPublish: <reason>' }` (the per-skill errors are kept; the entry with `path: ''` is the refusal). A refused listing is not offered again until the source's version changes or `refresh()` runs. The first read is offered too (`previous` empty).
-- `createSkillsController(name, source, options?)` returns `{ extension, refresh }`, so `createSkillsExtension` keeps its return type (it is `createSkillsController(...).extension` for a source). `await refresh(context)` reads the source now, whatever `maxAgeMs`, and publishes it through `onPublish`; `refresh(context, name)` takes only that skill from the new read (added, replaced or removed) and keeps the others as they were until the source's `version()` changes again: later `maxAgeMs` checks and `load_skill` misses do not re-read an unchanged source, and the first read after a change offers the whole source (through `onPublish`) as usual. A source only lists everything at once, so the others' pending edits are part of that next read. It resolves `true` when published, `false` when refused. Reads run one at a time, so a refresh never interleaves with a `maxAgeMs` check. Call it from the code that changed the skills (an editor save, a self-evolution keep); there is still no watcher.
+- `liveSkills(source, options)` returns `{ extension, refresh }`; `staticSkills` returns `{ extension }` only. `await refresh(context)` reads the source now, whatever `maxAgeMs`, and publishes it through `onPublish`; `refresh(context, name)` takes only that skill from the new read (added, replaced or removed) and keeps the others as they were until the source's `version()` changes again: later `maxAgeMs` checks and `load_skill` misses do not re-read an unchanged source, and the first read after a change offers the whole source (through `onPublish`) as usual. A source only lists everything at once, so the others' pending edits are part of that next read. It resolves `true` when published, `false` when refused. Reads run one at a time, so a refresh never interleaves with a `maxAgeMs` check. Call it from the code that changed the skills (an editor save, a self-evolution keep); there is still no watcher.
 
 **Refresh on miss.** On a source, `load_skill` for a name not in the conversation's listing checks the source once before answering, whatever `maxAgeMs`: `version()` now, and `list()` plus `onPublish` only when the version changed, serialized with the other reads. So a skill written a moment ago loads on the first try, and the listing shows it from the next request on. A model guessing names costs one `version()` per miss (a `fileInfo` per skill folder for the built-in sources), never a re-read of an unchanged source, and concurrent misses share one check in flight, so there is no time floor. A miss of a refused listing's skill stays a miss until the version changes or `refresh()` runs, as above.
 
 ```ts
-const skills = createSkillsController('workspace.skills', directorySkillSource(env, 'skills'), {
+const skills = liveSkills(directorySkillSource(env, 'skills'), {
+  name: 'workspace.skills',
   companionFiles: true,
   visible: (conversationId, skills) => billingConversations.has(conversationId) ? skills : skills.filter(skill => !skill.name.startsWith('billing-')),
   onDiagnostics: errors => errors.forEach(error => log.warn(`skill ${error.path}: ${error.message}`)),
@@ -386,6 +398,27 @@ const agent = defineAgent({ id: 'clerk', model, extensions: [skills.extension] }
 await skills.refresh(context, 'letters'); // after the host saved skills/letters/SKILL.md
 ```
 
+### Versioned skill folders
+
+`directorySkillSource(fs, root, { versioned: true })` reads skills published as whole versions, for example from a bucket mounted read-only into the agent runtime (the library only reads a folder through the workspace `FileSystem`; it does not know where the bytes live):
+
+```
+<root>/v12/<skill>/SKILL.md   (+ companion files)
+<root>/v13/<skill>/SKILL.md
+<root>/current                one line: v13
+```
+
+- **Publish**: write the new version folder completely, then overwrite `current` with its name. A version folder is never changed once written (the library reads each version once and keeps it).
+- **Rollback**: write the old version's name back into `current`.
+- **Which version a conversation sees**: a new conversation starts on the version `current` names (read again once older than `maxAgeMs`). A running conversation keeps the version it started on until the person sends `/reload-skill`, which moves that conversation only to the version `current` names now (reading that version's folder again). `{ flat: true }` applies inside each version folder.
+- **A bad pointer**: `current` missing or unreadable, a value that is not one folder name (`../v1`), or a version with no folder is reported to `onDiagnostics` as `{ path: '<root>/current', message }`; new conversations stay on the last good version, and `/reload-skill` answers `Skills stay on version <v>: <message>`. Before any good version, the agent has no skills.
+
+`/reload-skill` is the skills extension's native tool `reload_skill` (Pi extension point: a tool and the listing section of the extension, over the `SkillSource` on the workspace's `ExecutionEnv` `FileSystem`; no second loader). The listing tells the model that a message `/reload-skill` means calling it, as `/<skill-name>` means `load_skill`; the tool answers `Skills reloaded: version <v> (<names>).` A host command can do the same without the model: `refresh(context, undefined, conversationId)` moves one conversation, `refresh(context)` every conversation, and resolves `false` on a bad pointer. `refresh(context, name)` is refused (versions move whole), and so is `onPublish`. Limit: which version each conversation is on is kept in the process, so after a restart every conversation starts on the version `current` names then.
+
+```ts
+const agent = defineAgent({ id: 'clerk', model, skills: directorySkillSource(env, '/mnt/skills', { versioned: true }) });
+```
+
 ## Sub-agents and schedules
 
 These follow [Pi Durable on Cloudflare](https://earendil.com/posts/pi-durable-on-cloudflare/) and stay host-agnostic: a Node process and a Durable Object mount the same tools.
@@ -439,7 +472,7 @@ const delegates = [
 
 `defineAgent({ …, selfEvolving: true, workspace })` lets the agent keep its own standing instructions, skills and tools in the `.agent/` folder of its workspace and apply them with a `reload` tool; the plan and its reasons are in [SELF-EVOLUTION.md](../../docs/architecture/SELF-EVOLUTION.md). Off by default.
 
-- One native extension per workspace, named `self-evolving:<workspace>`, so two workspaces in one host never replace each other's tools. Without a fixed `workspace` the agent works in a workspace per conversation: `inWorkspace(name)` returns the agent of workspace `name` (made once, then the same), whose configuration selects only `self-evolving:<name>`; the host creates each conversation with the agent of its owner's workspace and installs and reloads that workspace's extension when the workspace opens, so one harness and one registry never offer one workspace's agent-written tools to another's. It carries the skills (the host's, then `.agent/skills/*.md` and `.agent/skills/<name>/SKILL.md` parsed with `parseSkill`, behind the usual `load_skill`), `reload`, the agent-written tools and the `agent-written` prompt section. It is selected last; the host's `instructions` become the first section (`host-instructions`) of `agent.<id>`, because Pi renders native `instructions` after every extension section.
+- One native extension per workspace, named `self-evolving:<workspace>`, so two workspaces in one host never replace each other's tools. Without a fixed `workspace` the agent works in a workspace per conversation: `inWorkspace(name)` returns the agent of workspace `name` (made once, then the same), whose configuration selects only `self-evolving:<name>`; the host creates each conversation with the agent of its owner's workspace and installs and reloads that workspace's extension when the workspace opens, so one harness and one registry never offer one workspace's agent-written tools to another's. It carries the skills (the host's, then `.agent/skills/*.md` and `.agent/skills/<name>/SKILL.md`, read with `directorySkillSource(env, '.agent/skills', { flat: true })`, behind the usual `load_skill`), `reload`, the agent-written tools and the `agent-written` prompt section. It is selected last; the host's `instructions` become the first section (`host-instructions`) of `agent.<id>`, because Pi renders native `instructions` after every extension section.
 - `.agent/AGENTS.md` is rendered by that section on every request through the request's environment, labelled as agent-written and capped at `MAX_AGENT_INSTRUCTIONS` (16,000) characters.
 - `.agent/tools/<name>.json` is `{ name, description, parameters, run }`: `name` snake_case and not one of the agent's other tools, `parameters` a JSON Schema with `"type": "object"`, `run` one command line; a path under `.agent/` that `run` names must exist. Each becomes a native `ToolRegistration` (through `jsonSchemaTool`, so Pi refuses arguments that do not match `parameters` before `run` starts) whose `execute` runs `run` through the call's own `ExecutionEnv.exec` (the same provider instance as the files it was read from), with the arguments as one line of JSON on standard input (a quoted here-document); the output is the result and a non-zero exit is an error.
 - `reload` (and `DefinedAgent.reload(env, context)`, which a host calls on open and for the person's `/reload`) reads `.agent/` through the given environment's `FileSystem`, rebuilds the extension and calls the native `registry.install()` in every registry `install` was given (same name: replaced in place). Reloads are serialised. The report (`SelfEvolutionReport`, its `text` is the tool result) names tools added, changed and removed, the agent's skills, the instructions and every load error (invalid JSON, schema, missing script, name conflict, unreadable file). A reload never imports or evaluates anything. Without `exec` the tools are reported unavailable and skipped; instructions and skills still load.
@@ -488,3 +521,33 @@ const navigate = createPresentationTool({
 Here `Type` is Pi AI's native schema builder, and `mounted`, `capturedTarget` and `canNavigate` belong to the host. The adapter passes native cancellation to the command and fixes replay to `unsafe`: an interrupted presentation call cannot safely be redirected or repeated. It acquires no controller, provider or Harness and owns none of their cleanup.
 
 This is direct in-process binding. A server cannot manipulate a remote browser through this adapter alone. The optional [canvas host recipe](../../docs/architecture/CANVAS.md#authenticated-remote-presentation-recipe) supplies authenticated selection/proposal delivery to a mounted canvas. Other viewer transports and deployment identity remain separate work. Presentation/proposal results are not publication receipts or human approval.
+
+## Structured actions
+
+`@hachej/boring-agent/actions` provides `withActionModels(models, { resolve })`, an optional adapter at the public `HarnessOptions.models` seam. A host decision admits one structured extraction; its single validated tool call is executed by Pi. The next native generation renders a template from the actual tool result, without contacting an LLM. Ambiguous requests return to the full model. No extra harness, tool dispatcher or durable journal is created.
+
+```ts
+import { ACTION_PROVIDER, withActionModels } from '@hachej/boring-agent/actions';
+
+const actionModels = withActionModels(admittedModels, {
+  resolve: id => id === 'notes' ? {
+    model: fullModel,
+    extraction: { model: extractionModel, instructions: 'Extract one new note.', tool: noteTool },
+    decide: async ({ message, history, signal }) => decideNote({ message, history, signal }),
+    reply: 'Saved {note.title}.',
+    uncertainReply: 'The outcome is uncertain. Check before retrying.',
+  } : undefined,
+});
+// Pass actionModels as the models option when the host opens its native Harness.
+await conversation.configure({ model: { provider: ACTION_PROVIDER, modelId: 'notes' } }, context);
+```
+
+`admittedModels` is the host's existing native Models, including its provider authentication and budget wrappers. `noteTool` is a native tool declaration, already installed and allowed in the conversation. The extraction schema may be stricter than that tool's schema; both are checked without coercion before returning a call. No commercial provider, API key, subscription or Jev client is embedded in the package. The host's `decide` adapts its chosen decision service; only literal `true` admits extraction. The callback gets native prior messages so the host can choose and bound the authorized decision context. Extraction receives only the current text input.
+
+The default decision deadline is 400 ms and the input cap is 1,500 characters; `decisionTimeoutMs` and `maxInputCharacters` override them. Decision failure/timeout, non-text input, missing current tool, malformed/multiple extraction calls or extraction refusal return to the full model. The decision receives an abort signal; an uncooperative service may finish later, but its result cannot start extraction. Native compaction uses `completeSimple` with a tool-free summarization context, which delegates to the full model. Explicit deferred requests also use the full model; polling and cancellation retain the underlying provider. Missing action definitions or full models return the native unavailable-model result. Unselected models and native registry capabilities remain available.
+
+Reply placeholders such as `{note.title}` accept actual strings, finite numbers and string arrays (joined by newline). Missing output, a failed tool or unreadable result produces `uncertainReply`, never a blind replay of a possible mutation. `rejectedWithoutEffect(result)` may opt into full-model handling only when the host can prove an atomic rejection; a throwing predicate leaves the outcome uncertain. Tools still own permission checks and durable idempotent receipts; the adapter cannot make external writes transactional. Install the adapter outside the metered Models so real extraction and fallback requests retain admission. Synthetic replies have zero usage; failed extraction usage needs host request metering because only the final fallback message enters Pi's transcript.
+
+Hosts must explicitly configure existing conversations when adopting this virtual model; deployment alone does not change their persisted selection. Keep the action's tool and result contract compatible while native work is pending. Changing definitions during an outstanding action is not a version-pinning guarantee.
+
+Evidence: `node --test test/packages/agent-actions.test.mjs` runs the public package through a native Harness, SQLite reopen, native tool gates and scripted models. `npm run test:definitions-consumer -- --actions` repeats these tests and checks strict installed declarations. Real-model speed and decision accuracy remain consumer evals, not claims of these scripted tests.

package/dist/actions.d.ts

@@ -0,0 +1,38 @@
+import type { Message, Models, Tool, ToolResultMessage } from '@earendil-works/pi-ai';
+import type { ModelRef } from '@earendil-works/pi-durable';
+/** Virtual model identity persisted by Pi; real requests use the host's Models. */
+export declare const ACTION_PROVIDER = "boring-action";
+export interface StructuredAction {
+    readonly model: ModelRef;
+    readonly extraction: {
+        readonly model: ModelRef;
+        readonly instructions: string;
+        readonly tool: Tool;
+    };
+    /** Host decision policy (Jev, another classifier, or deterministic rules). Literal true admits extraction. */
+    readonly decide: (input: {
+        readonly message: string;
+        readonly history: readonly Message[];
+        readonly signal: AbortSignal;
+    }) => Promise<boolean>;
+    readonly reply: string;
+    /** Host-localized text for an outcome that must not be retried automatically. */
+    readonly uncertainReply: string;
+    /** Only return true for a known atomic rejection with no effect. */
+    readonly rejectedWithoutEffect?: (result: ToolResultMessage) => boolean;
+    readonly decisionTimeoutMs?: number;
+    readonly maxInputCharacters?: number;
+}
+export interface ActionModelsOptions {
+    /** Resolve trusted configuration; this never registers tools or grants permissions. */
+    readonly resolve: (id: string) => StructuredAction | undefined;
+    readonly now?: () => number;
+}
+/** Substitute actual scalar results only. Missing values cannot become invented confirmations. */
+export declare function actionReply(template: string, result: unknown): string;
+/** Compose at HarnessOptions.models, outside the host's admitted/metered real Models.
+ * Pi still owns generation, tool execution, hooks, history and recovery. Tool-free requests
+ * (including native compaction) delegate to the full model. No tool is executed here.
+ */
+export declare function withActionModels<T extends Models>(models: T, options: ActionModelsOptions): T;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.js

@@ -0,0 +1,158 @@
+import { createAssistantMessageEventStream, getCurrentTools, normalizeContext } from '@earendil-works/pi-ai';
+import { Check } from 'typebox/schema';
+/** Virtual model identity persisted by Pi; real requests use the host's Models. */
+export const ACTION_PROVIDER = 'boring-action';
+const PREFIX = 'boring_action_';
+const zeroUsage = () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } });
+const inputText = (content) => typeof content === 'string' ? content : content.filter(p => p.type === 'text').map(p => p.text).join('');
+/** Substitute actual scalar results only. Missing values cannot become invented confirmations. */
+export function actionReply(template, result) {
+    return template.replace(/\{([\w.]+)\}/g, (_match, path) => {
+        let value = result;
+        for (const key of path.split('.')) {
+            value = value !== null && typeof value === 'object' && Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined;
+        }
+        if (Array.isArray(value) && value.every(v => typeof v === 'string'))
+            value = value.join('\n');
+        if (typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value)))
+            throw new Error(`Missing action result: ${path}`);
+        return String(value);
+    });
+}
+async function admitted(action, message, history, parent) {
+    const controller = new AbortController();
+    const signal = parent ? AbortSignal.any([parent, controller.signal]) : controller.signal;
+    if (signal.aborted)
+        return false;
+    let timer;
+    let onAbort = () => { };
+    const cancelled = new Promise(resolve => {
+        onAbort = () => resolve(false);
+        signal.addEventListener('abort', onAbort, { once: true });
+        timer = setTimeout(() => controller.abort(), action.decisionTimeoutMs ?? 400);
+    });
+    try {
+        return await Promise.race([Promise.resolve().then(() => action.decide({ message, history, signal })).then(value => value === true, () => false), cancelled]);
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+        controller.abort();
+    }
+}
+/** Compose at HarnessOptions.models, outside the host's admitted/metered real Models.
+ * Pi still owns generation, tool execution, hooks, history and recovery. Tool-free requests
+ * (including native compaction) delegate to the full model. No tool is executed here.
+ */
+export function withActionModels(models, options) {
+    const now = options.now ?? Date.now;
+    const required = (ref) => {
+        const model = models.getModel(ref.provider, ref.modelId);
+        if (!model || model.provider === ACTION_PROVIDER)
+            throw new Error(`Unavailable action model: ${ref.provider}/${ref.modelId}`);
+        return model;
+    };
+    const resolve = (id) => {
+        const action = options.resolve(id);
+        if (!action)
+            throw new Error(`No action agent ${id}`);
+        return action;
+    };
+    const wrapped = {
+        getModel(provider, id) {
+            if (provider !== ACTION_PROVIDER)
+                return models.getModel(provider, id);
+            const action = options.resolve(id);
+            const model = action && models.getModel(action.model.provider, action.model.modelId);
+            return model && model.provider !== ACTION_PROVIDER ? { ...model, provider, id } : undefined;
+        },
+        streamSimple(model, context, requestOptions) {
+            if (model.provider !== ACTION_PROVIDER)
+                return models.streamSimple(model, context, requestOptions);
+            const action = resolve(model.id);
+            const original = required(action.model);
+            const out = createAssistantMessageEventStream();
+            const full = async () => { for await (const event of models.streamSimple(original, context, requestOptions))
+                out.push(event); };
+            const emit = (message) => {
+                if (message.stopReason === 'error' || message.stopReason === 'aborted')
+                    out.push({ type: 'error', reason: message.stopReason, error: message });
+                else if (message.stopReason !== 'pending')
+                    out.push({ type: 'done', reason: message.stopReason, message });
+                else
+                    throw new Error('An action cannot emit a pending completion');
+            };
+            void (async () => {
+                const messages = context.messages.filter(message => message.role !== 'system');
+                const last = messages.at(-1), previous = messages.at(-2);
+                const calls = previous?.role === 'assistant' ? previous.content.filter(p => p.type === 'toolCall') : [];
+                const call = calls.length === 1 ? calls[0] : undefined;
+                if (last?.role === 'toolResult' && call?.id === last.toolCallId && call.name === action.extraction.tool.name && call.id.startsWith(PREFIX)) {
+                    if (last.isError) {
+                        let rejected = false;
+                        try {
+                            rejected = action.rejectedWithoutEffect?.(last) === true;
+                        }
+                        catch { /* Unknown outcomes remain uncertain. */ }
+                        if (rejected)
+                            return full();
+                    }
+                    let text = action.uncertainReply;
+                    if (!last.isError) {
+                        try {
+                            text = actionReply(action.reply, JSON.parse(inputText(last.content)));
+                        }
+                        catch { /* A possible effect must not be repeated. */ }
+                    }
+                    emit({ role: 'assistant', content: [{ type: 'text', text }], api: original.api, provider: ACTION_PROVIDER, model: model.id, usage: zeroUsage(), stopReason: 'stop', timestamp: now() });
+                    return;
+                }
+                const tool = getCurrentTools(normalizeContext(context).messages).find(tool => tool.name === action.extraction.tool.name);
+                if (!tool || last?.role !== 'user' || requestOptions?.signal?.aborted || requestOptions?.deferred)
+                    return full();
+                const raw = inputText(last.content);
+                if (!raw.trim() || raw.length > (action.maxInputCharacters ?? 1500) || (Array.isArray(last.content) && last.content.some(p => p.type !== 'text')))
+                    return full();
+                if (!await admitted(action, raw, messages.slice(0, -1), requestOptions?.signal) || requestOptions?.signal?.aborted)
+                    return full();
+                let extracted;
+                try {
+                    extracted = await models.streamSimple(required(action.extraction.model), {
+                        systemPrompt: action.extraction.instructions, messages: [last], tools: [action.extraction.tool],
+                    }, requestOptions).result();
+                    const extractedCalls = extracted.content.filter(p => p.type === 'toolCall');
+                    const extractedCall = extractedCalls.length === 1 ? extractedCalls[0] : undefined;
+                    if (extracted.stopReason !== 'toolUse' || !extractedCall || extractedCall.name !== tool.name ||
+                        !Check(action.extraction.tool.parameters, extractedCall.arguments) || !Check(tool.parameters, extractedCall.arguments))
+                        return full();
+                    // Native ToolTask owns the write, permission checks and host receipt; keep this ID in its transcript.
+                    const bytes = crypto.getRandomValues(new Uint8Array(16));
+                    const id = PREFIX + Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+                    emit({ ...extracted, content: [{ ...extractedCall, id }] });
+                }
+                catch {
+                    return full();
+                }
+            })().catch(error => emit({ role: 'assistant', content: [], api: original.api, provider: original.provider, model: original.id, usage: zeroUsage(), stopReason: 'error', errorMessage: String(error instanceof Error ? error.message : error), timestamp: now() })).finally(() => out.end());
+            return out;
+        },
+        stream(model, context, requestOptions) {
+            return models.stream(model.provider === ACTION_PROVIDER ? required(resolve(model.id).model) : model, context, requestOptions);
+        },
+        completeSimple: (model, context, requestOptions) => wrapped.streamSimple(model, context, requestOptions).result(),
+        complete: (model, context, requestOptions) => wrapped.stream(model, context, requestOptions).result(),
+        streamDeferred(model, handle, requestOptions) {
+            return models.streamDeferred(model.provider === ACTION_PROVIDER ? required(resolve(model.id).model) : model, handle, requestOptions);
+        },
+        fetchDeferred: (model, handle, requestOptions) => wrapped.streamDeferred(model, handle, requestOptions).result(),
+        cancelDeferred(model, handle, requestOptions) {
+            return models.cancelDeferred(model.provider === ACTION_PROVIDER ? required(resolve(model.id).model) : model, handle, requestOptions);
+        },
+    };
+    return new Proxy(models, { get(target, key) {
+            if (Object.hasOwn(wrapped, key))
+                return Reflect.get(wrapped, key);
+            const value = Reflect.get(target, key);
+            return typeof value === 'function' ? value.bind(target) : value;
+        } });
+}

package/dist/agents.d.ts

@@ -3,10 +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 { Skill } from './skills.js';
+import type { Skill, SkillSource } from './skills.js';
 export type { SelfEvolutionError, SelfEvolutionReport } from './self-evolving.js';
-export { createSkillsController, createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
-export type { Skill, SkillError, SkillFileSystem, SkillListing, SkillSource, SkillsController, SkillsExtensionOptions } from './skills.js';
+export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, 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';
 export { createDelegateTool, DELEGATE_DETAILS_KIND, DELEGATE_TOOL } from './delegate.js';
@@ -22,7 +22,11 @@ export interface AgentSpec {
     readonly tools?: readonly ToolRegistration[];
     /** Additional native extensions this agent selects, for example Pi's `CodingTools`. */
     readonly extensions?: readonly Extension[];
-    readonly skills?: readonly Skill[];
+    /**
+     * The agent's skills: an array, or a `SkillSource` (`directorySkillSource`, `fileSkillSource` or a host's own) read on use with
+     * `liveSkills`. A source cannot be combined with `selfEvolving`.
+     */
+    readonly skills?: readonly Skill[] | SkillSource;
     /**
      * Sub-agents this agent may hand a task to: each becomes a `delegate` tool (`createDelegateTool`) among this agent's tools, and
      * `install` installs the child agent's extensions too. The child runs in a conversation owned by the tool call, with only its own tools.
@@ -47,7 +51,7 @@ export interface DefinedAgent {
     readonly id: string;
     /** Every native extension this agent selects, own extension first; with `selfEvolving` the per-workspace extension (as first defined) last. */
     readonly extensions: readonly Extension[];
-    /** Name and description of this agent's skills, for hosts that offer them in a `/` menu. */
+    /** Name and description of this agent's skills (an array given to `skills`), for hosts that offer them in a `/` menu. A source's skills are read at run time and not listed. */
     readonly skills: readonly Pick<Skill, 'name' | 'description'>[];
     /** Native per-conversation agent configuration. */
     readonly agent: AgentChange;

package/dist/agents.js

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 import { AgentDoc, defineExtension } from '@earendil-works/pi-durable';
 import { createSelfEvolution } from './self-evolving.js';
-import { NAME, createSkillsExtension, parseSkill, validSkill } from './skills.js';
+import { NAME, isSkillArray, liveSkills, staticSkills, validSkill } from './skills.js';
 import { createDelegateTool } from './delegate.js';
-export { createSkillsController, createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
+export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, 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. */
@@ -23,7 +23,13 @@ export function defineAgent(spec) {
     // The skills of a self-evolving agent live in its per-workspace extension, so agent-written skills join them on reload. Without a
     // workspace (a self-evolving agent whose workspace is chosen per conversation, before `inWorkspace`) they stay the host's alone.
     const evolving = spec.selfEvolving === true && spec.workspace !== undefined;
-    const hostSkills = spec.skills?.length && !evolving ? [createSkillsExtension(`agent.${spec.id}.skills`, spec.skills)] : [];
+    if (spec.selfEvolving && spec.skills !== undefined && !isSkillArray(spec.skills))
+        throw new TypeError(`Agent ${spec.id}: selfEvolving takes an array of skills, not a SkillSource`);
+    const fixed = spec.skills === undefined ? [] : isSkillArray(spec.skills) ? spec.skills : [];
+    const skillsName = `agent.${spec.id}.skills`;
+    const hostSkills = spec.skills === undefined || evolving ? [] : isSkillArray(spec.skills)
+        ? (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);
     /** The agent as one native configuration: its own extensions, the host's, and with `evolution` the per-workspace one last. */
@@ -38,7 +44,7 @@ export function defineAgent(spec) {
             ...(spec.thinkingLevel === undefined ? {} : { thinkingLevel: spec.thinkingLevel }),
             ...(spec.cwd === undefined ? {} : { cwd: spec.cwd }),
         });
-        const fixedSkills = listed(spec.skills ?? []);
+        const fixedSkills = listed(fixed);
         return Object.freeze({
             id: spec.id, extensions, agent,
             get skills() { return evolution ? listed(evolution.skills()) : fixedSkills; },
@@ -58,7 +64,7 @@ export function defineAgent(spec) {
         });
     }
     const evolutionOf = (workspace) => createSelfEvolution({
-        name: `self-evolving:${workspace}`, skills: (spec.skills ?? []).map(validSkill), parseSkill, skillsExtension: createSkillsExtension, reserved,
+        name: `self-evolving:${workspace}`, skills: fixed.map(validSkill), reserved,
     });
     if (!spec.selfEvolving)
         return assemble([...own, ...hostSkills], undefined);

package/dist/mentions.d.ts

@@ -33,8 +33,8 @@ export declare const MENTION_LIMITS: Readonly<{
 }>;
 /** Every part this module adds starts with this prefix, so a viewer can tell it from what the person typed. */
 export declare const MENTION_FILE_PREFIX = "<file path=\"";
-/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax pi-chat produces. The registry item `pi-chat` cannot import this, so it copies the
- * parser (`MENTION_TOKEN` and `pieces` in `registry/pi-chat/config.ts`); `test/contracts/pi-chat-source.test.mjs` keeps the two equal. */
+/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax the chat writes. The browser cannot import this, so the kit's `chat-text` holds the
+ * same parser (`mentionedPaths`, `MENTION_TOKEN` and `pieces` of `@hachej/boring-ui-kit/chat-text`); `test/packages/ui-chat-text.test.mjs` keeps the two equal. */
 export declare function mentionedPaths(text: string): string[];
 /** A workspace-relative path with no absolute prefix, no `..`, no backslash and no control characters. */
 export declare function safeMentionPath(path: string): boolean;

package/dist/mentions.js

@@ -3,8 +3,8 @@ import { SNIFF_BYTES, fileKind, nativeImageType } from './file-types.js';
 export const MENTION_LIMITS = Object.freeze({ fileBytes: 100_000, totalBytes: 300_000, files: 20 });
 /** Every part this module adds starts with this prefix, so a viewer can tell it from what the person typed. */
 export const MENTION_FILE_PREFIX = '<file path="';
-/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax pi-chat produces. The registry item `pi-chat` cannot import this, so it copies the
- * parser (`MENTION_TOKEN` and `pieces` in `registry/pi-chat/config.ts`); `test/contracts/pi-chat-source.test.mjs` keeps the two equal. */
+/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax the chat writes. The browser cannot import this, so the kit's `chat-text` holds the
+ * same parser (`mentionedPaths`, `MENTION_TOKEN` and `pieces` of `@hachej/boring-ui-kit/chat-text`); `test/packages/ui-chat-text.test.mjs` keeps the two equal. */
 export function mentionedPaths(text) {
     const found = new Set();
     for (const match of text.matchAll(/(^|\s)@(?:"((?:[^"\\]|\\.)*)"|([^\s]+))/g)) {

package/dist/run-ledger.d.ts

@@ -0,0 +1,98 @@
+import type { Context } from '@earendil-works/chord';
+import type { SyncSql } from './run-outbox.js';
+import type { ResultCard, ResultConversation, ResultInvoke, ResultSubmission, ResultValidationRecord } from './run-result.js';
+import type { RunEnd, RunUsage, RunView } from './runs.js';
+/**
+ * The runs a home keeps in a person's own store, and the runner over them: start a run by its key (the same key is the same run),
+ * end it exactly once, deliver its end to the operation that started it, cancel it, and find again what a stopped process left.
+ * The store is the host's data (a table in its SQLite file); the model turns stay Pi's (the run is a native conversation).
+ */
+export declare const RUNS_TABLE = "CREATE TABLE IF NOT EXISTS _host_agent_runs (key TEXT PRIMARY KEY, agent TEXT NOT NULL, status TEXT NOT NULL, output TEXT, error TEXT, deliver TEXT, validation TEXT, delivered INTEGER NOT NULL DEFAULT 0, person TEXT NOT NULL, usage TEXT, started_at TEXT)";
+export interface RunRow {
+    readonly key: string;
+    readonly agent: string;
+    readonly status: string;
+    readonly output: string | null;
+    readonly error: string | null;
+    readonly deliver: string | null;
+    readonly validation: string | null;
+    readonly delivered: number;
+    readonly person: string;
+    readonly usage: string | null;
+    readonly started_at: string | null;
+}
+/** A refusal with an HTTP-like `status` (404: no such agent; 409: the key belongs to another agent). */
+export declare class RunRefused extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface EndOptions {
+    readonly output?: unknown;
+    readonly error?: string | null;
+    readonly validation?: ResultValidationRecord;
+    readonly usage?: RunUsage | null;
+}
+/** The ledger over a store's synchronous SQL (`SyncSql`: `UPDATE ... RETURNING` is what makes an end happen once). */
+export declare function createRunLedger(sql: SyncSql): {
+    ensure: () => void;
+    get: (key: string) => RunRow | undefined;
+    /** Record a new running run. The caller has checked `get(key)` first. */
+    begin(run: {
+        key: string;
+        agent: string;
+        deliver: string | null;
+        person: unknown;
+        startedAt: string;
+    }): void;
+    /** End a run still running, once (a cancel and the run's own end race): false when something else ended it first. */
+    end(key: string, status: RunEnd, options?: EndOptions): boolean;
+    /** A completed run whose delivery-time check failed: its end becomes the failure (never after it was delivered). */
+    fail(key: string, status: RunEnd, error: string): void;
+    markDelivered(key: string): void;
+    /** Runs a stopped process left: still running (they end `interrupted`), or ended and not delivered. */
+    left(): RunRow[];
+    view(row: RunRow): RunView;
+};
+export type RunLedger = ReturnType<typeof createRunLedger>;
+/** A started run's live handle: its conversation and first submission, and the card it answers. */
+export interface RunExecution {
+    readonly conversation: ResultConversation & {
+        abort(context: Context): Promise<unknown>;
+    };
+    readonly submission: ResultSubmission;
+    readonly card: ResultCard;
+}
+export interface RunnerOptions {
+    readonly ledger: RunLedger;
+    /** The person whose store this is: written on each row so another process can deliver it as them. */
+    readonly person: unknown;
+    readonly context: Context;
+    /** Whether the home has this agent (a start of an unknown agent is refused 404 before any row is written). */
+    readonly has: (agent: string) => boolean | Promise<boolean>;
+    /** Open the run's conversation and submit its input: null when the agent is gone. */
+    readonly prepare: (agent: string, input: unknown) => Promise<RunExecution | null>;
+    /** Call an operation as the person: the result validators and the delivery (which may reach an `internal` operation). */
+    readonly invoke: ResultInvoke;
+    /** The run's model answers summed, from its conversation; null when none answered. */
+    readonly usage?: (conversation: RunExecution['conversation']) => Promise<RunUsage | null>;
+    /** The host's spend meter: throws `over_budget` when the app may not spend now. A refused run is never started and ends `error: over_budget`. */
+    readonly admit?: () => void;
+    readonly now?: () => string;
+    readonly deliverAttempts?: number;
+    readonly deliverBackoffMs?: number;
+}
+/**
+ * The runner of one person's store. A run lives in this process: one a restart cut short is found by `recover` and ends
+ * `interrupted`; one that ended and was not delivered is delivered then. Delivery is once (the host's receipt `deliver:<key>`).
+ */
+export declare function createRunner(options: RunnerOptions): {
+    /** Starts the run of this key (a key already started is the same run, whatever else is asked): launched and returned at once. */
+    start(agent: string, input: unknown, key: string, deliverTo: string | null): Promise<RunView>;
+    /** The run of this key as recorded, or null. Never waits on a delivery in flight: safe to call from inside one. */
+    status(key: string): Promise<RunView | null>;
+    /** Cancels it (its delivery gets `cancelled`); a run that has ended stays as it is; null: no such run. */
+    cancel(key: string): Promise<RunView | null>;
+    recover: () => Promise<void>;
+};
+export type Runner = ReturnType<typeof createRunner>;
+//# sourceMappingURL=run-ledger.d.ts.map