@sleep2agi/agent-network 2.3.0-preview.18 → 2.3.0-preview.180

package/dist/src/codex-recovery-lease.d.ts

@@ -0,0 +1,39 @@
+export interface RecoveryLease {
+    release: () => void;
+}
+export interface RecoveryLeaseHolderDeps {
+    /** Register `fn` to run when the process exits; returns an unregister function.
+     * Defaults to process.on("exit"), which also covers `process.exit(1)` failure paths. */
+    onProcessExit?: (fn: () => void) => () => void;
+    log?: (message: string) => void;
+}
+export interface RecoveryLeaseHolder {
+    /** Take ownership of a lease returned by waitForCodexRecoveryResources. */
+    hold(lease: RecoveryLease): void;
+    /** Release the held lease (stops its heartbeat and drops the slot). Idempotent. */
+    release(reason?: string): void;
+    readonly held: boolean;
+}
+export declare function createRecoveryLeaseHolder(deps?: RecoveryLeaseHolderDeps): RecoveryLeaseHolder;
+export interface CopresencePieces {
+    /** `--tui-first`: restore the exact-session TUI before the bridge attaches. */
+    tuiFirst: boolean;
+    /** Piece ②: starts the bridge and resolves once it reported READY. */
+    launchBridge: () => Promise<void>;
+    /** Piece ③: starts the TUI session ("③ TUI … ready to attach"). */
+    launchTui: () => void;
+    /** Resolves once the TUI has painted a usable screen. */
+    requireTuiPainted: () => Promise<void>;
+    /** The TUI's own process tree must connect to the exact app-server; paint alone
+     * can precede WebSocket hydration and does not release the recovery lane. */
+    requireTuiConnected: () => Promise<void>;
+    /** Runs once both sessions were launched (marker refresh, liveness check). */
+    afterLaunch?: () => void;
+    /** Printed between the TUI paint and the bridge attach on the --tui-first path. */
+    announceTuiFirst?: () => void;
+    lease: RecoveryLeaseHolder;
+}
+/** Bring up the bridge and the TUI in the configured order, then release the
+ * recovery lease: the legacy resume (bridge) and the TUI hydration are the
+ * memory-heavy part the lane protects. The lease is released on failure too. */
+export declare function launchCopresencePiecesReleasingRecovery(p: CopresencePieces): Promise<void>;

package/dist/src/codex-recovery-resource-gate.d.ts

@@ -0,0 +1,15 @@
+import { waitForStartResources, type StartGateDeps, type StartGateResult } from "./start-resource-gate";
+/** A measured 500 MiB legacy recovery peaked at 8.4x its rollout size. Nine
+ * times the rollout leaves a small margin while remaining an explainable,
+ * testable admission estimate rather than pretending maxPayload bounds Codex. */
+export declare const CODEX_RECOVERY_MEMORY_MULTIPLIER = 9;
+export declare const CODEX_RECOVERY_MIN_MEMORY_MB = 4096;
+export declare function estimatedCodexRecoveryMemoryMb(rolloutBytes: number | null): number;
+export interface CodexRecoveryGateDeps extends StartGateDeps {
+    /** @internal seam: the shared start gate owns locking and stale-lease safety. */
+    gate?: typeof waitForStartResources;
+}
+/** Serialize the memory-heavy legacy resume phase and require enough effective
+ * MemAvailable for this rollout. The returned lease stays held through the
+ * launcher, bridge and TUI attachment and must then be released. */
+export declare function waitForCodexRecoveryResources(nodeId: string, rolloutBytes: number | null, deps?: CodexRecoveryGateDeps): Promise<StartGateResult>;

package/dist/src/codex-resume.d.ts

