@wirecat/cli-core 0.531.0 → 0.532.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ shape of this file.
 
 ## Unreleased
 
+## 0.532.0 — 01.11.2026
+
+### Added
+
+- **A message hit names its files**: `search messages` and `search all` hits carry
+  `attachments: [{ position, kind, name, size }]` (files only, absent when there are none; `name` and `size` when the
+  store has them). `position` counts every attachment from 1, as `attachments show --attachment` takes it.
+  `attachments.name` is listed in the hit's `untrusted` fields.
+- **`messages download --offline`** copies files the local store already holds, by chat and id or by a `msg:`
+  locator, and never connects; `--attachment <n>` picks one. A file not saved here fails with `not_found` before
+  anything is written, and the store keeps pointing at its own copy.
+- **`messages download` takes a `msg:` locator** in place of chat and id; the chat and id form still works.
+- **`messages link` lists a message's files**: `files: [{ position, kind, name, url, reason }]`. No messenger gives
+  a file its own link yet, so `url` is null with reason `unsupported_provider`.
+
 ## 0.531.0 — 01.11.2026
 
 ### Added

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

@@ -1,4 +1,5 @@
 import { Command } from "commander";
 import { type Messenger } from "./context.js";
+export declare const count: (value: string) => number;
 /** Files of stored messages: what is in them, for `content:` in a search. Nothing here is sent. */
 export declare const attachmentsCommand: (messenger: Messenger) => Command;

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

@@ -18,7 +18,7 @@ import { messengerContext, refuseLocalWrite } from "./context.js";
 import { addMediaArchiveCommands } from "./media-archive-command.js";
 import { stopOnSignal } from "./patience.js";
 import { readAll } from "./stdin.js";
