@mnemom/mnemom 0.17.34 → 0.17.36

package/dist/host/client.d.ts

@@ -89,6 +89,47 @@ export interface ExecutorApi {
         nonce: string;
         entries: readonly HeartbeatEntry[];
     }): Promise<HttpResult>;
+    /** S1 amendment 60: the content-free inbox summary of a session this executor holds. */
+    inboxSummary(sessionId: string): Promise<HttpResult>;
+    /** Marks up to `limit` messages delivered at the live epoch and answers their delivery text. */
+    inboxTake(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        limit: number;
+    }): Promise<HttpResult>;
+    inboxAck(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        inbox_id: string;
+        sha: string;
+    }): Promise<HttpResult>;
+    /** Hands a delivered message back undone (admitted again, or dead at its delivery limit). */
+    inboxRelease(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        inbox_id: string;
+        sha: string;
+        reason: "unconfirmed" | "refused" | "undeliverable";
+    }): Promise<HttpResult>;
+    /** S1 amendment 61: opens (or returns) the session's question approval; journals question.asked. */
+    questionAsk(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        tool_use_id: string;
+        questions: unknown;
+    }): Promise<HttpResult>;
+    /** The question's state; an answer is handed over once (the api marks it taken). */
+    questionPoll(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        approval_id: string;
+    }): Promise<HttpResult>;
+    /** The seat stopped waiting: the answer, now or later, goes to the inbox. */
+    questionRelease(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        approval_id: string;
+    }): Promise<HttpResult>;
 }
 export declare function executorApi(opts: {
     apiUrl: string;

package/dist/host/client.js

@@ -131,6 +131,13 @@ export function executorApi(opts) {
         seatExit: (id, body) => call("exec_seat_exit", id, "POST", body),
         fail: (id, body) => call("exec_fail", id, "POST", body),
         heartbeat: (body) => call("exec_heartbeat", undefined, "POST", body),
+        inboxSummary: (id) => call("exec_inbox", id, "GET"),
+        inboxTake: (id, body) => call("exec_inbox_take", id, "POST", body),
+        inboxAck: (id, body) => call("exec_inbox_ack", id, "POST", body),
+        inboxRelease: (id, body) => call("exec_inbox_release", id, "POST", body),
+        questionAsk: (id, body) => call("exec_question", id, "POST", body),
+        questionPoll: (id, body) => call("exec_question_poll", id, "POST", body),
+        questionRelease: (id, body) => call("exec_question_release", id, "POST", body),
     };
 }
 /** Map a claim response to what the daemon does with it (C12-R14, R31). */

package/dist/host/control.d.ts

@@ -16,7 +16,14 @@ export interface ControlHandlers {
         status: number;
         body: unknown;
     }>;
+    /** S1 amendment 61; absent: the question ops are unknown_op. */
+    relayQuestion?(op: ControlQuestionOp, sessionId: string, spawnId: string, epoch: number, payload: Record<string, unknown>): Promise<{
+        status: number;
+        body: unknown;
+    }>;
 }
+export declare const CONTROL_QUESTION_OPS: readonly ["question_ask", "question_poll", "question_release"];
+export type ControlQuestionOp = (typeof CONTROL_QUESTION_OPS)[number];
 export declare function handleControl(h: ControlHandlers, line: string): Promise<Record<string, unknown>>;
 export declare function startControlServer(socket: string, h: ControlHandlers, log: (s: string) => void): net.Server;
 /** dev and inode of the socket file at `socket`, or null when there is none. */

package/dist/host/control.js

@@ -5,6 +5,10 @@
  *   {op:"seat_key", session_id, spawn_id} -> {ok:true, lease_key} once per spawn, then {ok:false}
  *   {op:"hello",    session_id, spawn_id} -> {ok, status, body}: the daemon POSTs the executor hello
  *                                            (the executor key never leaves the daemon, C12-R27)
+ *   {op:"question_ask"|"question_poll"|"question_release", session_id, spawn_id, epoch, ...}
+ *                                         -> {ok, status, body}: S1 amendment 61; the daemon adds the
+ *                                            live lease's nonce and calls exec_question[_poll|_release]
+ *                                            for a registered seat of that spawn id AND epoch
  * Anything else is refused locally.
  */
 import * as fs from "node:fs";
