@leemour/max-cli 0.1.0

package/dist/cache/store.d.ts

@@ -0,0 +1,32 @@
+import type { Chat, Contact, Id, Message } from "../domain/models.js";
+import type { CacheDatabase } from "./driver.js";
+export interface CacheOptions {
+    database: CacheDatabase;
+    /** Injected so a freshness test costs nothing and does not wait. */
+    now?: () => number;
+}
+/** Nothing here ever throws on missing data: absent is a cache miss, not an error. */
+export interface CacheStore {
+    chats: {
+        read(freshForMs: number): Chat[] | undefined;
+        write(chats: Chat[]): void;
+    };
+    contacts: {
+        read(freshForMs: number): Contact[] | undefined;
+        write(contacts: Contact[]): void;
+    };
+    messages: {
+        /** The newest `limit` messages, but only if the window we hold is both fresh and contiguous. */
+        read(chatId: Id, limit: number, freshForMs: number): Message[] | undefined;
+        write(chatId: Id, messages: Message[]): void;
+        /** After a send, what we hold for that chat is missing the message we just added. */
+        invalidate(chatId: Id): void;
+    };
+    /** True when this process may go to MAX for that window; false when somebody else already is. */
+    claim(chatId: Id, anchor: string, holder: string, forMs: number): boolean;
+    release(chatId: Id, anchor: string): void;
+    clear(): void;
+    close(): void;
+}
+export declare const openStore: ({ database, now }: CacheOptions) => CacheStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/cache/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAGhD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAA;IACvB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE;QACL,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,SAAS,CAAA;QAC5C,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAAA;KAC3B,CAAA;IACD,QAAQ,EAAE;QACR,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;QAC/C,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;KACjC,CAAA;IACD,QAAQ,EAAE;QACR,gGAAgG;QAChG,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;QAC1E,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;QAC5C,qFAAqF;QACrF,UAAU,CAAC,MAAM,EAAE,EAAE,GAAG,IAAI,CAAA;KAC7B,CAAA;IACD,iGAAiG;IACjG,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IACzE,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,KAAK,IAAI,IAAI,CAAA;IACb,KAAK,IAAI,IAAI,CAAA;CACd;AAED,eAAO,MAAM,SAAS,GAAI,mBAAsC,YAAY,KAAG,UA8L9E,CAAA"}

package/dist/cache/store.js

