omkit 0.8.24 → 0.8.25

package/README.md

@@ -116,12 +116,12 @@ om(name: string): OmBuilder
 
 Returns a builder. Chain configuration, then finish with `.run(body)`, which launches the run.
 
-| Method                   | Purpose                                                                                                       |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `.describe({ summary })` | A one-line summary, shown by `omkit ls --describe`, the skill file, MCP and the report.                       |
-| `.args(schema)`          | A zod schema for the run's inputs. **Resolved at runtime**; see below.                                        |
-| `.mcp({ mode? })`        | Expose this om over MCP. `mode` is `"settling"` (default) or `"long-lived"`.                                  |
-| `.run(body)`             | Launch the run. `body(ctx, args?)` receives an [`OmContext`](#contexts) and, after `.args()`, the typed args. |
+| Method                      | Purpose                                                                                                                                                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.describe({ summary, … })` | A one-line summary, shown by `omkit ls --describe`, the skill file, MCP and the report. Any further props (`owner`, `docsUrl`, `needs: [...]`) are listed under it in the interactive picker and the report. |
+| `.args(schema)`             | A zod schema for the run's inputs. **Resolved at runtime**; see below.                                                                                                                                       |
+| `.mcp({ mode? })`           | Expose this om over MCP. `mode` is `"settling"` (default) or `"long-lived"`.                                                                                                                                 |
+| `.run(body)`                | Launch the run. `body(ctx, args?)` receives an [`OmContext`](#contexts) and, after `.args()`, the typed args.                                                                                                |
 
 `.run()` returns a promise that resolves once the run has torn down and written its record. It never rejects: failures are recorded in the run and set the process exit code. Whatever the body returns is recorded as the run's `value` in `result.json`.
 
@@ -156,14 +156,14 @@ import { action } from "omkit";
 action(name: string): ActionBuilder
 ```
 
-| Method                   | Purpose                                                                               |
-| ------------------------ | ------------------------------------------------------------------------------------- |
-| `.describe({ summary })` | A one-line summary, carried onto every run of this action.                            |
-| `.emits<Events>()`       | Declare the events this action emits, as a type: `{ ready: number; error: string }`.  |
-| `.ref<Handle>()`         | Declare the type of the value this action publishes with `attach`.                    |
-| `.args(schema)`          | Pin `.run`'s argument to a zod schema's type. **Type-level only** in code; see below. |
-| `.mcp({ mode? })`        | Expose this action over MCP as a runnable tool.                                       |
-| `.run(exec)`             | Bind the implementation. Returns an **Action**: a function you call to launch it.     |
+| Method                      | Purpose                                                                                                     |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `.describe({ summary, … })` | A one-line summary, plus any further props, carried onto every run of this action and listed in the report. |
+| `.emits<Events>()`          | Declare the events this action emits, as a type: `{ ready: number; error: string }`.                        |
+| `.ref<Handle>()`            | Declare the type of the value this action publishes with `attach`.                                          |
+| `.args(schema)`             | Pin `.run`'s argument to a zod schema's type. **Type-level only** in code; see below.                       |
+| `.mcp({ mode? })`           | Expose this action over MCP as a runnable tool.                                                             |
+| `.run(exec)`                | Bind the implementation. Returns an **Action**: a function you call to launch it.                           |
 
 `exec(ctx, ...args)` receives an [`ActionContext`](#contexts) and the arguments the action was called with. Its return value is the activity's result.
 

package/dist/cli/ui/views/OmList.d.ts

@@ -20,3 +20,5 @@ export declare function OmList({ oms, onSelect, status, hint, }: {
     status?: ReactNode;
     hint?: string;
 }): ReactElement;
+/** A description key as a label: `docsUrl` / `docs-url` / `docs_url` → `Docs url`. */
+export declare function labelOf(key: string): string;

package/dist/cli/ui/views/OmList.js

@@ -36,7 +36,32 @@ export function OmList({ oms, onSelect, status, hint = "↑↓ move · enter run
     const restWidth = Math.max(20, columns - nameWidth - 6);
     return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "omkit" }), _jsx(Text, { dimColor: true, children: ` · ${oms.length} om${oms.length === 1 ? "" : "s"}` }), status ? _jsx(Text, { dimColor: true, children: "  " }) : null, status ?? null] }), _jsx(SearchableList, { items: sorted, getKey: (o) => `${o.file}\0${o.name}`, getSearchText: (o) => `${o.name} ${o.summary ?? ""}`, onSelect: onSelect, alwaysShowSearch: true, searchLabel: "search \u203A ", searchPlaceholder: "type to filter by name or summary", renderRow: (o, selected) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { color: selected ? "cyan" : undefined, children: selected ? "❯ " : "  " }), _jsx(Text, { bold: selected, color: selected ? "cyan" : undefined, children: o.name.padEnd(nameWidth) }), "  ", _jsx(Text, { dimColor: true, children: truncate(o.summary ?? displayPath(o.file, root), restWidth) })] })), renderDetail: (o) => (o ? _jsx(OmDetail, { om: o, root: root }) : null) }), _jsx(Text, { dimColor: true, children: hint })] }));
 }
