@bli-cockpit/cli 0.2.242 → 0.2.244

package/dist/commands/msg-schedule-args.js

@@ -0,0 +1,114 @@
+/**
+ * Arguments of `cockpit msg schedule|remind|scheduled` (BLI-21802):
+ *   schedule <channel> --at <instant|"YYYY-MM-DD HH:MM"> [--timezone <zone>] [--thread <id>] [--request-id <uuid>]   (body on stdin)
+ *   remind <message-id> --at <...> [--timezone <zone>] [--note <text>] [--request-id <uuid>]
+ *   scheduled [--state <state|open|all>] [--before <cursor>] [--limit <n>]
+ *   scheduled change <id> [--at <...>] [--timezone <zone>] [--revision <n>]   (optional new body on stdin)
+ *   scheduled cancel <id> | scheduled done <id>
+ * Split out of `local-args-tower-msg.ts`.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl } from "./local-arg-values.js";
+export const MSG_SCHEDULE_ACTIONS = ["schedule", "remind", "scheduled"];
+export const MSG_SCHEDULE_VALUE_FLAGS = ["--at", "--note", "--state", "--revision"];
+export const SCHEDULE_STATE_NAMES = ["pending", "sent", "failed", "cancelled", "fired", "done", "open", "all"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NOTE_MAX = 500;
+export function isMsgScheduleAction(action) {
+    return MSG_SCHEDULE_ACTIONS.includes(action);
+}
+/** A schedule flag used on another msg verb is named, not ignored. */
+export function rejectMsgScheduleFlags(values) {
+    const flag = MSG_SCHEDULE_VALUE_FLAGS.find((name) => values.flags.has(name));
+    if (flag)
+        throw new Error(`${flag} belongs to \`cockpit msg schedule\`, \`msg remind\` or \`msg scheduled\`.`);
+}
+export function parseMsgScheduleArgs(action, values, rest) {
+    const stray = ["--channel", "--members", "--description", "--from", "--expected-revision", "--name", "--out", "--file", "--level", "--message", "--to"]
+        .find((flag) => values.flags.has(flag));
+    const strayBoolean = ["--private", "--mentions", "--threads", "--unread", "--mark-read", "--remove"].find((flag) => values.booleans.has(flag));
+    if (stray || strayBoolean)
+        throw new Error(`${stray ?? strayBoolean} does not belong to \`cockpit msg ${action}\`.`);
+    const base = {
+        kind: "msg",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        isPrivate: false,
+        json: values.booleans.has("--json"),
+    };
+    const at = optionalNonEmpty(values.flags.get("--at"));
+    const timezone = optionalNonEmpty(values.flags.get("--timezone"));
+    const thread = optionalNonEmpty(values.flags.get("--thread"));
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    const note = values.flags.get("--note");
+    const state = optionalNonEmpty(values.flags.get("--state"));
+    const before = optionalNonEmpty(values.flags.get("--before"));
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const revisionText = optionalNonEmpty(values.flags.get("--revision"));
+    const revision = revisionText === undefined ? undefined : optionalPositiveInteger(revisionText, "--revision");
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id takes a UUID.");
+    if (thread && (action !== "schedule" || !UUID.test(thread))) {
+        throw new Error(action === "schedule" ? "--thread takes a message id (a UUID)." : "--thread belongs to `cockpit msg schedule`.");
+    }
+    if (note !== undefined && action !== "remind")
+        throw new Error("--note belongs to `cockpit msg remind`.");
+    if (note !== undefined && note.length > NOTE_MAX)
+        throw new Error(`--note is limited to ${NOTE_MAX} characters.`);
+    if (requestId && action === "scheduled")
+        throw new Error("--request-id belongs to `cockpit msg schedule` and `msg remind`.");
+    if (action === "scheduled") {
+        const verb = rest[0];
+        if (verb === "change" || verb === "cancel" || verb === "done") {
+            const targetId = optionalNonEmpty(rest[1]);
+            if (!targetId || !UUID.test(targetId))
+                throw new Error(`msg scheduled ${verb} needs a schedule id (a UUID) from \`cockpit msg scheduled\`.`);
+            if (rest.length > 2)
+                throw new Error(`msg scheduled ${verb} takes one schedule id, not ${rest.length - 1}.`);
+            if (state || before || limit !== undefined)
+                throw new Error("--state, --before and --limit belong to `cockpit msg scheduled` (the list).");
+            if (verb !== "change" && (at || timezone || revision !== undefined))
+                throw new Error(`--at, --timezone and --revision belong to \`cockpit msg scheduled change\`.`);
+            return {
+                ...base, scheduleVerb: verb, targetId,
+                ...(at ? { scheduleAt: at } : {}), ...(timezone ? { timezone } : {}), ...(revision === undefined ? {} : { scheduleRevision: revision }),
+            };
+        }
+        if (rest.length > 0)
+            throw new Error(`msg scheduled does not take "${rest[0]}". Try change, cancel or done, or no word to list.`);
+        if (at || timezone || revision !== undefined)
+            throw new Error("--at, --timezone and --revision belong to `cockpit msg scheduled change`.");
+        if (state && !SCHEDULE_STATE_NAMES.includes(state)) {
+            throw new Error(`--state takes one of ${SCHEDULE_STATE_NAMES.join(", ")}.`);
+        }
+        return {
+            ...base, scheduleVerb: "list",
+            ...(state ? { scheduleState: state } : {}), ...(before ? { before } : {}), ...(limit === undefined ? {} : { limit }),
+        };
+    }
+    if (state || before || limit !== undefined || revision !== undefined) {
+        throw new Error(`--state, --before, --limit and --revision belong to \`cockpit msg scheduled\`, not \`msg ${action}\`.`);
+    }
+    const target = optionalNonEmpty(rest[0]);
+    if (rest.length > 1)
+        throw new Error(`msg ${action} takes one ${action === "schedule" ? "channel" : "message id"}, not ${rest.length}.`);
+    if (!at) {
+        throw new Error(action === "schedule"
+            ? 'msg schedule needs --at, e.g. `echo "standup notes" | cockpit msg schedule ops --at "2026-11-02 09:00" --timezone America/Toronto`.'
+            : 'msg remind needs --at, e.g. `cockpit msg remind <message-id> --at "2026-11-02 09:00" --timezone America/Toronto`.');
+    }
+    if (action === "schedule") {
+        if (!target)
+            throw new Error("msg schedule needs a channel id or name, e.g. `cockpit msg schedule ops --at ...`.");
+        return {
+            ...base, channelRef: target, scheduleAt: at,
+            ...(timezone ? { timezone } : {}), ...(thread ? { threadId: thread } : {}), ...(requestId ? { requestId } : {}),
+        };
+    }
+    if (!target || !UUID.test(target))
+        throw new Error("msg remind needs a message id (a UUID), e.g. `cockpit msg remind <message-id> --at ...`.");
+    return {
+        ...base, targetId: target, scheduleAt: at,
+        ...(timezone ? { timezone } : {}), ...(note !== undefined ? { scheduleNote: note } : {}), ...(requestId ? { requestId } : {}),
+    };
+}