@@ -47,6 +51,7 @@ export function ensureSocketDir(dir, uid = os.userInfo().uid) {
     checkOwnSocketDir(dir, uid);
 }
 export const controlSocketPath = (dir) => path.join(dir, "daemon.sock");
+export const CONTROL_QUESTION_OPS = ["question_ask", "question_poll", "question_release"];
 const ID = /^[0-9a-f-]{36}$/i;
 export async function handleControl(h, line) {
     let req;
@@ -70,6 +75,16 @@ export async function handleControl(h, line) {
         const r = await h.relayHello(sid, spawn);
         return { ok: r.status === 200, status: r.status, body: r.body };
     }
+    if (h.relayQuestion && CONTROL_QUESTION_OPS.includes(req.op)) {
+        const op = req.op;
+        if (!Number.isSafeInteger(req.epoch) || req.epoch < 0)
+            return { ok: false, error: "bad_request" };
+        const payload = op === "question_ask"
+            ? { tool_use_id: req.tool_use_id, questions: req.questions }
+            : { approval_id: req.approval_id };
+        const r = await h.relayQuestion(op, sid, spawn, req.epoch, payload);
+        return { ok: r.status === 200, status: r.status, body: r.body };
+    }
     return { ok: false, error: "unknown_op" };
 }
 export function startControlServer(socket, h, log) {

package/dist/host/daemon.d.ts

@@ -1,6 +1,7 @@
 import type { ClaimUnavailableCause, CwdCheckCause } from "../vendor/shared/durable-contract/codes.js";
 import { type ExecutorApi, type SessionItem } from "./client.js";
 import { type SeatPane } from "./tmux.js";
+import type { ControlQuestionOp } from "./control.js";
 export declare const TICK_MS = 1000;
 export declare const ADOPT_RETRY_MS = 2000;
 export { SPAWNED_KIND, spawnIdempotencyKey } from "./s1-names.js";
@@ -99,6 +100,16 @@ export interface DaemonDeps {
         epoch: number;
         spawnId: string;
     }, turnId: string | null) => Promise<unknown>;
+    /**
+     * S1 amendment 60: deliver each seat's durable inbox into it (host/inbox-delivery.ts), once per
+     * pass after the seats are checked. Absent: no inbox delivery.
+     */
+    readonly inbox?: (seats: readonly {
+        sessionId: string;
+        tmuxSession: string;
+        epoch: number;
+        ready: boolean;
+    }[]) => Promise<readonly string[]>;
 }
 export interface UnavailableInfo {
     cause: ClaimUnavailableCause | null;
@@ -217,5 +228,14 @@ export declare class HostDaemon {
         status: number;
         body: unknown;
     }>;
+    /**
+     * Relay a seat's question op (S1 amendment 61). Only for a registered, hello-accepted seat this
+     * daemon holds, with its own spawn id and epoch; the daemon adds the live lease's epoch and nonce
+     * (the executor key never leaves the daemon). The api checks the payload's closed shape.
+     */
+    relayQuestion(op: ControlQuestionOp, sessionId: string, spawnId: string, epoch: number, payload: Record<string, unknown>): Promise<{
+        status: number;
+        body: unknown;
+    }>;
     private publish;
 }

package/dist/host/daemon.js

@@ -16,10 +16,11 @@
 import { randomUUID } from "node:crypto";
 import { EXECUTOR_POLL_S, HEARTBEAT_DIVISOR, RESPAWN_CONCURRENCY, CLAIM_BACKOFF_BASE_S, CLAIM_BACKOFF_MAX_S, CLAIM_BACKOFF_JITTER, LEASE_SECONDS_DEFAULT, } from "../vendor/shared/durable-contract/constants.js";
 import { TERMINAL_STATES } from "../vendor/shared/durable-contract/states.js";
+import { questionAskMatches, questionAskResponseOk, } from "../vendor/shared/durable-contract/question.js";
 import { IDLE_LOG } from "./gate.js";
 import { classifyClaim, errorCode, } from "./client.js";
 import { seatTmuxSession } from "./tmux.js";
