@wirecat/max-cli 0.0.0 → 0.42.0

package/dist/spec/operations/session.js

@@ -0,0 +1,202 @@
+import * as v from "valibot";
+import { defineOperation } from "../define.js";
+import { id } from "../scalars.js";
+/**
+ * What we claim to be, as a shape rather than a constant.
+ *
+ * Declaring it strictly is the point: every field here is one the official web client sends
+ * (`REQUIREMENTS.md` §34), and a field we invented would be refused before it reached the socket.
+ */
+const WebUserAgent = v.strictObject({
+    deviceType: v.literal("WEB"),
+    pushDeviceType: v.literal("WEBPUSH"),
+    locale: v.string(),
+    deviceLocale: v.string(),
+    osVersion: v.string(),
+    deviceName: v.string(),
+    headerUserAgent: v.string(),
+    isPwa: v.literal(false),
+    appVersion: v.string(),
+    screen: v.string(),
+    timezone: v.string(),
+});
+/**
+ * **The keep-alive, which only `max serve` sends** — a one-shot command is gone long before it
+ * would matter. `interactive` is whether the tab is visible; ours is never, as LOGIN's is.
+ */
+export const sessionPing = defineOperation({
+    name: "session.ping",
+    constant: "PING",
+    opcode: 1,
+    auth: true,
+    request: v.strictObject({ interactive: v.boolean() }),
+    response: v.looseObject({}),
+    guard: null,
+    provenance: {
+        confidence: "confirmed",
+        sources: ["web.max.ru bundle read 2026-09-24: `cmd(1, {interactive})` every 30 s", "PyMax Opcode.PING = 1"],
+        notes: "MAX pings too; `Connection` answers those itself when it is live.",
+    },
+});
+/**
+ * **Telemetry, and only the one event a hidden web tab sends** (`MAX-8`): the chat list shown,
+ * 20 s after the tab opened. A one-shot command never sends it — a hidden tab closed that soon
+ * sends nothing either. Why exactly this and nothing more: `docs/dev/capture/requirements.md`.
+ *
+ * The request is strict and literal on purpose: anything beyond this one event claims a person in
+ * front of a visible tab, which is a different decision.
+ */
+export const sessionLog = defineOperation({
+    name: "session.log",
+    constant: "LOG",
+    opcode: 5,
+    auth: true,
+    request: v.strictObject({
+        events: v.array(v.strictObject({
+            type: v.literal("NAV"),
+            userId: id(),
+            time: v.number(),
+            sessionId: v.number(),
+            event: v.literal("GO"),
+            params: v.strictObject({
+                action_id: v.literal(1),
+                screen_to: v.literal(150),
+                prev_time: v.literal(0),
+                source_id: id(),
+            }),
+        })),
+    }),
+    response: v.looseObject({}),
+    guard: null,
+    provenance: {
+        confidence: "observed",
+        sources: [
+            "web.max.ru frames captured 2026-09-25 (docs/dev/capture/2026-09-25-web-tab.md): a hidden tab's only event, answered with an empty body",
+            "ids wrapped in extension 1 and times plain: inferred from the frame's unpacked size, 144 bytes, which only that encoding gives",
+        ],
+    },
+});
+export const sessionInit = defineOperation({
+    name: "session.init",
+    constant: "SESSION_INIT",
+    opcode: 6,
+    auth: false,
+    request: v.strictObject({ userAgent: WebUserAgent, deviceId: v.string() }),
+    response: v.looseObject({}),
+    guard: null,
+    provenance: {
+        confidence: "measured",
+        sources: ["measured against MAX 2026-09-19", "max-api-docs/protocol/auth.md", "tsmax createWebAgent"],
+        notes: "MAX answers nothing before this and LOGIN, in that order.",
+    },
+});
+export const sessionLogin = defineOperation({
+    name: "session.login",
+    constant: "LOGIN",
+    opcode: 19,
+    auth: false,
+    request: v.strictObject({
+        token: v.string(),
+        // 100 works and 200 comes back `'chatsCount' out of range`; refusing locally beats a round
+        // trip that only tells us what we already know. The real boundary is `PROTO-3`.
+        chatsCount: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100)),
+        /**
+         * False, always: we are a script reading, and claiming a human is present is the small lie that
+         * becomes a side effect nobody can trace (`RES-5`). **Correction 2026-09-25:** this said the web
+         * client sends true; its LOGIN on a live socket sent `false` too — `true` goes in its pings.
+         */
+        interactive: v.literal(false),
+        /**
+         * **Delta markers, not flags** — measured 2026-09-20. Each is a moment in time, and MAX
+         * returns only what changed in that collection since it. `0` means "everything", which is what
+         * `src/session/handshake.ts` sends and is why every command re-fetches the whole list — except
+         * a `max serve` re-login, which sends its newest chat event in `chatsSync` (`MAX-51`).
+         *
+         * The measurement, on a real account: `0` returned 6 contacts and 25 chats; the `time` the
+         * previous login answered with returned 0 and 0; a week earlier returned 1 and 11. The last of
+         * those is the one that matters — without it, "nothing came back" would equally have meant
+         * "any non-zero value suppresses the collection".
+         *
+         * Feeding them back is `MAX-10`, and it needs somewhere to keep the marker per profile.
+         */
+        chatsSync: v.number(),
+        contactsSync: v.number(),
+        presenceSync: v.number(),
+        draftsSync: v.number(),
+        /** Only when the same connection's owner logs in again — `resume` in `src/session/handshake.ts` (`MAX-51`). */
+        lastLogin: v.optional(v.number()),
+        configHash: v.optional(v.string()),
+    }),
+    response: v.looseObject({
+        profile: v.optional(v.looseObject({})),
+        chats: v.optional(v.array(v.looseObject({}))),
+        contacts: v.optional(v.array(v.looseObject({}))),
+        /**
+         * ⚠ **Shape unknown, and this field is why the response check exists.**
+         *
+         * It was declared as an array here and MAX sends an **object** — found 2026-09-20 by routing
+         * the handshake through the checked path. Nothing broke, because the reader is tolerant; what
+         * happened instead is that every message the login carries has been silently discarded since
+         * the specification was written, after we paid a request for them.
+         *
+         * The reference documents no top-level `messages` on this response at all — each chat carries
+         * its own `lastMessage` (`max-api-docs/protocol/chats.md:61`). So the array was **invented**,
+         * not misread, which is the failure `REQUIREMENTS.md` §10 exists to prevent: an unsourced
+         * shape stated with the same confidence as a measured one.
+         *
+         * Left as `unknown` until somebody looks (`PROTO-6`). `pnpm probe:ids` reports its type and key count.
+         */
+        messages: v.optional(v.unknown()),
+        /**
+         * **A replacement for a credential that has aged** — measured on the real account 2026-09-22
+         * (`pnpm probe:token`). Logging in with a token pasted months earlier answers with a different
+         * one; logging in with *that* one answers with the same one back. So it is an exchange that
+         * happens once, not a rotation on every login.
+         *
+         * It was undeclared until then, so the exchange happened on every login and the client threw
+         * the result away, leaving the profile on whatever was pasted in months ago (`MAX-11`,
+         * `NEED-106`). The old token goes on working, which is why this is hygiene rather than repair.
+         * `NEED-8` had asserted the rotation in 2026-09-18 on the strength of `tsmax/src/app.ts:99` —
+         * somebody else's client — which is a claim; this is the measurement.
+         *
+         * ⚠ **It is a credential.** Nothing may print it, log it or put it in a fixture. `MaxClient`
+         * writes it to the keyring and never returns it.
+         */
+        token: v.optional(v.string()),
+        presence: v.optional(v.unknown()),
+        time: v.optional(v.number()),
+        chatMarker: v.optional(v.unknown()),
+        config: v.optional(v.unknown()),
+        videoChatHistory: v.optional(v.unknown()),
+    }),
+    guard: null,
+    provenance: {
+        confidence: "measured",
+        sources: [
+            "measured against MAX 2026-09-19",
+            "measured against MAX 2026-09-20 (`messages` is an object)",
+            "measured against MAX 2026-09-22 (`token` replaces a stale credential once, then repeats)",
+        ],
+        notes: "Unusually generous: the answer carries the profile, chats, contacts and recent messages, so `me` and `chats` need no further request.",
+    },
+});
+export const sessionLogout = defineOperation({
+    name: "session.logout",
+    constant: "LOGOUT",
+    opcode: 20,
+    auth: true,
+    /** The web client adds its push subscription's `pushToken`; a session without one has nothing to add. */
+    request: v.strictObject({}),
+    response: v.looseObject({}),
+    // Ends this session and nobody else's — though a token copied from a browser tab is that tab's session.
+    guard: null,
+    provenance: {
+        confidence: "confirmed",
+        sources: [
+            "web.max.ru chunk `_app/immutable/chunks/Cdo8IOYe.js`, read 2026-10-08: `send(20, {pushToken})`",
+            "PyMax 53103f0 `logout` and rumax a9ecaf3 `logout`: `{}`",
+            "max-api-docs/protocol/auth.md",
+        ],
+    },
+});
+//# sourceMappingURL=session.js.map

