omkit 0.4.8 → 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+## 0.7.0
+
+### Added
+
+- **`omkit skill` — generate the map an assistant reads before its first call.** Writes
+  `.claude/skills/omkit-runs/SKILL.md` from what a project's oms and actions declare: what each
+  one does, the arguments it takes, and how to invoke it — both the shell form, which always
+  works, and the MCP form when the server is wired up. The MCP server answers the same questions
+  at runtime, but charges a round trip for it: an assistant has to call `list_oms` before it can
+  build arguments for anything. A skill file is already in context.
+- **A static "calls" outline per workflow.** Read from the body rather than from a run: the
+  imported calls it makes, in source order, each with the `.tag("…")` its author wrote. Tags turn
+  out to be the right signal precisely because they were already an outline written by the person
+  who wrote the run. Labelled in the generated file as the approximation it is — a conditional
+  call is listed unconditionally, a loop once, a dynamically chosen action not at all, and a call
+  made inside a helper function is invisible to it.
+- **`omkit skill --check`.** Compares a `registry-hash` carried in the file's header against a
+  fresh read of the project and exits non-zero on drift, for a pre-commit hook or a CI step. The
+  hash covers the registry — names, paths, summaries, modes, schemas, outlines — and deliberately
+  not the rendered markdown, so reformatting the file is not drift while an edited om is.
+- **`omkit ls --describe`.** Renders each entry's summary and an `[mcp]` / `[mcp, long-lived]`
+  marker, from the same discovery fork. Opt-in on purpose: plain `omkit ls` stays the static scan
+  and nothing else, which is what keeps it instant and safe to run in a repo whose oms would
+  otherwise start servers.
+- `--out` and `--root` for `omkit skill` — where the file lands, and what its recorded paths are
+  relative to. The root defaults to the tsconfig's directory, which is the same place for the
+  common layout; `--root` covers a repo that keeps its om project in a subfolder, where the
+  reader's working directory is the repo and so the paths must be too.
+- `RegistrationSet.registry` — the static scan that chose the candidate files, carried through so
+  a caller wanting both halves does not build a second TypeScript program.
+
+- **`drivePage` — evaluate JS in a live page and report what came back.** Reaches its page
+  either way round: given a capability handle it drives a page an earlier action in the same
+  run published, and given a CDP address it attaches to a browser in another process. That
+  second mode is what makes browser work callable from outside — `browser` and `chromePage`
+  publish handles, and a handle is not something a caller across a process boundary can pass.
+  Nothing is owned in either mode, so finishing, failing, or being cancelled never tears down
+  the stack it attached to.
+- **`chromePage` can attach to a tab that is already open**, via `match`. A string or regex
+  tests the URL; a `{ js }` predicate is evaluated inside each page until one returns something
+  truthy, which is the only way to select on what a URL cannot express — the title, a rendered
+  element, whether the app has finished booting. No match is an error listing what _was_ open,
+  rather than a silent blank tab.
+
+### Fixed
+
+- **Two spellings of one path no longer mean two different things** (Windows). A
+  case-insensitive filesystem let `d:\repo\om.ts` and `D:\repo\om.ts` name the same file, and
+  omkit keyed on the string twice. Node caches ES modules by URL, so a child forked with one
+  spelling loaded a _second_ copy of omkit — and an action could not see the run it was
+  running inside, failing with a bare "no active om() run". The same mismatch gave one om two
+  `omHash` identities, so `logs/<name>-<hash>/` stopped meaning "every run of this om" and the
+  folder `start_om` predicted was not the folder the run created. Paths are now canonicalised
+  through the OS at the two points that matter: the static scan, and the fork.
+  Existing run folders are unaffected — they were already written under the canonical spelling;
+  it was discovery that disagreed with them.
+
+### Changed
+
+- `DiscoveredOm` gained `calls`, so `omkit ls --json` carries the outline. Additive, and derived
+  statically, so `discover()` is still the pass that never executes user code.
+- The generated `description` in the skill's frontmatter is preserved across regeneration. It is
+  the field that decides whether an assistant loads the file at the right moment, so it has to say
+  _when to use this_ — which is authored prose, not something a generator should overwrite. The
+  built-in wording is only ever written into a file that does not exist yet.
+
+## 0.6.0
+
+### Added
+
+- **`omkit mcp` — serve a project over the Model Context Protocol.** A third frontend beside
+  the terminal commands and the interactive app, on stdio, so Claude and other assistants can
+  list a project's runnable oms, run one, and read what the run produced. Six tools, fixed
+  however many oms a project has: list them, run one and wait for a verdict, start one and get
+  a handle, check on a run, tail its log from a cursor, cancel it.
+- **`om(name).mcp({ mode })` and `action(name).mcp({ mode })`** — the exposure marker. Without
+  it an entry is invisible to the server: `.describe()` and `.args()` alone expose nothing, so
+  a project opts in per entry. `mode` is `"settling"` (the default) or `"long-lived"`; MCP has
+  no way to say a tool never finishes, so omkit says it instead, and `run_om` refuses a
+  long-lived entry rather than blocking on it.
+- **Run folders as MCP resources**, under `omkit://runs/{run}/latest/{file}` and
+  `omkit://runs/{run}/{date}/{time}/{file}`. The `latest` form is what a stable run identity
+  buys: an assistant can ask for the last run of an om without having watched it happen. Every
+  read is confined under the project's `logs/`, checked lexically and through the resolved real
+  path, size-capped, and read-only.
+- **Progress, cancellation and elicitation during a run.** Milestones become progress
+  notifications keyed on the run's own log sequence; a cancelled request tears the run down and
+  it still writes its record; and a prompt raised mid-run reaches the client as an elicitation.
+  A client that declines, or cannot elicit, gets the prompt's default instead of leaving the run
+  waiting.
+- **`discoverRegistrations()` / `readRegistrations()` on the client.** Reads what a project's
+  oms and actions declare — summaries and real argument schemas — by importing them in a
+  throwaway child with `OMKIT_DISCOVER=1`, where `.run(body)` registers instead of launching.
+  Necessary because importing an om file runs it. `discover()` is unchanged and still never
+  executes user code, so `omkit ls` is exactly as fast as before.
+- **Action-backed tools.** An exposed action is forked through a host om omkit ships, since an
+  action cannot run outside a run. Its runs land in the same `logs/` tree, under a name that
+  carries the action's own identity, so two same-named actions in different files never share a
+  folder.
+- `RunOptions.env` — extra environment for a run's child process. This is how arguments reach
+  a run the server starts.
+
+### Fixed
+
+- **Two runs of the same om starting within the same second no longer share a run folder.**
+  Folder names have second resolution, and `raw.jsonl` is opened truncating — so a collision
+  did not mean "the later run wins", it meant both processes truncated the same file and wrote
+  at independent offsets, leaving bytes that were not valid JSONL. Creating the directory is now
+  itself the lock (`mkdir` without `recursive` fails atomically, across processes), and a
+  genuine collision gets a `-02` suffix. Names are unchanged in the ordinary case.
+
+### Notes
+
+- Nothing changes for a project that never calls `.mcp()`. The MCP SDK is imported only under
+  the new `mcp/` folder, so the runtime is untouched for everyone else.
+
+## 0.5.0
+
+### Breaking
+
+- **`om(name, body)` removed.** Use `om(name).run(body)`. Run folders are unchanged:
+  identity is the om's name plus its defining file, and line numbers are excluded from
+  the hash, so migrating a call site preserves its history. A two-argument call now
+  throws and names the replacement rather than silently dropping the body.
+
+### Added
+
+- `om(name).describe({ summary })` and `action(name).describe({ summary })` — the summary
+  survives every builder link and is stored where it can be read back: on the `Action` an
+  action's `.run(...)` returns, and on the run an om's `.run(...)` starts. Nothing in the
+  runtime reads it yet — `omkit ls` does not show it.
+- `action(name).args(schema)` pins the type of `.run`'s args parameter (the action's first
+  argument) to a zod schema's inferred type. Type-level only: the schema is not validated
+  at runtime, because an action launched from an om body is passed its arguments in code.
+- `om(name).args(schema)` declares the run's inputs and resolves them at run start, passing
+  the typed result to `.run`'s body as its second parameter. Each field is filled from what
+  was supplied (`OMKIT_ARGS`, a JSON object, read once at run start and then cleared from the
+  environment so subprocesses do not inherit it), then the schema's defaults, then by prompting
+  — and if nobody can be asked, the run fails naming every unresolved field at once rather
+  than blocking on a question no one will see. A blank answer re-asks instead of coercing;
+  an object or array field can be answered with a pasted JSON blob or the path to a JSON file.
+  The resolved values are recorded on the root node, so `result.json` and the `main.log`
+  header report what the run was actually given.
+- `ctx.artifact(name, file, opts?)` labels a file the run produced. Registrations reach
+  the timeline and `artifacts.log` (every call, chronologically) and `result.json`, which
+  carries the latest registration per `(node, name)` — so one node re-labelling a name
+  updates in place, while two nodes choosing the same name both survive.
+- `prompt({ kind: "multiline" })` reads a block of text, terminated by parseable JSON,
+  a sentinel line, or a predicate.
+
+_Releases before 0.5.0 predate this file._

