@wirecat/cli-core 0.399.0 → 0.401.0

package/dist/cli/messenger/tasks-command.js

@@ -29,7 +29,7 @@ const line = ({ id, key, state, kind, group, createdAt, message, note }) => [
             : "(not in the store)",
 ].join("  ");
 const when = (at) => (at === null ? "—" : at.slice(0, 16).replace("T", " "));
-const toReview = (count) => count ? `; ${count} possible duplicate pair(s) went to tasks duplicates` : "";
+const toReview = (count) => count ? `; ${count} possible duplicate pair(s) went to tasks duplicates list` : "";
 const suggestionLine = ({ as, by, certainty, reason }) => `close suggested: ${as} by ${by} at certainty ${certainty}${reason === null ? "" : ` — ${reason}`}; waits on the owner`;
 const card = (task) => [
     `${task.key}  ${task.status}  ${task.type}  ${task.category ?? "—"}  ${task.title}`,
@@ -44,7 +44,7 @@ const card = (task) => [
 ].join("\n");
 const applyText = (pass, yes, tool) => yes
     ? `${pass.chat}: ${pass.messages} messages read; ${pass.added} opened, ${pass.closed} closed` +
-        (pass.review ? `; ${pass.review} may be the same job as another — ${tool} tasks duplicates` : "")
+        (pass.review ? `; ${pass.review} may be the same job as another — ${tool} tasks duplicates list` : "")
     : [
         `${pass.chat}: ${pass.messages} messages read; would open ${pass.tasks.length}, close ${pass.closed}`,
         ...pass.tasks.map((task) => `  ${task.kind.padEnd(8)} ${(task.category ?? "—").padEnd(13)} ${task.source}`),
@@ -152,6 +152,7 @@ export const tasksCommand = (messenger) => {
             context.renderer.note("no tasks — review, inbox and messages sync add them as questions arrive");
     });
     planOptions(destroysNothing(annotate(tasks.command("add"), {
+        output: { entity: "task_created" },
         effects: LOCAL_WRITE,
         examples: [`${tool} personal tasks add note:101 --type promise --category documents --title "Review draft"`],
     }))
@@ -185,6 +186,7 @@ export const tasksCommand = (messenger) => {
             context.renderer.note(`${task.key ?? task.id} follows up ${followUpOf.key} (${followUpOf.status}), which stays closed: linked follow-up-of`);
     });
     planOptions(destroysNothing(annotate(tasks.command("plan"), {
+        output: { entity: "task_card" },
         effects: LOCAL_WRITE,
         examples: [`${tool} personal tasks plan DOC-12 --title "Review draft"`],
     }))
@@ -201,6 +203,7 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(planned)), () => `${card(planned)}\n`);
     });
     destroysNothing(annotate(tasks.command("link"), {
+        output: { entity: "task_links" },
         effects: LOCAL_WRITE,
         examples: [`${tool} personal tasks link DOC-12 https://example.com/draft`],
     }))
@@ -221,9 +224,13 @@ export const tasksCommand = (messenger) => {
             ? `${linked.relations.map((one) => `${one.from} ${one.kind} ${one.to}`).join("\n")}\n`
             : `${card(linked)}\n`);
         if (!("relations" in linked) && linked.review && context.format === "pretty")
-            context.renderer.note(`${linked.review} possible duplicate pair(s) went to tasks duplicates`);
+            context.renderer.note(`${linked.review} possible duplicate pair(s) went to tasks duplicates list`);
     });