package/dist/spec/operations/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/spec/operations/session.ts"],"names":[],"mappings":"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"}

package/dist/spec/operations/uploads.d.ts

@@ -0,0 +1,31 @@
+import * as v from "valibot";
+export declare const uploadsPhoto: import("../define.js").Operation<v.StrictObjectSchema<{
+    readonly count: v.LiteralSchema<1, undefined>;
+    readonly type: v.LiteralSchema<0, undefined>;
+    readonly uploaderType: v.LiteralSchema<0, undefined>;
+    readonly profile: v.BooleanSchema<undefined>;
+}, undefined>, v.LooseObjectSchema<{
+    readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>>;
+export declare const uploadsFile: import("../define.js").Operation<v.StrictObjectSchema<{
+    readonly count: v.LiteralSchema<1, undefined>;
+    readonly type: v.LiteralSchema<0, undefined>;
+    readonly uploaderType: v.LiteralSchema<0, undefined>;
+    readonly profile: v.LiteralSchema<false, undefined>;
+}, undefined>, v.LooseObjectSchema<{
+    readonly info: v.OptionalSchema<v.ArraySchema<v.LooseObjectSchema<{}, undefined>, undefined>, undefined>;
+}, undefined>>;
+export declare const uploadsVideo: import("../define.js").Operation<v.UnionSchema<[v.StrictObjectSchema<{
+    readonly count: v.LiteralSchema<1, undefined>;
+    readonly type: v.LiteralSchema<0, undefined>;
+    readonly uploaderType: v.LiteralSchema<0, undefined>;
+    readonly profile: v.LiteralSchema<false, undefined>;
+}, undefined>, v.StrictObjectSchema<{
+    readonly count: v.LiteralSchema<1, undefined>;
+    readonly type: v.LiteralSchema<2, undefined>;
+    readonly uploaderType: v.LiteralSchema<1, undefined>;
+    readonly profile: v.LiteralSchema<false, undefined>;
+}, undefined>], undefined>, v.LooseObjectSchema<{
+    readonly info: v.OptionalSchema<v.ArraySchema<v.LooseObjectSchema<{}, undefined>, undefined>, undefined>;
+}, undefined>>;
+//# sourceMappingURL=uploads.d.ts.map

package/dist/spec/operations/uploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../../src/spec/operations/uploads.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAU5B,eAAO,MAAM,YAAY;;;;;;;cAevB,CAAA;AAEF,eAAO,MAAM,WAAW;;;;;;;cActB,CAAA;AAEF,eAAO,MAAM,YAAY;;;;;;;;;;;;cAqBvB,CAAA"}

package/dist/spec/operations/uploads.js

@@ -0,0 +1,59 @@
+import * as v from "valibot";
+import { defineOperation } from "../define.js";
+const uploadRequest = v.strictObject({
+    count: v.literal(1),
+    type: v.literal(0),
+    uploaderType: v.literal(0),
+    profile: v.literal(false),
+});
+export const uploadsPhoto = defineOperation({
+    name: "uploads.photo",
+    constant: "PHOTO_UPLOAD",
+    opcode: 80,
+    auth: true,
+    /** `profile: true` for a profile photo (2026-09-27, `pnpm probe:profile`). */
+    request: v.strictObject({ ...uploadRequest.entries, profile: v.boolean() }),
+    response: v.looseObject({ url: v.optional(v.string()) }),
+    guard: null,
+    provenance: {
+        confidence: "measured",
+        sources: ["measured against MAX 2026-09-24 in Saved messages (`pnpm probe:upload`)", "PyMax upload_photo"],
+        notes: 'Answers `{url}`. A multipart POST of the image, field `file`, answers `{photos: {<key>: {token}}}`; the message attaches `{_type: "PHOTO", photoToken}`.',
+    },
+});
+export const uploadsFile = defineOperation({
+    name: "uploads.file",
+    constant: "FILE_UPLOAD",
+    opcode: 87,
+    auth: true,
+    request: uploadRequest,
+    response: v.looseObject({ info: v.optional(v.array(v.looseObject({}))) }),
+    guard: null,
+    provenance: {
+        confidence: "measured",
+        sources: ["measured against MAX 2026-09-24 in Saved messages (`pnpm probe:upload`)", "PyMax upload_file"],
+        notes: 'Answers `{info: [{url, fileId, token}]}`. The bytes are POSTed raw with `Content-Range: 0-<end>/<size>`; MAX then pushes 136 `{fileId}`, and a send before that is refused `attachment.not.ready`. The message attaches `{_type: "FILE", fileId}`.',
+    },
+});
+export const uploadsVideo = defineOperation({
+    name: "uploads.video",
+    constant: "VIDEO_UPLOAD",
+    opcode: 82,
+    auth: true,
+    request: v.union([
+        v.strictObject({ count: v.literal(1), type: v.literal(0), uploaderType: v.literal(0), profile: v.literal(false) }),
+        v.strictObject({ count: v.literal(1), type: v.literal(2), uploaderType: v.literal(1), profile: v.literal(false) }),
+    ]),
+    response: v.looseObject({ info: v.optional(v.array(v.looseObject({}))) }),
+    guard: null,
+    provenance: {
+        confidence: "measured",
+        sources: [
+            "measured against MAX 2026-09-27 in Saved messages (`pnpm probe:video`, `pnpm probe:voice`)",
+            "PyMax 2.4.1 upload_video",
+            "web.max.ru bundle (voice)",
+        ],
+        notes: 'Answers `{info: [{url, videoId, token}]}`. `type: 0` is a video; `type: 2, uploaderType: 1` an Ogg Opus voice message. The bytes are POSTed raw with `Content-Range: bytes 0-<end>/<size>`; a send straight after the upload was accepted, before push 136 `{videoId}`. A video attaches `{_type: "VIDEO", videoId, token, videoType: 0}`, a voice message `{_type: "AUDIO", audioId: <videoId>, duration, wave, token}` — `duration` in ms, `wave` 80 bytes of 0–127.',
+    },
+});
+//# sourceMappingURL=uploads.js.map

package/dist/spec/operations/uploads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.js","sourceRoot":"","sources":["../../../src/spec/operations/uploads.ts"],"names":[],"mappings":"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"}

package/dist/spec/scalars.d.ts

@@ -0,0 +1,17 @@
+import * as v from "valibot";
+/** `BigInt` also reads `0x1f`, `0b1` and `" 7 "` — each a different message than the one typed. */
+export declare const toWireId: (value: string) => bigint;
+/**
+ * An id in a request we build: a domain string in, the wire form out.
+ *
+ * The schema is the encoder as well as the check, so there is no second place where a conversion
+ * could be forgotten — `v.parse(request, { chatId: "0" })` yields `{ chatId: 0n }`.
+ */
+export declare const id: () => v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an id is a whole number written as a string">, v.TransformAction<string, bigint>]>;
+/**
+ * An id in an answer we read. **Not the same as `id()` and not a transform**: a response schema
+ * reports, it does not convert (§4.6 of the plan), and the conversion to our own string form is
+ * the domain mapper's job.
+ */
+export declare const wireId: () => v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BigintSchema<undefined>], undefined>;
+//# sourceMappingURL=scalars.d.ts.map