@@ -0,0 +1,153 @@
+import { migrate } from "./schema.js";
+export const openStore = ({ database, now = () => Date.now() }) => {
+    migrate(database);
+    const markFetched = database.prepare("INSERT INTO fetched (kind, at) VALUES (?, ?) ON CONFLICT(kind) DO UPDATE SET at = excluded.at");
+    const fetchedAt = database.prepare("SELECT at FROM fetched WHERE kind = ?");
+    const isFresh = (kind, freshForMs) => {
+        const at = fetchedAt.get(kind)?.at;
+        return at !== undefined && now() - at <= freshForMs;
+    };
+    const putChat = database.prepare(`
+    INSERT INTO chats (id, title, kind, unread_count, last_message_at, participants_count, fetched_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      title = excluded.title, kind = excluded.kind, unread_count = excluded.unread_count,
+      last_message_at = excluded.last_message_at, participants_count = excluded.participants_count,
+      fetched_at = excluded.fetched_at, generation = chats.generation + 1`);
+    const putContact = database.prepare(`
+    INSERT INTO contacts (id, name, username, description, fetched_at) VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name, username = excluded.username,
+      description = excluded.description, fetched_at = excluded.fetched_at`);
+    /**
+     * **Compares MAX's clock, never ours.** `update_time` is what MAX sets on an edit and is `NULL`
+     * on a message nobody has changed (measured 2026-09-20).
+     *
+     * The comparison has to be on that value rather than on when we fetched, and the difference is
+     * not academic: agent A reads a chat after an edit, agent B read it before but finishes writing
+     * second. Ordering on fetch time puts B's pre-edit text back over A's correct one. Ordering on
+     * MAX's `update_time`, an edit always beats a version that never saw it, whoever writes last.
+     *
+     * `>=` rather than `>` so that two ordinary re-fetches of the same unedited message both go
+     * through — they carry identical text, so the write is harmless and refreshing `fetched_at` is
+     * the point of it.
+     */
+    const putMessage = database.prepare(`
+    INSERT INTO messages (chat_id, id, sender_id, sender_name, time, update_time, text, outgoing, attachments, fetched_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(chat_id, id) DO UPDATE SET
+      sender_name = excluded.sender_name, update_time = excluded.update_time, text = excluded.text,
+      outgoing = excluded.outgoing, attachments = excluded.attachments, fetched_at = excluded.fetched_at
+    WHERE coalesce(excluded.update_time, 0) >= coalesce(messages.update_time, 0)`);
+    const toChat = (row) => ({
+        id: String(row.id),
+        title: row.title === null ? null : String(row.title),
+        kind: String(row.kind),
+        unreadCount: row.unread_count === null ? null : Number(row.unread_count),
+        lastMessageAt: row.last_message_at === null ? null : new Date(Number(row.last_message_at)).toISOString(),
+        participantsCount: row.participants_count === null ? null : Number(row.participants_count),
+    });
+    const toMessage = (row) => ({
+        id: String(row.id),
+        chatId: String(row.chat_id),
+        senderId: row.sender_id === null ? null : String(row.sender_id),
+        senderName: row.sender_name === null ? null : String(row.sender_name),
+        timestamp: new Date(Number(row.time)).toISOString(),
+        editedAt: row.update_time === null ? null : new Date(Number(row.update_time)).toISOString(),
+        text: String(row.text),
+        outgoing: row.outgoing === null ? null : row.outgoing === 1,
+        attachments: JSON.parse(String(row.attachments)),
+    });
+    const epoch = (iso) => (iso === null ? null : new Date(iso).getTime());
+    return {
+        chats: {
+            read: (freshForMs) => {
+                if (!isFresh("chats", freshForMs))
+                    return undefined;
+                return database.prepare("SELECT * FROM chats ORDER BY last_message_at DESC").all().map(toChat);
+            },
+            write: (chats) => {
+                const at = now();
+                for (const chat of chats) {
+                    putChat.run(chat.id, chat.title, chat.kind, chat.unreadCount, epoch(chat.lastMessageAt), chat.participantsCount, at);
+                }
+                markFetched.run("chats", at);
+            },
+        },
+        contacts: {
+            read: (freshForMs) => {
+                if (!isFresh("contacts", freshForMs))
+                    return undefined;
+                return database
+                    .prepare("SELECT * FROM contacts ORDER BY name")
+                    .all()
+                    .map((row) => ({
+                    id: String(row.id),
+                    name: row.name === null ? null : String(row.name),
+                    username: row.username === null ? null : String(row.username),
+                    description: row.description === null ? null : String(row.description),
+                }));
+            },
+            write: (contacts) => {
+                const at = now();
+                for (const contact of contacts) {
+                    putContact.run(contact.id, contact.name, contact.username, contact.description, at);
+                }
+                markFetched.run("contacts", at);
+            },
+        },
+        messages: {
+            read: (chatId, limit, freshForMs) => {
+                if (!isFresh(`messages:${chatId}`, freshForMs))
+                    return undefined;
+                const rows = database
+                    .prepare("SELECT * FROM messages WHERE chat_id = ? ORDER BY time DESC LIMIT ?")
+                    .all(chatId, limit);
+                // A window we never claimed to hold completely cannot answer "the newest twenty": we have
+                // no way to know whether a twenty-first arrived between the fetch and now.
+                const range = database
+                    .prepare("SELECT to_time FROM ranges WHERE chat_id = ? ORDER BY to_time DESC LIMIT 1")
+                    .get(chatId);
+                if (!range)
+                    return undefined;
+                return rows.map(toMessage).reverse();
+            },
+            write: (chatId, messages) => {
+                if (messages.length === 0)
+                    return;
+                const at = now();
+                for (const message of messages) {
+                    putMessage.run(chatId, message.id, message.senderId, message.senderName, epoch(message.timestamp) ?? 0, epoch(message.editedAt), message.text, message.outgoing === null ? null : Number(message.outgoing), JSON.stringify(message.attachments), at);
+                }
+                const times = messages.map((message) => epoch(message.timestamp) ?? 0);
+                database
+                    .prepare(`INSERT INTO ranges (chat_id, from_time, to_time) VALUES (?, ?, ?)
+             ON CONFLICT(chat_id, from_time) DO UPDATE SET to_time = max(ranges.to_time, excluded.to_time)`)
+                    .run(chatId, Math.min(...times), Math.max(...times));
+                markFetched.run(`messages:${chatId}`, at);
+            },
+            invalidate: (chatId) => {
+                database.prepare("DELETE FROM fetched WHERE kind = ?").run(`messages:${chatId}`);
+            },
+        },
+        claim: (chatId, anchor, holder, forMs) => {
+            const at = now();
+            return (database
+                .prepare(`INSERT INTO fetch_lease (chat_id, anchor, holder, expires_at) VALUES (?, ?, ?, ?)
+             ON CONFLICT(chat_id, anchor) DO UPDATE
+               SET holder = excluded.holder, expires_at = excluded.expires_at
+               WHERE fetch_lease.expires_at <= ?`)
+                .run(chatId, anchor, holder, at + forMs, at).changes === 1);
+        },
+        release: (chatId, anchor) => {
+            database.prepare("DELETE FROM fetch_lease WHERE chat_id = ? AND anchor = ?").run(chatId, anchor);
+        },
+        clear: () => {
+            for (const table of ["messages", "chats", "contacts", "ranges", "fetched", "fetch_lease"]) {
+                database.exec(`DELETE FROM ${table}`);
+            }
+        },
+        close: () => database.close(),
+    };
+};
+//# sourceMappingURL=store.js.map