-const count = (value) => {
+export const count = (value) => {
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed < 1)
         throw new CliError("validation_error", `"${value}" is not a count`);

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

@@ -4,6 +4,8 @@ import { setTimeout as sleep } from "node:timers/promises";
 import { CliError, writeSecurely } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { NOT_FILES } from "../../domain/attachments.js";
+import { isLocator } from "../../domain/locator.js";
+import { messageLinkTarget } from "../../domain/message-link.js";
 import { FETCHING, keyOf } from "../../services/archive.js";
 import { batchProgress, mergeBatches } from "../../services/batch.js";
 import { saveFiles } from "../../services/file-download.js";
@@ -15,25 +17,45 @@ import { patiently } from "../../services/patience.js";
 import { FETCH } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { nextStep } from "../steps.js";
+import { count } from "./attachments-command.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 import { stopOnSignal } from "./patience.js";
 /** `messages download`: every file of one message, or with `--all` of a whole chat, never over a file already there. */
 export const downloadSubcommand = (messages, messenger) => annotate(messages.command("download"), {
     output: { entity: "message_download" },
-    examples: [`${messenger.app.command} personal messages download "Book club" 101 --output-dir ./downloads`],
+    examples: [
+        `${messenger.app.command} personal messages download "Book club" 101 --output-dir ./downloads`,
+        `${messenger.app.command} personal messages download msg:${messenger.provider}/me/500/101 --attachment 1 --offline`,
+    ],
     effects: FETCH,
 })
     .summary("download files attached to stored messages")
-    .description("save a message's photos, files, videos and voice notes to a folder — or a whole chat's with --all")
-    .argument("<chat>", messenger.chatArgument)
-    .argument("[message]", "the message id; left out with --all")
+    .description("save a message's photos, files, videos and voice notes to a folder — or a whole chat's with --all; " +
+    "with --offline, copy the ones this computer already holds, one by --attachment")
+    .argument("<chat>", `${messenger.chatArgument}; or a msg: locator, with no message id after it`)
+    .argument("[message]", "the message id; left out with --all or a locator")
     .option("--output-dir <dir>", "where to save them; created if missing", ".")
+    .option("--attachment <n>", "which file of the message, from 1; needed when it has more than one", count)
     .option("--all", "every file of the chat, newest first; run it again to continue where it stopped")
     .option("--pause <duration>", "with --all, a pause between pages, to stay under the provider's limits", messenger.fetching?.pause ?? FETCHING.pause)
     .option("--extract", "read text layers from the files this download maps into the local content index")
     .action(async function (chat, messageId) {
     const context = messengerContext(this, messenger);
-    const { outputDir: output, all, pause, extract, } = this.opts();
+    const { outputDir: output, all, pause, extract, attachment, } = this.opts();
+    if (context.settings.offline) {
+        if (all || extract)
+            throw new CliError("validation_error", "--offline copies one message's saved files; leave out --all and --extract");
+        const saved = await context.withServices((services) => services.attachments.saveHeld({
+            chat,
+            ...(messageId === undefined ? {} : { message: messageId.trim() }),
+            ...(attachment === undefined ? {} : { attachment }),
+            output,
+        }));
+        renderAnswer(this, context, itemOf(snakeKeys({ files: saved })), () => `${saved.map((one) => one.path).join("\n")}\n`);
+        return;
+    }
+    if (attachment !== undefined)
+        throw new CliError("validation_error", "--attachment picks a file this computer already holds; add --offline");
     if (extract)
         refuseLocalWrite(context, messenger.app.command, "attachments.extract");
     if (all && messageId !== undefined) {
@@ -43,18 +65,19 @@ export const downloadSubcommand = (messages, messenger) => annotate(messages.com
         await downloadChat(this, context, messenger, chat, output, parseDuration(pause, "--pause"), extract);
         return;
     }
-    if (messageId === undefined)
+    if (messageId === undefined && !isLocator(chat))
         throw new CliError("validation_error", "name a message id, or use --all");
-    const id = messageId.trim();
+    const target = messageLinkTarget(chat, messageId?.trim(), messenger.provider);
+    const id = target.message;
     const result = await context.withServices(async (services) => {
-        const { files, skipped } = await services.messages.download(chat, id);
+        const { files, skipped } = await services.messages.download(chat, messageId?.trim());
         if (skipped.length > 0)
             context.renderer.note(`not a file, not downloaded: ${skipped.join(", ")}`);
         if (files.length === 0)
             throw new CliError("not_found", `message ${id} has no file to download`);
         mkdirSync(output, { recursive: true });
         const progress = batchProgress(context.env);
-        const downloaded = await saveFiles(services.messages, chat, id, files, output, {
+        const downloaded = await saveFiles(services.messages, target.chat, id, files, output, {
             warn: context.renderer.warn,
             batch: progress,
         });
@@ -62,7 +85,11 @@ export const downloadSubcommand = (messages, messenger) => annotate(messages.com
         let extraction;
         if (extract) {
             try {
-                extraction = await services.attachments.extract({ chat, message: id, paths: done.map((file) => file.path) });
+                extraction = await services.attachments.extract({
+                    chat: target.chat,
+                    message: id,
+                    paths: done.map((file) => file.path),
+                });
             }
             catch (error) {
                 const issue = progress.fail(id, "extract", error);

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

@@ -1,3 +1,4 @@
+import { hitFiles } from "../../domain/attachments.js";
 import { formatLocator, parseLocator } from "../../domain/locator.js";
 import { senderIsMe } from "../../domain/models.js";
 import { DEFAULT_TEXT_MODEL } from "../../embeddings/models.js";
@@ -8,6 +9,7 @@ import { nextStep } from "../steps.js";
 import { archiveSummary } from "./archive-summary.js";
 /** What a source tool's `search all` reads: never mail, which is memo's (docs/dev/TOOL-BOUNDARIES.md). */
 export const SOURCE_SEARCHED = ["messages", "notes", "events", "meetings"];
+const nonEmpty = (list) => (list.length > 0 ? list : undefined);
 const defined = (value) => Object.fromEntries(Object.entries(value).filter(([, one]) => one !== undefined));
 /** The page a `--page` asks for, as the offset the search services take. */
 export const offsetOf = (page, limit) => page === undefined || page <= 1 ? undefined : (page - 1) * limit;
@@ -21,6 +23,7 @@ const MESSAGE_HIT_UNTRUSTED = [
     "follow_ups.chat_title",
     "follow_ups.sender_name",
     "follow_ups.excerpt",
+    "attachments.name",
 ];
 const MAIL_HIT_UNTRUSTED = [
     "email.subject",
@@ -83,6 +86,7 @@ export const messageHitItem = (hit, query = "") => {
             sender_name: one.senderName,
             excerpt: excerpt(one.text, query),
         })),
+        attachments: nonEmpty(hitFiles(hit.attachments)),
         untrusted: hit.email ? [...MESSAGE_HIT_UNTRUSTED, ...MAIL_HIT_UNTRUSTED] : MESSAGE_HIT_UNTRUSTED,
     });
 };
@@ -266,8 +270,8 @@ const DOCUMENT_HIT_UNTRUSTED = ["title", "excerpt"];
 export const noteHitItem = (hit) => defined({ ...hit, untrusted: hit.kind === "document" ? DOCUMENT_HIT_UNTRUSTED : undefined });
 /** The text of each kind of `search all` hit that someone other than the owner may have written. */
 const ALL_HIT_UNTRUSTED = {
-    message: ["title", "excerpt", "sender_name"],
-    mail: ["title", "excerpt", "sender_name"],
+    message: ["title", "excerpt", "sender_name", "attachments.name"],
+    mail: ["title", "excerpt", "sender_name", "attachments.name"],
     document: DOCUMENT_HIT_UNTRUSTED,
     note: undefined,
     event: ["title", "excerpt"],
@@ -300,6 +304,7 @@ export const allHitItem = (item) => item.kind === "meeting"
         sender_is_me: item.senderIsMe,
         sender_ref: item.from?.ref,
         found_by: item.foundBy,
+        attachments: item.attachments === undefined ? undefined : nonEmpty(item.attachments),
         untrusted: ALL_HIT_UNTRUSTED[item.kind],
     });
 /** Meaning was not searched because the model is not downloaded; `--exact` leaving it out is no gap. */

package/dist/domain/attachments.d.ts

@@ -1,6 +1,14 @@
-import type { ProviderMetadata } from "./models.js";
+import type { Attachment, ProviderMetadata } from "./models.js";
 /** Attachments that are never a file, so their messages cost no download request. */
 export declare const NOT_FILES: ReadonlySet<string>;
+/** A file a message carries, as a search hit names it; `position` counts every attachment, from 1. */
+export interface HitFile {
+    position: number;
+    kind: string;
+    name?: string;
+    size?: number;
+}
+export declare const hitFiles: (attachments: readonly Attachment[] | undefined) => HitFile[];
 /** The stored kinds `has:<kind>` matches: MAX stores a file as `file`, Telegram as `document`. */
 export declare const storedKinds: (kind: string) => string[];
 /** One file `messages download` saved, as the messenger described it. */

package/dist/domain/attachments.js

@@ -9,6 +9,18 @@ export const NOT_FILES = new Set([
     "call",
     "inline_keyboard",
 ]);
+// The position is taken before the filter: the store numbers every attachment, and `--attachment` takes that number.
+// A server search hit built by an adapter may come without attachments at all.
+export const hitFiles = (attachments) => (attachments ?? []).flatMap(({ kind, name, size }, index) => NOT_FILES.has(kind)
+    ? []
+    : [
+        {
+            position: index + 1,
+            kind,
+            ...(name === undefined ? {} : { name }),
+            ...(size === undefined ? {} : { size }),
+        },
+    ]);
 /** The stored kinds `has:<kind>` matches: MAX stores a file as `file`, Telegram as `document`. */
 export const storedKinds = (kind) => (kind === "file" ? ["file", "document"] : [kind]);
 /**

package/dist/domain/message-link.d.ts

@@ -1,3 +1,4 @@
+import type { Attachment } from "./models.js";
 export type MessagePermalink = {
     url: string;
     access: "public" | "restricted" | "unknown";
@@ -7,9 +8,22 @@ export type MessagePermalink = {
     access: "unavailable";
     reason: "unsupported_chat" | "unsupported_provider" | "offline";
 };
+/**
+ * A link to one file of the message, apart from the message's own. No messenger gives one yet: Telegram and
+ * WhatsApp have none, and MAX's are short-lived download addresses that hand the bytes to whoever holds them.
+ */
+export interface FileLink {
+    position: number;
+    kind: string;
+    name?: string;
+    url: null;
+    reason: "unsupported_provider";
+}
 export type MessageLink = MessagePermalink & {
     locator: string;
+    files?: FileLink[];
 };
+export declare const fileLinks: (attachments: readonly Attachment[]) => FileLink[];
 export declare const messageLinkTarget: (reference: string, message: string | undefined, provider: string) => {
     chat: string;
     message: string;

package/dist/domain/message-link.js

@@ -1,5 +1,13 @@
 import { CliError } from "@wirecat/cli-base";
+import { hitFiles } from "./attachments.js";
 import { isLocator, parseLocator } from "./locator.js";
+export const fileLinks = (attachments) => hitFiles(attachments).map(({ position, kind, name }) => ({
+    position,
+    kind,
+    ...(name === undefined ? {} : { name }),
+    url: null,
+    reason: "unsupported_provider",
+}));
 export const messageLinkTarget = (reference, message, provider) => {
     if (isLocator(reference)) {
         if (message !== undefined)

package/dist/entities/attachment.d.ts

@@ -39,3 +39,10 @@ export declare const attachment: v.StrictObjectSchema<{
         readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>, undefined>, undefined>;
 }, undefined>;
+/** A file named on a search hit: `position` is the one `attachments show` and `messages download` take. */
+export declare const hitFile: v.StrictObjectSchema<{
+    readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly kind: v.StringSchema<undefined>;
+    readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly size: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+}, undefined>;

package/dist/entities/attachment.js

@@ -35,3 +35,5 @@ export const attachment = v.strictObject({
         url: v.optional(text),
     })))),
 });
+/** A file named on a search hit: `position` is the one `attachments show` and `messages download` take. */
+export const hitFile = v.strictObject({ position: count, kind: text, name: v.optional(text), size: v.optional(count) });

package/dist/entities/hit.d.ts

@@ -24,6 +24,13 @@ export declare const hit: v.StrictObjectSchema<{
     readonly scope: v.OptionalSchema<v.PicklistSchema<["transcript", "chat", "summary"], undefined>, undefined>;
     /** A meeting passage's stored line, so two passages of one meeting stay apart; `search meetings` gives the same. */
     readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    /** A message's files; absent when it has none. */
+    readonly attachments: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
+        readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly size: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    }, undefined>, undefined>, undefined>;
     /** Absent on a note hit: the owner wrote it. */
     readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
 }, undefined>;

package/dist/entities/hit.js

@@ -1,4 +1,5 @@
 import * as v from "valibot";
+import { hitFile } from "./attachment.js";
 import { count, reference, text, time, untrusted } from "./fields.js";
 /** One result of `search all`: a message, a mail, a note, a calendar event or a meeting passage, best first. */
 export const hit = v.strictObject({
@@ -25,6 +26,8 @@ export const hit = v.strictObject({
     scope: v.optional(v.picklist(["transcript", "chat", "summary"])),
     /** A meeting passage's stored line, so two passages of one meeting stay apart; `search meetings` gives the same. */
     id: v.optional(v.pipe(v.string(), v.minLength(1))),
+    /** A message's files; absent when it has none. */
+    attachments: v.optional(v.array(hitFile)),
     /** Absent on a note hit: the owner wrote it. */
     untrusted,
 });

package/dist/entities/index.d.ts

@@ -1231,6 +1231,13 @@ export declare const ENTITIES: {
                 readonly demoted: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
             }, undefined>, undefined>;
         }, undefined>, undefined>;
+        /** The files the message carries; absent when it has none. */
+        readonly attachments: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
+            readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly kind: v.StringSchema<undefined>;
+            readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly size: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        }, undefined>, undefined>, undefined>;
         readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
     }, undefined>;
     readonly "message.summary": Omit<v.StrictObjectSchema<{
@@ -1895,6 +1902,13 @@ export declare const ENTITIES: {
         readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly access: v.PicklistSchema<["public", "restricted", "unknown", "unavailable"], undefined>;
         readonly reason: v.NullableSchema<v.PicklistSchema<["unsupported_chat", "unsupported_provider", "offline"], undefined>, undefined>;
+        readonly files: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
+            readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly kind: v.StringSchema<undefined>;
+            readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly reason: v.NullableSchema<v.PicklistSchema<["unsupported_provider"], undefined>, undefined>;
+        }, undefined>, undefined>, undefined>;
     }, undefined>;
     readonly message_write: v.StrictObjectSchema<{
         readonly operation_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
@@ -4554,6 +4568,12 @@ export declare const ENTITIES: {
         readonly offset_ms: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>, undefined>;
         readonly scope: v.OptionalSchema<v.PicklistSchema<["transcript", "chat", "summary"], undefined>, undefined>;
         readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        readonly attachments: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
+            readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly kind: v.StringSchema<undefined>;
+            readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly size: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        }, undefined>, undefined>, undefined>;
         readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
     }, undefined>;
     readonly document: v.StrictObjectSchema<{

package/dist/entities/index.js

@@ -8,7 +8,7 @@ import { accountSession } from "./account-session.js";
 import { adminReport } from "./admin-report.js";
 import { agenda } from "./agenda.js";
 import { analysisConsent, analysisConsentRevocation } from "./analysis-consent.js";
-import { attachment } from "./attachment.js";
+import { attachment, hitFile } from "./attachment.js";
 import { attachmentBytes, attachmentExtraction, attachmentTextChange } from "./attachment-results.js";
 import { chart } from "./chart.js";
 import { chat } from "./chat.js";
@@ -120,6 +120,8 @@ export const ENTITIES = {
             "follow_ups",
             "email",
         ]).entries,
+        /** The files the message carries; absent when it has none. */
+        attachments: v.optional(v.array(hitFile)),
         untrusted,
     }),
     "message.summary": v.pick(message, [

package/dist/entities/message-link.d.ts

@@ -6,4 +6,12 @@ export declare const messageLink: v.StrictObjectSchema<{
     readonly access: v.PicklistSchema<["public", "restricted", "unknown", "unavailable"], undefined>;
     /** Why there is no link. */
     readonly reason: v.NullableSchema<v.PicklistSchema<["unsupported_chat", "unsupported_provider", "offline"], undefined>, undefined>;
+    /** The message's files, each with its own link where the messenger gives one; absent when it has none. */
+    readonly files: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
+        readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly reason: v.NullableSchema<v.PicklistSchema<["unsupported_provider"], undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
 }, undefined>;

package/dist/entities/message-link.js

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import { reference, text } from "./fields.js";
+import { count, reference, text } from "./fields.js";
 /** Where a message can be opened: its locator always, a provider link when there is one and who that link reaches. */
 export const messageLink = v.strictObject({
     ref: reference,
@@ -7,4 +7,12 @@ export const messageLink = v.strictObject({
     access: v.picklist(["public", "restricted", "unknown", "unavailable"]),
     /** Why there is no link. */
     reason: v.nullable(v.picklist(["unsupported_chat", "unsupported_provider", "offline"])),
+    /** The message's files, each with its own link where the messenger gives one; absent when it has none. */
+    files: v.optional(v.array(v.strictObject({
+        position: count,
+        kind: text,
+        name: v.optional(text),
+        url: v.nullable(text),
+        reason: v.nullable(v.picklist(["unsupported_provider"])),
+    }))),
 });

package/dist/services/attachments.d.ts

@@ -9,6 +9,7 @@ import { attachment as attachmentEntity } from "../entities/attachment.js";
 import { type TextOrigin } from "../store/store.js";
 import { batchProgress } from "./batch.js";
 import { type ServiceDeps } from "./deps.js";
+import { type Saved } from "./file-download.js";
 export type ExtractStatus = "extracted" | "needs-agent" | "unreadable" | "engine-missing" | "too-large" | "missing";
 /** One file looked at. Never its text: the text stays in the local store. */
 export interface ExtractItem {
@@ -114,6 +115,16 @@ export interface AttachmentsService {
         items: AttachmentItem[];
         has_more: boolean;
     }>;
+    /**
+     * Copies files the store already holds to `output`, never over a file there, and never asks the messenger: one
+     * not held locally is an error before anything is written. The store keeps pointing at its own copy.
+     */
+    saveHeld(target: {
+        chat: string;
+        message?: string;
+        attachment?: number;
+        output: string;
+    }): Promise<Saved[]>;
     /** Keeps text an agent read from a file — a scan, a photo — replacing whatever was there. Sends nothing. */
     setText(target: {
         chat: string;

package/dist/services/attachments.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { constants } from "node:fs";
-import { open, readFile, stat } from "node:fs/promises";
+import { constants, mkdirSync } from "node:fs";
+import { lstat, open, readFile, stat } from "node:fs/promises";
 import { CliError } from "@wirecat/cli-base";
 import { queryFieldsOf, walkQuery } from "@wirecat/cli-base/query";
 import { directoryPaths } from "../attachments/directory.js";
@@ -18,6 +18,7 @@ import { refusedPlace } from "../sends/upload.js";
 import { attachmentColumns, queryFilter, } from "../store/store.js";
 import { batchProgress } from "./batch.js";
 import { accountStore } from "./deps.js";
+import { save } from "./file-download.js";
 import { chatIdIn } from "./message-resolution.js";
 export const ATTACHMENT_QUERY = {
     entity: "attachment",
@@ -407,6 +408,48 @@ export const attachmentsService = (deps) => ({
             ...preview,
         };
     },
+    saveHeld: async ({ chat, message, attachment, output }) => {
+        if (attachment !== undefined && (!Number.isSafeInteger(attachment) || attachment < 1))
+            throw new CliError("validation_error", "attachment must be a position from 1");
+        const store = await accountStore(deps);
+        const { account } = store;
+        const { chatId, messageId } = await messageOf(deps, store, chat, message);
+        const ref = formatLocator({ ...account, chat: chatId, message: messageId });
+        const files = (await store.attachments.attachments({ chatId, messageId, limit: 1000 })).filter(({ kind }) => !NOT_FILES.has(kind));
+        if (files.length === 0)
+            throw new CliError("not_found", `the local store holds no file of ${ref}`);
+        const chosen = attachment === undefined ? files : files.filter(({ position }) => position === attachment - 1);
+        if (chosen.length === 0)
+            throw new CliError("not_found", `${ref} has no file at position ${attachment}; its files are at ${files.map(({ position }) => position + 1).join(", ")}`);
+        const env = deps.env ?? process.env;
+        const held = await Promise.all(chosen.map(async (file) => {
+            const missing = new CliError("not_found", `file ${file.position + 1} of ${ref} is not saved on this computer; run messages download without --offline`);
+            if (file.localPath === null)
+                throw missing;
+            if (refusedPlace(file.localPath, deps.messenger.app, env))
+                throw new CliError("validation_error", "cannot copy known credential files, the WireCat apps' own files or the message store");
+            const found = await lstat(file.localPath).catch(() => undefined);
+            if (!found)
+                throw missing;
+            if (!found.isFile())
+                throw new CliError("validation_error", "the saved attachment must be a regular file");
+            return { file, path: file.localPath };
+        }));
+        mkdirSync(output, { recursive: true });
+        const saved = [];
+        for (const { file, path } of held)
+            saved.push(await save({
+                kind: file.kind,
+                ...(file.name === null ? {} : { name: file.name }),
+                ...(file.mime === null ? {} : { mime: file.mime }),
+                position: file.position,
+                bytes: async function* () {
+                    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+                    yield* handle.createReadStream();
+                },
+            }, output, `${messageId}-${file.position + 1}`));
+        return saved;
+    },
     setText: async ({ chat, message, attachment, text }) => {
         if (text.trim() === "")
             throw new CliError("validation_error", "the text is empty — nothing to keep");

package/dist/services/deps.d.ts

@@ -72,7 +72,7 @@ export declare const fromStore: (deps: Pick<ServiceDeps, "offline" | "reads">) =
 export declare const nothingStored: (messenger: MessengerTraits) => string;
 /** Where a store-mode messenger's history comes from, for what it cannot do. */
 export declare const PUSHED = "this messenger's history is read from the local store";
-export declare const OFFLINE = "--offline answers only from what is kept locally: `chats list|show`, `messages list|show|context`, `contacts list|show` and `review`";
+export declare const OFFLINE = "--offline answers only from what is kept locally: `chats list|show`, `messages list|show|context|download`, `contacts list|show` and `review`";
 /** Over a connection that is already open — an MCP session holds one for minutes. */
 export declare const onlineDeps: (messenger: ServiceMessenger, adapter: MessengerAdapter, guard: SendGuard, where?: {
     profile?: string;

package/dist/services/deps.js

@@ -55,7 +55,7 @@ export const fromStore = (deps) => deps.offline || deps.reads === "store";
 export const nothingStored = (messenger) => `nothing stored for this chat yet — keep \`${typedCommand(messenger.app.command, "serve")}\` running`;
 /** Where a store-mode messenger's history comes from, for what it cannot do. */
 export const PUSHED = "this messenger's history is read from the local store";
-export const OFFLINE = "--offline answers only from what is kept locally: `chats list|show`, `messages list|show|context`, `contacts list|show` and `review`";
+export const OFFLINE = "--offline answers only from what is kept locally: `chats list|show`, `messages list|show|context|download`, `contacts list|show` and `review`";
 /** Over a connection that is already open — an MCP session holds one for minutes. */
 export const onlineDeps = (messenger, adapter, guard, where = {}) => ({
     messenger,

package/dist/services/messages.d.ts

@@ -197,7 +197,6 @@ export interface Reacted {
 }
 /** max-cli's: many at once is what a ban for automation looks like. */
 export declare const DELETE_AT_ONCE = 10;
-/** Every write goes through the guard: asked before it goes, told after, on every outcome. */
 export interface MessagesService {
     /** The account these messages are read as, which names each one's locator. */
     reader(): Promise<AccountKey>;
@@ -212,8 +211,8 @@ export interface MessagesService {
     }): Promise<Page<Message> & {
         discussion: Discussion;
     }>;
-    /** The files of one message. Always from the messenger, whatever its history is read from. */
-    download(chat: string, message: Id): Promise<Download>;
+    /** The files of one message, `chat` and its id or a `msg:` locator alone. Always from the messenger. */
+    download(chat: string, message?: Id): Promise<Download>;
     /**
      * Records in the local store where the files went, so their text can be read later. Only a
      * message the store holds; answers how many attachments it recorded.

package/dist/services/messages.js

@@ -1,7 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { validateFormattedText, visibleFormattedText } from "../domain/formatting.js";
 import { formatLocator } from "../domain/locator.js";
-import { messageLinkTarget, validatePermalink } from "../domain/message-link.js";
+import { fileLinks, messageLinkTarget, validatePermalink } from "../domain/message-link.js";
 import { pinDurationsText } from "../domain/pin-duration.js";
 import { threadIdOf } from "../domain/thread.js";
 import { capability } from "../ports/messenger.js";
@@ -22,6 +22,12 @@ import { searchServer, sourceKey, } from "./server-search.js";
 import { readThreadContext, threadBounds } from "./thread-context.js";
 /** max-cli's: many at once is what a ban for automation looks like. */
 export const DELETE_AT_ONCE = 10;
+/** Every write goes through the guard: asked before it goes, told after, on every outcome. */
+/** Only a message with files says what can be linked of them. */
+const filesOf = ({ attachments }) => {
+    const files = fileLinks(attachments);
+    return files.length > 0 ? { files } : {};
+};
 export const messagesService = (deps) => {
     const { guard } = deps;
     const inStore = async (read) => read(await deps.store(), await deps.account());
@@ -185,13 +191,15 @@ export const messagesService = (deps) => {
                 const store = await deps.store();
                 const chat = await readChatId(deps, target.chat, store, account);
                 const found = await store.messages.around(account, chat, target.message, { before: 0, after: 0 });
-                if (!found.some((item) => item.id === target.message && item.chatId === chat))
+                const held = found.find((item) => item.id === target.message && item.chatId === chat);
+                if (!held)
                     throw new CliError("not_found", "no such message in this account's stored chat");
                 return {
                     locator: formatLocator({ ...account, chat, message: target.message }),
                     url: null,
                     access: "unavailable",
                     reason: deps.offline ? "offline" : "unsupported_provider",
+                    ...filesOf(held),
                 };
             }
             const connection = await deps.connection();
@@ -199,20 +207,31 @@ export const messagesService = (deps) => {
                 throw new CliError("authentication_error", "the connected account differs from the recorded profile; refresh the session before linking");
             const { id: chat } = await connection.resolve(target.chat);
             const locator = formatLocator({ ...account, chat, message: target.message });
-            if (connection.permalink)
-                return { locator, ...validatePermalink(await connection.permalink(chat, target.message)) };
+            if (connection.permalink) {
+                const permalink = validatePermalink(await connection.permalink(chat, target.message));
+                const held = await deps
+                    .store()
+                    .then((store) => store.messages.around(account, chat, target.message, { before: 0, after: 0 }))
+                    .then((found) => found.find((item) => item.id === target.message && item.chatId === chat))
+                    .catch(() => undefined);
+                return { locator, ...permalink, ...(held ? filesOf(held) : {}) };
+            }
             const found = await capability(connection, "around", "read a message")(chat, target.message, {
                 before: 0,
                 after: 0,
             });
-            if (!found.some((item) => item.id === target.message && item.chatId === chat))
+            const held = found.find((item) => item.id === target.message && item.chatId === chat);
+            if (!held)
                 throw new CliError("not_found", "no such message in this chat");
-            return { locator, url: null, access: "unavailable", reason: "unsupported_provider" };
+            return { locator, url: null, access: "unavailable", reason: "unsupported_provider", ...filesOf(held) };
         },
-        download: async (chat, message) => {
+        download: async (reference, message) => {
+            const target = messageLinkTarget(reference, message, deps.messenger.provider);
+            if (target.account !== undefined && target.account !== (await deps.account()).account)
+                throw new CliError("validation_error", "that locator belongs to another account; select its profile first");
             const connection = await deps.connection();
             const download = capability(connection, "download", "download attachments");
-            return download((await connection.resolve(chat)).id, message);
+            return download((await connection.resolve(target.chat)).id, target.message);
         },
         keepDownloaded: (chat, message, files) => inStore(async (store, account) => {
             const chatId = (await storedChatId(deps.messenger, chat, store, account).catch(() => undefined)) ??

package/dist/services/search-all.d.ts

@@ -1,4 +1,5 @@
 import { type ErrorCode } from "@wirecat/cli-base";
+import { type HitFile } from "../domain/attachments.js";
 import { type MailFields } from "../domain/models.js";
 import type { MessengerTraits } from "../ports/traits.js";
 import type { AccountKey, MessageStore } from "../store/store.js";
@@ -30,6 +31,8 @@ export interface SearchAllItem {
     senderIsMe?: boolean;
     /** A mail's people, labels and thread, as `search mail` gives them. */
     email?: MailFields;
+    /** A message's or a mail's files, as `search messages` names them. */
+    attachments?: HitFile[];
     /** Which search found it: words, meaning or both. */
     foundBy: ("title" | "words" | "meaning")[];
 }

package/dist/services/search-all.js

@@ -1,5 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { parseLucene } from "@wirecat/cli-base/query";
+import { hitFiles } from "../domain/attachments.js";
 import { parseLocator } from "../domain/locator.js";
 import { senderIsMe } from "../domain/models.js";
 import { INTERNAL_NOTES, kindIn } from "../domain/providers.js";
@@ -102,6 +103,7 @@ export const searchAll = async (store, account, request, messenger = {}, searchM
                     : { name: hit.senderName, ref: null },
                 senderIsMe: senderIsMe(hit, at.account),
                 ...(hit.email ? { email: hit.email } : {}),
+                attachments: hitFiles(hit.attachments),
                 foundBy,
             };
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.531.0",
+  "version": "0.532.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",

package/parity.json

@@ -3329,6 +3329,9 @@
         "--all": {
           "in": "all"
         },
+        "--attachment": {
+          "in": "all"
+        },
         "--extract": "all",
         "--output-dir": {
           "in": "all"