package/dist/spec/scalars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalars.d.ts","sourceRoot":"","sources":["../../src/spec/scalars.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAgB5B,mGAAmG;AACnG,eAAO,MAAM,QAAQ,UAAW,MAAM,KAAG,MAGxC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,EAAE,uKACkG,CAAA;AAEjH;;;;GAIG;AACH,eAAO,MAAM,MAAM,mHAAsD,CAAA"}

package/dist/spec/scalars.js

@@ -0,0 +1,33 @@
+import * as v from "valibot";
+/**
+ * The two directions an id travels, and why they are not the same schema.
+ *
+ * MAX ids are 64-bit. `asId` in `../protocol/frame.ts` is the read direction: whatever arrived —
+ * a number when small, a bigint when not — leaves as a string, because an id is an identifier and
+ * never arithmetic. The write direction did not exist, and `Number(id)` was standing in for it:
+ * `Number("7268926000000000001")` is `7268926000000000000`, which is a different chat.
+ *
+ * The frame codec sends a `bigint` as a 64-bit integer wrapped in MessagePack extension 1, the way
+ * web.max.ru sends an id, so every digit reaches MAX (`src/protocol/frame.ts`).
+ */
+const WHOLE_NUMBER = /^-?\d+$/;
+/** `BigInt` also reads `0x1f`, `0b1` and `" 7 "` — each a different message than the one typed. */
+export const toWireId = (value) => {
+    if (!WHOLE_NUMBER.test(value))
+        throw new TypeError("an id is a whole number written as a string");
+    return BigInt(value);
+};
+/**
+ * An id in a request we build: a domain string in, the wire form out.
+ *
+ * The schema is the encoder as well as the check, so there is no second place where a conversion
+ * could be forgotten — `v.parse(request, { chatId: "0" })` yields `{ chatId: 0n }`.
+ */
+export const id = () => v.pipe(v.string(), v.regex(WHOLE_NUMBER, "an id is a whole number written as a string"), v.transform(toWireId));
+/**
+ * An id in an answer we read. **Not the same as `id()` and not a transform**: a response schema
+ * reports, it does not convert (§4.6 of the plan), and the conversion to our own string form is
+ * the domain mapper's job.
+ */
+export const wireId = () => v.union([v.string(), v.number(), v.bigint()]);
+//# sourceMappingURL=scalars.js.map