package/README.md

@@ -7,6 +7,19 @@
 
 A tiny runtime for the workflows _around_ your code — start servers, wait for health checks, build, watch, drive a browser, read state back, and tear it all down together. You write the orchestration as ordinary TypeScript; the run **narrates itself** into a structured, on-disk record — what launched, what came up, what attached, what failed, what the world actually looked like — that an AI assistant can read instead of guessing from terminal scrollback. Where [tskb](https://www.npmjs.com/package/tskb) is the _knowledge_ layer (what your system **is**), `omkit` is the _operational_ one (what it's **doing right now**).
 
+## Migrating from om(name, body)
+
+`om(name, body)` was removed in 0.5.0. `om(name)` now returns a builder, and `.run(body)` takes the place of the second argument:
+
+```diff
+-om("dev", async (ctx) => {
++om("dev").run(async (ctx) => {
+   // ...
+ });
+```
+
+Run folders are unaffected — a run's identity is its name plus its defining file, and line numbers are not part of the hash, so migrating a call site keeps its history.
+
 ## The problem
 
 You know the script. Start the API, start the web server, wait until they're _actually_ serving, open the app, maybe run a smoke check — then Ctrl+C and hope everything shut down. Most of us glue this together with `concurrently`, `wait-on`, a shell script, and a pile of opaque interleaved output. When it breaks, you're grepping stdout to find out which process died.
@@ -19,7 +32,7 @@ Now hand that same script to an AI assistant. It has it even worse: interleaved
 import { om } from "omkit";
 import { command, healthcheck, browser, chromePage } from "omkit/actions";
 
-om("dev", async () => {
+om("dev").run(async () => {
   // `command` names the action after the command and launches it — a normal action call.
   command("npm run dev", { cwd: "api" }).tag("api"); // start both dev servers as daemons…
   command("npm run dev", { cwd: "web" }).tag("web");
@@ -74,7 +87,46 @@ const build = action("build").run(({ proc }) => proc("tsc")`tsc -b`);
 const activity = build(); // calling launches; returns the live Activity
 ```
 
-`om(name, async (ctx) => …)` hosts the orchestration as the root of a run. The name plus the file it's defined in identify the run — logs land in `logs/<name>-<hash8>/…`, so same-named oms in different files never share a folder. You write ordinary `await` / `if` / loops / variables; the Activities you launch keep running in parallel, and because the body stays in-flight while you `await`, the run never idles shut between steps. Config chained synchronously on an Activity right after launching it (like `withCache`) applies before its body runs — the body commits one microtask later, so chain it in the same tick, before you `await`. For a one-off inline step, `step(name, fn)` runs `fn` as its own node without a reusable definition.
+Chain `.describe({ summary })` before `.run(...)` to attach a human-readable summary — stored on the definition, for `omkit ls` and future tooling to read; nothing reads it yet, so today it is documentation that travels with the code. Same shape as `om`'s, below. `.args(schema)` pins the type of `.run`'s second parameter to a zod schema's inferred type. It's **type-level only**: nothing here resolves, prompts for, or validates the value — an action launched from an om body is passed its arguments directly in code, so the schema exists to type that call site, not to gate it. (Resolving/prompting for arguments is an `om`-level concern, not `action`'s.)
+
+```ts
+import { z } from "zod";
+
+const seed = action("seed")
+  .describe({ summary: "Seeds the database" })
+  .args(z.object({ rows: z.number() }))
+  .run(async (_ctx, { rows }) => {
+    /* rows: number — typed, not validated */
+  });
+
+seed({ rows: 500 }); // calling launches it; the shape is pinned, not checked at runtime
+```
+
+`om(name).run(async (ctx) => …)` hosts the orchestration as the root of a run. `om(name)` returns a builder: chain `.describe({ summary })` to attach a human-readable summary (stored on the run; nothing reads it yet) and/or `.args(schema)` to declare what the run needs, then finish with `.run(body)`, which launches it. The name plus the file it's defined in identify the run — logs land in `logs/<name>-<hash8>/…`, so same-named oms in different files never share a folder. You write ordinary `await` / `if` / loops / variables; the Activities you launch keep running in parallel, and because the body stays in-flight while you `await`, the run never idles shut between steps. Config chained synchronously on an Activity right after launching it (like `withCache`) applies before its body runs — the body commits one microtask later, so chain it in the same tick, before you `await`. For a one-off inline step, `step(name, fn)` runs `fn` as its own node without a reusable definition.
+
+### Run arguments — `om(name).args(schema)`
+
+An om declares what it needs, and omkit fills it in. Unlike `action`'s `.args()`, this one is **resolved at runtime**: `.run`'s body receives the resolved, validated values as its second parameter, typed by the schema.
+
+```ts
+import { z } from "zod";
+
+om("seed")
+  .args(z.object({ rows: z.number(), truncate: z.boolean().default(false) }))
+  .run(async (ctx, args) => {
+    // args: { rows: number; truncate: boolean } — already resolved and validated
+    await command(`./seed.sh --rows ${args.rows}`).result;
+  });
+```
+
+Each field is filled from the first of these that can answer:
+
+1. **Supplied** — `OMKIT_ARGS`, a JSON object in the environment. It is read once at run start and then cleared, so a subprocess the run spawns doesn't inherit one om's args and resolve them against another's schema.
+2. **Defaults** — anything the schema defaults, which is therefore never asked about.
+3. **Prompt** — whatever is still missing, one field at a time, with a one-line type sketch (`rows (number)`). Objects and arrays are asked for as a multiline JSON block — paste it, or answer with the path to a JSON file. A blank answer is _no answer_, not a value: it re-asks rather than coercing (`Number("")` is `0`). Resolution gives up after three rounds.
+4. **Fail** — if nobody can be asked (no supervising picker and no TTY), the run fails naming every unresolved field at once, instead of prompting into the void.
+
+Resolution happens **inside** the run, so a prompt and its answer land on the run's own timeline, and the values it settled on are recorded in `result.json` and the `main.log` header — a later reader can see exactly what the run was given.
 
 ### Typed capabilities
 
@@ -91,7 +143,7 @@ const server = action("server")
 
 const migrate = action("migrate").run((_ctx, port: Promise<number>) => runMigrations(port));
 
-om("migrate", async () => {
+om("migrate").run(async () => {
   const s = server();
   migrate(s.ref); // migrate receives the port the moment the server attaches it — typed
 });
@@ -133,12 +185,12 @@ flakyBackgroundJob().result.catch((e) => console.warn("job failed, carrying on",
 
 Every action's output, events, asserts, snapshots, and lifecycle land on **one timeline** — streamed live to the terminal (curated milestones) and written to a per-run folder:
 
-- `result.json` — the run's tree, per-node status, and verdict.
+- `result.json` — the run's tree, per-node status, verdict, and curated artifacts.
 - `raw.jsonl` — every entry, machine-readable.
 - `main.log` + one `.log` per action — the human-readable timelines.
-- `events.log` / `asserts.log` / `snapshots.log` — cross-cutting rollups.
+- `events.log` / `asserts.log` / `snapshots.log` / `artifacts.log` — cross-cutting rollups.
 
-`ctx` also gives each action `assert(cond, msg)` (tallies into the run's verdict) and `snapshot(name, value)` (captures JSON state to the run folder) — so a run is an inspectable artifact, not just an exit code.
+`ctx` also gives each action `assert(cond, msg)` (tallies into the run's verdict), `snapshot(name, value)` (captures JSON state to the run folder), and `artifact(name, file, opts?)` (labels a file the action wrote — name, optional description, MIME inferred from the extension — and returns its absolute path) — so a run is an inspectable artifact, not just an exit code. Write the files you label under `ctx.artifactsFolder`, the run's own output folder.
 
 Run folders have a **stable identity**: `logs/<name>-<hash8>/<date>/<time>/`, keyed by the om's name and the file that defines it. An assistant (or a script) can always find "the latest `tskb-dev` run" without parsing scrollback, diff two runs of the same pipeline, or answer questions with evidence instead of inference: _did the server actually pass its healthcheck? which process died first? what config did the build run with?_ It's all in the folder — attributed per action, timestamped, with a verdict.
 
@@ -153,7 +205,7 @@ The batteries are built around **ground truth**. `healthcheck` gates on the serv
 ```ts
 const build = action("build").run(({ proc }) => proc("tsc")`tsc -b`);
 
-om("build", async () => {
+om("build").run(async () => {
   const out = await build().withCache(`${process.cwd()}/src`).result;
   if (out === undefined) console.log("no changes — skipped the build");
 });
@@ -164,7 +216,7 @@ om("build", async () => {
 ```ts
 import { watchDir } from "omkit/actions";
 
-om("watch", async () => {
+om("watch").run(async () => {
   const watcher = watchDir("src").tag("watch");
   watcher.on("update", (file) => console.log(`changed: ${file}`));
   // body returns, but the watcher keeps the run alive until Ctrl+C
@@ -174,7 +226,7 @@ om("watch", async () => {
 **Gate a deploy on green tests.** A red test rejects at the `await`; catch it to branch:
 
 ```ts
-om("ship", async () => {
+om("ship").run(async () => {
   try {
     await command("npm test").result; // resolves on green, throws on red
   } catch {
@@ -189,7 +241,7 @@ om("ship", async () => {
 ```ts
 import { prompt } from "omkit/actions";
 
-om("deploy", async () => {
+om("deploy").run(async () => {
   const answer = await prompt({
     kind: "choice",
     message: "Deploy to production?",
@@ -201,6 +253,21 @@ om("deploy", async () => {
 });
 ```
 
+**Take a block of text.** `kind: "multiline"` reads lines until `until` says stop: parseable JSON (the default), a sentinel line, or a predicate over the text so far. The JSON default is self-terminating, so a pretty-printed blob can be pasted straight in with nothing to explain:
+
+```ts
+om("seed").run(async () => {
+  const blob = await prompt({
+    kind: "multiline",
+    message: "Paste the service config",
+    hint: "{ host: string; port: number }", // a one-line type sketch, shown under the message
+    until: "json", // the default; or "." to end on that line, or (text) => text.length > 500
+  }).result;
+  const config = JSON.parse(blob);
+  await command(`./seed.sh --host ${config.host}`).result;
+});
+```
+
 ## Events
 
 An Activity exposes its declared events plus the lifecycle ones (`done`, `error`, `attached`):
@@ -224,7 +291,7 @@ Reusable actions built on the core engine. For anything beyond these, drop down
 - **`tailLog`** — tail a file another process writes, folding its lines into the combined log.
 - **`healthcheck`** — poll a URL/port until the status (and optionally body) matches.
 - **`portFree`** — the mirror of `healthcheck`: poll a TCP port until nothing is listening, so a restart can rebind without racing the old process.
-- **`prompt`** — ask the terminal for input or a choice, with a timeout that falls back to a default; the answer is its handle.
+- **`prompt`** — ask the terminal for input, a choice, or a multiline block, with a timeout that falls back to a default; the answer is its handle.
 - **`browser`** — launch a Chromium browser with Playwright and expose the live `Browser` as a handle (defaults to the installed Chrome); closed on teardown. Feed its `.ref` to `chromePage`.
 - **`chromePage`** — attach to Chrome over CDP, or to an existing Playwright `Page`/`Browser`/`Context` (including a `browser` handle or an Electron window), and expose the live `Page` as a handle.
 
@@ -235,12 +302,101 @@ Point the `omkit` bin at a project — a `tsconfig.omkit.json` that lists your `
 - **`omkit init`** — scaffold a starter project: `tsconfig.omkit.json`, a sample `oms/dev.ts`, and `actions/hello.ts`.
 - **`omkit run`** — with no argument, open the interactive picker: browse and search your oms, run one, and watch its milestones stream live — answering any `prompt` in-console. A bare `omkit` does the same (`run` is the default command).
 - **`omkit run <om>`** — run one om directly by name or file path, inheriting the terminal.
-- **`omkit ls`** — list the discovered oms and actions.
+- **`omkit ls`** — list the discovered oms and actions. Add `--describe` to show each one's `.describe({ summary })` and whether it's exposed; without it, `ls` is a static scan that never imports your code.
 - **`omkit check`** — typecheck the project (`tsc --noEmit`) and report diagnostics.
+- **`omkit skill`** — generate `.claude/skills/omkit-runs/SKILL.md`, a map of what's runnable (see below).
+- **`omkit mcp`** — serve the project over the Model Context Protocol on stdio (see below).
 - **`omkit help`** — print the command overview (also `--help` / `-h`).
 
 Both paths run the om in its own child process and narrate it to a run folder (see above). The picker **supervises** the child — piping its output into the live view and answering prompts for it — while `omkit run <om>` runs it **bare**, handing the om your terminal directly.
 
+## MCP — let an assistant drive your oms
+
+`omkit mcp` serves a project over the [Model Context Protocol](https://modelcontextprotocol.io), so Claude and other assistants can discover your oms, run one, and read what the run produced — instead of shelling out and scraping stdout.
+
+**Nothing is exposed unless you say so.** Add `.mcp()` to an om or action; without it the server neither lists nor runs it. `.describe()` and `.args()` alone expose nothing.
+
+```ts
+om("smoke-test")
+  .describe({ summary: "Boot the app and run the smoke suite" })
+  .args(z.object({ headless: z.boolean().default(true) }))
+  .mcp() // ← now an assistant can run it
+  .run(async (ctx, { headless }) => {
+    /* … */
+  });
+```
+
+`mode` defaults to `"settling"` — a run that finishes on its own. Declare `.mcp({ mode: "long-lived" })` for a server or a watcher: MCP has no way to express "this never finishes", so omkit does. `run_om` refuses a long-lived entry and points you at `start_om`.
+
+Point your client at the project:
+
+```json
+{
+  "mcpServers": {
+    "omkit": {
+      "command": "npx",
+      "args": ["--no", "--", "omkit", "mcp"]
+    }
+  }
+}
+```
+
+The server takes its **project root from the working directory your client launches it in**, and resolves `logs/` under that root — so runs it starts are the runs its resources can serve. If your config lives at the repo root but the om project sits in a subfolder, point at the config explicitly rather than relying on a `cwd` field your client may not support: `["--no", "--", "omkit", "mcp", "--tsconfig", "om/tsconfig.omkit.json"]`.
+
+### Inspecting it
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) drives the same binary, so you can exercise every tool by hand before pointing an assistant at it:
+
+```sh
+npx -y @modelcontextprotocol/inspector npx --no -- omkit mcp
+```
+
+It serves a UI on `localhost:6274` and prints an auth token to paste in. Because omkit declares real input schemas, you get form fields per tool — and the history pane shows the full request and response for each call, `structuredContent` and resource links included. That is usually all the debugging you need: it is a client, so it shows you what _you_ sent, not what an assistant sent.
+
+Two things to know. On Windows the Inspector cannot spawn a `.cmd` shim directly, so if `npx` fails there, point it at the binary instead — `node node_modules/omkit/dist/cli/index.js mcp`. And the Inspector owns the runs it starts: closing it tears down anything `start_om` left running, the same rule that applies to any client.
+
+**Six tools**, however many oms you have — adding one changes what `list_oms` returns, never the tool list:
+
+| Tool                    | What it does                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `list_oms`              | Exposed oms and actions: summary, mode, and the JSON Schema for their arguments |
+| `run_om(name, args)`    | Runs a settling entry to completion and returns its verdict and assert tally    |
+| `start_om(name, args)`  | Starts anything and returns a handle immediately                                |
+| `get_run(run)`          | Status, verdict once settled, and links to the files the run produced           |
+| `tail_run(run, cursor)` | Log lines since `cursor` — live while running, from `raw.jsonl` once settled    |
+| `cancel_run(runId)`     | Tears a run down; it still finishes writing its run folder                      |
+
+Call `list_oms` first — `run_om`'s `args` is a plain object, so its schema comes from the listing rather than from the tool definition. That is the cost of a tool list that doesn't churn every time you edit a file.
+
+**Run folders are resources.** `omkit://runs/{run}/latest/{file}` reads from the newest run of an om, and `omkit://runs/{run}/{date}/{time}/{file}` from one specific run. Reads are confined under the project's `logs/`, size-capped, and read-only. Files a run labelled with `ctx.artifact` come back named and described.
+
+**While a run is going**, milestones arrive as progress notifications, cancelling the request tears the run down (and it still writes its record), and a `prompt` raised mid-run reaches you as an elicitation — the client is the supervisor.
+
+## A skill file — the map, before the first call
+
+`list_oms` answers "what can I run here?" at runtime, but charges a round trip for it: an assistant has to call it before it can build arguments for anything. `omkit skill` writes the same answer to disk, where it's already in context:
+
+```sh
+omkit skill          # writes .claude/skills/omkit-runs/SKILL.md
+omkit skill --check  # exits non-zero when it no longer matches the project
+```
+
+Each exposed workflow gets its summary, its argument shape, the path to its source, and an outline of what it calls — read statically from the body, with the `.tag("…")` names you already wrote:
+
+```
+### `tskb:build` — settling
+
+Rebuild the tskb knowledge graph from this repo's .tskb.tsx docs.
+
+- **Defined in:** `om/oms/tskb-build.ts`
+- **Args:** `{ verbose?: boolean, projectName?: string }`
+- **Calls:** `watchDir` [watch:build:daemon] → `buildDocs` [build]
+```
+
+Generating it runs nothing — it uses the same discovery fork as `list_oms`, where `.run(body)` reports what it declares instead of launching. The file documents the shell invocation as well as the MCP one, so it's useful with no MCP wiring at all.
+
+It's meant to be committed. A `registry-hash` in the header covers the project's declarations rather than the rendered markdown, so `--check` catches an edited om but not a reformatted file — put it in a pre-commit hook or CI. The one field you should edit by hand is the frontmatter `description`, which decides when an assistant loads the file; regeneration preserves it.
+
 ## Install
 
 ```sh

package/dist/actions/chrome-page.d.ts

@@ -16,10 +16,51 @@ export interface ChromePageEvents {
     pageerror: string;
     navigated: string;
 }
+/**
+ * How to pick one page out of the several a browser may have open.
+ *
+ * A plain string or regex tests the URL, which costs nothing and touches no page. A
+ * `{ js }` predicate is **evaluated inside each page** until one returns something truthy,
+ * which is the only way to select on things a URL cannot express — the document's title, a
+ * rendered element, whether the app has finished booting.
+ *
+ * The predicate is a JS **expression**, not a function body: `document.title.includes("x")`,
+ * not `return document.title…`. Wrap multiple statements in an IIFE when you need them.
+ * Keep it pure — it runs against pages that turn out not to match.
+ */
+export type PageMatch = string | RegExp | {
+    js: string;
+};
 export interface ChromePageOptions {
     /** Navigate the attached page here once acquired. Omit to drive it as-is. */
     url?: string;
+    /**
+     * Attach to a page **already open** in the target. Without it the action takes the first
+     * page it finds, or opens a fresh one when {@link ChromePageOptions.url} is set — neither
+     * is what you want when reattaching to a browser someone else is driving.
+     *
+     * No match is an error, not a silent new tab: asking for a specific page and quietly
+     * getting a blank one hides the failure until something downstream reads the wrong
+     * document.
+     */
+    match?: PageMatch;
 }
+/** Every page open across every context — a reattached browser may have more than one. */
+export declare const pagesOf: (browser: Browser) => Page[];
+/**
+ * Find the one open page a {@link PageMatch} selects, or explain what was open instead.
+ *
+ * Listing the candidates matters more here than anywhere else in this action: the caller is
+ * attaching to a browser they did not launch, so "no match" is nearly always a stale URL or a
+ * predicate written against the wrong page — and both are obvious the moment you can see what
+ * was actually there.
+ *
+ * A predicate that throws (a chrome:// page, a document still loading, a cross-origin frame)
+ * counts as "did not match" rather than failing the search, but is reported, because a
+ * predicate that threw on every page is a very different problem from one that simply found
+ * nothing.
+ */
+export declare function selectPage(pages: readonly Page[], match: PageMatch): Promise<Page>;
 /**
  * Publishes a Chrome/Chromium {@link Page} as this action's handle, so downstream
  * actions can await `instance.ref` and drive the same live page. The source is a

package/dist/actions/chrome-page.js

@@ -5,6 +5,80 @@ const isPage = (x) => typeof x.mainFrame === "function";
 const isBrowser = (x) => typeof x.contexts === "function";
 /** Take the first existing page of a context, or open one. */
 const pageOf = (context, fresh) => fresh ? context.newPage() : (context.pages()[0] ?? context.newPage());
+/** Every page open across every context — a reattached browser may have more than one. */
+export const pagesOf = (browser) => browser.contexts().flatMap((c) => c.pages());
+/**
+ * Find the one open page a {@link PageMatch} selects, or explain what was open instead.
+ *
+ * Listing the candidates matters more here than anywhere else in this action: the caller is
+ * attaching to a browser they did not launch, so "no match" is nearly always a stale URL or a
+ * predicate written against the wrong page — and both are obvious the moment you can see what
+ * was actually there.
+ *
+ * A predicate that throws (a chrome:// page, a document still loading, a cross-origin frame)
+ * counts as "did not match" rather than failing the search, but is reported, because a
+ * predicate that threw on every page is a very different problem from one that simply found
+ * nothing.
+ */
+export async function selectPage(pages, match) {
+    const describe = () => pages.length ? pages.map((p) => `  ${p.url()}`).join("\n") : "  (no pages are open)";
+    if (typeof match === "string" || match instanceof RegExp) {
+        const hit = pages.find((p) => typeof match === "string" ? p.url().includes(match) : match.test(p.url()));
+        if (hit)
+            return hit;
+        throw new Error(`no open page matched ${String(match)}. Open pages:\n${describe()}`);
+    }
+    // Sequential, not parallel: stopping at the first hit keeps the predicate off pages it
+    // never needed to touch, which matters because it is someone else's live browser.
+    const threw = [];
+    for (const page of pages) {
+        try {
+            if (await page.evaluate(match.js))
+                return page;
+        }
+        catch (e) {
+            threw.push(`  ${page.url()} — ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const errors = threw.length ? `\nThe predicate threw on:\n${threw.join("\n")}` : "";
+    throw new Error(`no open page satisfied \`${match.js}\`. Open pages:\n${describe()}${errors}`);
+}
+/**
+ * Resolve a {@link ChromePageSource} down to one live page.
+ *
+ * With `match` the page must already exist and is searched for across **every** context: a
+ * reattached browser belongs to someone else, and nothing says the page you want lives in the
+ * context we would otherwise default to. Without `match` the old behaviour stands — take the
+ * first page, or open a fresh one when navigating.
+ */
+async function acquire(source, opts) {
+    const { url, match } = opts;
+    const fresh = url !== undefined;
+    if (typeof source === "string") {
+        const cdpUrl = source.includes("://") ? source : `http://${source}`;
+        let owned;
+        try {
+            owned = await chromium.connectOverCDP(cdpUrl);
+        }
+        catch (cause) {
+            throw new Error(`could not connect to Chrome over CDP at ${cdpUrl}`, { cause });
+        }
+        const page = match
+            ? await selectPage(pagesOf(owned), match)
+            : await pageOf(owned.contexts()[0] ?? (await owned.newContext()), fresh);
+        return { page, from: cdpUrl, owned };
+    }
+    if (isPage(source))
+        return { page: source, from: "page handle" };
+    if (isBrowser(source)) {
+        const page = match
+            ? await selectPage(pagesOf(source), match)
+            : await pageOf(source.contexts()[0] ?? (await source.newContext()), fresh);
+        return { page, from: "browser handle" };
+    }
+    const page = match ? await selectPage(source.pages(), match) : await pageOf(source, fresh);
+    return { page, from: "context handle" };
+}
 /**
  * Publishes a Chrome/Chromium {@link Page} as this action's handle, so downstream
  * actions can await `instance.ref` and drive the same live page. The source is a
@@ -20,35 +94,9 @@ export const chromePage = action("chromePage")
     .run(async ({ signal, emit, attach, tag }, label, source, opts = {}) => {
     tag(label);
     const { url } = opts;
-    // Only a CDP connection we open here is ours to close; handles belong to callers.
-    let owned;
-    let page;
-    let from;
-    if (typeof source === "string") {
-        const cdpUrl = source.includes("://") ? source : `http://${source}`;
-        from = cdpUrl;
-        try {
-            owned = await chromium.connectOverCDP(cdpUrl);
-        }
-        catch (cause) {
-            throw new Error(`could not connect to Chrome over CDP at ${cdpUrl}`, { cause });
-        }
-        const context = owned.contexts()[0] ?? (await owned.newContext());
-        page = await pageOf(context, url !== undefined);
-    }
-    else if (isPage(source)) {
-        from = "page handle";
-        page = source;
-    }
-    else if (isBrowser(source)) {
-        from = "browser handle";
-        const context = source.contexts()[0] ?? (await source.newContext());
-        page = await pageOf(context, url !== undefined);
-    }
-    else {
-        from = "context handle";
-        page = await pageOf(source, url !== undefined);
-    }
+    // With both `match` and `url`, acquire finds the existing page and this navigates it —
+    // "go to that tab, then send it here" rather than opening a second one.
+    const { page, from, owned } = await acquire(source, opts);
     page.on("console", (msg) => {
         console.log(`console: ${msg.text()}`);
         emit("console", `from: ${label}:  ${msg.text()}`);

package/dist/actions/drive-page.d.ts

@@ -0,0 +1,50 @@
+import { type ChromePageSource, type PageMatch } from "./chrome-page.ts";
+export interface DrivePageOptions {
+    /**
+     * Where the page is. Either a **CDP endpoint** (`host:port` or a URL) for a browser
+     * running in another process, or a **live handle** — a `Page`, `BrowserContext`, or
+     * `Browser` — published by an earlier action in this same run.
+     *
+     * Both matter, and for different reasons. The address form is plain data, so it can be
+     * described by a schema and called from outside the process; the handle form skips the
+     * network entirely when the browser is already yours, which is what an om driving its own
+     * stack wants. Defaults to the endpoint `browser` opens when given a debugging port.
+     */
+    target?: ChromePageSource;
+    /** Which open tab to drive. Omit to take the first page the browser has open. */
+    match?: PageMatch;
+    /** Navigate the chosen tab here first. Omit to drive it wherever it already is. */
+    url?: string;
+    /**
+     * The JS to run in the page, as an **expression** — `document.title`, not `return …`.
+     * Wrap several statements in an IIFE: `(() => { …; return x })()`. The result travels
+     * back through the run's log, so it has to be JSON-serialisable.
+     */
+    js: string;
+    /** Save a PNG of the page afterwards and register it as a run artifact. Default true. */
+    screenshot?: boolean;
+}
+/** What {@link drivePage} reports back. */
+export interface DrivePageResult {
+    /** Whatever the expression evaluated to. */
+    readonly value: unknown;
+    readonly title: string;
+    readonly url: string;
+    /** Absolute path of the screenshot, when one was taken. */
+    readonly screenshot?: string;
+}
+/**
+ * Evaluate an expression in a live page and report what came back.
+ *
+ * Reaches its page either way round, and that is the point. Given a **handle** it drives a
+ * page an earlier action in the same run already published — the cheap path, and the one an
+ * om driving its own stack should take. Given a **CDP address** it attaches to a browser in
+ * another process entirely, which is what lets this action be described by a schema and
+ * called by name from outside: `browser` and {@link chromePage} publish capability handles,
+ * and a handle is not something a caller across a process boundary can pass.
+ *
+ * Nothing here is owned. `chromePage` closes only a CDP connection it opened, and closing a
+ * CDP connection disconnects the client rather than stopping the browser — so this finishing,
+ * failing, or being cancelled never tears down the stack it attached to, in either mode.
+ */
+export declare const drivePage: import("../core/types.ts").Action<[opts: DrivePageOptions], DrivePageResult, import("../core/types.ts").NoEvents, void>;