-    annotate(tasks.command("show"), { effects: LOCAL_READ, examples: [`${tool} personal tasks show DOC-12`] })
+    annotate(tasks.command("show"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_READ,
+        examples: [`${tool} personal tasks show DOC-12`],
+    })
         .description("one task: its plan and everything linked to it")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .action(async function (id) {
@@ -231,7 +238,11 @@ export const tasksCommand = (messenger) => {
         const shown = await context.withServices((services) => services.tasks.show(id));
         renderAnswer(this, context, itemOf(snakeKeys(shown)), () => `${card(shown)}\n`);
     });
-    annotate(tasks.command("related"), { effects: LOCAL_READ, examples: [`${tool} tasks related PR-12`] })
+    annotate(tasks.command("related"), {
+        output: { entity: "task_similar" },
+        effects: LOCAL_READ,
+        examples: [`${tool} tasks related PR-12`],
+    })
         .summary("tasks that may be the same job as this one, best first; merges nothing")
         .description("tasks that may be the same job as this one, best first, each with a band — likely, maybe, different — and the " +
         "reasons; merges nothing")
@@ -255,7 +266,11 @@ export const tasksCommand = (messenger) => {
         if (found.length === 0 && context.format === "pretty")
             context.renderer.note("no open or recent task looks alike");
     });
-    const duplicates = withQuery(annotate(tasks.command("duplicates"), { effects: LOCAL_READ })
+    const duplicates = tasks.command("duplicates").description("pairs of tasks that may be one job");
+    withQuery(annotate(duplicates.command("list"), {
+        effects: LOCAL_READ,
+        examples: [`${tool} tasks duplicates list --limit 10`, `${tool} tasks duplicates list decision:unsure`],
+    })
         .summary("pairs of tasks a rule opened that may be one job, newest first")
         .description("pairs of tasks a rule opened that may be one job, newest first, with score and reasons: merge, reject or " +
         "defer each; decision:unsure lists the ones deferred to the owner"), TASK_PAIR_QUERY)
@@ -263,10 +278,10 @@ export const tasksCommand = (messenger) => {
         .action(async function (words) {
         const context = messengerContext(this, messenger);
         const { limit, offset } = pageOf(context.settings);
-        const decision = queryTerms(words, TASK_PAIR_QUERY, "tasks duplicates").get("decision");
+        const decision = queryTerms(words, TASK_PAIR_QUERY, "tasks duplicates list").get("decision");
         const rows = await context.withServices((services) => services.tasks.duplicates({ decision, limit: limit + 1, offset }));
         const shown = rows.slice(0, limit);
-        renderAnswer(this, context, pagedList("tasks duplicates", context.settings, {
+        renderAnswer(this, context, pagedList("tasks duplicates list", context.settings, {
             items: shown.map(snakeKeys),
             has_more: rows.length > limit,
         }), () => (shown.length === 0 ? "" : `${shown.map(pairLine).join("\n")}\n`));
@@ -280,6 +295,7 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(pair)), () => `${pair.decision}  ${pairLine(pair)}\n`);
     };
     destroysNothing(annotate(duplicates.command("reject"), {
+        output: { entity: "task_pair" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tasks duplicates reject PR-14 PR-12`],
     }))
@@ -289,6 +305,7 @@ export const tasksCommand = (messenger) => {
         .argument("<other-task>", "the task it was paired with")
         .action(decided("rejected", "tasks.duplicates.reject"));
     destroysNothing(annotate(duplicates.command("defer"), {
+        output: { entity: "task_pair" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tasks duplicates defer PR-14 PR-12`],
     }))
@@ -297,7 +314,11 @@ export const tasksCommand = (messenger) => {
         .argument("<task>", "the task listed as the duplicate, by its id or key")
         .argument("<other-task>", "the task it was paired with")
         .action(decided("unsure", "tasks.duplicates.defer"));
-    destroysNothing(annotate(tasks.command("merge"), { effects: LOCAL_WRITE, examples: [`${tool} tasks merge PR-14 --into PR-12`] }))
+    destroysNothing(annotate(tasks.command("merge"), {
+        output: { entity: "task_merge" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks merge PR-14 --into PR-12`],
+    }))
         .summary("one job seen twice: fold the duplicate into the task that stays")
         .description("one job seen twice: link every message of the duplicate to the task and close the duplicate dismissed, " +
         "duplicate-of the task; nothing is deleted, and tasks unmerge undoes it")
@@ -311,7 +332,11 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(merged)), () => `${dup} merged into ${merged.task.key}; ${merged.linked} message(s) linked${toReview(merged.review)}\n` +
             `${card(merged.task)}\n`);
     });
-    destroysNothing(annotate(tasks.command("unmerge"), { effects: LOCAL_WRITE, examples: [`${tool} tasks unmerge PR-14`] }))
+    destroysNothing(annotate(tasks.command("unmerge"), {
+        output: { entity: "task_unmerge" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks unmerge PR-14`],
+    }))
         .summary("undo a merge: reopen the task and remove its duplicate-of relation")
         .description("undo a merge: reopen the task and remove its duplicate-of relation; messages the merge linked stay linked")
         .argument("<task>", "the merged task, by its id or key")
@@ -344,7 +369,11 @@ export const tasksCommand = (messenger) => {
         }));
         renderAnswer(this, context, itemOf(agendaItem(agenda)), () => `${agendaText(agenda)}\n`);
     });
-    annotate(tasks.command("categories"), { effects: LOCAL_READ, examples: [`${tool} tasks categories`] })
+    annotate(tasks.command("categories"), {
+        output: { entity: "task_categories" },
+        effects: LOCAL_READ,
+        examples: [`${tool} tasks categories`],
+    })
         .summary("the categories a task takes, with what each means")
         .description("the categories a task takes, with what each means and the words a rule picks it by")
         .action(async function () {
@@ -365,6 +394,7 @@ export const tasksCommand = (messenger) => {
         ].join("\n"));
     });
     destroysNothing(annotate(tasks.command("scan"), {
+        output: { entity: "task_scan" },
         effects: LOCAL_WRITE,
         examples: [`${tool} tasks scan <chat>`, `${tool} tasks scan <chat> --last 300 --yes`],
     }))