package/dist/commands/msg-schedule.js

@@ -0,0 +1,226 @@
+/**
+ * The schedule verbs of `cockpit msg` (BLI-21802): `schedule`, `remind`, `scheduled` (list), `scheduled change|cancel|done`.
+ * Same doors the browser calls (`/api/msg/schedules`, `.../<id>`, `.../<id>/done`); `--json` prints the door's body unchanged so
+ * ids, states, instants and reasons match HTTP, the web page, MCP and JARVIS. `--at` is an ISO instant with an offset, or a
+ * wall time "YYYY-MM-DD HH:MM" in `--timezone` (this machine's zone when none is given, and the answer names it). A schedule
+ * is yours alone. The message body is piped in and never travels on the command line. A refusal keeps the door's reason:
+ * invalid_schedule_time, invalid_timezone, schedule_limit_reached, schedule_not_found, schedule_already_sent,
+ * schedule_revision_conflict, request_id_reused.
+ */
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[msg cli]";
+const DEADLINE_MS = 30_000;
+const BODY_MAX_CHARS = 8_000;
+const LOCAL_WALL = /^\d{4}-\d\d-\d\d[ T]\d\d:\d\d$/;
+function systemZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+/** The `at` field of a door body, plus the zone the answer should name when the person gave a wall time without one. */
+function atField(command) {
+    const raw = (command.scheduleAt ?? "").trim();
+    if (LOCAL_WALL.test(raw)) {
+        const assumedZone = !command.timezone;
+        const zone = command.timezone ?? systemZone();
+        return { at: { local: raw, timezone: zone }, zone, assumedZone };
+    }
+    return { at: raw, zone: command.timezone ?? null, assumedZone: false };
+}
+function oneLine(text) {
+    const line = (text ?? "").split("\n")[0] ?? "";
+    return line.length > 100 ? `${line.slice(0, 97)}...` : line;
+}
+function describe(row) {
+    return `${row.id}  ${row.state}  ${row.kind}  ${row.due_at} (${row.timezone})  rev ${row.revision}${row.reason ? `  ${row.reason}` : ""}`;
+}
+/** A write whose answer may have been lost keeps its request id: the same input with the same id stores once. */
+function refuseWrite(door, answer, requestId) {
+    const mutation = answer.body?.mutation;
+    if (answer.httpStatus === undefined || answer.httpStatus >= 500) {
+        writeLine(door.io.stderr, `${TAG} the result is unknown. List with \`cockpit msg scheduled\`, or retry unchanged input with --request-id ${requestId}; it stores once.`);
+    }
+    return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+}
+async function readBody(command, door, required) {
+    if (isInteractiveStdin(door.io)) {
+        if (!required)
+            return { ok: true, text: "" };
+        return { ok: false, code: failAgentDoor(door, TAG, "nothing_piped", 'Pipe the message in, e.g. `echo "hello" | cockpit msg schedule ops --at "2026-11-02 09:00"`. A message never travels on the command line.') };
+    }
+    try {
+        const text = await readPipedText(door.io.stdin, { maxChars: BODY_MAX_CHARS, overflowMessage: `A scheduled message is limited to ${BODY_MAX_CHARS} characters.` });
+        return { ok: true, text: text.trim() };
+    }
+    catch (error) {
+        void command;
+        return { ok: false, code: failAgentDoor(door, TAG, "content_too_long", error instanceof Error ? error.message : String(error)) };
+    }
+}
+function sayAssumedZone(door, zone, assumed) {
+    if (assumed && zone)
+        writeLine(door.io.stderr, `${TAG} no --timezone given; read that wall time in this machine's zone, ${zone}.`);
+}
+async function scheduleVerb(command, door, resolve) {
+    const ref = command.channelRef ?? "";
+    const resolved = await resolve(ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "channel_not_found_or_unreadable", `That channel does not exist, or you cannot read it: ${ref}`);
+    }
+    const body = await readBody(command, door, true);
+    if (!body.ok)
+        return body.code;
+    if (body.text === "")
+        return failAgentDoor(door, TAG, "content_too_long", "Nothing was piped in. A scheduled message is 1 to 8000 characters.");
+    const when = atField(command);
+    sayAssumedZone(door, when.zone, when.assumedZone);
+    const requestId = command.requestId ?? randomUUID();
+    const answer = await askAgentDoor(door, {
+        path: "/api/msg/schedules",
+        method: "POST",
+        label: "msg schedule",
+        timeoutMs: DEADLINE_MS,
+        body: {
+            kind: "message", channel_id: resolved.id, body: body.text, at: when.at, request_id: requestId,
+            ...(when.zone && typeof when.at === "string" ? { timezone: when.zone } : {}),
+            ...(command.threadId ? { thread_parent_id: command.threadId } : {}),
+        },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    const stored = answer.body.schedule;
+    writeLine(door.io.stderr, `${TAG} scheduled ${JSON.stringify({ schedule_id: stored?.id ?? null, channel_id: resolved.id, request_id: requestId, replayed: answer.body.replayed === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    writeLine(door.io.stdout, `Scheduled ${stored?.id ?? "a message"} for ${stored?.due_at ?? command.scheduleAt} (${stored?.timezone ?? when.zone ?? "UTC"}) in ${ref}. List: cockpit msg scheduled.`);
+    return 0;
+}
+async function remindVerb(command, door) {
+    const when = atField(command);
+    sayAssumedZone(door, when.zone, when.assumedZone);
+    const requestId = command.requestId ?? randomUUID();
+    const answer = await askAgentDoor(door, {
+        path: "/api/msg/schedules",
+        method: "POST",
+        label: "msg remind",
+        timeoutMs: DEADLINE_MS,
+        body: {
+            kind: "reminder", message_id: command.targetId, at: when.at, request_id: requestId,
+            ...(when.zone && typeof when.at === "string" ? { timezone: when.zone } : {}),
+            ...(command.scheduleNote ? { note: command.scheduleNote } : {}),
+        },
+    });
+    if (!answer.ok)
+        return refuseWrite(door, answer, requestId);
+    const stored = answer.body.schedule;
+    writeLine(door.io.stderr, `${TAG} reminder ${JSON.stringify({ schedule_id: stored?.id ?? null, message_id: command.targetId, request_id: requestId })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    writeLine(door.io.stdout, `Reminder ${stored?.id ?? ""} set for ${stored?.due_at ?? command.scheduleAt} (${stored?.timezone ?? when.zone ?? "UTC"}). It shows under \`cockpit msg scheduled --state fired\` when due; nothing is posted.`);
+    return 0;
+}
+async function listVerb(command, door) {
+    const query = new URLSearchParams();
+    if (command.scheduleState)
+        query.set("state", command.scheduleState);
+    if (command.before)
+        query.set("before", command.before);
+    if (command.limit)
+        query.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/schedules${query.size > 0 ? `?${query.toString()}` : ""}`,
+        method: "GET",
+        label: "msg scheduled",
+        timeoutMs: DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const items = body.items ?? [];
+    writeLine(door.io.stderr, `${TAG} scheduled ${JSON.stringify({ state: command.scheduleState ?? "open", returned: items.length, has_more: body.hasMore === true })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    for (const row of items)
+        writeLine(door.io.stdout, `${describe(row)}  ${oneLine(row.body)}`);
+    if (items.length === 0)
+        writeLine(door.io.stdout, "Nothing scheduled.");
+    writeLine(door.io.stdout, body.hasMore && body.nextCursor ? `more: --before ${body.nextCursor}` : "complete");
+    return 0;
+}
+async function changeVerb(command, door) {
+    const body = await readBody(command, door, false);
+    if (!body.ok)
+        return body.code;
+    if (!command.scheduleAt && body.text === "") {
+        return failAgentDoor(door, TAG, "invalid_body", "Change the time with --at, the text by piping it in, or both.");
+    }
+    const when = command.scheduleAt ? atField(command) : null;
+    if (when)
+        sayAssumedZone(door, when.zone, when.assumedZone);
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/schedules/${encodeURIComponent(command.targetId ?? "")}`,
+        method: "PATCH",
+        label: "msg scheduled change",
+        timeoutMs: DEADLINE_MS,
+        body: {
+            ...(when ? { at: when.at, ...(when.zone && typeof when.at === "string" ? { timezone: when.zone } : {}) } : {}),
+            ...(body.text !== "" ? { body: body.text } : {}),
+            ...(command.scheduleRevision === undefined ? {} : { expected_revision: command.scheduleRevision }),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail, scheduleExtra(answer.body));
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} change ${JSON.stringify({ schedule_id: command.targetId, changed: result.changed !== false })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    writeLine(door.io.stdout, result.changed === false
+        ? `Unchanged: ${command.targetId} already has that time and text.`
+        : `Changed ${command.targetId}: now due ${result.schedule?.due_at} (${result.schedule?.timezone}), revision ${result.schedule?.revision}.`);
+    return 0;
+}
+function scheduleExtra(body) {
+    const mutation = body?.mutation;
+    return mutation ? { mutation } : {};
+}
+async function cancelOrDone(command, door) {
+    const done = command.scheduleVerb === "done";
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/schedules/${encodeURIComponent(command.targetId ?? "")}${done ? "/done" : ""}`,
+        method: done ? "POST" : "DELETE",
+        label: `msg scheduled ${done ? "done" : "cancel"}`,
+        timeoutMs: DEADLINE_MS,
+    });
+    if (!answer.ok) {
+        const sentId = answer.body?.mutation?.message_id;
+        if (answer.reason === "schedule_already_sent" && sentId)
+            writeLine(door.io.stderr, `${TAG} it already went out as message ${sentId}.`);
+        return failAgentDoor(door, TAG, answer.reason, answer.detail, scheduleExtra(answer.body));
+    }
+    const result = answer.body;
+    writeLine(door.io.stderr, `${TAG} ${done ? "done" : "cancel"} ${JSON.stringify({ schedule_id: command.targetId, changed: result.changed !== false })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...answer.body });
+    const past = done ? "Marked done" : "Cancelled";
+    writeLine(door.io.stdout, result.changed === false ? `${past} already: ${command.targetId}.` : `${past} ${command.targetId}.`);
+    return 0;
+}
+export async function runMsgSchedule(command, door, resolve) {
+    if (command.action === "schedule")
+        return scheduleVerb(command, door, resolve);
+    if (command.action === "remind")
+        return remindVerb(command, door);
+    switch (command.scheduleVerb ?? "list") {
+        case "change": return changeVerb(command, door);
+        case "cancel":
+        case "done": return cancelOrDone(command, door);
+        default: return listVerb(command, door);
+    }
+}

package/dist/commands/msg-search-args.js

@@ -0,0 +1,71 @@
+/**
+ * The message-search flags shared by `cockpit msg search` and `cockpit search --kind msg` (BLI-21658, slice 8):
+ * `--from <email|me>` (repeatable), `--in <channel>`, `--since` / `--until` (`YYYY-MM-DD`, both inclusive local
+ * days), `--timezone <IANA>`, `--replies` or `--top-level`, `--has-file`. One reader, one query-string writer, so
+ * the two commands cannot mean different things. The door checks the values; this file only checks shape.
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+export const MSG_SEARCH_VALUE_FLAGS = ["--in", "--since", "--until"];
+export const MSG_SEARCH_BOOLEAN_FLAGS = ["--replies", "--top-level", "--has-file"];
+/** Flags only a message search reads (`--from` and `--timezone` are shared with other verbs, so they are not listed). */
+export const MSG_SEARCH_ONLY_FLAGS = [...MSG_SEARCH_VALUE_FLAGS, ...MSG_SEARCH_BOOLEAN_FLAGS];
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+function machineZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+function day(flag, value) {
+    const given = optionalNonEmpty(value);
+    if (given === undefined)
+        return undefined;
+    if (!DAY.test(given))
+        throw new Error(`${flag} takes a day written YYYY-MM-DD, not "${given}".`);
+    return given;
+}
+/** Reads the filter flags. The machine's IANA zone is sent unless `--timezone` is given. */
+export function readMsgSearchFilters(values) {
+    const replies = values.booleans.has("--replies");
+    const topLevel = values.booleans.has("--top-level");
+    if (replies && topLevel)
+        throw new Error("Pick one of --replies or --top-level.");
+    const from = (values.flagValues.get("--from") ?? []).map((entry) => entry.trim()).filter((entry) => entry !== "");
+    const channel = optionalNonEmpty(values.flags.get("--in"));
+    const since = day("--since", values.flags.get("--since"));
+    const until = day("--until", values.flags.get("--until"));
+    if (since && until && since > until)
+        throw new Error(`--since ${since} is after --until ${until}.`);
+    return {
+        ...(from.length > 0 ? { from } : {}),
+        ...(channel ? { in: channel } : {}),
+        ...(since ? { since } : {}),
+        ...(until ? { until } : {}),
+        timezone: optionalNonEmpty(values.flags.get("--timezone")) ?? machineZone(),
+        ...(replies ? { thread: "reply" } : topLevel ? { thread: "root" } : {}),
+        ...(values.booleans.has("--has-file") ? { hasFile: true } : {}),
+    };
+}
+/** True when a flag that narrows the search was given (the zone alone does not narrow). */
+export function hasMsgSearchFilterFlags(filters) {
+    return Boolean(filters.from || filters.in || filters.since || filters.until || filters.thread || filters.hasFile);
+}
+/** The structured query parameters `GET /api/msg/search` and `GET /api/search` read. */
+export function appendMsgSearchParams(params, filters) {
+    for (const person of filters.from ?? [])
+        params.append("from", person);
+    if (filters.in)
+        params.set("channel", filters.in);
+    if (filters.since)
+        params.set("since", filters.since);
+    if (filters.until)
+        params.set("until", filters.until);
+    if (filters.timezone)
+        params.set("tz", filters.timezone);
+    if (filters.thread)
+        params.set("thread", filters.thread);
+    if (filters.hasFile)
+        params.set("has", "file");
+}

package/dist/commands/msg-search.js

@@ -0,0 +1,48 @@
+/**
+ * `cockpit msg search [words] [--from <email|me>]... [--in <channel>] [--since YYYY-MM-DD] [--until YYYY-MM-DD]
+ * [--timezone <zone>] [--replies|--top-level] [--has-file] [--before <cursor>] [--limit <n>] [--json]` (BLI-21658).
+ *
+ * The door the browser's message box presses (`GET /api/msg/search`): newest first, paged by `nextCursor`. `--json`
+ * prints the door's body unchanged so ids, filters and paging match HTTP. Split out of `msg.ts` for the file-size ratchet.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { appendMsgSearchParams } from "./msg-search-args.js";
+const TAG = "[msg cli]";
+const READ_DEADLINE_MS = 30_000;
+const SNIPPET_LENGTH = 140;
+function snippet(content) {
+    const flat = (content ?? "").replace(/\s+/g, " ").trim();
+    if (flat === "")
+        return "(attachment, no text)";
+    return flat.length > SNIPPET_LENGTH ? `${flat.slice(0, SNIPPET_LENGTH - 3)}...` : flat;
+}
+export async function runMsgSearch(command, door) {
+    const params = new URLSearchParams({ q: command.searchQuery ?? "" });
+    appendMsgSearchParams(params, command.searchFilters ?? {});
+    if (command.before)
+        params.set("before", command.before);
+    if (command.limit)
+        params.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/search?${params.toString()}`,
+        method: "GET",
+        label: "msg search",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const hits = body.hits ?? [];
+    writeLine(door.io.stderr, `${TAG} search ${JSON.stringify({ returned: hits.length, has_more: body.hasMore === true, coverage: body.coverage ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    if (hits.length === 0)
+        writeLine(door.io.stdout, "No messages match.");
+    for (const hit of hits) {
+        const where = hit.channel ? (hit.channel.is_dm ? "direct message" : `#${hit.channel.name ?? "unnamed"}`) : hit.channel_id;
+        writeLine(door.io.stdout, `${hit.id}  ${where}  ${hit.author_name ?? hit.user_id}  ${hit.created_at}  ${snippet(hit.content)}`);
+    }
+    writeLine(door.io.stdout, body.hasMore && body.nextCursor ? `more: --before ${body.nextCursor}` : "complete");
+    return 0;
+}

package/dist/commands/msg-write.js

@@ -13,7 +13,21 @@ const CONTENT_MAX_CHARS = 8_000;
 /** The one sentence a deleted message reads as, on every surface. */
 export const DELETED_SENTENCE = "This message was deleted";
 export function messageText(message) {
-    return message.deleted_at ? `(${DELETED_SENTENCE})` : (message.content ?? "");
+    if (message.deleted_at)
+        return `(${DELETED_SENTENCE})`;
+    const names = message.files?.map((file) => file.name) ?? [];
+    if (message.content)
+        return names.length > 0 ? `${message.content} [files: ${names.join(", ")}]` : message.content;
+    // BLI-21521: an attachment-only post has NULL content and is not deleted.
+    const blockCount = Array.isArray(message.blocks)
+        ? Number(message.blocks.find((block) => block?.type === "files")?.count ?? 0)
+        : 0;
+    const count = names.length || blockCount;
+    if (count === 1 && names[0])
+        return `Shared a file: ${names[0]}`;
+    if (count === 1)
+        return "Shared a file";
+    return count > 1 ? `Shared ${count} files` : "";
 }
 export async function readContent(io) {
     if (isInteractiveStdin(io)) {

package/dist/commands/msg.js

@@ -17,21 +17,24 @@
  */
 import { randomUUID } from "node:crypto";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
-import { writeLine } from "./cli-io.js";
+import { isInteractiveStdin, writeLine } from "./cli-io.js";
 import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js";
 import { markReadThrough } from "./msg-read-line.js";
+import { runMsgActivityVerb } from "./msg-activity.js";
 import { runMsgDraft } from "./msg-draft.js";
+import { runMsgSearch } from "./msg-search.js";
+import { openDm } from "./msg-dm.js";
+import { runMsgMark } from "./msg-mark.js";
+import { runMsgChannel } from "./msg-channel.js";
+import { runMsgFile } from "./msg-file.js";
 import { deleteMessage, editMessage, messageOutcome, messageText, readContent, refuseMsgWrite } from "./msg-write.js";
 const TAG = "[msg cli]";
-const READ_DEADLINE_MS = 30_000;
-const WRITE_DEADLINE_MS = 30_000;
+const [READ_DEADLINE_MS, WRITE_DEADLINE_MS] = [30_000, 30_000];
 export async function runMsg(command, io) {
     const door = await openAgentDoor("msg", command, io);
     switch (command.action) {
-        case "show":
-            return showMessage(command, door);
-        case "channels":
-            return listChannels(door);
+        case "show": return showMessage(command, door);
+        case "channels": return listChannels(door);
         case "read":
             return readChannel(command, door);
         case "unread":
@@ -46,12 +49,35 @@ export async function runMsg(command, io) {
             return messageOutcome(command, door);
         case "draft":
             return draftVerb(command, door);
+        case "file":
+            return fileVerb(command, door);
         case "thread":
             return readThread(command, door);
-        case "create":
-            return createChannel(command, door);
-        case "dm":
-            return openDm(command, door);
+        case "create": return createChannel(command, door);
+        case "dm": return openDm(command, door);
+        case "search":
+            return runMsgSearch(command, door);
+        case "channel":
+        case "members":
+        case "hide":
+        case "unhide":
+            return runMsgChannel(command, door, (ref) => resolveChannelId(door, ref));
+        case "save":
+        case "saved":
+        case "pin":
+        case "pins":
+        case "forward":
+        case "schedule":
+        case "remind":
+        case "scheduled":
+        case "context":
+            return runMsgMark(command, door, (ref) => resolveChannelId(door, ref));
+        case "activity":
+        case "follow":
+        case "unfollow":
+        case "react":
+        case "notify":
+            return runMsgActivityVerb(command, door, (ref) => resolveChannelId(door, ref));
     }
 }
 /** `msg draft`: `list` needs no channel; every other verb resolves the channel the same way read and send do. */
@@ -66,6 +92,18 @@ async function draftVerb(command, door) {
         return channelNotFound(door, ref);
     return runMsgDraft(command, door, resolved.id);
 }
+/** `msg file`: `upload` and `list` name a channel; the other verbs name a file. */
+async function fileVerb(command, door) {
+    if (command.fileVerb !== "upload" && command.fileVerb !== "list")
+        return runMsgFile(command, door, null);
+    const ref = command.channelRef ?? "";
+    const resolved = await resolveChannelId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found")
+        return channelNotFound(door, ref);
+    return runMsgFile(command, door, resolved.id);
+}
 async function fetchChannels(door) {
     const answer = await readThroughCache({
         io: door.io,
@@ -276,10 +314,16 @@ async function sendMessage(command, door) {
         return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
     if (resolved.status === "not_found")
         return channelNotFound(door, ref);
-    const content = await readContent(door.io);
-    if (!content.ok)
-        return failAgentDoor(door, TAG, content.reason, content.detail);
-    if (content.text === "")
+    // BLI-21521: with --file the text is optional; stdin is read only when something is piped in.
+    const fileIds = command.fileIds ?? [];
+    let text = "";
+    if (fileIds.length === 0 || !isInteractiveStdin(door.io)) {
+        const content = await readContent(door.io);
+        if (!content.ok)
+            return failAgentDoor(door, TAG, content.reason, content.detail);
+        text = content.text;
+    }
+    if (text === "" && fileIds.length === 0)
         return failAgentDoor(door, TAG, "invalid_body", "There was nothing to send. Nothing was sent.");
     // BLI-21314: every send carries a request id, so a lost response can be checked and a retry posts once.
     const requestId = command.requestId ?? randomUUID();
@@ -289,7 +333,8 @@ async function sendMessage(command, door) {
         label: "msg send",
         timeoutMs: WRITE_DEADLINE_MS,
         body: {
-            content: content.text,
+            ...(text === "" ? {} : { content: text }),
+            ...(fileIds.length > 0 ? { file_ids: fileIds } : {}),
             request_id: requestId,
             ...(command.threadId ? { thread_parent_id: command.threadId } : {}),
         },
@@ -297,7 +342,7 @@ async function sendMessage(command, door) {
     if (!answer.ok)
         return refuseMsgWrite(door, answer, requestId, "send");
     const { message = null, mutation = null } = answer.body;
-    writeLine(door.io.stderr, `${TAG} sent ${JSON.stringify({ channel_id: resolved.id, message_id: message?.id ?? null, request_id: requestId, chars: content.text.length })}`);
+    writeLine(door.io.stderr, `${TAG} sent ${JSON.stringify({ channel_id: resolved.id, message_id: message?.id ?? null, request_id: requestId, chars: text.length, files: fileIds.length })}`);
     if (door.json)
         return emitAgentDoor(door, { ok: true, message, mutation });
     writeLine(door.io.stdout, `Sent to ${ref} (${message?.id ?? "?"}).`);
@@ -360,28 +405,6 @@ function reportChannelCreationToHuman(door, channel, name, requestedMembers, mem
         writeLine(door.io.stdout, `Not added (${failure.reason}): ${failure.userId}`);
     }
 }
-async function openDm(command, door) {
-    const email = command.dmEmail ?? "";
-    if (email === "")
-        return failAgentDoor(door, TAG, "invalid_body", "msg dm needs an email address.");
-    const answer = await askAgentDoor(door, {
-        path: "/api/msg/channels",
-        method: "POST",
-        label: "msg dm",
-        timeoutMs: WRITE_DEADLINE_MS,
-        body: { dm_participant_emails: [email] },
-    });
-    if (!answer.ok)
-        return failAgentDoor(door, TAG, answer.reason, answer.detail);
-    const channel = answer.body.channel ?? null;
-    writeLine(door.io.stderr, `${TAG} dm resolved ${JSON.stringify({ channel_id: channel?.id ?? null })}`);
-    if (door.json)
-        return emitAgentDoor(door, { ok: true, channel });
-    // Idempotent by contract (`get_or_create_dm`), so the wording says what is
-    // true either way rather than claiming a creation that may not have happened.
-    writeLine(door.io.stdout, `Direct message with ${email}: ${channel?.id ?? "?"}`);
-    return 0;
-}
 async function showMessage(command, door) {
     const answer = await askAgentDoor(door, { path: `/api/msg/messages/${encodeURIComponent(command.threadId ?? "")}`, method: "GET", label: "msg show", timeoutMs: READ_DEADLINE_MS });
     if (!answer.ok)