@@ -0,0 +1,89 @@
+import { type ExternalThread } from "./codex-adopt";
+import { type CollectEnv, type CodexMenuNode } from "./codex-menu";
+export type CodexResumeKind = "co-presence" | "codex-sdk";
+export interface CodexResumeFacts {
+    readonly alias: string;
+    readonly kind: CodexResumeKind;
+    /** "running" | "stopped" | "partial 1/3" (codex-menu's row.state). */
+    readonly state: string;
+    readonly running: boolean;
+    /** The CODEX_HOME the node's codex runs with (its own, or the host ~/.codex for a codex-sdk node). */
+    readonly codexHome: string;
+    readonly homeExists: boolean;
+    /** true = codex's default ~/.codex (no CODEX_HOME needed to log it in). */
+    readonly homeIsHost: boolean;
+    readonly loggedIn: boolean;
+    /** codexThreadId (co-presence) / session (codex-sdk) from the node config. */
+    readonly recordedThread: string | null;
+    /** Every rollout under `<codexHome>/sessions`, newest first. */
+    readonly threads: readonly ExternalThread[];
+}
+export interface CodexResumeRequest {
+    /** --thread <id|unique prefix> (also --session <id>, the old spelling). */
+    readonly thread?: string | null;
+    readonly pick?: boolean;
+    /** stdin and stdout are both a terminal. */
+    readonly tty: boolean;
+}
+export type CodexResumeDecision = 
+/** Nothing was done. `lines[0]` is the reason with the fix; exit with `code`. */
+{
+    readonly kind: "refuse";
+    readonly code: number;
+    readonly lines: readonly string[];
+}
+/** --pick without a terminal: the list plus a copy-paste command. Nothing was done. */
+ | {
+    readonly kind: "list";
+    readonly code: number;
+    readonly lines: readonly string[];
+}
+/** --pick in a terminal: show `lines`, ask for a number in 1..`choices.length`. */
+ | {
+    readonly kind: "ask";
+    readonly lines: readonly string[];
+    readonly choices: readonly string[];
+}
+/** Already running on exactly that thread — attach instead (exit 0). */
+ | {
+    readonly kind: "already";
+    readonly lines: readonly string[];
+}
+/** Go: record `threadId` (when `changed`) and start the node. */
+ | {
+    readonly kind: "resume";
+    readonly threadId: string;
+    readonly changed: boolean;
+    readonly rolloutPath: string;
+};
+/** How many threads the picker numbers; older ones are reachable with --thread. */
+export declare const PICK_LIMIT = 20;
+export declare function freshStartCommand(f: Pick<CodexResumeFacts, "alias" | "kind">): string;
+export declare function codexLoginCommand(f: Pick<CodexResumeFacts, "codexHome" | "homeIsHost">): string;
+/** Numbered rows: time (UTC, as codex wrote it), short id, first user line. The recorded thread is marked. */
+export declare function formatNodeThreadList(threads: readonly ExternalThread[], recorded: string | null, limit?: number): string[];
+export declare function resumeCommandFor(alias: string, threadId: string): string;
+/** The whole decision. Order: request shape → home → which thread → login → process state. */
+export declare function decideCodexResume(f: CodexResumeFacts, req: CodexResumeRequest): CodexResumeDecision;
+/** A typed answer to the picker: a number from the list; empty / q = cancel. */
+export declare function parsePickAnswer(answer: string | null, choices: readonly string[]): {
+    kind: "ok";
+    threadId: string;
+} | {
+    kind: "cancel";
+} | {
+    kind: "bad";
+    message: string;
+};
+/**
+ * `anet node codex resume` records the thread in config before its state
+ * machine runs. If the run stops before anything was touched, the old value
+ * goes back — the config must not name a thread the node is not running (#531 §5).
+ */
+export declare function resumeConfigShouldRollBack(stoppedAt: string): boolean;
+/**
+ * The facts for one node, from the same helpers the codex menu uses
+ * (collectCodexRows: kind / state / login; effectiveCodexHome: which home).
+ * Read-only. null = not a codex node.
+ */
+export declare function gatherCodexResumeFacts(node: CodexMenuNode, env: CollectEnv): CodexResumeFacts | null;