@@ -389,7 +419,11 @@ export const tasksCommand = (messenger) => {
         }, { name: "tasks scan" });
         renderAnswer(this, context, listOf("tasks scan", { items: passes.map(snakeKeys), limit: passes.length, has_more: false }), () => `${passes.map((pass) => applyText(pass, yes, tool)).join("\n")}\n`);
     });
-    destroysNothing(annotate(tasks.command("claim"), { effects: LOCAL_WRITE, examples: [`${tool} tasks claim PR-12 --lease 2h`] }))
+    destroysNothing(annotate(tasks.command("claim"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks claim PR-12 --lease 2h`],
+    }))
         .description("take an open task so no other agent works it at once; the claim lapses by itself")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .option("--lease <duration>", "how long the claim lasts: 30m, 2h (default 30m); claiming again extends it", durationOf("--lease"))
@@ -401,7 +435,11 @@ export const tasksCommand = (messenger) => {
         const claimed = await context.withServices((services) => services.tasks.claim(id, holderOf(this), lease));
         renderAnswer(this, context, itemOf(snakeKeys(claimed)), () => `${card(claimed)}\n`);
     });
-    destroysNothing(annotate(tasks.command("release"), { effects: LOCAL_WRITE, examples: [`${tool} tasks release PR-12`] }))
+    destroysNothing(annotate(tasks.command("release"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks release PR-12`],
+    }))
         .description("give back a task you claimed, before the claim lapses; the owner may release any")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .option("--holder <name>", HOLDER_HELP)