-/** The highlighted om in full. */
+/** Steps listed before the rest collapse into `+N more`, so the box keeps a steady height. */
+const MAX_STEPS = 10;
+/** A description key as a label: `docsUrl` / `docs-url` / `docs_url` → `Docs url`. */
+export function labelOf(key) {
+    const words = key
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[-_]+/g, " ")
+        .trim()
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** One label/value row; the value wraps under itself, not under the label. */
+function Field({ label, width, children, }) {
+    return (_jsxs(Box, { children: [_jsx(Box, { width: width + 2, flexShrink: 0, children: _jsx(Text, { dimColor: true, children: label }) }), _jsx(Box, { flexGrow: 1, children: children })] }));
+}
+/**
+ * The highlighted om in full: its name, then a field per thing it says about itself — the
+ * summary, any further `.describe(…)` props, where it is defined — then its steps, numbered.
+ * The steps are the static outline, an approximation (see `outlineBody`), and say so.
+ */
 function OmDetail({ om, root }) {
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1, marginTop: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: om.name }), om.summary ? (_jsx(Text, { children: om.summary })) : (_jsxs(Text, { dimColor: true, italic: true, children: ["No summary. Add .describe(", "{ summary }", ") to the om."] })), _jsx(Text, { dimColor: true, children: `${displayPath(om.file, root)}:${om.line}` }), om.calls?.length ? (_jsxs(Text, { wrap: "wrap", children: [_jsx(Text, { dimColor: true, children: "calls " }), om.calls.map((c, i) => (_jsxs(Text, { children: [i > 0 ? _jsx(Text, { dimColor: true, children: " \u2192 " }) : null, c.name, c.tag ? _jsx(Text, { dimColor: true, children: ` [${c.tag}]` }) : null] }, `${c.name}\0${c.tag ?? ""}`)))] })) : null] }));
+    const details = (om.details ?? []).map((d) => ({ label: labelOf(d.key), value: d.value }));
+    const width = Math.max("Summary".length, "Defined".length, ...details.map((d) => d.label.length));
+    const steps = om.calls ?? [];
+    const shown = steps.slice(0, MAX_STEPS);
+    const stepWidth = Math.min(24, Math.max(0, ...shown.map((c) => c.name.length)));
+    const numWidth = String(shown.length).length;
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1, marginTop: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: om.name }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Field, { label: "Summary", width: width, children: om.summary ? (_jsx(Text, { wrap: "wrap", children: om.summary })) : (_jsxs(Text, { dimColor: true, italic: true, children: ["none \u00B7 add .describe(", "{ summary }", ") to the om"] })) }), details.map((d) => (_jsx(Field, { label: d.label, width: width, children: _jsx(Text, { wrap: "wrap", children: d.value }) }, d.label))), _jsx(Field, { label: "Defined", width: width, children: _jsx(Text, { dimColor: true, wrap: "truncate-start", children: `${displayPath(om.file, root)}:${om.line}` }) })] }), shown.length ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "Steps" }), _jsx(Text, { dimColor: true, italic: true, children: "  read from source · approximate" })] }), shown.map((c, i) => (_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: `  ${String(i + 1).padStart(numWidth)}  ` }), c.tag ? c.name.padEnd(stepWidth) : c.name, c.tag ? _jsx(Text, { color: "cyan", children: `  ${c.tag}` }) : null] }, `${c.name}\0${c.tag ?? ""}`))), steps.length > shown.length ? (_jsx(Text, { dimColor: true, children: `  ${" ".repeat(numWidth)}  +${steps.length - shown.length} more` })) : null] })) : null] }));
 }

package/dist/cli/ui/views/shellLines.d.ts