package/dist/spec/scalars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalars.js","sourceRoot":"","sources":["../../src/spec/scalars.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;GAUG;AAEH,MAAM,YAAY,GAAG,SAAS,CAAA;AAE9B,mGAAmG;AACnG,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAU,EAAE;IAChD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAA;IACjG,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,EAAE,CACrB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,6CAA6C,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;AAEjH;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA"}

package/dist/transcribe/index.d.ts

@@ -0,0 +1,70 @@
+import { CliError } from "@wirecat/cli-core";
+import type { MaxClient } from "../client.js";
+import type { AttachmentLink, Id, Message } from "../domain/models.js";
+import type { MaxRecord } from "../record.js";
+import { type SpeechModel } from "./models.js";
+import { type Recognizer } from "./speech.js";
+export interface Transcript {
+    chatId: Id;
+    messageId: Id;
+    text: string;
+    model: string;
+    /** Length of the recording; `null` when the text came from the cache. */
+    seconds: number | null;
+    cached: boolean;
+}
+export interface TranscribeOptions {
+    model: SpeechModel;
+    directory: string;
+    record?: Pick<MaxRecord, "transcript" | "keepTranscript"> | undefined;
+    /** Called once the audio is in hand, so the connection closes before the long part begins. */
+    release?: () => Promise<void>;
+    fetchAudio?: (link: AttachmentLink) => Promise<Uint8Array>;
+    open?: (model: SpeechModel, directory: string) => Recognizer;
+}
+export declare const notDownloaded: (model: SpeechModel) => CliError;
+export declare const openInstalled: (model: SpeechModel, directory: string) => Recognizer;
+/**
+ * One voice message to text, on this machine. A text already heard by the same model comes from
+ * the shared store, with no connection and no model loaded.
+ *
+ * ⚠ **The model is never downloaded from here** (`NEED-231`): an agent calling this through MCP must
+ * not start a 230–670 MB download. The refusal names the command that does it.
+ */
+export declare const transcribe: (client: MaxClient, chatId: Id, messageId: Id, { model, directory, record, release, fetchAudio, open }: TranscribeOptions) => Promise<Transcript>;
+export interface Voice {
+    chatId: Id;
+    messageId: Id;
+}
+export declare const voiceKey: ({ chatId, messageId }: Voice) => string;
+export interface Heard {
+    /** By `voiceKey`: the text of every voice message heard now or kept from before. */
+    transcripts: Map<string, string>;
+    unheard: Voice[];
+    /** Why some were not heard — the first reason; the messages are still worth showing. */
+    problem?: string;
+}
+export interface HearAllOptions extends Omit<TranscribeOptions, "model"> {
+    /** Without one, only texts already kept are used. */
+    model?: SpeechModel | undefined;
+    /** Told how many are about to be heard, just before the long part. */
+    progress?: (count: number) => void;
+}
+/**
+ * Many voice messages at once — a page, an inbox, a review. Kept texts first, whichever model heard
+ * them. Then every recording still needed is fetched **before** the connection is released and the
+ * model runs: recognition is synchronous for up to a minute each, and a socket that answers no ping
+ * that long is a client MAX can tell apart. One recognizer serves the whole run.
+ */
+export declare const hearAll: (client: MaxClient, voices: readonly Voice[], { model, directory, record, release, fetchAudio, open, progress }: HearAllOptions) => Promise<Heard>;
+export declare const isVoice: (message: Message) => boolean;
+/** A message with its transcript, when there is one; others pass through unchanged. */
+export declare const withTranscript: <T extends Pick<Message, "id" | "chatId">>(message: T, heard: Heard) => T & {
+    transcript?: string;
+};
+/** How a person sees one: the text MAX has, then what was heard. */
+export declare const spoken: <T extends Message & {
+    transcript?: string;
+}>({ transcript, ...message }: T) => Omit<T, "transcript">;
+export declare const hearingLine: (count: number, model: string) => string;
+//# sourceMappingURL=index.d.ts.map