package/dist/src/codex-rollout-history-guard.d.ts

@@ -0,0 +1,84 @@
+/** First codex release that writes paginated rollouts with per-line ordinals. */
+export declare const PAGINATED_ROLLOUT_MIN_CODEX = "0.145.0";
+/** Read the first line in chunks of this size … */
+export declare const FIRST_LINE_CHUNK_BYTES: number;
+/** … and give up (do not block) when no newline shows up within this many bytes. */
+export declare const FIRST_LINE_MAX_BYTES: number;
+export declare const BOARD_REF = "board #734";
+export interface FirstLineRead {
+    /** The first line without its newline; null when it could not be read. */
+    line: string | null;
+    /** How many bytes were actually read from the file. */
+    bytesRead: number;
+    /** Why `line` is null. */
+    reason?: string;
+}
+/** Bounded read of the first line. Never reads past `maxBytes`. */
+export declare function readRolloutFirstLine(path: string, maxBytes?: number, chunkBytes?: number): FirstLineRead;
+export type HistoryModeParse = {
+    ok: true;
+    historyMode: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+/** `payload.history_mode` of the session-meta line; null when the field is absent (legacy rollout). */
+export declare function parseRolloutHistoryMode(line: string): HistoryModeParse;
+/** <0, 0, >0 — numeric `x.y.z` compare; null when either side is not a version. */
+export declare function compareVersions(a: string, b: string): number | null;
+/**
+ * Version from `codex --version` output. Only a codex-identifying token counts
+ * (`codex-cli 0.159.2`, `codex 0.145.0`): a wrapper that prints its own version
+ * first (`nvm 0.39.7`) must not be read as the codex version. No match = unknown.
+ */
+export declare function parseCodexVersionOutput(text: string | undefined | null): string | null;
+/** `<bin> --version` → `x.y.z`, cached per binary for the life of the process. */
+export declare function probeCodexVersionCached(bin: string, timeoutMs?: number): string | null;
+/**
+ * The rollout codex would resume for `threadId`, following codex's own filesystem
+ * order (codex-rs thread-store thread_rollout_resolver): `sessions/` first, newest
+ * matching file wins; `archived_sessions/` only when nothing is in `sessions/`.
+ * (codex consults its SQLite index before the filesystem; that index is not read here.)
+ * The ONE resolver every anet guard uses (co-presence launchers and agent-node).
+ */
+export declare function resolveCodexResumeRollout(codexHome: string, threadId: string): string | null;
+export interface RolloutCompatInput {
+    threadId: string;
+    /** Exact rollout path, or null when the caller could not find one. */
+    rolloutPath: string | null;
+    /** How the operator would name the binary (path or command). */
+    codexBin: string;
+    /** Parsed version of `codexBin`; null/undefined = unknown. */
+    codexVersion: string | null | undefined;
+    /** How to point THIS node at another codex (one line per option). */
+    pointAtNewerCodex: string[];
+    /** Injected for tests; defaults to the bounded reader. */
+    readFirstLine?: (path: string) => FirstLineRead;
+}
+export type RolloutCompatVerdict = {
+    verdict: "block";
+    lines: string[];
+    historyMode: string;
+    codexVersion: string;
+} | {
+    verdict: "allow";
+    historyMode: string | null;
+    codexVersion: string | null;
+} | {
+    verdict: "unknown";
+    lines: string[];
+};
+/**
+ * Decide whether starting `codexBin` on `threadId` is safe.
+ * block   — paginated rollout + codex < 0.145: starting would make the thread unresumable.
+ * allow   — legacy rollout, or codex new enough.
+ * unknown — could not tell; caller must NOT block (warn and continue as before).
+ */
+export declare function checkRolloutCodexCompat(input: RolloutCompatInput): RolloutCompatVerdict;
+export declare const MISSING_ORDINAL_RE: RegExp;
+export declare function isMissingOrdinalError(text: string): boolean;
+/** Explanation for the upstream "missing an ordinal" resume failure; [] when `text` is something else. */
+export declare function describeMissingOrdinalFailure(text: string, ctx?: {
+    threadId?: string;
+    rolloutPath?: string | null;
+}): string[];

package/dist/src/codex-tui-client-health.d.ts

@@ -0,0 +1,30 @@
+export declare function bridgeClientHealthReceipt(remote: string, threadId: string): string;
+export interface MigratedCodexPendingThread {
+    version: 1;
+    threadId: string;
+    serverUrl: string;
+    marker: string;
+}
+/**
+ * Move a crash-window deferred candidate onto the launcher's new owned
+ * app-server generation. The old URL is an authority supplied by the same
+ * private node config, not by the pending object itself; every mismatch is a
+ * hard stop so restart never guesses or adopts a second thread.
+ */
+export declare function migrateCodexPendingThread(value: unknown, oldServerUrl: unknown, expectedOldMarker: unknown, newServerUrl: string, newMarker: string): MigratedCodexPendingThread;
+export declare function requirePromotedCodexPendingThread(value: unknown, pendingThreadId: string): string;
+/**
+ * argv for the human TUI attached to the co-presence app-server.
+ *
+ * #505 — the permission override is only passed on the FRESH path. On
+ * `resume --remote <ws> <thread>` codex 0.155.1 exits immediately with
+ *   "Error: Permission overrides are not supported when resuming a remote task."
+ * (anet then reports "TUI tmux session exited during startup"). Measured in
+ * Docker against a real app-server + real thread: 0.155.1 rejects
+ * resume + --dangerously-bypass-approvals-and-sandbox and accepts it fresh
+ * (TUI up, "permissions: YOLO mode"); 0.133.0 (agent-node's pin) accepts both.
+ * Nothing is lost by dropping it on resume: the app-server itself is started
+ * with `-c approval_policy=… -c sandbox_mode=…` from the same posture.
+ */
+export declare function codexTuiLaunchArgs(remote: string, model: string, threadId?: string, dangerFullAccess?: boolean): string[];
+export declare function assertPendingServerQuiesced(serverUrl: unknown, isListening: (port: number) => boolean | Promise<boolean>): Promise<void>;

package/dist/src/commhub-response.d.ts

@@ -0,0 +1 @@
+export declare function parseCommhubToolResult(json: any): any;

package/dist/src/controlled-upload.d.ts

@@ -0,0 +1,83 @@
+/**
+ * #693 — token-bound node controlled local file → Hub /api/upload bridge.
+ *
+ * Security boundary (hard gates):
+ *  1. Cross-host: bytes travel over HTTP multipart; Hub never reads agent FS.
+ *  2. Identity: caller supplies the node's bearer token; ntok binds network.
+ *  3. Path safety: realpath + allowlisted roots; reject NUL, symlink, traversal.
+ *  4. Size ≤ 12 MiB enforced with same-fd fstat + bounded read (no full slurp).
+ *  5. Hub /api/upload is the sole write surface (atomic on hub side).
+ *
+ * Adversarial add-only (#694 DO-NOT-MERGE fixes):
+ *  - TOCTOU: open O_NOFOLLOW → fstat(fd) → read(fd) only; no re-open by path.
+ *  - Bounded read: never allocate/read past CONTROLLED_UPLOAD_MAX_BYTES.
+ *  - NUL guard is live and reachable before any fs call.
+ */
+/** Mirrors server/src/uploads.ts MAX_UPLOAD_BYTES. */
+export declare const CONTROLLED_UPLOAD_MAX_BYTES: number;
+/** Chunk size for bounded streaming read from a single fd. */
+export declare const CONTROLLED_UPLOAD_READ_CHUNK: number;
+export type ControlledUploadErrorCode = "path_required" | "path_nul" | "path_not_found" | "path_untrusted" | "path_symlink" | "path_not_regular" | "path_empty" | "payload_too_large" | "read_failed" | "auth_required" | "hub_url_required" | "upload_failed" | "bad_response" | "missing_file_id";
+export type ControlledUploadFail = {
+    ok: false;
+    error: ControlledUploadErrorCode;
+    message: string;
+};
+export type ControlledUploadOk = {
+    ok: true;
+    file_id: string;
+    name: string;
+    mime: string;
+    size: number;
+    url?: string;
+};
+export type ControlledUploadResult = ControlledUploadOk | ControlledUploadFail;
+export interface ControlledUploadDeps {
+    hubUrl: string;
+    authToken: string;
+    allowedRoots?: string[];
+    alias?: string;
+    nodeDir?: string;
+    fetch?: typeof fetch;
+    home?: string;
+}
+/** Normalize a client filename: basename only, strip controls, cap 255. */
+export declare function normalizeUploadName(input: string | undefined | null, fallback?: string): string;
+export declare function defaultControlledUploadRoots(opts?: {
+    home?: string;
+    alias?: string;
+    nodeDir?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): string[];
+/** True iff canonicalPath is strictly inside one of the allowlisted roots. */
+export declare function isPathInsideAllowedRoots(canonicalPath: string, allowedRoots: string[]): boolean;
+/**
+ * Resolve a user-supplied path to a canonical path under an allowlisted root.
+ * Does not open the file for reading — open+fstat+read is a separate same-fd step.
+ */
+export declare function resolveControlledUploadPath(rawPath: string, allowedRoots: string[]): {
+    ok: true;
+    canonicalPath: string;
+} | ControlledUploadFail;
+export type ControlledFileBytes = {
+    ok: true;
+    bytes: Buffer;
+    size: number;
+    canonicalPath: string;
+} | ControlledUploadFail;
+/**
+ * Open → fstat(fd) → bounded read(fd) on the **same fd** (TOCTOU hard gate).
+ * Uses O_NOFOLLOW when available so a symlink swap at open is rejected.
+ * Never uses path-based readFileSync after the initial open.
+ */
+export declare function openFstatBoundedReadControlledFile(canonicalPath: string, allowedRoots: string[], maxBytes?: number): ControlledFileBytes;
+/**
+ * Upload a controlled local file to Hub POST /api/upload.
+ * Returns file_id + metadata for send_reply attachments.
+ * Never falls back to sending a raw path to the Hub.
+ */
+export declare function uploadControlledLocalFile(rawPath: string, deps: ControlledUploadDeps, opts?: {
+    name?: string;
+    mime?: string;
+}): Promise<ControlledUploadResult>;

package/dist/src/copresence-deps.d.ts

@@ -0,0 +1,22 @@
+export interface CopresenceDep {
+    readonly name: string;
+    readonly present: boolean;
+    /** Exact command for this platform, or null when we cannot name one. */
+    readonly install: string | null;
+    readonly why: string;
+}
+export type CommandProbe = (cmd: string) => boolean;
+/** Which agent binary this co-presence lane is built on. */
+export type CopresenceAgent = "codex" | "grok";
+export declare function copresenceDeps(probe: CommandProbe, platform?: NodeJS.Platform, agent?: CopresenceAgent): CopresenceDep[];
+export declare function missingCopresenceDeps(probe: CommandProbe, platform?: NodeJS.Platform, agent?: CopresenceAgent): CopresenceDep[];
+/** One block naming every gap and how to close it — never one gap at a time. */
+export declare function describeMissingDeps(missing: readonly CopresenceDep[], displayName: string): string;
+/**
+ * May we start this hub ourselves?
+ *
+ * Only a loopback hub. A remote URL that refuses the connection is somebody
+ * else's service — spawning a local one would silently point the node at a
+ * DIFFERENT hub than its profile names, which is worse than failing.
+ */
+export declare function isLoopbackHub(hubUrl: string): boolean;