@@ -13,9 +13,9 @@ import type { ScrollLine } from "./Scrollback.tsx";
  */
 export declare function shellLine(e: LogEntry, node: RunNode | undefined, tearingDown: boolean): ScrollLine | null;
 /**
- * The verdict's recap, cut to what you reach for next: the report, and the assert tally when the
- * run asserted anything. The full block (every sibling log) is in the run folder and at the foot
- * of `main.log`. A summary of any other shape — the output of a child that died before it could
+ * The verdict's recap, cut to what you reach for next: `main.log` and the report, and the assert
+ * tally when the run asserted anything. The full block (every sibling log) is in the run folder
+ * and at the foot of `main.log`. A summary of any other shape — the output of a child that died before it could
  * report — is the only account of what went wrong, so it is kept whole.
  */
 export declare function recapLines(summary: readonly string[]): ScrollLine[];

package/dist/cli/ui/views/shellLines.js

@@ -34,9 +34,9 @@ export function shellLine(e, node, tearingDown) {
     return null;
 }
 /**
- * The verdict's recap, cut to what you reach for next: the report, and the assert tally when the
- * run asserted anything. The full block (every sibling log) is in the run folder and at the foot
- * of `main.log`. A summary of any other shape — the output of a child that died before it could
+ * The verdict's recap, cut to what you reach for next: `main.log` and the report, and the assert
+ * tally when the run asserted anything. The full block (every sibling log) is in the run folder
+ * and at the foot of `main.log`. A summary of any other shape — the output of a child that died before it could
  * report — is the only account of what went wrong, so it is kept whole.
  */
 export function recapLines(summary) {
@@ -46,8 +46,9 @@ export function recapLines(summary) {
     const lines = [];
     for (const line of summary) {
         const trimmed = line.trim();
-        if (trimmed.startsWith("report "))
+        if (trimmed.startsWith("main log ") || trimmed.startsWith("report ")) {
             lines.push({ text: `  ${trimmed}`, dim: true });
+        }
         const tally = /⊨ (\d+) passed · ⊭ (\d+) failed/.exec(trimmed);
         if (tally && Number(tally[1]) + Number(tally[2]) > 0) {
             lines.push({

package/dist/client/discovery.js

@@ -6,7 +6,7 @@ import { omHash } from "../foundation/ids.js";
 import { fsSafe } from "../foundation/fsSafe.js";
 import { canonicalPath } from "../foundation/canonicalPath.js";
 import { tsxLoader } from "./runner.js";
-import { chainRoot, importedNames, outlineBody, summaryOf } from "./outline.js";
+import { chainRoot, detailsOf, importedNames, outlineBody, summaryOf } from "./outline.js";
 import { checkedProgram } from "./tsCache.js";
 /**
  * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
@@ -43,12 +43,13 @@ export function discover(tsconfigPath) {
                 node.expression.text === names.om) {
                 const arg = node.arguments[0];
                 if (arg && ts.isStringLiteralLike(arg)) {
-                    const { calls, summary } = outlines.get(arg.text) ?? {};
+                    const { calls, summary, details } = outlines.get(arg.text) ?? {};
                     oms.push({
                         name: arg.text,
                         file,
                         line: lineOf(sf, node),
                         ...(summary !== undefined ? { summary } : {}),
+                        ...(details?.length ? { details } : {}),
                         ...(calls?.length ? { calls } : {}),
                     });
                 }
@@ -80,7 +81,7 @@ export function discover(tsconfigPath) {
 }
 /**
  * Outline every `om("name")…​.run(body)` chain in a file, keyed by om name, along with the
- * chain's literal `.describe({ summary })`.
+ * chain's literal `.describe({ summary, … })`.
  *
  * Collected in its own pass rather than alongside the `om(...)` match, because a body is only
  * reachable from the `.run` end of the chain and the om name only from the other — and the
@@ -99,9 +100,11 @@ function outlinesIn(sf, omName, imported) {
             const name = root?.call.arguments[0];
             if (root?.name === omName && name && ts.isStringLiteralLike(name)) {
                 const summary = summaryOf(root);
+                const details = detailsOf(root);
                 outlines.set(name.text, {
                     ...(body && ts.isFunctionLike(body) ? { calls: outlineBody(body, imported) } : {}),
                     ...(summary !== undefined ? { summary } : {}),
+                    ...(details.length ? { details } : {}),
                 });
             }
         }

package/dist/client/outline.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import type { OmCall } from "./registry.ts";
+import type { DescriptionDetail, OmCall } from "./registry.ts";
 /**
  * Every identifier a file binds through an import — the whole allow-list for the outline.
  * An action always arrives by import (`omkit/actions`, or a local actions module), so
@@ -40,3 +40,10 @@ export declare function outlineBody(body: ts.Node, imported: ReadonlySet<string>
  */
 /** The `summary` of a `.describe({ summary: "…" })` in the chain, when it is a string literal. */
 export declare function summaryOf(chain: ChainRoot): string | undefined;
+/**
+ * The props of a `.describe({ … })` in the chain besides `summary`, in source order, with each
+ * value rendered as text. Like {@link summaryOf}, only what the AST can read without evaluating:
+ * a string, number or boolean literal, or an array of those (joined with commas). A prop with
+ * any other value is left out rather than guessed at.
+ */
+export declare function detailsOf(chain: ChainRoot): DescriptionDetail[];

package/dist/client/outline.js

@@ -106,6 +106,50 @@ export function summaryOf(chain) {
     }
     return undefined;
 }
+/**
+ * The props of a `.describe({ … })` in the chain besides `summary`, in source order, with each
+ * value rendered as text. Like {@link summaryOf}, only what the AST can read without evaluating:
+ * a string, number or boolean literal, or an array of those (joined with commas). A prop with
+ * any other value is left out rather than guessed at.
+ */
+export function detailsOf(chain) {
+    const details = [];
+    for (const call of chain.calls) {
+        const callee = call.expression;
+        if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== "describe")
+            continue;
+        const arg = call.arguments[0];
+        if (!arg || !ts.isObjectLiteralExpression(arg))
+            continue;
+        for (const prop of arg.properties) {
+            if (!ts.isPropertyAssignment(prop))
+                continue;
+            const key = ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name)
+                ? prop.name.text
+                : undefined;
+            if (key === undefined || key === "summary")
+                continue;
+            const value = literalText(prop.initializer);
+            if (value !== undefined)
+                details.push({ key, value });
+        }
+    }
+    return details;
+}
+/** A literal's value as text, or `undefined` when it needs evaluating. Arrays join with commas. */
+function literalText(node) {
+    if (ts.isStringLiteralLike(node) || ts.isNumericLiteral(node))
+        return node.text;
+    if (node.kind === ts.SyntaxKind.TrueKeyword)
+        return "true";
+    if (node.kind === ts.SyntaxKind.FalseKeyword)
+        return "false";
+    if (ts.isArrayLiteralExpression(node)) {
+        const items = node.elements.map((e) => literalText(e));
+        return items.every((i) => i !== undefined) ? items.join(", ") : undefined;
+    }
+    return undefined;
+}
 function tagOf(chain) {
     let tag;
     for (const call of chain.calls) {

package/dist/client/registry.d.ts

@@ -5,6 +5,11 @@ export interface OmCall {
     /** The `.tag("…")` literal from the same fluent chain, when the author wrote one. */
     readonly tag?: string;
 }
+/** One `.describe(…)` prop besides `summary`: its key, and its literal value as text. */
+export interface DescriptionDetail {
+    readonly key: string;
+    readonly value: string;
+}
 /** A runnable om discovered from a top-level `om("name", …)` call. */
 export interface DiscoveredOm {
     /** The om's name — its first string argument. */
@@ -19,6 +24,11 @@ export interface DiscoveredOm {
      * the import-based pass, `discoverRegistrations`.
      */
     readonly summary?: string;
+    /**
+     * The `.describe(…)` props besides `summary`, in source order, each value rendered as text
+     * (a list joined with commas). Read statically like `summary`, so only literal values appear.
+     */
+    readonly details?: readonly DescriptionDetail[];
     /**
      * A static approximation of what the body calls, in source order. Absent when the walk
      * found nothing recognisable. Never a contract — see {@link import("./outline.ts").outlineBody}

package/dist/core/types.d.ts

@@ -63,7 +63,14 @@ export interface ActionContext<Events extends object = NoEvents, Handle = void>
 export interface OmDescription {
     /** One line saying what this does. */
     summary: string;
+    /**
+     * Anything else worth knowing before running it — an owner, a docs link, what it needs.
+     * Listed under the summary, keyed by name, in the interactive picker and the run report.
+     */
+    readonly [prop: string]: DescriptionValue;
 }
+/** What a description prop can hold: values that read plainly in a terminal and a report. */
+export type DescriptionValue = string | number | boolean | readonly string[] | undefined;
 /** How an om or action behaves when a client runs it as an MCP tool. */
 export type McpMode = "settling" | "long-lived";
 /**