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

package/dist/durable/seat-proxy.d.ts

@@ -0,0 +1,107 @@
+import http from "node:http";
+import type { Duplex } from "node:stream";
+import { TurnOrigins } from "../turn-origin.mjs";
+import { type LockResult } from "./flock.js";
+import { type SeatIdentity, type HelloRelay } from "./seat-socket.js";
+export declare const EXIT_CONFIG = 2;
+export declare const EXIT_LOCK_HELD = 3;
+export declare const EXIT_KEY_DEAD = 4;
+/**
+ * The drop reasons and exit reasons this proxy logs (the C13 test hooks name them). These are local
+ * literals, not S1 values: S1 freezes no drop-reason or exit-reason enum (gap
+ * c3-seat-proxy-enums-not-in-s1), so other pieces cannot import them yet.
+ */
+export type DropReason = "arm_missing" | "arm_unparseable" | "unattended_hold_off" | "unattended_fence_off" | "turn_wait_timeout" | "pre_first_prompt" | "no_session";
+export type ExitReason = "fenced_exit" | "revoked_exit" | "ended_exit";
+/** The most a dead-key-status (401/409/410) body is buffered to; a longer one is dropped, never truncated. */
+export declare const DEAD_BODY_CAP: number;
+/** The largest request body forwarded (the Messages API request limit); a larger one gets a local 413. */
+export declare const REQUEST_BODY_CAP: number;
+/**
+ * Client headers that never pass: hop-by-hop, proxy-authorization and every x-mnemom-* (the proxy
+ * sets the Mnemom ones from the lease). The provider credential (authorization, x-api-key) passes:
+ * the seat carries it exactly as `mnemom agent` does (dogfood B6 ruling, superseding C13-R2/R8).
+ */
+export declare function isStrippedClientHeader(name: string): boolean;
+export interface SeatProxyArgs {
+    conversation: string;
+    agentId: string;
+    door: URL;
+    cwd: string;
+    seat: SeatIdentity | null;
+    helloRelay: string | null;
+}
+/**
+ * Parse and validate the argv after `seat-proxy`. Errors name the option, never echo a value.
+ * `isDir` and `env` are injected so the check is pure.
+ */
+export declare function parseSeatProxyArgs(argv: readonly string[], env: Record<string, string | undefined>, isDir: (p: string) => boolean): {
+    ok: true;
+    args: SeatProxyArgs;
+} | {
+    ok: false;
+    error: string;
+};
+/** The first stdin line (CR stripped), or "" on EOF / timeout. Only the first line is ever read. */
+export declare function readKeyLine(stream: NodeJS.ReadableStream, timeoutMs?: number): Promise<string>;
+/** The arm verdict for one door response: forward, or the drop reason. */
+export declare function armVerdict(pathname: string, rawHeaders: readonly string[]): {
+    forward: true;
+} | {
+    forward: false;
+    reason: DropReason;
+};
+/** The dead-key signal in a door response (C13-R7), read from the JSON body's error.type. */
+export declare function deadKeyReason(status: number, body: string): ExitReason | null;
+/** Whether a request path is origin-form and free of dot segments (raw or percent-encoded). */
+export declare function isCleanOriginForm(url: string): boolean;
+export type Route = "messages" | "count_tokens" | "hello" | "telemetry" | "refused";
+/** Where a request goes: the two model POSTs are forwarded; startup paths are answered locally. */
+export declare function routeOf(method: string, pathname: string): Route;
+export interface SeatProxyDeps {
+    log: (line: string) => void;
+    exit: (code: number) => void;
+    turns: TurnOrigins;
+    requestId?: () => string;
+    /** Overrides REQUEST_BODY_CAP (tests). */
+    requestBodyCap?: number;
+    /** Overrides DEAD_BODY_CAP (tests). */
+    deadBodyCap?: number;
+}
+export interface SeatProxyState {
+    dead: ExitReason | null;
+}
+/** The request handler of a seat proxy for `cfg` with lease key `key`. */
+export declare function createSeatProxyHandler(cfg: SeatProxyArgs, key: string, deps: SeatProxyDeps, state?: SeatProxyState): (req: http.IncomingMessage, res: http.ServerResponse) => void;
+export interface SeatProxyMainDeps {
+    env: Record<string, string | undefined>;
+    stdin: NodeJS.ReadableStream;
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    exit: (code: number) => void;
+    home: string;
+    isDir: (p: string) => boolean;
+    lock: (lockPath: string) => LockResult;
+    relayFor: (socketPath: string) => HelloRelay;
+    keyTimeoutMs?: number;
+    /** Loopback listen addresses (tests override them to exercise a failed bind). */
+    hostV4?: string;
+    hostV6?: string;
+}
+export declare function defaultMainDeps(): SeatProxyMainDeps;
+/**
+ * The 'connect' listener for a seat proxy's loopback servers: a CONNECT (a tunnel request, never
+ * origin-form) is refused with a 400 and the socket closed. Without a listener Node would drop the
+ * socket silently; this makes the refusal explicit and logged.
+ */
+export declare function refuseConnect(log: (line: string) => void): (req: http.IncomingMessage, socket: Duplex) => void;
+export interface RunningSeatProxy {
+    port: number;
+    socketPath: string;
+    close: () => Promise<void>;
+}
+/**
+ * `mnemom agent host seat-proxy …`: validate, read the key, take the conversation lock, listen,
+ * print READY. Resolves with the running proxy, or with an exit code it already passed to `exit`.
+ */
+export declare function seatProxyMain(argv: readonly string[], deps?: SeatProxyMainDeps): Promise<RunningSeatProxy | number>;