package/dist/transcribe/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transcribe/index.ts"],"names":[],"mappings":"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"}

package/dist/transcribe/index.js

@@ -0,0 +1,127 @@
+import { CliError } from "@wirecat/cli-core";
+import { fetchBytes, LARGEST_VOICE } from "../download.js";
+import { installedBytes, isInstalled, megabytes, modelPath, vadPath } from "./install.js";
+import { MODELS, VAD } from "./models.js";
+import { decodeOgg, openRecognizer, toModelRate } from "./speech.js";
+export const notDownloaded = (model) => new CliError("not_found", [
+    `the speech model ${model.id} (${model.languages}) is not downloaded — ` +
+        `\`max models audio download ${model.id}\` fetches it (${sizeOf(model)}, once)`,
+    ...MODELS.filter((other) => other.id !== model.id).map((other) => `  or ${other.id}: ${other.languages}, ${sizeOf(other)}`),
+].join("\n"));
+const sizeOf = (model) => megabytes(installedBytes(model) + VAD.bytes);
+export const openInstalled = (model, directory) => openRecognizer(model, modelPath(directory, model), vadPath(directory));
+/** The recording of one voice message, fetched while the connection is still open. */
+const fetchVoice = async (client, chatId, messageId, fetchAudio) => {
+    const { links } = await client.messages.links(chatId, messageId);
+    const voice = links.find((link) => link.kind === "audio");
+    if (!voice)
+        throw new CliError("validation_error", `message ${messageId} has no voice recording to transcribe`);
+    const bytes = await fetchAudio(voice);
+    if (bytes.length > LARGEST_VOICE) {
+        throw new CliError("validation_error", `the recording is larger than ${LARGEST_VOICE / 1024 ** 2} MiB — not decoded`);
+    }
+    return bytes;
+};
+const hear = async (bytes, recognizer) => {
+    const { samples, rate } = await decodeOgg(bytes).catch((error) => {
+        throw new CliError("invalid_response", `the recording could not be read as Ogg Opus: ${error.message}`);
+    });
+    return { text: recognizer.recognize(toModelRate(samples, rate)), seconds: Math.round(samples.length / rate) };
+};
+/**
+ * One voice message to text, on this machine. A text already heard by the same model comes from
+ * the shared store, with no connection and no model loaded.
+ *
+ * ⚠ **The model is never downloaded from here** (`NEED-231`): an agent calling this through MCP must
+ * not start a 230–670 MB download. The refusal names the command that does it.
+ */
+export const transcribe = async (client, chatId, messageId, { model, directory, record, release, fetchAudio = fetchBytes, open = openInstalled }) => {
+    const kept = await record?.transcript(chatId, messageId);
+    if (kept && kept.source === model.id) {
+        return { chatId, messageId, text: kept.text, model: model.id, seconds: null, cached: true };
+    }
+    if (!isInstalled(model, directory))
+        throw notDownloaded(model);
+    const bytes = await fetchVoice(client, chatId, messageId, fetchAudio);
+    await release?.();
+    const recognizer = open(model, directory);
+    try {
+        const { text, seconds } = await hear(bytes, recognizer);
+        await record?.keepTranscript(chatId, messageId, text, model.id);
+        return { chatId, messageId, text, model: model.id, seconds, cached: false };
+    }
+    finally {
+        recognizer.free();
+    }
+};
+export const voiceKey = ({ chatId, messageId }) => `${chatId}/${messageId}`;
+/**
+ * Many voice messages at once — a page, an inbox, a review. Kept texts first, whichever model heard
+ * them. Then every recording still needed is fetched **before** the connection is released and the
+ * model runs: recognition is synchronous for up to a minute each, and a socket that answers no ping
+ * that long is a client MAX can tell apart. One recognizer serves the whole run.
+ */
+export const hearAll = async (client, voices, { model, directory, record, release, fetchAudio = fetchBytes, open = openInstalled, progress }) => {
+    const transcripts = new Map();
+    const unheard = [];
+    let problem;
+    const failed = (voice, error) => {
+        problem ??= error instanceof Error ? error.message : String(error);
+        unheard.push(voice);
+    };
+    const needed = [];
+    for (const voice of voices) {
+        const kept = await record?.transcript(voice.chatId, voice.messageId);
+        if (kept)
+            transcripts.set(voiceKey(voice), kept.text);
+        else
+            needed.push(voice);
+    }
+    if (needed.length === 0 || !model)
+        return { transcripts, unheard: needed };
+    if (!isInstalled(model, directory)) {
+        return { transcripts, unheard: needed, problem: notDownloaded(model).message };
+    }
+    const fetched = [];
+    for (const voice of needed) {
+        try {
+            fetched.push({ voice, bytes: await fetchVoice(client, voice.chatId, voice.messageId, fetchAudio) });
+        }
+        catch (error) {
+            failed(voice, error);
+        }
+    }
+    if (fetched.length > 0) {
+        await release?.();
+        progress?.(fetched.length);
+        const recognizer = open(model, directory);
+        try {
+            for (const { voice, bytes } of fetched) {
+                try {
+                    const { text } = await hear(bytes, recognizer);
+                    await record?.keepTranscript(voice.chatId, voice.messageId, text, model.id);
+                    transcripts.set(voiceKey(voice), text);
+                }
+                catch (error) {
+                    failed(voice, error);
+                }
+            }
+        }
+        finally {
+            recognizer.free();
+        }
+    }
+    return { transcripts, unheard, ...(problem === undefined ? {} : { problem }) };
+};
+export const isVoice = (message) => message.attachments.some(({ kind }) => kind === "audio");
+/** A message with its transcript, when there is one; others pass through unchanged. */
+export const withTranscript = (message, heard) => {
+    const transcript = heard.transcripts.get(voiceKey({ chatId: message.chatId, messageId: message.id }));
+    return transcript === undefined ? message : { ...message, transcript };
+};
+/** How a person sees one: the text MAX has, then what was heard. */
+export const spoken = ({ transcript, ...message }) => transcript === undefined
+    ? message
+    : { ...message, text: [message.text, `🎤 ${transcript}`].filter(Boolean).join("\n") };
+export const hearingLine = (count, model) => `hearing ${count} voice message${count === 1 ? "" : "s"} with ${model} on this machine`;
+//# sourceMappingURL=index.js.map

