@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.2

package/dist/lib/durable/live.d.ts

@@ -0,0 +1,194 @@
+/**
+ * The live wiring of the durable verbs: real fetch, the stored login (JWT) or the personal org
+ * MNEMOM_API_KEY, the active org, launcher.toml's `durable` key, the process table. Thin by design:
+ * every decision lives in the injected modules and is unit-tested there.
+ */
+import { type LauncherConfig } from "../launcher-config.js";
+import { type ProcDeps } from "../../durable/proc.js";
+import type { LauncherKey } from "../../vendor/shared/durable-contract/fixlines.js";
+import type { DurableVerbDeps } from "../../commands/durable-verbs.js";
+import type { SessionsReadDeps } from "../../commands/durable-sessions.js";
+import { type DoctorLine } from "../../commands/durable-doctor.js";
+import { type OriginalLaunch, type LockDeps, type LockOutcome } from "../../commands/durable-lock.js";
+import { DurableApi, type RegistryRow } from "./api.js";
+import { type DurableLaunchPlan, type PlanDeps, type RegistryReads, type SeatDeps } from "./launch.js";
+import { type HandoverDeps } from "./handover.js";
+import { type HostInstance } from "../../host/instance.js";
+import { type OwnerHttp } from "../../host/owner.js";
+import { type FirstTurnLock } from "./first-turn.js";
+import type { HomeFacts } from "./view.js";
+export declare function liveDurableApi(): DurableApi;
+/** launcher.toml `durable`, defaulting to off (only read while the gate is on); unreadable is off. */
+export declare function liveLauncherKey(load?: () => {
+    durable?: LauncherKey;
+}): LauncherKey;
+/** PIDs of local claude processes whose argv names `ccSessionId` (pure over a `ps` listing). */
+export declare function claudePidsFor(psOutput: string, ccSessionId: string, selfPid: number): number[];
+export declare function liveVerbDeps(): DurableVerbDeps;
+export declare function liveSessionsReadDeps(): SessionsReadDeps;
+export declare function liveLockDeps(): LockDeps;
+/** The live original's exact argv, its parent launcher's passthrough and its shape (C14-R13). */
+export declare function liveReadOriginal(pid: number, deps?: ProcDeps): OriginalLaunch | null;
+/** What the idle source's RC naming reads (live: the launcher config, the entitlement, the probe). */
+export interface RcNamingIo {
+    env: NodeJS.ProcessEnv;
+    loadConfig: () => LauncherConfig;
+    entitlement: () => Promise<{
+        remote_control?: boolean;
+    } | null>;
+    capable: (env: NodeJS.ProcessEnv) => boolean;
+}
+export declare const liveRcNamingIo: () => RcNamingIo;
+/** The idle source's RC naming, as `mnemom agent <name>` would resolve it (fail-closed: false). */
+export declare function liveRcNamed(io?: RcNamingIo): Promise<boolean>;
+/** `mnemom agent doctor`'s durable lines (C02-R19), read through the live registry client. */
+export declare function liveDoctorDurableLines(): Promise<DoctorLine[]>;
+/** This machine's launch-ledger records, or null when the ledger is missing or unreadable. */
+export declare function readLedgerRecords<T>(exists: () => boolean, read: () => T): T | null;
+/** The live C02-R26 handover: the process table, real signals, and the registry row. */
+export declare function liveHandoverDeps(api: Pick<DurableApi, "getSession">): HandoverDeps;
+/**
+ * The lock verb's deps: the handover on, and EPIPE on stdout ignored (under `/mnemom lock` the
+ * parent may be gone by the time the lock line prints; C02-R26 step 7).
+ */
+export declare function liveLockVerbDeps(): LockDeps;
+/**
+ * C02-R26 step 7 for the launcher: its tracked child ended. When a handover locked the session,
+ * restore the terminal mode saved before the spawn (`stty -g`), print the lock line and attach;
+ * the exit status, or null to exit with the child's status as today.
+ */
+export declare function liveParentAfterChildEnded(row: RegistryRow, name: string, launcherKey: LauncherKey, savedTty: string | null): Promise<number | null>;
+/** The terminal mode (`stty -g`) before claude starts, or null off a TTY. */
+export declare function saveTtyMode(): string | null;
+/** Run this CLI (`node <bin> ...args`) and capture its exit status and stdout. */
+export type CliRunner = (bin: string, args: string[]) => {
+    status: number | null;
+    stdout: unknown;
+};
+/** `mnemom agent host status --json` (C2), or null when it is not available. */
+export declare function readHostStatus(bin?: string | undefined, run?: CliRunner): Record<string, unknown> | null;
+/**
+ * agents.agent_durable_only from an agent record (bare or under `agent`); null when the record
+ * carries no boolean flag. Absent is never read as false: the api once never served the field
+ * (a PostgREST computed field missed by `select=*`, mnemom-api #4263), and false skipped C02-R24.
+ */
+export declare function agentDurableOnlyOf(body: unknown): boolean | null;
+/**
+ * agents.agent_durable_only of an agent (A2 serves it on the agent record). It fails closed
+ * (C02-R24): a record that cannot be read (transport, timeout, 5xx, any non-200) refuses with
+ * session_registry_unavailable before any spawn, so a durable-only agent never gets a tracked
+ * claude on an unreadable flag. A 200 without the field refuses the same way: absent is not false.
+ */
+export declare function readAgentDurableOnly(api: Pick<DurableApi, "getAgent">, agentId: string): Promise<boolean>;
+/**
+ * This machine's label: the machine_label of its current executor in the owner executor list
+ * (exec_list), matched by the state file's executor id. Never the hostname: enrollment takes any
+ * --label. Null when not enrolled here, when the list can't be read, or when the row has no
+ * label; the unreachable-home rule then never applies (the home reads elsewhere).
+ */
+export declare function readLocalMachineLabel(localExecutorId: string | null, list: () => Promise<OwnerHttp>): Promise<string | null>;
+/**
+ * The org this machine's executor is enrolled in (exec_list, matched by id), or null when the list
+ * can't be read or names no org for it. Read only to explain a durable_no_executor lock refusal.
+ */
+export declare function readExecutorOrg(executorId: string, list: () => Promise<OwnerHttp>): Promise<string | null>;
+export declare function liveHomeFacts(): Promise<HomeFacts>;
+/** The launcher's registry reads (entitlement, then the list by name) over one client. */
+export declare function liveRegistryReads(api: DurableApi): RegistryReads;
+export declare function livePlanDeps(servedAgentId: string, transcriptExists: (cc: string) => boolean, askYesNo: (q: string, d: boolean) => Promise<boolean>): PlanDeps;
+/**
+ * A host daemon serves this machine when launchd has it loaded, or when one is running here
+ * outside launchd (`mnemom agent host run` in the foreground): status reports its pid only while
+ * that pid holds host.lock and wrote the runtime file.
+ */
+export declare function daemonPresent(status: Record<string, unknown> | null): boolean;
+/**
+ * The seat of a session from host status (C2). Status names its host by the launchd label
+ * (`instance`); a status for another host is never attached to. The socket is this host's tmux
+ * socket, resolved from the environment as the daemon resolves it (host/instance.ts), never the
+ * label: the two differ on every host. The target is the seat's tmux session, named as the daemon
+ * names it from the session and spawn ids (host/tmux.ts seatTmuxSession).
+ */
+export declare function seatOf(status: Record<string, unknown> | null, row: RegistryRow, instance: HostInstance): {
+    socket: string;
+    target: string;
+} | null;
+/** tmux's argv to attach a seat. */
+export declare function seatAttachArgv(seat: {
+    socket: string;
+    target: string;
+}): string[];
+/** The host instance this CLI talks to, or null when its env names an invalid one. */
+export declare function envInstance(env?: Readonly<Record<string, string | undefined>>): HostInstance | null;
+/** The seat to attach to: none when the env names no valid instance (status is then never read). */
+export declare function seatIn(row: RegistryRow, instance: HostInstance | null, status: () => Record<string, unknown> | null): {
+    socket: string;
+    target: string;
+} | null;
+/**
+ * Attach the terminal to a seat with tmux and return tmux's exit status; a tmux ended by a signal
+ * (no status) is a failed attach, 1.
+ */
+export declare function attachSeat(seat: {
+    socket: string;
+    target: string;
+}, run: (cmd: string, argv: string[], opts: {
+    stdio: "inherit";
+}) => {
+    status: number | null;
+}): number;
+export declare function liveSeatDeps(launcherKey: LauncherKey): SeatDeps;
+export interface RegisterDeps {
+    api: Pick<DurableApi, "createSession">;
+    cwd: () => string;
+}
+/** Register a new session (POST create) or return the continued row; a refusal is thrown. */
+export declare function registerDurableSession(plan: Extract<DurableLaunchPlan, {
+    kind: "spawn";
+}>, name: string, agentId: string, deps?: RegisterDeps): Promise<RegistryRow>;
+/**
+ * C02-R23 (c)/(e): lock instead of spawning. The exit status when locked (attach or the non-TTY
+ * line), or null when the lock refused (refusal and fix printed; the caller spawns tracked).
+ */
+export interface LockInsteadDeps {
+    /** The idle-source lock of the row (durable-lock.ts lockResolvedRow over `lockDeps`). */
+    lockRow: (row: RegistryRow, name: string, deps: LockDeps) => Promise<LockOutcome>;
+    lockDeps: LockDeps;
+    seat: SeatDeps;
+}
+export declare function lockInsteadOfSpawn(row: RegistryRow, name: string, launcherKey: LauncherKey, durableOnly: true, d?: LockInsteadDeps): Promise<number>;
+export declare function lockInsteadOfSpawn(row: RegistryRow, name: string, launcherKey: LauncherKey, durableOnly: boolean, d?: LockInsteadDeps): Promise<number | null>;
+/** The row a create-and-lock is about to make: what the idle-source lock reads (cwd, cc id). */
+export declare function bornRow(plan: Extract<DurableLaunchPlan, {
+    kind: "spawn";
+}>, name: string, agentId: string, cwd: string): RegistryRow;
+/**
+ * B5a (as amended): `--new` under `always` on a durable-only agent creates the session locked in
+ * one request (the create route with the lock verb's body; the api commits both in one
+ * transaction), then attaches to the seat like any lock instead of spawning. No tracked row, no
+ * attended claude, so no turn ever runs on a plain key. The lock is the lock verb's own
+ * (lockResolvedRow: cwd rule, executor id, spec); only its POST goes to the create route. A
+ * refusal is the durable_only_agent refusal and exit 1 (C02-R24), never a tracked spawn.
+ *
+ * No claude runs before the lock, so the spec cannot be read from a live original as the lock after
+ * the first turn does: the launch's own `--model` / `--effort` stand in for it (a passthrough
+ * `-- --model` / `--effort` first, as it comes last on claude's argv; else the flag, else
+ * launcher.toml), with its `--trim-mcp`, so the seat runs as the launch chose, never the default.
+ */
+export declare function createLockedInsteadOfSpawn(plan: Extract<DurableLaunchPlan, {
+    kind: "spawn";
+}>, name: string, agentId: string, launcherKey: LauncherKey, launch: {
+    model?: string;
+    effort?: string;
+    trimMcp?: boolean;
+}, d?: LockInsteadDeps & {
+    api: Pick<DurableApi, "createSession">;
+}): Promise<number>;
+/**
+ * Dogfood B5: the live lock after the first turn of a new session (lib/durable/first-turn.ts). The
+ * transcript is read under `${CLAUDE_CONFIG_DIR:-~/.claude}/projects`; the lock is the lock verb's
+ * (cwd rule, transcript slug check, executor id) under the running-session handover, so a commit
+ * freezes the attended claude, waits for the seat's hello and ends it, and the launcher's exit path
+ * attaches to the seat (C02-R26 step 7). A refusal is printed with its fix line; claude goes on.
+ */
+export declare function liveLockAfterFirstTurn(row: RegistryRow, name: string, launcherKey: LauncherKey, childAlive: () => boolean): Promise<FirstTurnLock>;