-import { CODE, SEAT_UNKNOWN, SPAWNED_KIND, spawnIdempotencyKey } from "./s1-names.js";
+import { CODE, SEAT_BAD_ANSWER, SEAT_UNKNOWN, SPAWNED_KIND, spawnIdempotencyKey, } from "./s1-names.js";
 export const TICK_MS = 1000;
 export const ADOPT_RETRY_MS = 2000;
 export { SPAWNED_KIND, spawnIdempotencyKey } from "./s1-names.js";
@@ -179,6 +180,19 @@ export class HostDaemon {
             return did;
         }
         await this.checkSeats(did);
+        if (this.d.inbox) {
+            try {
+                did.push(...(await this.d.inbox([...this.seats.values()].map((x) => ({
+                    sessionId: x.sessionId,
+                    tmuxSession: x.tmuxSession,
+                    epoch: x.epoch,
+                    ready: x.helloAccepted,
+                })))));
+            }
+            catch (e) {
+                this.d.log(`inbox delivery: ${e.message}`);
+            }
+        }
         await this.heartbeat(did);
         if (polled && this.items.size > 0)
             await this.claimWave(did);
@@ -587,6 +601,65 @@ export class HostDaemon {
         }
         return { status: r.status, body: r.body };
     }
+    /**
+     * Relay a seat's question op (S1 amendment 61). Only for a registered, hello-accepted seat this
+     * daemon holds, with its own spawn id and epoch; the daemon adds the live lease's epoch and nonce
+     * (the executor key never leaves the daemon). The api checks the payload's closed shape.
+     */
+    async relayQuestion(op, sessionId, spawnId, epoch, payload) {
+        const s = this.seats.get(sessionId);
+        if (!s || s.spawnId !== spawnId || !s.registered || !s.helloAccepted || s.epoch !== epoch)
+            return {
+                status: 404,
+                body: {
+                    error: { code: SEAT_UNKNOWN, message: "no live seat with that spawn id and epoch" },
+                },
+            };
+        const fence = { epoch: s.epoch, nonce: this.d.nonce };
+        if (op === "question_ask") {
+            const ask = {
+                session_id: sessionId,
+                tool_use_id: String(payload.tool_use_id),
+                questions: payload.questions,
+            };
+            const r = await this.d.api.questionAsk(sessionId, {
+                ...fence,
+                tool_use_id: ask.tool_use_id,
+                questions: ask.questions,
+            });
+            if (r.status !== 200)
+                return { status: r.status, body: r.body };
+            if (!questionAskResponseOk(r.body))
+                return {
+                    status: 502,
+                    body: { error: { code: SEAT_BAD_ANSWER, message: "not a question answer" } },
+                };
+            // The seat waits only on its own question (S1 question.ts questionAskMatches; the hook cannot
+            // import the contract, so the check is here): an answer about another is that question still
+            // being open, so the hook denies as for durable_question_busy and polls or releases nothing.
+            if (!(await questionAskMatches(r.body, ask)))
+                return {
+                    status: 409,
+                    body: {
+                        error: {
+                            code: CODE.durable_question_busy,
+                            message: "another question of this session is still open",
+                        },
+                    },
+                };
+            return { status: r.status, body: r.body };
+        }
+        const r = op === "question_poll"
+            ? await this.d.api.questionPoll(sessionId, {
+                ...fence,
+                approval_id: String(payload.approval_id),
+            })
+            : await this.d.api.questionRelease(sessionId, {
+                ...fence,
+                approval_id: String(payload.approval_id),
+            });
+        return { status: r.status, body: r.body };
+    }
     // ---- status ------------------------------------------------------------------------------------
     publish(state) {
         this.d.publish({

package/dist/host/inbox-delivery.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The homed inbox delivery (S1 amendment 60, signed off by Wassim 2026-11-02): the host daemon gives each
+ * seat it hosts the messages in its session's durable inbox, one at a time, as the seat's next
+ * prompt, and acks each once the turn answering it has ended. It replaces the Slack wake's pane
+ * typing (draft PR #3145's host/seat-wake.ts): Slack, the CLI and allowlisted agents all send
+ * through ROUTES.own_inbox_send, and the api, not a local file, holds what is waiting.
+ *
+ * Per seat, each pass:
+ *   1. Nothing in flight: when the seat is idle (its proxy said hello, the transcript's last turn
+ *      finished, claude's input line is drawn and no turn is running) on two consecutive passes,
+ *      read exec_inbox (content-free) and, when anything waits, exec_inbox_take one message. The api
+ *      marks it delivered at the seat's epoch and journals inbox.delivered BEFORE the paste, so its
+ *      sha is in the resolver's inbox_open by the time the turn reaches the gateway.
+ *   2. Paste the api's text (bracketed paste, then Enter), with every control character but TAB
+ *      and LF removed first (`pasteSafe`), so no byte of a body can end the bracketed paste. Its
+ *      first line is `[mnemom inbox <sha>] from ...`; the seat proxy stamps `inbox=<sha>` on that
+ *      transcript entry (durable/turn-chain.ts), which A60 admits unattended while the sha is open.
+ *   3. Confirm the prompt landed: a transcript entry carrying the marker within CONFIRM_MS, else
+ *      paste again while the seat is idle, waiting twice as long after each paste (at most
+ *      PASTE_TRIES = INBOX_DELIVERY_LIMIT pastes). After that it is released (unconfirmed), so the
+ *      api offers it again or, at its delivery limit, marks it dead. A paste whose Enter failed is
+ *      submitted with Enter alone, never pasted again; a seat that is never idle again releases an
+ *      unconfirmed message after INBOX_STALL_MS.
+ *   4. Once the turn after the marker has ended (idle again), exec_inbox_ack. A 409
+ *      durable_inbox_not_open (already acked, or the epoch moved) also settles it.
+ *
+ * What is in flight is kept per session in `stateDir` (inbox id, sha, epoch, text), so a daemon
+ * restart neither pastes a message twice nor loses its ack. A record from an older epoch is dropped:
+ * the api re-offers that message to the new seat. When the dropped record's prompt had already
+ * reached the transcript, its sha is kept as handled first, and the re-offer is acked at the new
+ * epoch instead of pasted, so the conversation never sees one message twice.
+ *
+ * A take whose answer is lost or malformed may still have marked messages delivered at this epoch.
+ * Nothing is dropped on it: any message the answer does name is released (undeliverable), and the
+ * empty-take latch below lapses after INBOX_REOFFER_S, when the api re-offers the rest.
+ *
+ * Pure over injected deps; host/run.ts wires the executor API, tmux, the transcript and the log.
+ */
+import { type InboxReleaseReason } from "../vendor/shared/durable-contract/inbox.js";
+import type { HttpResult } from "./client.js";
+/** How long a first paste has to show up in the transcript before it is pasted again (doubling). */
+export declare const CONFIRM_MS = 15000;
+/** The longest wait between two pastes of one message. */
+export declare const CONFIRM_MAX_MS = 300000;
+/** Pastes of one taken message at most (the api's own take limit, S1 INBOX_DELIVERY_LIMIT). */
+export declare const PASTE_TRIES = 5;
+/** How long paste number `tries` (1-based) has to show up before the next one. */
+export declare const confirmWindow: (tries: number) => number;
+/**
+ * The delivery text as it may be pasted into a terminal: CR LF and CR become LF, and every other
+ * control character but TAB and LF (C0 including ESC, DEL, C1) is removed. ESC[201~ inside a
+ * bracketed paste would end it and the bytes after it would reach claude as typed keys (a CR
+ * submits, `!` runs a shell command, Shift+Tab changes the permission mode). S1 inboxBodyOk refuses
+ * these at send; this holds whatever the api admitted.
+ */
+export declare function pasteSafe(text: string): string;
+/** At most one exec_inbox read per seat in this period while idle. */
+export declare const INBOX_POLL_MS = 5000;
+/**
+ * An unconfirmed paste on a seat that never shows idle again (a hung turn) is released after this
+ * long, so the api re-offers it and a later pass takes it again, instead of parking it forever.
+ */
+export declare const INBOX_STALL_MS: number;
+/** The handled shas kept per session (a re-offer comes within one epoch change of its paste). */
+export declare const HANDLED_MAX = 32;
+export interface InboxSeat {
+    readonly sessionId: string;
+    readonly tmuxSession: string;
+    readonly epoch: number;
+    /** The seat's proxy said hello: claude is up and owns the conversation. */
+    readonly ready: boolean;
+}
+export interface InFlight {
+    readonly inboxId: string;
+    readonly sha: string;
+    readonly epoch: number;
+    readonly text: string;
+    pastedAt: number;
+    tries: number;
+    confirmed: boolean;
+    /**
+     * The last paste was followed by its Enter. False between a paste and its Enter: if the Enter
+     * fails the text is still in claude's input line, so the next pass presses Enter again, never
+     * pastes it a second time.
+     */
+    submitted: boolean;
+}
+export interface InboxExecApi {
+    inboxSummary(sessionId: string): Promise<HttpResult>;
+    inboxTake(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        limit: number;
+    }): Promise<HttpResult>;
+    inboxAck(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        inbox_id: string;
+        sha: string;
+    }): Promise<HttpResult>;
+    inboxRelease(sessionId: string, body: {
+        epoch: number;
+        nonce: string;
+        inbox_id: string;
+        sha: string;
+        reason: InboxReleaseReason;
+    }): Promise<HttpResult>;
+}
+export interface InboxDeliveryDeps {
+    api: InboxExecApi;
+    nonce: () => string;
+    /** The session's transcript text (its tail is enough), or null when not on disk. */
+    transcript: (sessionId: string) => string | null;
+    capture: (tmuxSession: string) => Promise<string | null>;
+    /** Paste `text` into the pane's input line as one prompt (not submitted). */
+    paste: (tmuxSession: string, text: string) => Promise<void>;
+    /** Press Enter in the pane: submits what was pasted. */
+    submit: (tmuxSession: string) => Promise<void>;
+    load: (sessionId: string) => InFlight | null;
+    save: (sessionId: string, f: InFlight | null) => void;
+    /** The shas whose prompt reached the session's transcript but were never acked, oldest first. */
+    loadHandled: (sessionId: string) => string[];
+    saveHandled: (sessionId: string, shas: readonly string[]) => void;
+    now: () => number;
+    log: (line: string) => void;
+}
+interface Rec {
+    readonly type?: unknown;
+    readonly isMeta?: unknown;
+    readonly message?: {
+        readonly role?: unknown;
+        readonly content?: unknown;
+    };
+}
+/** The marker sha a user record's prompt carries, or null. */
+export declare function recordInboxSha(r: Rec): string | null;
+/**
+ * What a transcript says about a delivery: whether its last turn finished (the last conversation
+ * record is the assistant's own text with no tool call; an empty transcript is a fresh session,
+ * which is idle too), whether a prompt carrying `sha` is in it, and whether the turn that prompt
+ * started has ended.
+ */
+export declare function transcriptView(transcript: string, sha: string | null): {
+    finished: boolean;
+    seen: boolean;
+    answered: boolean;
+};
+/** claude's input line is drawn and no turn is running. */
+export declare function paneIdle(screen: string | null): boolean;
+/**
+ * A stored in-flight record, or null when any field is missing or out of range (a record from
+ * another daemon version, say): it is then treated as absent, so it can never re-paste unbounded.
+ * A record written before `submitted` existed was submitted (its paste and Enter were one step).
+ */
+export declare function inFlightOf(v: unknown): InFlight | null;
+export declare function fileInFlight(dir: string): Pick<InboxDeliveryDeps, "load" | "save" | "loadHandled" | "saveHandled">;
+export declare class InboxDelivery {
+    private readonly d;
+    private readonly state;
+    constructor(d: InboxDeliveryDeps);
+    /** One pass over the daemon's seats. Returns what it did (for logs and tests). */
+    sync(seats: readonly InboxSeat[]): Promise<string[]>;
+    private seat;
+    /** Save `f` as not yet submitted, paste it, press Enter, then save it as submitted. */
+    private put;
+    private markHandled;
+    /**
+     * A re-offer of a message whose prompt is already in the conversation: ack it at this epoch
+     * without pasting. A failed ack keeps the sha handled; the api re-offers it again later.
+     */
+    private ackHandled;
+    private release;
+}
+export {};