package/dist/transcribe/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transcribe/index.ts"],"names":[],"mappings":"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"}

package/dist/transcribe/install.d.ts

@@ -0,0 +1,2 @@
+export { type Fetch, install, installedBytes, isInstalled, megabytes, modelPath, modelsDirectory, vadPath, } from "@wirecat/cli-messaging/speech";
+//# sourceMappingURL=install.d.ts.map

package/dist/transcribe/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/transcribe/install.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EACV,OAAO,EACP,cAAc,EACd,WAAW,EACX,SAAS,EACT,SAAS,EACT,eAAe,EACf,OAAO,GACR,MAAM,+BAA+B,CAAA"}

package/dist/transcribe/install.js

@@ -0,0 +1,2 @@
+export { install, installedBytes, isInstalled, megabytes, modelPath, modelsDirectory, vadPath, } from "@wirecat/cli-messaging/speech";
+//# sourceMappingURL=install.js.map

package/dist/transcribe/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/transcribe/install.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,OAAO,EACP,cAAc,EACd,WAAW,EACX,SAAS,EACT,SAAS,EACT,eAAe,EACf,OAAO,GACR,MAAM,+BAA+B,CAAA"}

package/dist/transcribe/models.d.ts

@@ -0,0 +1,5 @@
+export { findModel, type ModelFile, type SpeechModel, speechModel, VAD } from "@wirecat/cli-messaging/speech";
+export declare const DEFAULT_MODEL = "gigaam-v3";
+export declare const SPEECH_MODELS: string[];
+export declare const MODELS: import("@wirecat/cli-messaging/speech").SpeechModel[];
+//# sourceMappingURL=models.d.ts.map

package/dist/transcribe/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/transcribe/models.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,+BAA+B,CAAA;AAE7G,eAAO,MAAM,aAAa,cAAc,CAAA;AACxC,eAAO,MAAM,aAAa,UAAkD,CAAA;AAC5E,eAAO,MAAM,MAAM,uDAA+B,CAAA"}

package/dist/transcribe/models.js

@@ -0,0 +1,6 @@
+import { orderedModels } from "@wirecat/cli-messaging/speech";
+export { findModel, speechModel, VAD } from "@wirecat/cli-messaging/speech";
+export const DEFAULT_MODEL = "gigaam-v3";
+export const SPEECH_MODELS = [DEFAULT_MODEL, "gigaam-v3-ctc", "parakeet-v3"];
+export const MODELS = orderedModels(SPEECH_MODELS);
+//# sourceMappingURL=models.js.map

package/dist/transcribe/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/transcribe/models.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAE7D,OAAO,EAAE,SAAS,EAAoC,WAAW,EAAE,GAAG,EAAE,MAAM,+BAA+B,CAAA;AAE7G,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AACxC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,aAAa,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;AAC5E,MAAM,CAAC,MAAM,MAAM,GAAG,aAAa,CAAC,aAAa,CAAC,CAAA"}