@wirecat/cli-core 0.410.0 → 0.411.0

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

@@ -101,7 +101,7 @@ export declare const chatShown: (account: AccountKey, card: Parameters<typeof ch
         check?: {
             [x: string]: unknown;
         } | undefined;
-    }[] | null | undefined;
+    }[] | undefined;
 }>;
 /** The lowest score `score>=n` asks for; the audit's own floor when the query names none. */
 export declare const scoreFloor: (ast: QueryAst | undefined) => number;

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

@@ -38,7 +38,7 @@ export const chatAnswer = (account, chat) => defined({
     description: chat.description,
     invite_link: chat.link,
     settings: chat.settings ? settingsOf(chat.settings) : undefined,
-    members: chat.members === undefined ? undefined : (chat.members?.map(memberAnswer) ?? null),
+    members: chat.members?.map(memberAnswer),
 });
 export const memberAnswer = (member) => {
     const group = member;

package/dist/cli/messenger/chat-lists.d.ts

@@ -61,7 +61,7 @@ export declare const chatsList: (services: Services, query: QueryWords, paging:
         check?: {
             [x: string]: unknown;
         } | undefined;
-    }[] | null | undefined;
+    }[] | undefined;
 }>>;
 export declare const chatEvents: (services: Services, chat: string, query: QueryWords) => Promise<import("../envelope.js").ListBody<{
     chat_id: string;

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

@@ -109,6 +109,8 @@ export const chatsCommand = (messenger) => {
         "admins add": `"Book club" "Alex Example"${messenger.pickAdminRights === false ? "" : ` --can ${messenger.adminRights?.[0] ?? "info"}`}`,
         "admins remove": '"Book club" "Alex Example"',
         create: '"Book club" "Alex Example"',
+        app: '"Example Bot"',
+        start: '"Example Bot"',
         "documents list": '"Project room" --limit 10',
         events: '"Book club"',
         "folders create": '"Reading" --chat "Book club"',
@@ -125,6 +127,7 @@ export const chatsCommand = (messenger) => {
         "links list": '"Book club"',
         "links reset": '"Book club"',
         "links remove": '"Book club" https://example.com/invite/book-club',
+        "links update": '"Book club" https://example.com/invite/book-club --max-uses 25',
         "links show": '"Book club"',
         list: "--limit 10",
         "mark-read": '"Book club" --until-id 101',

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

@@ -1,5 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
+import { defineQuery } from "@wirecat/cli-base/query";
 import { Command } from "commander";
 import { REGISTRIES, registriesCover } from "../../botcheck/registries.js";
 import { levelFor } from "../../sends/permissions.js";
@@ -12,7 +13,7 @@ import { readSecret } from "../../terminal/prompt.js";
 import { secretInputOf } from "../context.js";
 import { FETCH, LOCAL_WRITE, REMOTE_READ } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
-import { listQuery, nativeTerms, typedQuery, withQuery } from "../list-query.js";
+import { listQuery, nativeField, nativeTerms, termField, timeBounds, typedQuery, withQuery } from "../list-query.js";
 import { positiveCount, window, withPaging } from "../paging.js";
 import { casKey } from "../registry-keys.js";
 import { commandAt, nextStep } from "../steps.js";
@@ -23,6 +24,19 @@ import { hideNever } from "./lacks.js";
 import { CONTACTS_QUERY, notesAllowed } from "./people-queries.js";
 import { privatePeopleCommands } from "./private-people-command.js";
 import { syncsFirst } from "./search-sync-options.js";
+const CONTACT_ACTIVITY_QUERY = defineQuery({
+    entity: "contact_activity",
+    backend: "native",
+    fields: [
+        termField("scope", "enum", "scope:work", { values: SCOPES }),
+        nativeField({
+            name: "at",
+            type: "time",
+            operators: ["term", "phrase", "range"],
+            example: "at:[2026-10-01 TO 2026-10-31]",
+        }),
+    ],
+});
 /** People this account has a one-to-one chat with, as the people service counts them. */
 const collect = (value, previous = []) => [...previous, value];
 export const contactsCommand = (messenger) => {
@@ -173,28 +187,24 @@ export const contactsCommand = (messenger) => {
             meta: { ...window.meta, ...(hasMore ? { truncated: true } : {}) },
         }));
     });