@@ -412,6 +450,7 @@ export const tasksCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(released)), () => `${card(released)}\n`);
     });
     destroysNothing(annotate(tasks.command("close"), {
+        output: { entity: "task_closed" },
         effects: LOCAL_WRITE,
         examples: [
             `${tool} tasks close Q-15 --as done --certainty 0.9 --reason answered-in-chat`,
@@ -452,7 +491,11 @@ export const tasksCommand = (messenger) => {
             context.renderer.note(`${closed.key ?? id} stays open: the close waits on the owner — ${tool} tasks close ${closed.key ?? id} ` +
                 `confirms it, ${tool} tasks reject ${closed.key ?? id} refuses it`);
     });
-    annotate(tasks.command("reject"), { effects: LOCAL_WRITE, examples: [`${tool} tasks reject Q-15`] })
+    annotate(tasks.command("reject"), {
+        output: { entity: "task_card" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} tasks reject Q-15`],
+    })
         .summary("refuse an agent's close of a task: it stays open and the suggestion goes")
         .description("refuse the close an agent suggested: the task stays open and leaves close:suggested; the agent may close it again")
         .argument("<task>", "the task's id or key, as tasks list shows it")

package/dist/cli/messenger/transcribe-command.js

@@ -9,6 +9,7 @@ import { heardAnswer } from "./message-answers.js";
 import { keepRefreshedRefs } from "./refreshed-refs.js";
 /** `messages transcribe`: a voice message as text, by the messenger or by a model on this machine. */
 export const transcribeSubcommand = (messages, messenger) => annotate(messages.command("transcribe"), {
+    output: { entity: "message_transcript" },
     examples: [`${messenger.app.command} personal messages transcribe "Book club" 101`],
     effects: REMOTE_READ,
 })

package/dist/cli/messenger/watch-answers.d.ts

@@ -0,0 +1,6 @@
+import type * as v from "valibot";
+import type { MessageEvent, MessageHit } from "../../domain/models.js";
+import type { messageEvent, watchedMessage } from "../../entities/listener.js";
+import type { AccountKey } from "../../store/store.js";
+export declare const watchedMessageItem: (value: MessageHit, account: AccountKey) => v.InferOutput<typeof watchedMessage>;
+export declare const watchEventItem: (value: MessageEvent, account: AccountKey) => v.InferOutput<typeof messageEvent>;

package/dist/cli/messenger/watch-answers.js

@@ -0,0 +1,69 @@
+import { chatEventAnswer, memberAnswer, pollVoteAnswer } from "./chat-answers.js";
+import { messageItem } from "./message-items.js";
+const observed = (value) => ({
+    value: value.value,
+    observed_at: value.observedAt,
+    source: value.source,
+    ...(value.reactions === undefined ? {} : { reactions: value.reactions }),
+});
+export const watchedMessageItem = (value, account) => {
+    const counters = value.counterObservations;
+    return {
+        ...messageItem(value, account),
+        ...(value.starred === undefined ? {} : { starred: value.starred }),
+        ...(counters === undefined
+            ? {}
+            : {
+                counter_observations: {
+                    ...(counters.views === undefined ? {} : { views: observed(counters.views) }),
+                    ...(counters.reactions === undefined ? {} : { reactions: observed(counters.reactions) }),
+                    ...(counters.comments === undefined ? {} : { comments: observed(counters.comments) }),
+                },
+            }),
+    };
+};
+const affected = (value) => ({
+    chat_id: value.chatId,
+    chat_title: value.chatTitle,
+    message_id: value.messageId,
+});
+export const watchEventItem = (value, account) => {
+    switch (value.event) {
+        case "message":
+        case "edit":
+            return { event: value.event, message: watchedMessageItem(value.message, account) };
+        case "delete":
+            return { event: value.event, chat_id: value.chatId, chat_title: value.chatTitle, message_id: value.messageId };
+        case "reaction":
+            return {
+                event: value.event,
+                ...affected(value),
+                reactions: value.reactions,
+                ...(value.counterObservation === undefined ? {} : { counter_observation: observed(value.counterObservation) }),
+            };
+        case "vote":
+            return { event: value.event, ...affected(value), vote: pollVoteAnswer(value.vote) };
+        case "person_reaction":
+            return {
+                event: value.event,
+                ...affected(value),
+                reaction: {
+                    person: memberAnswer(value.reaction.person),
+                    own: value.reaction.own,
+                    reaction: value.reaction.reaction,
+                    reacted_at: value.reaction.reactedAt,
+                },
+            };
+        case "star":
+            return { event: value.event, ...affected(value), starred: value.starred };
+        case "delivery":
+            return { event: value.event, ...affected(value), delivery: value.delivery, at: value.at };
+        case "chat_event":
+            return {
+                event: value.event,
+                chat_id: value.chatId,
+                chat_title: value.chatTitle,
+                change: chatEventAnswer(value.chatId, value.change),
+            };
+    }
+};

package/dist/cli/messenger/watch-command.d.ts

@@ -4,7 +4,7 @@ import type { MessengerAdapter } from "../../ports/messenger.js";
 import { type Messenger, type MessengerContext } from "./context.js";
 /**
  * New messages as they arrive, until Ctrl-C or `--timeout` — both a normal end, exit 0: listening
- * for a minute is a complete answer. One `MessageHit` per line with `--jsonl`; `--json` is refused,
+ * for a minute is a complete answer. Canonical item records and one end record with `--jsonl`; `--json` is refused,
  * because a stream is not one value. Nothing is marked read.
  */
 export declare const watchCommand: (messenger: Messenger) => Command;

package/dist/cli/messenger/watch-command.js

@@ -4,21 +4,25 @@ import { Command } from "commander";
 import { renderMessages } from "../../render/messages.js";
 import { environmentOf } from "../context.js";
 import { REMOTE_READ } from "../effects.js";
+import { jsonlRecords, listOf } from "../envelope.js";
 import { withoutProviderRefs } from "../provider-refs.js";
 import { messengerContext } from "./context.js";
+import { selfOf } from "./message-items.js";
+import { watchEventItem, watchedMessageItem } from "./watch-answers.js";
 /**
  * New messages as they arrive, until Ctrl-C or `--timeout` — both a normal end, exit 0: listening
- * for a minute is a complete answer. One `MessageHit` per line with `--jsonl`; `--json` is refused,
+ * for a minute is a complete answer. Canonical item records and one end record with `--jsonl`; `--json` is refused,
  * because a stream is not one value. Nothing is marked read.
  */
 export const watchCommand = (messenger) => annotate(new Command("watch"), {
+    output: { entity: "watch_item" },
     effects: REMOTE_READ,
     lifetime: "persistent",
     examples: [`${messenger.app.command} personal watch --jsonl --timeout 30s`],
 })
     .summary("stream new messages until interrupted or timed out")
     .description("print new messages as they arrive, until Ctrl-C or --timeout (either ends it normally)")
-    .option("--events", "also edits, deletions, reactions, poll votes and chat events; every line then names its event")
+    .option("--events", "include changes and receipts; each item names its event")
     .action(async function () {
     const events = this.opts().events === true;
     const context = messengerContext(this, messenger);
@@ -35,19 +39,59 @@ export const watchCommand = (messenger) => annotate(new Command("watch"), {
         provider: messenger.provider,
         locale: messenger.app.locale,
     })}`;
-    // Without --events the stream is bare messages, as it always was: a reader of it never meets
-    // a line of another shape.
+    // Event-tagged payloads are opt-in; ordinary items remain message values.
     const stop = new AbortController();
+    let connection;
+    let printed = 0;
+    const account = () => {
+        if (!connection)
+            throw new Error("watch has no connected account");
+        return selfOf(messenger, connection);
+    };
     const print = (event) => {
         if (stop.signal.aborted || (!events && event.event !== "message"))
             return;
         if (context.format === "jsonl") {
-            context.streams.data(JSON.stringify(withoutProviderRefs(events ? event : event.message)));
+            const data = events
+                ? watchEventItem(event, account())
+                : event.event === "message"
+                    ? watchedMessageItem(event.message, account())
+                    : undefined;
+            if (data === undefined)
+                return;
+            context.streams.data(JSON.stringify({ type: "item", data: withoutProviderRefs(data) }));
+            printed++;
         }
         else
             context.streams.data(describe(event, render));
     };
-    await listenUntilStopped(this, context, messenger, print, { stop, pipe: true });
+    const finish = (complete, error) => {
+        if (context.format !== "jsonl" || environmentOf(this).commandSignal?.aborted)
+            return;
+        const issues = !complete && error instanceof CliError ? [{ code: error.code, source: "watch" }] : undefined;
+        for (const record of jsonlRecords(listOf("watch", {
+            items: [],
+            limit: Math.max(1, printed),
+            has_more: false,
+            paging: "cursor",
+            meta: { complete, ...(issues ? { issues } : {}) },
+        })))
+            context.streams.data(JSON.stringify(record));
+    };
+    try {
+        await listenUntilStopped(this, context, messenger, print, {
+            stop,
+            pipe: true,
+            connected: (open) => {
+                connection = open;
+            },
+        });
+    }
+    catch (error) {
+        finish(false, error);
+        throw error;
+    }
+    finish(true);
 });
 /**
  * Listens until Ctrl-C, SIGTERM, `--timeout` or — with `pipe` — a reader that has gone away.
@@ -55,7 +99,11 @@ export const watchCommand = (messenger) => annotate(new Command("watch"), {
  * `feed` runs it beside `watch`, so what the messenger pushes reaches the store (`stored`).
  */
 export const listenUntilStopped = async (command, context, messenger, onEvent, { stop, pipe = false, catchUp = false, onReady = () => context.renderer.note("listening — Ctrl-C to stop"), connected, }) => {
-    const given = environmentOf(command).signal;
+    const environment = environmentOf(command);
+    const phase = environment.untilStopped?.();
+    const given = phase
+        ? AbortSignal.any([phase, ...[environment.signal].filter((one) => one !== undefined)])
+        : environment.signal;
     const end = () => stop.abort();
     given?.addEventListener("abort", end, { once: true });
     const signals = given ? [] : ["SIGINT", "SIGTERM"];
@@ -96,6 +144,7 @@ export const listenUntilStopped = async (command, context, messenger, onEvent, {
         if (pipe && !given)
             process.stdout.off("error", closed);
         given?.removeEventListener("abort", end);
+        environment.endUntilStopped?.();
     }
 };
 const describe = (event, render) => {

package/dist/cli/program.js

@@ -11,7 +11,7 @@ import { failureContext } from "../errors/reasons.js";
 import { envName, readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { recorded, wasSettled } from "../runs/recording.js";
 import { processRun, useAsProcessRun } from "../runs/scope.js";
-import { keyForCommand } from "../sends/permissions.js";
+import { AUTHORITY_KEY, keyForCommand } from "../sends/permissions.js";
 import { logParsedArgv, logVersion } from "./argv-log.js";
 import { commandPathOf } from "./command-contract.js";
 import { outputFor, provide } from "./context.js";
@@ -254,6 +254,10 @@ const runOnce = async (argv, definition, options) => {
         if (lock && changesAuthorityNow(action) && !flags.dryRun)
             throw new CliError("permission_error", `this process is read-only (${lock}) — \`${command} ${path.join(" ")}\` changes what a later run may do; ` +
                 `run it without ${lock}`);
+        if (options.agent && options.agent.authority !== true && changesAuthorityNow(action))
+            throw new CliError("permission_error", `\`${command} ${path.join(" ")}\` changes what a later run may do, and this profile keeps that from agents ` +
+                `(${AUTHORITY_KEY}) — the owner turns it on in a terminal: ` +
+                `\`${command} <profile> config set${path[0] === "bot" ? " --bot" : ""} permissions.${AUTHORITY_KEY} allow\``, { permission: AUTHORITY_KEY, sent: false });
         const { lifetime, cooperative: stopsAtItsPace } = metaOf(action);
         const persistent = lifetime === "persistent";
         listens = persistent;

package/dist/cli/runs/command.js

@@ -1,13 +1,14 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command, Option } from "commander";
+import { Command } from "commander";
 import { findRun, listRuns, readEvents, runsDirFor } from "../../runs/run.js";
 import { environmentOf, outputFor } from "../context.js";
 import { LOCAL_READ, NO_EFFECTS } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { typedQuery, withQuery } from "../list-query.js";
 import { positiveCount } from "../paging.js";
 import { lineOf } from "../steps.js";
-import { runsFound, searchRuns } from "./search.js";
+import { RUNS_QUERY, runListFilter } from "./query.js";
 /** Reading the log is not itself worth recording, so **nothing here starts a run**. */
 export const runsCommand = (app) => {
     const command = new Command("runs").description("recorded runs — what this tool did, and when");
@@ -18,24 +19,35 @@ export const runsCommand = (app) => {
             throw new CliError("not_found", `no recorded run "${id}" — \`${lineOf(from, "runs list")}\` shows them`);
         return found;
     };
-    annotate(command.command("list"), {
-        effects: LOCAL_READ,
+    withQuery(annotate(command.command("list"), {
         examples: [`${app.command} runs list --limit 10`],
-    })
+        effects: LOCAL_READ,
+    }), RUNS_QUERY)
         .description("recorded runs, newest first")
         .option("--limit <n>", "how many to show", positiveCount("--limit"), 20)
         .option("--page <n>", "which page, starting at 1", positiveCount("--page"), 1)
-        .action(function () {
+        .action(function (words) {
+        const filter = runListFilter(words);
         const { limit, page } = this.opts();
         const output = outputFor(this);
         const { renderer } = output;
-        const runs = listRuns(dir(this), { atLeast: page * limit + 1 });
+        const runs = listRuns(dir(this), { atLeast: page * limit + 1, filter });
         const shown = runs.slice((page - 1) * limit, page * limit);
-        renderAnswer(this, output, listOf("runs list", { items: shown.map(snakeKeys), limit, page, has_more: runs.length > page * limit }));
+        renderAnswer(this, output, listOf("runs list", {
+            items: shown.map(snakeKeys),
+            limit,
+            page,
+            has_more: runs.length > page * limit,
+            args: words.length ? { query: typedQuery(words) } : {},
+        }));
         if (runs.length === 0)
             renderer.note("nothing recorded — a run is kept with `--record`, or when it fails");
     });
-    annotate(command.command("show"), { effects: LOCAL_READ, examples: [`${app.command} runs show run-101`] })
+    annotate(command.command("show"), {
+        examples: [`${app.command} runs show run-101`],
+        effects: LOCAL_READ,
+        output: { entity: "run", view: "details" },
+    })
         .argument("<run-id>", `an id from \`${app.command} runs list\``)
         .description("one run: what it was, how it ended, and every event it logged")
         .option("--problems", "only failed responses, warnings and crashes")
@@ -56,36 +68,11 @@ export const runsCommand = (app) => {
         if (shown.length < events.length)
             renderer.note(`${events.length - shown.length} other events — \`${lineOf(this, `runs show ${id}`)}\` shows them all`);
     });
-    annotate(command.command("search"), {
-        effects: LOCAL_READ,
-        examples: [`${app.command} runs search timeout --limit 10`],
+    annotate(command.command("path"), {
+        examples: [`${app.command} runs path run-101`],
+        effects: NO_EFFECTS,
+        output: { entity: "run_location" },
     })
-        .description("search recorded diagnostic metadata and events; no message contents")
-        .argument("[query]", "case-insensitive literal diagnostic text")
-        .addOption(new Option("--status <status>", "run outcome").choices(["success", "failed", "partial", "running"]))
-        .option("--error-code <code>", "one stable error code")
-        .option("--operation <name>", "one operation, such as messages.download")
-        .option("--profile <name>", "one recorded profile")
-        .option("--since-time <time>", "runs starting on or after an ISO time or 2h / 1d ago")
-        .option("--limit <n>", "matches per page, at most 100", positiveCount("--limit"), 20)
-        .option("--page <n>", "result page", positiveCount("--page"), 1)
-        .action(function (query) {
-        const options = this.opts();
-        const found = searchRuns(dir(this), {
-            ...options,
-            since: options.sinceTime,
-            ...(query === undefined ? {} : { query }),
-        });
-        renderAnswer(this, outputFor(this), runsFound(found, {
-            query,
-            status: options.status,
-            error_code: options.errorCode,
-            operation: options.operation,
-            profile: options.profile,
-            since_time: options.sinceTime,
-        }));
-    });
-    annotate(command.command("path"), { effects: NO_EFFECTS, examples: [`${app.command} runs path run-101`] })
         .argument("<run-id>", `an id from \`${app.command} runs list\``)
         .description("the directory holding one run")
         .action(function (id) {

package/dist/cli/runs/query.d.ts

@@ -0,0 +1,5 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import type { RunListFilter } from "../../runs/run.js";
+import { type QueryWords } from "../list-query.js";
+export declare const RUNS_QUERY: QueryRegistry;
+export declare const runListFilter: (words: QueryWords) => RunListFilter;

package/dist/cli/runs/query.js

@@ -0,0 +1,32 @@
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { recordedRun } from "../../entities/index.js";
+import { queryTerms } from "../list-query.js";
+export const RUNS_QUERY = {
+    entity: "run",
+    backend: "native",
+    fields: queryFieldsOf(recordedRun, {
+        native: ["run_id", "command", "profile", "status", "error_code"],
+        examples: {
+            command: 'command:"messages send"',
+            profile: "profile:work",
+            status: "status:failed",
+            error_code: "error_code:timeout",
+        },
+    }).map((field) => field.native
+        ? {
+            ...field,
+            operators: field.operators.filter((operator) => operator === "term" || operator === "phrase"),
+        }
+        : field),
+};
+export const runListFilter = (words) => {
+    const terms = queryTerms(words, RUNS_QUERY, "runs list");
+    const status = recordedRun.entries.status.options.find((value) => value === terms.get("status"));
+    return {
+        ...(terms.has("run_id") ? { runId: terms.get("run_id") } : {}),
+        ...(terms.has("command") ? { command: terms.get("command") } : {}),
+        ...(terms.has("profile") ? { profile: terms.get("profile") } : {}),
+        ...(status === undefined ? {} : { status }),
+        ...(terms.has("error_code") ? { errorCode: terms.get("error_code") } : {}),
+    };
+};

package/dist/cli/runs/search-command.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import type { AppIdentity } from "../../ports/app.js";
+/** Diagnostic files are independent of linked accounts and never start a recorded run themselves. */
+export declare const runsSearchCommand: (app: AppIdentity) => Command;

package/dist/cli/runs/search-command.js

@@ -0,0 +1,27 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { runsDirFor } from "../../runs/run.js";
+import { environmentOf, outputFor } from "../context.js";
+import { LOCAL_READ } from "../effects.js";
+import { renderAnswer } from "../envelope.js";
+import { typedQuery, withQuery } from "../list-query.js";
+import { positiveCount } from "../paging.js";
+import { runsFound, searchRuns } from "./search.js";
+import { RUN_SEARCH_QUERY, runSearchFilter } from "./search-query.js";
+/** Diagnostic files are independent of linked accounts and never start a recorded run themselves. */
+export const runsSearchCommand = (app) => annotate(withQuery(new Command("runs")
+    .summary("search recorded diagnostic metadata and events")
+    .description("search recorded diagnostic metadata and events; literal words and field:value terms joined by AND; no message contents")
+    .option("--since-time <time>", "runs starting on or after an ISO time or 2h / 1d ago")
+    .option("--limit <n>", "matches per page, at most 100", positiveCount("--limit"), 20)
+    .option("--page <n>", "result page", positiveCount("--page"), 1), RUN_SEARCH_QUERY), {
+    effects: LOCAL_READ,
+    output: { entity: "run", view: "hit" },
+    examples: [`${app.command} search runs timeout status:failed --limit 10`],
+}).action(function (words) {
+    const filter = runSearchFilter(words);
+    const options = this.opts();
+    const dir = runsDirFor(app, environmentOf(this).env ?? process.env);
+    const found = searchRuns(dir, { ...filter, ...options, since: options.sinceTime });
+    renderAnswer(this, outputFor(this), runsFound(found, { query: typedQuery(words), since_time: options.sinceTime }));
+});

package/dist/cli/runs/search-query.d.ts

@@ -0,0 +1,4 @@
+import { type QueryWords } from "../list-query.js";
+import type { RunSearch } from "./search.js";
+export declare const RUN_SEARCH_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
+export declare const runSearchFilter: (words: QueryWords) => Pick<RunSearch, "terms" | "status" | "errorCode" | "operation" | "profile">;