package/dist/cache/store.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,103 @@
+import type { CacheStore } from "./cache/store.js";
+import type { Chat, Contact, Id, Message, Profile } from "./domain/models.js";
+import { Connection } from "./protocol/connection.js";
+import { type DiagnosticEvent } from "./runs/events.js";
+import type { SessionStore } from "./session/store.js";
+export interface MaxClientOptions {
+    store: SessionStore;
+    timeoutMs?: number;
+    /** Injected by tests; defaults to a real WebSocket connection. */
+    connection?: Connection;
+    /**
+     * Where a protocol note goes. Never stdout: in machine mode that stream carries one JSON value
+     * and nothing else.
+     */
+    warn?: (message: string) => void;
+    /** Where reads are recorded. It is a record, not a shortcut — see `offline`. */
+    cache?: CacheStore;
+    /**
+     * Answer from what was recorded and **never connect**.
+     *
+     * Off by default, and deliberately: `LOGIN` already returns the chats, the contacts and recent
+     * messages, so once a command connects at all those are fresh for free. Serving them from disk
+     * instead buys only the right to skip connecting — which is the same act as deciding not to find
+     * out what changed. For a messenger that is backwards (§3.4z of the cache plan).
+     */
+    offline?: boolean;
+    /**
+     * One event per request, for whoever is keeping a diagnostic. Injected the way `warn` is: the
+     * client reports what it did and never decides where that goes. Absent means nothing is kept.
+     */
+    events?: (event: DiagnosticEvent) => void;
+}
+/**
+ * **The only thing above this line that knows MAX exists.** Commands speak the domain model; the
+ * opcodes and the frames stop here, so a different transport underneath changes this file and
+ * nothing else (REQUIREMENTS §25).
+ *
+ * The methods are grouped by subject — `client.chats.list()`, `client.messages.send()` — which is
+ * the shape §8 sketched. **There is only this door.** The generated per-operation wrappers sit
+ * underneath and stay internal: they return raw MAX payloads, without the resend rule, the name
+ * filling or the id conversion that make this safe to point at a real account (`NEED-34`).
+ *
+ * One instance is one connection. `open` then `close`, always in a `finally`.
+ */
+export declare class MaxClient {
+    #private;
+    constructor({ store, timeoutMs, connection, warn, cache, offline, events }: MaxClientOptions);
+    readonly account: {
+        me: () => Profile;
+    };
+    readonly chats: {
+        /**
+         * Chats come with the login; a limit trims rather than fetching more.
+         *
+         * **A one-to-one chat has no title of its own** — its name is the other person's, which MAX
+         * does not put in the chat object. So the partner is looked up once, for every dialog at a
+         * time, and the name is filled in. Without this, `max chats` shows a column of blanks for
+         * exactly the chats a person recognises by name.
+         */
+        list: (limit?: number) => Promise<Chat[]>;
+        /**
+         * Turns what the person typed into a chat id.
+         *
+         * A number is taken as an id. Anything else is matched against chat titles, exactly first and
+         * then as a fragment — and **an ambiguous name is an error, not a guess**: sending to the wrong
+         * conversation is not undoable, so the caller is shown the candidates and asked to be specific.
+         */
+        resolve: (reference: string) => Promise<Id>;
+    };
+    readonly contacts: {
+        /** The people this account has a one-to-one chat with, named. */
+        list: () => Promise<Contact[]>;
+    };
+    readonly messages: {
+        list: (chatId: Id, limit?: number) => Promise<Message[]>;
+        /**
+         * Sends one message, retrying **only with the same `cid`**.
+         *
+         * §17 allows a send to be retried when the protocol has a verified deduplication handle. It has
+         * one, measured against MAX on 2026-09-19: sending the same `cid` twice returned the same
+         * message id and left **one** copy in the chat — and it held across two separate connections
+         * and logins, which is the case a retry actually faces.
+         *
+         * So one retry, same `cid`, and nothing beyond that. What is still unmeasured is how long the
+         * server remembers a `cid`; the two probes were seconds apart. If the retry also fails the
+         * answer is `outcome_unknown` — never failed, never sent — and it names the `cid`, because
+         * `max send --cid <n>` can then repeat the attempt without risking a second message.
+         */
+        send: (chatId: Id, text: string, options?: {
+            cid?: number;
+            notify?: boolean;
+        }) => Promise<Message>;
+    };
+    /**
+     * Opens the connection and logs in with the stored token.
+     *
+     * The login response carries the profile, the chats, the contacts and recent messages, so most
+     * commands need no further request — measured against MAX on 2026-09-19.
+     */
+    connect(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAG7E,OAAO,EAAE,UAAU,EAAiB,MAAM,0BAA0B,CAAA;AAEpE,OAAO,EAAY,KAAK,eAAe,EAAS,MAAM,kBAAkB,CAAA;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGtD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kEAAkE;IAClE,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,gFAAgF;IAChF,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;;gBAaR,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,OAAe,EAAE,MAAM,EAAE,EAAE,gBAAgB;IASpG,QAAQ,CAAC,OAAO;kBACN,OAAO;MAChB;IAED,QAAQ,CAAC,KAAK;QACZ;;;;;;;WAOG;uBACkB,MAAM,KAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAuB7C;;;;;;WAMG;6BACwB,MAAM,KAAG,OAAO,CAAC,EAAE,CAAC;MAgBhD;IAED,QAAQ,CAAC,QAAQ;QACf,iEAAiE;oBACjD,OAAO,CAAC,OAAO,EAAE,CAAC;MASnC;IAED,QAAQ,CAAC,QAAQ;uBACM,EAAE,qBAAe,OAAO,CAAC,OAAO,EAAE,CAAC;QA0BxD;;;;;;;;;;;;WAYG;uBACkB,EAAE,QAAQ,MAAM,YAAW;YAAE,GAAG,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAA;SAAE,KAAQ,OAAO,CAAC,OAAO,CAAC;MAuC3G;IAED;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAyJ7B"}