@wirecat/cli-core 0.399.0 → 0.401.0

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

@@ -0,0 +1,50 @@
+import { defineQuery, parseLucene, queryError, validateQuery } from "@wirecat/cli-base/query";
+import { LIST_QUERY_GUIDE, termField, typedQuery } from "../list-query.js";
+export const RUN_SEARCH_QUERY = defineQuery({
+    entity: "run",
+    backend: "native",
+    fields: [
+        termField("text", "kw", "text:timeout"),
+        termField("status", "enum", "status:failed", { values: ["success", "failed", "partial", "running"] }),
+        termField("error_code", "kw", "error_code:rate_limited"),
+        termField("operation", "kw", "operation:messages.download"),
+        termField("profile", "kw", "profile:work"),
+    ],
+});
+export const runSearchFilter = (words) => {
+    const text = typedQuery(words).trim();
+    if (!text)
+        return {};
+    const context = { command: "search runs", guide: LIST_QUERY_GUIDE };
+    const ast = parseLucene(text, { defaultField: "text", ...context });
+    validateQuery(ast, RUN_SEARCH_QUERY, context);
+    const terms = [];
+    const fields = new Map();
+    const add = (node) => {
+        if (node.kind === "boolean") {
+            for (const clause of node.clauses) {
+                if (clause.occur !== "must")
+                    queryError("query.unsupported-placement", clause.node.span, "run search takes terms joined by AND", context);
+                add(clause.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")
+            terms.push(node.value);
+        else {
+            if (fields.has(node.field))
+                queryError("query.unsupported-placement", node.span, `${node.field} only once here`, context);
+            fields.set(node.field, node.value);
+        }
+    };
+    add(ast.root);
+    return {
+        ...(terms.length ? { terms } : {}),
+        ...(fields.has("status") ? { status: fields.get("status")?.toLowerCase() } : {}),
+        ...(fields.has("error_code") ? { errorCode: fields.get("error_code") } : {}),
+        ...(fields.has("operation") ? { operation: fields.get("operation") } : {}),
+        ...(fields.has("profile") ? { profile: fields.get("profile") } : {}),
+    };
+};

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

@@ -1,5 +1,6 @@
 export interface RunSearch {
     query?: string;
+    terms?: readonly string[];
     status?: "success" | "failed" | "partial" | "running";
     errorCode?: string;
     operation?: string;
@@ -8,7 +9,7 @@ export interface RunSearch {
     limit?: number;
     page?: number;
 }
-export declare const searchRuns: (dir: string, { query, status, errorCode, operation, profile, since, limit, page }?: RunSearch) => {
+export declare const searchRuns: (dir: string, { query, terms, status, errorCode, operation, profile, since, limit, page }?: RunSearch) => {
     items: {
         runId: string;
         command: string;

package/dist/cli/runs/search.js

@@ -32,14 +32,14 @@ const safeEvent = (event) => Object.fromEntries(FIELDS.flatMap((name) => {
     }
     return typeof value === "string" || typeof value === "number" ? [[name, value]] : [];
 }));
-export const searchRuns = (dir, { query = "", status, errorCode, operation, profile, since, limit = 20, page = 1 } = {}) => {
+export const searchRuns = (dir, { query = "", terms = [], status, errorCode, operation, profile, since, 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 from = window.since;
     if (from !== undefined && !Number.isFinite(from))
         throw new CliError("validation_error", "--since-time must be a valid date or ISO timestamp");
-    const needle = query.toLowerCase();
+    const needles = [...(query ? [query] : []), ...terms].map((term) => term.toLowerCase());
     const offset = (page - 1) * limit;
     const matches = [];
     for (const run of listRuns(dir, from === undefined ? {} : { since: from })) {
@@ -51,11 +51,11 @@ export const searchRuns = (dir, { query = "", status, errorCode, operation, prof
             run.errorCode === errorCode ||
             run.partial?.failures.some((failure) => failure.errorCode === errorCode)) &&
             !operation &&
-            (!needle || JSON.stringify(run).toLowerCase().includes(needle));
+            needles.every((needle) => JSON.stringify(run).toLowerCase().includes(needle));
         // A finished run lists its operations and codes, so a run that cannot match is never opened.
         // One still running, or killed, has no such list and is read.
         const ruledOut = !metadataMatch &&
-            !needle &&
+            needles.length === 0 &&
             ((operation !== undefined && run.operations !== undefined && !run.operations.includes(operation)) ||
                 (errorCode !== undefined && run.codes !== undefined && !run.codes.includes(errorCode)));
         if (ruledOut)
@@ -64,7 +64,7 @@ export const searchRuns = (dir, { query = "", status, errorCode, operation, prof
         const events = found ? readEvents(found.dir).map(safeEvent) : [];
         const filtered = events.filter((event) => (!errorCode || event.error_code === errorCode || event.code === errorCode) &&
             (!operation || event.operation === operation) &&
-            (!needle || JSON.stringify(event).toLowerCase().includes(needle)));
+            needles.every((needle) => JSON.stringify(event).toLowerCase().includes(needle)));
         if (!metadataMatch && filtered.length === 0)
             continue;
         const metadata = {
@@ -110,7 +110,7 @@ export const searchRuns = (dir, { query = "", status, errorCode, operation, prof
     };
 };
 /** A page of `searchRuns` in the list envelope; `args` are the search's own, so `page.next` reruns it. */
-export const runsFound = (found, args) => listOf("runs search", {
+export const runsFound = (found, args) => listOf("search runs", {
     items: found.items.map(snakeKeys),
     limit: found.limit,
     has_more: found.hasMore,

package/dist/documents/index.d.ts

@@ -3,6 +3,7 @@ export { type Complete, extractMemories } from "../services/documents/extraction
 export { documentIngestion, type IngestionOptions } from "../services/documents/ingestion.js";
 export { type DocumentKnowledge, documentKnowledge } from "../services/documents/knowledge.js";
 export { blocksMarkdown, inlineMarkdown, spliceMarkdown } from "../services/documents/markdown-splice.js";
+export { conflictReport, fileMirrorState, type Mirror, type MirrorSyncOptions, mirrorId, mirrorStatus, syncMirrors, } from "../services/documents/mirrors.js";
 export type { SyncOptions } from "../services/documents/ports.js";
 export { extractDocumentMemories, type ImportedSource, type ProposalOptions } from "../services/documents/proposals.js";
 export { type PushConflict, type PushOptions, type PushResult, planPush, pushDocuments, scanLocal, } from "../services/documents/push.js";

package/dist/documents/index.js

@@ -3,6 +3,7 @@ export { extractMemories } from "../services/documents/extraction.js";
 export { documentIngestion } from "../services/documents/ingestion.js";
 export { documentKnowledge } from "../services/documents/knowledge.js";
 export { blocksMarkdown, inlineMarkdown, spliceMarkdown } from "../services/documents/markdown-splice.js";
+export { conflictReport, fileMirrorState, mirrorId, mirrorStatus, syncMirrors, } from "../services/documents/mirrors.js";
 export { extractDocumentMemories } from "../services/documents/proposals.js";
 export { planPush, pushDocuments, scanLocal, } from "../services/documents/push.js";
 export { syncDocuments } from "../services/documents/sync.js";

package/dist/domain/attachments.js

@@ -1,5 +1,13 @@
 /** Attachments that are never a file, so their messages cost no download request. */
-export const NOT_FILES = new Set(["webpage", "share", "poll", "location", "contact"]);
+export const NOT_FILES = new Set([
+    "webpage",
+    "share",
+    "poll",
+    "location",
+    "contact",
+    "control",
+    "inline_keyboard",
+]);
 /** 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/rankings-options.js

@@ -33,11 +33,11 @@ export const rankingOptions = (target, input) => {
     const { measure, score, weights: given, minMessages } = input;
     const messageKind = input.messageKind ?? "all";
     if (!["all", "posts", "comments"].includes(messageKind))
-        invalid("--message-kind takes all, posts or comments");
+        invalid("message_kind takes all, posts or comments");
     if (target === "messages" && minMessages !== undefined)
-        invalid("--min-messages applies to stats contacts top");
+        invalid("min_messages applies to stats contacts top");
     if (minMessages !== undefined && (!Number.isSafeInteger(minMessages) || minMessages < 1))
-        invalid("--min-messages takes a positive integer");
+        invalid("min_messages takes a positive integer");
     if (measure !== undefined && !measures.includes(measure))
         invalid(`--measure takes ${measures.join(", ")}`);
     if (measure !== undefined && (score !== undefined || given !== undefined))

package/dist/entities/account-change.d.ts

@@ -0,0 +1,89 @@
+import * as v from "valibot";
+export declare const accountChange: v.StrictObjectSchema<{
+    readonly operation_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly account: Omit<v.StrictObjectSchema<{
+        readonly provider: v.StringSchema<undefined>;
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly username: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly phone: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly scope: v.OptionalSchema<v.PicklistSchema<["personal", "work"], undefined>, undefined>;
+    }, undefined>, "entries" | "~run" | "~standard" | "~types"> & {
+        readonly entries: Omit<{
+            readonly provider: v.StringSchema<undefined>;
+            readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly username: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly phone: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly scope: v.OptionalSchema<v.PicklistSchema<["personal", "work"], undefined>, undefined>;
+        }, "provider" | "scope">;
+        readonly "~standard": v.StandardProps<{
+            id: string;
+            name: string | null;
+            username: string | null;
+            phone?: string | null | undefined;
+        }, {
+            id: string;
+            name: string | null;
+            username: string | null;
+            phone?: string | null | undefined;
+        }>;
+        readonly "~run": (dataset: v.UnknownDataset, config: v.Config<v.BaseIssue<unknown>>) => v.OutputDataset<{
+            id: string;
+            name: string | null;
+            username: string | null;
+            phone?: string | null | undefined;
+        }, v.MinLengthIssue<string, 1> | v.StrictObjectIssue | v.StringIssue>;
+        readonly "~types"?: {
+            readonly input: {
+                id: string;
+                name: string | null;
+                username: string | null;
+                phone?: string | null | undefined;
+            };
+            readonly output: {
+                id: string;
+                name: string | null;
+                username: string | null;
+                phone?: string | null | undefined;
+            };
+            readonly issue: v.MinLengthIssue<string, 1> | v.StrictObjectIssue | v.StringIssue;
+        } | undefined;
+    };
+}, undefined>;
+export declare const endedAccountSessions: v.StrictObjectSchema<{
+    readonly operation_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly sessions: v.ArraySchema<v.StrictObjectSchema<{
+        readonly current: v.BooleanSchema<undefined>;
+        readonly client: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly device: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly location: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly last_active_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly created_at: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export declare const accountPrivacy: v.StrictObjectSchema<{
+    readonly find_by_phone: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+    readonly phone_number: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+    readonly calls: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+    readonly chat_invites: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+    readonly hide_online: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    readonly read_receipts: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    readonly profile_photo: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody", "contacts_except"], undefined>, undefined>;
+    readonly about: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody", "contacts_except"], undefined>, undefined>;
+    readonly last_seen: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody", "contacts_except"], undefined>, undefined>;
+}, undefined>;
+export declare const accountPrivacyChange: v.StrictObjectSchema<{
+    readonly operation_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly privacy: v.StrictObjectSchema<{
+        readonly find_by_phone: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+        readonly phone_number: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+        readonly calls: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+        readonly chat_invites: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody"], undefined>, undefined>;
+        readonly hide_online: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly read_receipts: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly profile_photo: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody", "contacts_except"], undefined>, undefined>;
+        readonly about: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody", "contacts_except"], undefined>, undefined>;
+        readonly last_seen: v.OptionalSchema<v.PicklistSchema<["everyone", "contacts", "nobody", "contacts_except"], undefined>, undefined>;
+    }, undefined>;
+}, undefined>;

package/dist/entities/account-change.js

@@ -0,0 +1,20 @@
+import * as v from "valibot";
+import { account } from "./account.js";
+import { accountSession } from "./account-session.js";
+import { id } from "./fields.js";
+export const accountChange = v.strictObject({ operation_id: id, account: v.omit(account, ["provider", "scope"]) });
+export const endedAccountSessions = v.strictObject({ operation_id: id, sessions: v.array(accountSession) });
+const audience = v.picklist(["everyone", "contacts", "nobody"]);
+const shownAudience = v.picklist(["everyone", "contacts", "nobody", "contacts_except"]);
+export const accountPrivacy = v.strictObject({
+    find_by_phone: v.optional(audience),
+    phone_number: v.optional(audience),
+    calls: v.optional(audience),
+    chat_invites: v.optional(audience),
+    hide_online: v.optional(v.boolean()),
+    read_receipts: v.optional(v.boolean()),
+    profile_photo: v.optional(shownAudience),
+    about: v.optional(shownAudience),
+    last_seen: v.optional(shownAudience),
+});
+export const accountPrivacyChange = v.strictObject({ operation_id: id, privacy: accountPrivacy });

package/dist/entities/account-profile.d.ts

@@ -0,0 +1,7 @@
+import * as v from "valibot";
+export declare const accountProfile: v.StrictObjectSchema<{
+    readonly profile: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly current: v.BooleanSchema<undefined>;
+    readonly account: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;

package/dist/entities/account-profile.js

@@ -0,0 +1,8 @@
+import * as v from "valibot";
+import { id, text } from "./fields.js";
+export const accountProfile = v.strictObject({
+    profile: id,
+    current: v.boolean(),
+    account: v.nullable(id),
+    name: v.nullable(text),
+});

package/dist/entities/analysis-consent.d.ts

@@ -0,0 +1,9 @@
+import * as v from "valibot";
+export declare const analysisConsent: v.StrictObjectSchema<{
+    readonly chat: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly provider: v.StringSchema<undefined>;
+    readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+}, undefined>;
+export declare const analysisConsentRevocation: v.StrictObjectSchema<{
+    readonly revoked: v.BooleanSchema<undefined>;
+}, undefined>;

package/dist/entities/analysis-consent.js

@@ -0,0 +1,4 @@
+import * as v from "valibot";
+import { id, text, time } from "./fields.js";
+export const analysisConsent = v.strictObject({ chat: id, provider: text, at: time });
+export const analysisConsentRevocation = v.strictObject({ revoked: v.boolean() });

package/dist/entities/attachment-results.d.ts

@@ -0,0 +1,96 @@
+import * as v from "valibot";
+/** Resource/image MCP responses put bytes in a separate content block; CLI JSON carries base64 here. */
+export declare const attachmentBytes: v.StrictObjectSchema<{
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly attachment: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly mime_type: v.StringSchema<undefined>;
+    readonly total_bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly sha256: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+    readonly offset_bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly read_bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly next_offset_bytes: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly complete: v.BooleanSchema<undefined>;
+    readonly base64: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly pdf: v.OptionalSchema<v.StrictObjectSchema<{
+        readonly page: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly page_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly source_sha256: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+        readonly source_bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>;
+}, undefined>;
+/** JSON reports all files and totals; JSONL streams each extraction item. */
+export declare const attachmentExtraction: v.UnionSchema<[v.StrictObjectSchema<{
+    readonly extracted: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly failed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly needs_agent: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly complete: v.BooleanSchema<undefined>;
+    readonly batch: v.OptionalSchema<v.StrictObjectSchema<{
+        readonly attempted: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly succeeded: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly failed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly error_rate: v.NumberSchema<undefined>;
+        readonly failures: v.ArraySchema<v.StrictObjectSchema<{
+            readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly stage: v.StringSchema<undefined>;
+            readonly error: v.ObjectWithRestSchema<{
+                readonly code: v.StringSchema<undefined>;
+                readonly message: v.StringSchema<undefined>;
+                readonly retryable: v.BooleanSchema<undefined>;
+                readonly retry_after_ms: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            }, v.UnknownSchema, undefined>;
+            readonly attachment: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        }, undefined>, undefined>;
+        readonly stop_reason: v.OptionalSchema<v.PicklistSchema<["rate_limited", "authentication", "error_rate", "cancelled"], undefined>, undefined>;
+        readonly max_error_percent: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>;
+    readonly unchanged: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly not_downloaded: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly unsupported: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly engines_missing: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly cursor: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly files: v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly attachment: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly status: v.PicklistSchema<["extracted", "needs-agent", "unreadable", "engine-missing", "too-large", "missing"], undefined>;
+        readonly extractor: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly chars: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly local_path: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly pages: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly ocr_pages: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly error: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly issue: v.OptionalSchema<v.ObjectWithRestSchema<{
+            readonly code: v.StringSchema<undefined>;
+            readonly message: v.StringSchema<undefined>;
+            readonly retryable: v.BooleanSchema<undefined>;
+            readonly retry_after_ms: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        }, v.UnknownSchema, undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>, v.StrictObjectSchema<{
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly attachment: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly kind: v.StringSchema<undefined>;
+    readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly status: v.PicklistSchema<["extracted", "needs-agent", "unreadable", "engine-missing", "too-large", "missing"], undefined>;
+    readonly extractor: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly chars: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly local_path: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly pages: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly ocr_pages: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly error: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly issue: v.OptionalSchema<v.ObjectWithRestSchema<{
+        readonly code: v.StringSchema<undefined>;
+        readonly message: v.StringSchema<undefined>;
+        readonly retryable: v.BooleanSchema<undefined>;
+        readonly retry_after_ms: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+    }, v.UnknownSchema, undefined>, undefined>;
+}, undefined>], undefined>;
+export declare const attachmentTextChange: v.StrictObjectSchema<{
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly attachment: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly origin: v.LiteralSchema<"agent", undefined>;
+    readonly chars: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly replaced: v.NullableSchema<v.PicklistSchema<["extracted", "agent"], undefined>, undefined>;
+}, undefined>;

package/dist/entities/attachment-results.js

@@ -0,0 +1,31 @@
+import * as v from "valibot";
+import { extractionItem, extractionReport } from "./extraction-report.js";
+import { count, reference, text } from "./fields.js";
+const fingerprint = v.pipe(text, v.regex(/^[a-f0-9]{64}$/));
+/** Resource/image MCP responses put bytes in a separate content block; CLI JSON carries base64 here. */
+export const attachmentBytes = v.strictObject({
+    ref: reference,
+    attachment: count,
+    name: v.nullable(text),
+    mime_type: text,
+    total_bytes: count,
+    sha256: fingerprint,
+    offset_bytes: count,
+    read_bytes: count,
+    next_offset_bytes: v.nullable(count),
+    complete: v.boolean(),
+    base64: v.optional(text),
+    pdf: v.optional(v.strictObject({ page: count, page_count: count, source_sha256: fingerprint, source_bytes: count })),
+});
+/** JSON reports all files and totals; JSONL streams each extraction item. */
+export const attachmentExtraction = v.union([
+    v.strictObject({ ...v.omit(extractionReport, ["items"]).entries, files: v.array(extractionItem) }),
+    extractionItem,
+]);
+export const attachmentTextChange = v.strictObject({
+    ref: reference,
+    attachment: count,
+    origin: v.literal("agent"),
+    chars: count,
+    replaced: v.nullable(v.picklist(["extracted", "agent"])),
+});

package/dist/entities/batch-result.d.ts

@@ -0,0 +1,27 @@
+import * as v from "valibot";
+/** Per-item recovery retains the diagnostic fields the provider supplied. */
+export declare const actionableError: v.ObjectWithRestSchema<{
+    readonly code: v.StringSchema<undefined>;
+    readonly message: v.StringSchema<undefined>;
+    readonly retryable: v.BooleanSchema<undefined>;
+    readonly retry_after_ms: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+}, v.UnknownSchema, undefined>;
+export declare const batchResult: v.StrictObjectSchema<{
+    readonly attempted: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly succeeded: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly failed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly error_rate: v.NumberSchema<undefined>;
+    readonly failures: v.ArraySchema<v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly stage: v.StringSchema<undefined>;
+        readonly error: v.ObjectWithRestSchema<{
+            readonly code: v.StringSchema<undefined>;
+            readonly message: v.StringSchema<undefined>;
+            readonly retryable: v.BooleanSchema<undefined>;
+            readonly retry_after_ms: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        }, v.UnknownSchema, undefined>;
+        readonly attachment: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    }, undefined>, undefined>;
+    readonly stop_reason: v.OptionalSchema<v.PicklistSchema<["rate_limited", "authentication", "error_rate", "cancelled"], undefined>, undefined>;
+    readonly max_error_percent: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;

package/dist/entities/batch-result.js

@@ -0,0 +1,18 @@
+import * as v from "valibot";
+import { count, id, text } from "./fields.js";
+/** Per-item recovery retains the diagnostic fields the provider supplied. */
+export const actionableError = v.objectWithRest({
+    code: text,
+    message: text,
+    retryable: v.boolean(),
+    retry_after_ms: v.optional(v.number()),
+}, v.unknown());
+export const batchResult = v.strictObject({
+    attempted: count,
+    succeeded: count,
+    failed: count,
+    error_rate: v.number(),
+    failures: v.array(v.strictObject({ id, stage: text, error: actionableError, attachment: v.optional(count) })),
+    stop_reason: v.optional(v.picklist(["rate_limited", "authentication", "error_rate", "cancelled"])),
+    max_error_percent: count,
+});