-    annotate(contacts.command("events"), {
+    withQuery(annotate(contacts.command("events"), {
         effects: REMOTE_READ,
         output: { entity: "contact_activity" },
     })
         .summary("one person's activity across their linked identities")
         .description("everything one person took part in, in every messenger linked to them — messages they wrote or were " +
         "mentioned in, chats, mail, meetings, tasks — newest first, from the store; never connects")
-        .argument("<person>", "their id, @username, or part of their name")
-        .option("--scope <scope>", "only what belongs to personal or to work accounts: personal or work")
-        .option("--since-time <time>", "nothing older than this ISO 8601 time, or 2h / 1d ago")
-        .option("--until-time <time>", "through this ISO 8601 time, or 2h / 1d ago")
+        .argument("<person>", "their id, @username, or part of their name"), CONTACT_ACTIVITY_QUERY)
         .option("--limit <n>", `at most this many; ${TIMELINE_ITEMS} if not given`, positiveCount("--limit"))
         .option("--cursor <cursor>", "go on from where the last page stopped; page.next gives it, with the same filters")
-        .action(async function (person) {
-        const { scope, sinceTime, untilTime, limit, cursor } = this.opts();
+        .action(async function (person, words) {
+        const terms = nativeTerms(listQuery(typedQuery(words), CONTACT_ACTIVITY_QUERY, "contacts events"), "contacts events");
+        const scope = terms.get("scope")?.value.toLowerCase();
+        const { limit, cursor } = this.opts();
         if (scope !== undefined && !SCOPES.includes(scope))
             throw new CliError("validation_error", `--scope is personal or work, not "${scope}"`);
         const context = messengerContext(this, messenger);
-        const window = dateWindow({
-            ...(sinceTime === undefined ? {} : { sinceTime }),
-            ...(untilTime === undefined ? {} : { untilTime }),
-        });
+        const window = timeBounds(terms.get("at"));
         const found = await context.withServices((services) => services.people.timeline(person, {
             ...(scope === undefined ? {} : { scope: scope }),
             ...(window.since === undefined ? {} : { since: window.since }),
@@ -211,9 +221,7 @@ export const contactsCommand = (messenger) => {
             ...(found.cursor === undefined ? {} : { cursor: found.cursor }),
             args: {
                 person,
-                ...(scope === undefined ? {} : { scope }),
-                ...(sinceTime === undefined ? {} : { since_time: sinceTime }),
-                ...(untilTime === undefined ? {} : { until_time: untilTime }),
+                ...(words.length ? { query: typedQuery(words) } : {}),
             },
             meta: { ...window.meta, ...(pending > 0 ? { truncated: true } : {}) },
         }));

package/dist/cli/messenger/guard-commands.d.ts

@@ -1,9 +1,13 @@
 import { Command } from "commander";
+import { type SendEntry } from "../../sends/journal.js";
 import { type Messenger } from "./context.js";
 /**
  * The chats this profile may send to. Off until the first `add`; `clear` deletes it, which turns it off again. It stops
  * a model that a message talked into writing somewhere, not an agent set on getting around it.
  */
-export declare const recipientsCommand: (messenger: Messenger) => Command;
+export declare const recipientsCommand: (messenger: Messenger, options?: {
+    resolve?: "chat-card";
+}) => Command;
 /** Every attempt to send from this profile, kept whatever `--record` says. Never the text. */
 export declare const sendsCommand: (messenger: Messenger) => Command;
+export declare const sendAttemptItem: ({ sendId, operationId, ...entry }: SendEntry) => unknown;

package/dist/cli/messenger/guard-commands.js

@@ -15,7 +15,7 @@ import { SENDS_QUERY, sendFilter } from "./sends-query.js";
  * The chats this profile may send to. Off until the first `add`; `clear` deletes it, which turns it off again. It stops
  * a model that a message talked into writing somewhere, not an agent set on getting around it.
  */
-export const recipientsCommand = (messenger) => {
+export const recipientsCommand = (messenger, options = {}) => {
     const tool = `${messenger.app.command} personal`;
     const listFor = (profile, env) => new RecipientList(recipientsPathFor(messenger.app, profile, env), messenger.app.command);
     const command = new Command("recipients").description("the chats this profile may send to, when the list is on");
@@ -43,7 +43,8 @@ export const recipientsCommand = (messenger) => {
         .description("allow sending to this chat; the first add turns the list on")
         .action(async function (chat) {
         const context = messengerContext(this, messenger);
-        const found = await context.withMessenger((connection) => connection.resolve(chat));
+        // Some transports resolve an id without reading its title or dialog partner.
+        const found = await context.withMessenger((connection) => options.resolve === "chat-card" ? connection.chat(chat) : connection.resolve(chat));
         const partnerId = messenger.partnerOf?.(found);
         const added = await listFor(context.settings.profile, context.env).addAsync({
             id: found.id,
@@ -93,10 +94,11 @@ export const sendsCommand = (messenger) => new Command("sends").description("eve
     const from = settings.all ? 0 : (settings.page - 1) * settings.limit;
     const shown = settings.all ? entries : entries.slice(from, from + settings.limit);
     renderAnswer(this, context, pagedList("sends list", settings, {
-        items: shown.map(snakeKeys),
+        items: shown.map(sendAttemptItem),
         args: words.length ? { query: typedQuery(words) } : {},
         has_more: from + shown.length < entries.length,
     }));
     if (entries.length === 0)
         renderer.note(filter ? "no send attempts match the query" : `profile ${settings.profile} has not tried to send anything`);
 }));
+export const sendAttemptItem = ({ sendId, operationId, ...entry }) => snakeKeys({ ...entry, ...((operationId ?? sendId) === undefined ? {} : { operationId: operationId ?? sendId }) });

package/dist/cli/messenger/messages-press-command.js

@@ -5,7 +5,10 @@ import { REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { messengerContext } from "./context.js";
 /** `messages press` — one of a bot's callback buttons; the bot sees who pressed it. */
-export const pressCommand = (messenger) => annotate(new Command("press"), { effects: REMOTE_WRITE })
+export const pressCommand = (messenger) => annotate(new Command("press"), {
+    effects: REMOTE_WRITE,
+    examples: [`${messenger.app.command} personal messages press "Example Bot" 101 1`],
+})
     .description("press a bot's button under a message; the bot sees that you pressed it")
     .argument("<chat>", messenger.chatArgument)
     .argument("<message>", "the id of the message with the buttons")

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

@@ -1,7 +1,6 @@
 import { join } from "node:path";
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { defineQuery } from "@wirecat/cli-base/query";
 import { Command } from "commander";
 import { isTextModelInstalled, textModelsDirectory } from "../../embeddings/embed.js";
 import { embeddingKeys } from "../../embeddings/keys.js";
@@ -16,19 +15,12 @@ import { readSecret } from "../../terminal/prompt.js";
 import { baseContext, environmentOf } from "../context.js";
 import { FETCH, grantsAuthority, LOCAL_READ, LOCAL_WRITE, reachesOtherService } from "../effects.js";
 import { itemOf, listOf, renderAnswer } from "../envelope.js";
-import { listQuery, nativeTerms, termField, typedQuery, unfilteredQuery, withQuery } from "../list-query.js";
+import { listQuery, nativeTerms, typedQuery, unfilteredQuery, withQuery } from "../list-query.js";
+import { MODEL_CATALOGUE_QUERY } from "../model-catalogue-command.js";
 import { nextStep } from "../steps.js";
 /** A model list is the catalog this version ships. */
 const MODELS_QUERY = unfilteredQuery("model", modelEntity);
-const ROOT_MODELS_QUERY = defineQuery({
-    entity: "model",
-    backend: "native",
-    fields: [
-        termField("kind", "enum", "kind:audio", { values: ["audio", "text"] }),
-        termField("id", "kw", "id:e5-small"),
-        termField("downloaded", "bool", "downloaded:true"),
-    ],
-});
+const ROOT_MODELS_QUERY = MODEL_CATALOGUE_QUERY;
 /** Every model this version knows: a short, fixed list, never paged. */
 const everyModel = (command, items, next = []) => listOf(command, { items, limit: Math.max(1, items.length), has_more: false, next });
 const audioItem = (model, directory, chosen) => ({

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

@@ -22,7 +22,7 @@ const kindsOf = (typed) => {
 export const mediaCommand = (messenger) => annotate(new Command("media"), { effects: REMOTE_READ })
     .description("a chat's photos, videos, files, audio and links, from the messenger's server; reading marks nothing")
     .argument("<chat>", messenger.chatArgument)
-    .option("--type <names>", `only these kinds, comma-separated: ${MEDIA_KINDS.join(", ")}`)
+    .option("--type <type>", `only these kinds, comma-separated: ${MEDIA_KINDS.join(", ")}`)
     .option("--limit <n>", "how many to show", positiveCount("--limit"))
     .option("--cursor <cursor>", "go on from where page.next says the last page stopped")
     .action(async function (chat) {

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

@@ -108,6 +108,10 @@ const holderOf = (command) => holderIn(environmentOf(command).env ?? process.env
 const HOLDER_HELP = "who you are for claims: a session id or a chat id; default WIRECAT_HOLDER, else Claude Code's session, else the agent's name";
 const planFrom = (options) => {
     const plan = {};
+    if (options.priority !== undefined)
+        plan.priority = options.priority;
+    if (options.parent !== undefined)
+        plan.parent = options.parent;
     if (options.category !== undefined)
         plan.category = options.category;
     if (options.title !== undefined)
@@ -190,15 +194,21 @@ export const tasksCommand = (messenger) => {
         effects: LOCAL_WRITE,
         examples: [`${tool} personal tasks update DOC-12 --title "Review draft"`],
     }))
-        .summary("set a task's title, description, due date, next check, category and assignee")
-        .description("set a task's title, description, due date, next check, category and assignee; nothing reaches the messenger")
+        .summary("update a task's text, schedule, category, assignees, priority or parent")
+        .description("update a task's text, schedule, category, assignees, priority or parent; nothing reaches the messenger")
         .argument("<task>", "the task's id or key, as tasks list shows it")
-        .option("--category <name>", `${categoryHelp}; a change is kept in the task's history`), "send Alex the API token").action(async function (id) {
+        .option("--category <name>", `${categoryHelp}; a change is kept in the task's history`)
+        .option("--priority <n>", "priority from 0 (urgent) through 4 (low)", (value) => {
+        if (!/^[0-4]$/.test(value))
+            throw new CliError("validation_error", "--priority takes 0 through 4");
+        return Number(value);
+    })
+        .option("--parent <id>", "parent task in the same project; none clears it", (value) => value === "none" ? null : value), "send Alex the API token").action(async function (id) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "tasks.update");
         const plan = planFrom(this.opts());
         if (Object.keys(plan).length === 0)
-            throw new CliError("validation_error", "give at least one of --title, --description, --due, --remind-time, --category");
+            throw new CliError("validation_error", "give at least one of --title, --description, --due, --remind-time, --category, --priority, --parent");
         const planned = await context.withServices((services) => services.tasks.plan(id, plan, writerOf(this)));
         renderAnswer(this, context, itemOf(snakeKeys(planned)), () => `${card(planned)}\n`);
     });

package/dist/cli/model-catalogue-command.d.ts

@@ -0,0 +1,15 @@
+import { Command } from "commander";
+import type { AppIdentity } from "../ports/app.js";
+import { type Body } from "./envelope.js";
+export declare const MODEL_CATALOGUE_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
+export interface ModelCatalogueOptions {
+    kinds: readonly ("audio" | "text")[];
+    env: () => NodeJS.ProcessEnv;
+    output: (answer: Body, command: Command) => void;
+    diagnostic: (line: string) => void;
+    jsonOption?: boolean;
+    offline?: () => boolean;
+    defaultAudio?: () => string;
+}
+/** Provider composition supplies I/O and supported kinds; parsing, receipts and download policy stay shared. */
+export declare const modelCatalogueCommand: (app: AppIdentity, options: ModelCatalogueOptions) => Command;

package/dist/cli/model-catalogue-command.js

@@ -0,0 +1,110 @@
+import { join } from "node:path";
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { defineQuery } from "@wirecat/cli-base/query";
+import { Command } from "commander";
+import { isTextModelInstalled, textModelsDirectory } from "../embeddings/embed.js";
+import { DEFAULT_TEXT_MODEL, TEXT_MODELS } from "../embeddings/models.js";
+import { downloadTextModel } from "../services/model-downloads.js";
+import { install, installedBytes, isInstalled, modelsDirectory } from "../speech/install.js";
+import { DEFAULT_ORDER, orderedModels, speechModel } from "../speech/models.js";
+import { FETCH, LOCAL_READ, NO_EFFECTS } from "./effects.js";
+import { itemOf, listOf } from "./envelope.js";
+import { listQuery, nativeTerms, termField, typedQuery, withQuery } from "./list-query.js";
+export const MODEL_CATALOGUE_QUERY = defineQuery({
+    entity: "model",
+    backend: "native",
+    fields: [
+        termField("kind", "enum", "kind:audio", { values: ["audio", "text"] }),
+        termField("id", "kw", "id:e5-small"),
+        termField("downloaded", "bool", "downloaded:true"),
+    ],
+});
+/** Provider composition supplies I/O and supported kinds; parsing, receipts and download policy stay shared. */
+export const modelCatalogueCommand = (app, options) => {
+    if (options.kinds.length === 0)
+        throw new CliError("configuration_error", "declare at least one supported model kind");
+    const audio = (id, env) => {
+        const model = speechModel(id);
+        const directory = modelsDirectory(env);
+        return {
+            id,
+            kind: "audio",
+            title: model.title,
+            languages: model.languages,
+            size_bytes: installedBytes(model),
+            downloaded: isInstalled(model, directory),
+            default: id === (options.defaultAudio?.() ?? DEFAULT_ORDER[0]),
+            path: join(directory, id),
+        };
+    };
+    const text = (id, env) => {
+        const model = TEXT_MODELS.find((one) => one.id === id);
+        if (!model)
+            throw new CliError("validation_error", `unknown text model ${id}`);
+        const directory = textModelsDirectory(env);
+        return {
+            id,
+            kind: "text",
+            title: model.title,
+            languages: model.languages,
+            licence: model.licence,
+            size_bytes: model.files.reduce((sum, file) => sum + file.bytes, 0),
+            downloaded: isTextModelInstalled(model, directory),
+            default: id === DEFAULT_TEXT_MODEL,
+            path: join(directory, id),
+        };
+    };
+    const models = annotate(new Command("models"), { effects: NO_EFFECTS }).description("models that run on this machine");
+    withQuery(annotate(models.command("list"), {
+        effects: LOCAL_READ,
+        output: { entity: "model" },
+        examples: [`${app.command} models list`, `${app.command} models list kind:${options.kinds[0]}`],
+    }), MODEL_CATALOGUE_QUERY)
+        .description("speech and embedding models, their download status and the default of each kind")
+        .action(function (words) {
+        const terms = nativeTerms(listQuery(typedQuery(words), MODEL_CATALOGUE_QUERY, "models list"), "models list");
+        const env = options.env();
+        const items = [
+            ...(options.kinds.includes("audio") ? orderedModels().map((model) => audio(model.id, env)) : []),
+            ...(options.kinds.includes("text") ? TEXT_MODELS.map((model) => text(model.id, env)) : []),
+        ].filter((item) => (terms.get("kind") === undefined || item.kind === terms.get("kind")?.value) &&
+            (terms.get("id") === undefined || item.id === terms.get("id")?.value) &&
+            (terms.get("downloaded") === undefined || item.downloaded === (terms.get("downloaded")?.value === "true")));
+        options.output(listOf("models list", { items, limit: Math.max(1, items.length), has_more: false }), this);
+    });
+    annotate(models.command("download"), {
+        effects: FETCH,
+        output: { entity: "model" },
+        examples: [
+            `${app.command} models download ${options.kinds.includes("text") ? DEFAULT_TEXT_MODEL : DEFAULT_ORDER[0]}`,
+        ],
+    })
+        .description("download and verify one speech or embedding model")
+        .argument("<model>", "a model id from models list")
+        .option("--offline", "refuse a download that needs the network")
+        .option("--accept-terms", "accept the model's licence terms, for a model that has its own")
+        .action(async function (id, given) {
+        if (options.offline?.() || this.optsWithGlobals().offline)
+            throw new CliError("permission_error", "downloading a model needs the network; --offline was requested", {
+                reason: "model.offline",
+            });
+        const env = options.env();
+        if (TEXT_MODELS.some((model) => model.id === id)) {
+            if (!options.kinds.includes("text"))
+                throw new CliError("validation_error", "this tool does not use text models");
+            await downloadTextModel(id, { env, acceptTerms: given.acceptTerms === true, progress: options.diagnostic });
+            options.output(itemOf(text(id, env)), this);
+        }
+        else {
+            if (!options.kinds.includes("audio"))
+                throw new CliError("validation_error", "this tool does not use audio models");
+            await install(speechModel(id), modelsDirectory(env), { verifyExisting: true, progress: options.diagnostic });
+            options.output(itemOf(audio(id, env)), this);
+        }
+    });
+    if (options.jsonOption)
+        for (const command of models.commands)
+            command.option("--json", "print JSON");
+    return models;
+};

package/dist/cli/program.js

@@ -30,6 +30,7 @@ import { PreviewComplete, preview } from "./preview.js";
 import { commandWords, liftProfile, PROFILE_FREE, valuedOptions } from "./profile.js";
 import { absolutePaths, relayTarget } from "./relay-route.js";
 import { settingsFor } from "./settings.js";
+import { assertSharedContracts } from "./shared-contracts.js";
 import { commandAt, lineOf, withLines } from "./steps.js";
 /**
  * The command tree, built fresh on each call. Commander is global state by default —
@@ -66,6 +67,7 @@ export const createProgram = ({ app, commands, configure, firstScreen }, { out,
     for (const command of commands())
         program.addCommand(command);
     configure?.(program);
+    assertSharedContracts(program);
     installHelp(program, { pitch: app.description, ...firstScreen });
     // Commander builds a usage line from the command tree, where the profile is not a word.
     for (const top of program.commands) {

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

@@ -12,7 +12,6 @@ import { RUN_SEARCH_QUERY, runSearchFilter } from "./search-query.js";
 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,
@@ -22,6 +21,6 @@ export const runsSearchCommand = (app) => annotate(withQuery(new Command("runs")
     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 }));
+    const found = searchRuns(dir, { ...filter, ...options });
+    renderAnswer(this, outputFor(this), runsFound(found, { query: typedQuery(words) }));
 });

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

@@ -1,4 +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">;
+export declare const runSearchFilter: (words: QueryWords) => Pick<RunSearch, "terms" | "status" | "errorCode" | "operation" | "profile" | "since" | "until">;

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

@@ -1,9 +1,15 @@
-import { defineQuery, parseLucene, queryError, validateQuery } from "@wirecat/cli-base/query";
-import { LIST_QUERY_GUIDE, termField, typedQuery } from "../list-query.js";
+import { defineQuery, parseLucene, queryError, validateQuery, } from "@wirecat/cli-base/query";
+import { LIST_QUERY_GUIDE, nativeField, termField, timeBounds, typedQuery } from "../list-query.js";
 export const RUN_SEARCH_QUERY = defineQuery({
     entity: "run",
     backend: "native",
     fields: [
+        nativeField({
+            name: "started_at",
+            type: "time",
+            operators: ["term", "phrase", "range"],
+            example: "started_at>=7d",
+        }),
         termField("text", "kw", "text:timeout"),
         termField("status", "enum", "status:failed", { values: ["success", "failed", "partial", "running"] }),
         termField("error_code", "kw", "error_code:rate_limited"),
@@ -20,6 +26,7 @@ export const runSearchFilter = (words) => {
     validateQuery(ast, RUN_SEARCH_QUERY, context);
     const terms = [];
     const fields = new Map();
+    let started;
     const add = (node) => {
         if (node.kind === "boolean") {
             for (const clause of node.clauses) {
@@ -29,6 +36,12 @@ export const runSearchFilter = (words) => {
             }
             return;
         }
+        if (node.field === "started_at") {
+            if (started)
+                queryError("query.unsupported-placement", node.span, "started_at only once here; use a range", context);
+            started = node;
+            return;
+        }
         if (node.operator !== "term" && node.operator !== "phrase")
             queryError("query.unsupported-placement", node.span, "run search takes literal words and field:value terms", context);
         if (node.field === "text")
@@ -40,7 +53,10 @@ export const runSearchFilter = (words) => {
         }
     };
     add(ast.root);
+    const window = timeBounds(started);
     return {
+        ...(window.since === undefined ? {} : { since: new Date(window.since).toISOString() }),
+        ...(window.until === undefined ? {} : { until: new Date(window.until).toISOString() }),
         ...(terms.length ? { terms } : {}),
         ...(fields.has("status") ? { status: fields.get("status")?.toLowerCase() } : {}),
         ...(fields.has("error_code") ? { errorCode: fields.get("error_code") } : {}),

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

@@ -6,10 +6,11 @@ export interface RunSearch {
     operation?: string;
     profile?: string;
     since?: string;
+    until?: string;
     limit?: number;
     page?: number;
 }
-export declare const searchRuns: (dir: string, { query, terms, status, errorCode, operation, profile, since, limit, page }?: RunSearch) => {
+export declare const searchRuns: (dir: string, { query, terms, status, errorCode, operation, profile, since, until, limit, page }?: RunSearch) => {
     items: {
         runId: string;
         command: string;

package/dist/cli/runs/search.js

@@ -32,10 +32,10 @@ const safeEvent = (event) => Object.fromEntries(FIELDS.flatMap((name) => {
     }
     return typeof value === "string" || typeof value === "number" ? [[name, value]] : [];
 }));
-export const searchRuns = (dir, { query = "", terms = [], status, errorCode, operation, profile, since, limit = 20, page = 1 } = {}) => {
+export const searchRuns = (dir, { query = "", terms = [], status, errorCode, operation, profile, since, until, limit = 20, page = 1 } = {}) => {
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(page) || page < 1)
         throw new CliError("validation_error", "run search uses a limit from 1 to 100 and a positive page");
-    const window = dateWindow(since === undefined ? {} : { sinceTime: since });
+    const window = dateWindow({ sinceTime: since, untilTime: until });
     const from = window.since;
     if (from !== undefined && !Number.isFinite(from))
         throw new CliError("validation_error", "--since-time must be a valid date or ISO timestamp");
@@ -45,7 +45,8 @@ export const searchRuns = (dir, { query = "", terms = [], status, errorCode, ope
     for (const run of listRuns(dir, from === undefined ? {} : { since: from })) {
         if ((profile !== undefined && run.profile !== profile) ||
             (status !== undefined && run.status !== status) ||
-            (from !== undefined && Date.parse(run.startedAt) < from))
+            (from !== undefined && Date.parse(run.startedAt) < from) ||
+            (window.until !== undefined && Date.parse(run.startedAt) > window.until))
             continue;
         const metadataMatch = (!errorCode ||
             run.errorCode === errorCode ||