@sleep2agi/agent-network 2.3.0-preview.16 → 2.3.0-preview.160

package/dist/src/start-resource-gate.d.ts

@@ -0,0 +1,146 @@
+export declare const START_GATE_DEFAULT_MIN_MEM_MB = 4096;
+export declare const START_GATE_DEFAULT_MEM_FRACTION = 0.15;
+export declare const START_GATE_DEFAULT_MAX_LOAD_PER_CPU = 4;
+export declare const START_GATE_DEFAULT_MAX_WAIT_SEC = 600;
+export declare const START_GATE_DEFAULT_MAX_CONCURRENT = 2;
+export declare const START_GATE_SINGLE_LANE_CONCURRENT = 1;
+export declare const START_GATE_RECHECK_MS = 15000;
+/** Jitter added to each re-check while still inside the max wait: uniform [0, RECHECK_JITTER_MS). */
+export declare const START_GATE_RECHECK_JITTER_MS = 5000;
+export declare const START_GATE_WAITING_MEMORY_STATUS = "\u7B49\u5F85\u5185\u5B58";
+export declare const START_GATE_WAITING_LOAD_STATUS = "\u7B49\u5F85\u8D1F\u8F7D";
+export declare const START_GATE_WAITING_BOTH_STATUS = "\u7B49\u5F85\u5185\u5B58\u548C\u8D1F\u8F7D";
+export declare const START_GATE_WAITING_PROBE_STATUS = "\u7B49\u5F85\u8D44\u6E90\u63A2\u6D4B";
+/** #686 compatibility alias for callers that used the original memory-only status. */
+export declare const START_GATE_WAITING_STATUS = "\u7B49\u5F85\u5185\u5B58";
+export declare const START_GATE_SINGLE_LANE_STATUS = "\u5DF2\u8D85\u65F6\uFF0C\u6309\u5355\u8DEF\u653E\u884C";
+/** Logged when one waiter atomically replaces a stuck lease. The wait cap must not admit without this. */
+export declare const START_GATE_TAKEOVER_STATUS = "\u63A5\u7BA1\u5361\u6B7B\u79DF\u7EA6";
+/** Startup leases older than this are not live. ANET_START_LEASE_TTL_SEC overrides it. */
+export declare const START_GATE_LEASE_TTL_MS: number;
+/** A healthy holder renews well before the default lease expiry. */
+export declare const START_GATE_LEASE_HEARTBEAT_MS = 30000;
+/** An empty or unreadable lock younger than this is still being published, not dead. */
+export declare const START_GATE_LOCK_STALE_MS = 30000;
+/**
+ * A live matching lock is an orphan when the monotonic timestamp stored in
+ * the lock is older than this. Legacy locks with no stamp still use wall
+ * mtime, which a clock step can age out. The critical section only renames
+ * and writes a few files, so a live holder past this window is stuck.
+ */
+export declare const START_GATE_LOCK_ORPHAN_MS = 60000;
+export interface StartGateDeps {
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    /** Returns file contents, or null when unreadable. */
+    readFile?: (path: string) => string | null;
+    cpuCount?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    random?: () => number;
+    log?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    /** Hub/task text. Errors are swallowed so a report failure cannot block a start. */
+    report?: (text: string) => void;
+    /** Host lease directory. Tests must inject this; the default is ~/.anet/run/start-slots. */
+    slotsDir?: string;
+    /** Lease key. Alias is not unique across workspaces; pass the node id. */
+    nodeId?: string;
+    /** Pid written into the lease. Default: this process. */
+    holderPid?: number;
+    /** ESRCH = dead, EPERM = alive. Injected so tests never signal a real pid. */
+    isPidAlive?: (pid: number) => boolean;
+    /** /proc/<pid>/stat field 22. null means unknown — do not treat that as a mismatch. */
+    readProcessStartTicks?: (pid: number) => string | null;
+    /** Override the 15s re-check. With jitterMs 0 the single-lane retry uses this as-is. */
+    recheckMs?: number;
+    /** Override the 0–5s jitter span. 0 keeps the sleep exactly recheckMs. */
+    jitterMs?: number;
+    /** Lease lifetime. Default 10 minutes, or ANET_START_LEASE_TTL_SEC. */
+    leaseTtlMs?: number;
+    /** @internal deterministic short-TTL seam. Defaults to min(30s, TTL/3). */
+    leaseHeartbeatMs?: number;
+    /** Empty/unreadable locks younger than this are held, not dead. */
+    lockStaleMs?: number;
+    /** A live matching lock older than this is an orphan. Default 60s. */
+    lockOrphanMs?: number;
+    /**
+     * Monotonic milliseconds shared by every process on this host.
+     * Default reads /proc/uptime. null means unknown: a stamped lock is kept.
+     */
+    monotonicNow?: () => number | null;
+}
+export type StartGateOutcome = "disabled" | "unsupported" | "ok" | "waited" | "single-lane";
+export interface StartGateResult {
+    outcome: StartGateOutcome;
+    waitedMs: number;
+    checks: number;
+    /** Always callable and idempotent. Drops the lease only if this call created it. */
+    release: () => void;
+}
+export interface HostSample {
+    /** Effective free MiB: min(MemAvailable, cgroup free) when a real cgroup limit exists. */
+    memAvailableMb: number;
+    /** /proc MemAvailable, before the cgroup min. */
+    procAvailableMb: number;
+    /** Cgroup free MiB, or null when there is no real limit. */
+    cgroupFreeMb: number | null;
+    /** Cgroup limit MiB, or null when there is no real limit. The floor uses this, not the host alone. */
+    cgroupLimitMb: number | null;
+    /** 0 when MemTotal could not be read (the floor then falls back to 4096). */
+    memTotalMb: number;
+    load1: number;
+    cpuCount: number;
+}
+export interface StartGateStatusSnapshot {
+    status: string;
+    task?: string;
+}
+/** True only for blocked text owned by this gate, including single-lane wait. */
+export declare function isStartGateBlockedStatus(task: string | undefined): boolean;
+/**
+ * Once admission returns, restore the pre-gate status only if the live status
+ * is still ours. A concurrent task/status update must win over stale restore.
+ */
+export declare function startGateStatusToRestore(live: StartGateStatusSnapshot, previous: StartGateStatusSnapshot): StartGateStatusSnapshot | null;
+/** MemAvailable in MiB from /proc/meminfo text, or null. */
+export declare function parseMemAvailableMb(meminfo: string): number | null;
+/** MemTotal in MiB from /proc/meminfo text, or null. */
+export declare function parseMemTotalMb(meminfo: string): number | null;
+/** 1-minute load average from /proc/loadavg text, or null. */
+export declare function parseLoad1(loadavg: string): number | null;
+/**
+ * Field 22 of /proc/<pid>/stat (starttime, clock ticks since boot).
+ * The comm field is in parentheses and may contain spaces; everything after the
+ * last ")" is field 3 onward, so field 22 is index 19 of that tail.
+ */
+export declare function parseProcStartTicks(statText: string): string | null;
+/**
+ * Default free-memory floor. A fixed 4 GiB is too high for a small machine
+ * or a small container, so the floor is min(4 GiB, 15% of the effective total).
+ * The effective total is min(MemTotal, cgroup limit) when a real cgroup limit
+ * exists — a container must not be judged against the host's MemTotal.
+ * Missing/invalid numbers fall back to 4 GiB. ANET_START_MIN_MEM_MB replaces
+ * this when set.
+ */
+export declare function defaultStartMinMemMb(memTotalMb: number, cgroupLimitMb?: number | null): number;
+/** Reasons the host is too busy to start, empty when it is fine. */
+export declare function startGateReasons(s: HostSample, minMemMb: number, maxLoadPerCpu: number): string[];
+/** User-facing blocked status. Keep this structured instead of parsing the diagnostic reasons. */
+export declare function startGateWaitingStatus(s: HostSample | null, minMemMb: number, maxLoadPerCpu: number): string | null;
+/**
+ * Free MiB inside a real cgroup limit, or null when the limit is missing/unlimited.
+ * `memory.current` counts page cache; inactive_file (v1: total_inactive_file) is subtracted.
+ * statText null keeps the old arithmetic so existing fixtures stay valid.
+ */
+export declare function cgroupFreeMb(maxText: string, currentText: string, memTotalMb: number, statText?: string | null, v1?: boolean): number | null;
+/** Real cgroup limit in MiB, or null when the limit is missing/unlimited. */
+export declare function cgroupLimitMb(maxText: string, memTotalMb: number): number | null;
+/**
+ * Block until this host may start one heavy process.
+ * Returns a release() the caller must invoke once that process is up or has failed.
+ * Never throws (except when the injected sleep rejects — tests use that to stop a wait).
+ */
+export declare function waitForStartResources(label: string, deps?: StartGateDeps): Promise<StartGateResult>;
+/** Run `fn` while holding one start lease. Release runs on success and on failure. */
+export declare function withHeavyStartAdmission<T>(label: string, deps: StartGateDeps, fn: () => Promise<T>): Promise<T>;

package/dist/src/stopped-receipt.d.ts

@@ -0,0 +1,8 @@
+/** Capture BEFORE asynchronous manual start. Successful start supersedes only
+ * this exact receipt, without unlinking it: check-then-unlink would race another
+ * process writing a new stop. A late certificate can never supersede that new
+ * receipt, even if its JSON is identical (inode/ctime are part of identity). */
+export declare function stoppedReceiptAtStart(nodeDir: string, nodeId: unknown): () => void;
+/** Missing stop => runnable. Unreadable/unsafe/legacy stop => stay stopped.
+ * Keep the fleet boot probe's wire format in sync (Docker parity test). */
+export declare function isHubStopped(nodeDir: string, nodeId: unknown): boolean;

package/dist/src/subcommand-redirect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `anet daemon <sub>` 认不出子命令时，原先只走 `suggestSimilar`，而它的候选集
+ * 是 `["init","start","restart","up","list"]` —— **全是会改变状态的命令**。
+ *
+ * 🔴 实测（用仓里那个 `suggestSimilar` 本身跑的，不是推的）：
+ *
+ *      anet daemon rm     → 建议 "up"      想删,被指去「创建 + 启动」
+ *      anet daemon state  → 建议 "start"   想看状态,被指去「启动」
+ *      anet daemon stat   → 建议 "start"   同上
+ *      anet daemon stop   → 建议 null      (levenshtein("stop","start") = 3)
+ *
+ * 一个「你是不是想 X」的提示，把只读/销毁意图导向一个会动世界的命令，
+ * 比不给提示更贵。
+ *
+ * 而这些动作**本来就有**：daemon 就是一个 role=host_supervisor 的 agent-node，
+ * `anet daemon restart` 内部调的正是 `anet node stop` 用的那个 stopCommand()。
+ * 缺的从来不是功能，是**可发现性**。
+ */
+/** 这些是 `anet daemon` 自己的子命令 —— 它们**会改变状态**，所以任何
+ *  只读/销毁意图都不该被导向它们。测试用它做对照。 */
+export declare const DAEMON_STATE_CHANGING: readonly ["init", "start", "restart", "up"];
+export declare const PROJECT_STATE_CHANGING: readonly ["up", "restart"];
+export declare const NODE_STATE_CHANGING: readonly ["create", "start", "restart", "resume", "rename", "loop"];
+export declare const daemonSubcommandRedirect: (sub: unknown, name?: unknown) => string[] | null;
+export declare const projectSubcommandRedirect: (sub: unknown, name?: unknown) => string[] | null;
+export declare const nodeSubcommandRedirect: (sub: unknown, name?: unknown) => string[] | null;

package/dist/src/task-trace.d.ts

@@ -0,0 +1,33 @@
+export type TaskTraceTransport = "mcp_http" | "sdk_mcp_proxy" | "channel_mcp_proxy";
+export type TaskTraceStatus = "sending" | "delivered" | "failed" | "acked" | "started" | "replied" | "expired";
+export interface TaskTraceEvent {
+    event: string;
+    from_alias: string;
+    to_alias: string;
+    task_id: string | null;
+    parent_task_id: string | null;
+    network_id: string | null;
+    transport: TaskTraceTransport;
+    status: TaskTraceStatus;
+    duration_ms: number;
+    lifecycle_tracking: "tracked" | "not_tracked";
+    error_code?: string;
+    error_message?: string;
+}
+export declare function safeTaskTraceError(value: unknown): string;
+export declare function renderTaskTrace(event: TaskTraceEvent, json?: boolean): string;
+export declare function taskTraceEvent(input: Omit<TaskTraceEvent, "event">): TaskTraceEvent;
+export interface SendTaskTraceInput {
+    fromAlias: string;
+    toAlias: string;
+    parentTaskId: string | null;
+    networkId: string | null;
+    transport: TaskTraceTransport;
+    lifecycleTracking: "tracked" | "not_tracked";
+}
+export interface SendTaskTraceDependencies {
+    send: () => Promise<any>;
+    log: (line: string) => void;
+    now?: () => number;
+}
+export declare function sendTaskWithTrace(input: SendTaskTraceInput, dependencies: SendTaskTraceDependencies): Promise<any>;

package/dist/src/tmux-attach.d.ts

@@ -0,0 +1,11 @@
+export type TmuxSession = {
+    id: string;
+    name: string;
+};
+/** argv for `execTmux`: `-u list-sessions -F '#{session_id}|ANETSEP|#{session_name}'` (#533). */
+export declare const SESSION_LIST_ARGS: readonly string[];
+/** Parse SESSION_LIST_ARGS output (legacy `id\tname` rows still accepted). */
+export declare function parseTmuxSessions(output: string): TmuxSession[];
+/** Resolve by exact decoded session name, then attach by tmux's opaque ID.
+ * This avoids tmux target prefix matching and works for Unicode names. */
+export declare function findExactTmuxSession(output: string, expectedName: string): TmuxSession | null;

package/dist/src/tmux-capability.d.ts

@@ -0,0 +1,58 @@
+/** Lowest tmux version whose `new-session` understands `-e KEY=VALUE`. */
+export declare const MIN_TMUX_MAJOR = 3;
+export declare const MIN_TMUX_MINOR = 2;
+export interface TmuxVersion {
+    major: number;
+    minor: number;
+    /** Trailing letter suffix, e.g. the "a" of "3.0a". Not used for ordering. */
+    suffix: string;
+    raw: string;
+}
+/**
+ * Parse the output of `tmux -V`, e.g.:
+ *   "tmux 3.2a"        → { major: 3, minor: 2,  suffix: "a" }
+ *   "tmux 3.0a"        → { major: 3, minor: 0,  suffix: "a" }
+ *   "tmux 3.4"         → { major: 3, minor: 4,  suffix: ""  }
+ *   "tmux next-3.4"    → { major: 3, minor: 4,  suffix: ""  }
+ *   "tmux 2.9"         → { major: 2, minor: 9,  suffix: ""  }
+ *
+ * Returns null when no version can be extracted (unknown build, empty
+ * output, `tmux master` with no numbers). Callers must treat null as
+ * "unknown" and NOT as "too old" — refusing to start on an unparseable
+ * version string would break hosts whose tmux is perfectly capable.
+ */
+export declare function parseTmuxVersion(raw: string): TmuxVersion | null;
+/**
+ * True when this version's `new-session` supports `-e KEY=VALUE` (>= 3.2).
+ * Note 3.0a / 3.1c sort BELOW 3.2 — the letter suffix is a patch marker,
+ * never a minor bump, so it must not participate in the comparison.
+ */
+export declare function tmuxSupportsSessionEnv(v: TmuxVersion): boolean;
+export type TmuxCapabilityVerdict = {
+    kind: "ok";
+    version: TmuxVersion;
+} | {
+    kind: "unknown";
+    detail: string;
+} | {
+    kind: "too_old";
+    version: TmuxVersion;
+    detail: string;
+    remedy: string[];
+} | {
+    kind: "missing";
+    detail: string;
+    remedy: string[];
+};
+/**
+ * Pure decision function — `runVersionCmd` returns `tmux -V` output, or
+ * throws if tmux is absent/unrunnable. Split from the printing/exiting
+ * wrapper so tests drive every branch without a tmux binary.
+ */
+export declare function checkTmuxCapability(runVersionCmd: () => string): TmuxCapabilityVerdict;
+/**
+ * cli.ts wrapper: run the check, print an actionable message, and exit
+ * non-zero when tmux cannot carry the marker. `unknown` is deliberately
+ * permissive — we log and continue.
+ */
+export declare function assertTmuxSupportsSessionEnv(runVersionCmd: () => string, log: (msg: string) => void, fail: (msg: string) => never): void;

package/dist/src/tmux-exact-target.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Exact-match tmux target for a session name.
+ *
+ * tmux treats a leading `=` as "this exact name, no prefix matching". Names are
+ * passed to tmux as argv entries, never through a shell, so no quoting belongs
+ * here — callers that build a copy-pasteable command for a human should shell-
+ * quote the result themselves.
+ */
+export declare function exactSession(name: string): string;
+/**
+ * True when this target is already pinned to an exact session.
+ *
+ * Applying the prefix twice would look for a session literally named `=x`.
+ */
+export declare function isExactTarget(target: string): boolean;
+/** Idempotent form, for call sites that may receive either shape. */
+export declare function ensureExactSession(nameOrTarget: string): string;
+/** One row of `tmux -u list-panes -a -F PANE_LIST_FORMAT` (session, `window.pane`). */
+export interface PaneRow {
+    session: string;
+    /** `window.pane`, e.g. `0.0`. */
+    coord: string;
+}
+export declare function parsePaneRows(listOutput: string): PaneRow[];
+/**
+ * Pane target for a session, or null when that exact session has no pane.
+ *
+ * Matching is exact string equality on the session name — the whole point is to
+ * not hand tmux a name it might prefix-match, and to not hand it a `=` form it
+ * cannot resolve for non-ASCII names.
+ */
+export declare function paneTargetFor(listOutput: string, sessionName: string): string | null;
+/** The format string the two functions above expect. */
+export declare const PANE_LIST_FORMAT: string;
+/** Full argv (`-u list-panes -a -F …`) for `execTmux`; locale-proof (#533). */
+export declare const PANE_LIST_ARGS: readonly string[];

package/dist/src/tmux-format.d.ts

@@ -0,0 +1,20 @@
+/** Field separator inside a `-F` format. Printable, so tmux never rewrites it. */
+export declare const TMUX_FIELD_SEP = "|ANETSEP|";
+/** Prefix tmux argv with `-u` so its output keeps UTF-8 names in any locale. */
+export declare function tmuxUtf8Args(args: readonly string[]): string[];
+/** The `-F` format string for these fields. */
+export declare function tmuxFormat(fields: readonly string[]): string;
+/**
+ * argv for a tmux listing whose output anet parses:
+ * `tmuxListArgs(["list-sessions"], ["#{session_id}", "#{session_name}"])`
+ * → `["-u", "list-sessions", "-F", "#{session_id}|ANETSEP|#{session_name}"]`.
+ * Pass the result to `execTmux` (which adds `-S` isolation in front).
+ */
+export declare function tmuxListArgs(command: readonly string[], fields: readonly string[]): string[];
+/**
+ * Split tmux format output into rows of exactly `fieldCount` fields.
+ * Lines with a different field count are dropped (never guessed at).
+ * A line without the separator is read as a legacy TAB-separated row, so
+ * fixtures and callers that captured the old wire shape still parse.
+ */
+export declare function parseTmuxRows(output: string, fieldCount: number): string[][];

package/dist/src/tmux-pane-prompt.d.ts

@@ -0,0 +1,22 @@
+/** A prompt the watcher knows how to answer, or null. */
+export type PanePrompt = "dev-channels" | "folder-trust";
+/**
+ * Which known prompt (if any) the pane is currently blocking on.
+ *
+ * Dev-channels is checked FIRST, even though it appears second in time. The two
+ * prompts are sequential — trust, then channels — so a capture showing both
+ * means the trust prompt is already answered and only its text is still sitting
+ * in the pane. Classifying that as "folder-trust" would make a watcher that has
+ * already answered trust ignore the prompt it was waiting for, and the node
+ * would hang exactly as if the fix had never been made. Preferring the later
+ * prompt keeps a stale line of scrollback from outranking the live prompt.
+ */
+export declare function classifyPanePrompt(pane: string): PanePrompt | null;
+/**
+ * Best-effort one-line explanation of why a detached start died, taken from the
+ * dead pane's own output.
+ *
+ * Returns null when the pane holds nothing that looks like a refusal — the
+ * caller must then fall back to a generic message rather than inventing one.
+ */
+export declare function extractStartFailureReason(pane: string): string | null;

package/dist/src/tmux.d.ts

@@ -0,0 +1,44 @@
+import { type ChildProcess, type ExecFileSyncOptions, type ExecFileSyncOptionsWithBufferEncoding, type ExecFileSyncOptionsWithStringEncoding, type SpawnOptions, type SpawnSyncOptions, type SpawnSyncReturns } from "node:child_process";
+export type TmuxEnv = Record<string, string | undefined>;
+export interface TmuxIsolation {
+    /** Socket path passed to tmux as `-S`. */
+    socket: string;
+    /** Which variable asked for isolation. */
+    source: "ANET_TMUX_SOCKET" | "TMUX_TMPDIR";
+}
+export declare class TmuxKillServerRefused extends Error {
+    constructor(args: readonly string[]);
+}
+/**
+ * Where tmux should talk to, or null for "today's default behaviour".
+ * `TMUX_TMPDIR` resolves the same way tmux itself does: `$TMUX_TMPDIR/tmux-<uid>/default`.
+ */
+export declare function resolveTmuxIsolation(env?: TmuxEnv, uid?: number): TmuxIsolation | null;
+/** The socket path inside `$TMUX` (`<socket>,<server pid>,<session idx>`), or null. */
+export declare function socketOfTmuxVar(value: string | undefined): string | null;
+/**
+ * True when argv asks tmux to kill its server, including `a ; kill-server`
+ * chains and the unambiguous prefixes tmux accepts (`kill-ser`, `kill-serv`, …).
+ */
+export declare function isKillServer(args: readonly string[]): boolean;
+export interface TmuxInvocation {
+    file: "tmux";
+    args: string[];
+    /** undefined ⇒ inherit the caller's env exactly as before (no isolation requested). */
+    env: TmuxEnv | undefined;
+    isolation: TmuxIsolation | null;
+}
+/**
+ * Pure argv/env builder. Throws TmuxKillServerRefused for kill-server.
+ * `env` is the env the child would otherwise get (the caller's `options.env`,
+ * else process.env); isolation is decided from it.
+ */
+export declare function buildTmuxInvocation(args: readonly string[], env?: TmuxEnv, uid?: number): TmuxInvocation;
+/** `execFileSync("tmux", args, options)` through the #505 rules. */
+export declare function execTmux(args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding): string;
+export declare function execTmux(args: readonly string[], options?: ExecFileSyncOptionsWithBufferEncoding): Buffer;
+export declare function execTmux(args: readonly string[], options?: ExecFileSyncOptions): string | Buffer;
+/** `spawnSync("tmux", args, options)` through the #505 rules. */
+export declare function spawnSyncTmux(args: readonly string[], options?: SpawnSyncOptions): SpawnSyncReturns<string | Buffer>;
+/** `spawn("tmux", args, options)` through the #505 rules. */
+export declare function spawnTmux(args: readonly string[], options?: SpawnOptions): ChildProcess;

package/dist/src/token-cli.d.ts

@@ -0,0 +1,13 @@
+export type TokenCreateNameResult = {
+    ok: true;
+    name: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Parse only `anet token create` operands.
+ *
+ * The legacy positional form stays supported, while flag parsing is strict so
+ * a typo cannot become the name of a newly issued credential.
+ */
+export declare function parseTokenCreateName(argv: readonly string[]): TokenCreateNameResult;

package/dist/src/tool-allowlist.d.ts

@@ -0,0 +1,28 @@
+export declare const CLAUDE_KNOWN_TOOLS: readonly string[];
+type Runtime = string;
+/** Parse the comma-joined --tools string, validate each token, return the
+ * trimmed list. Runtime-scoped:
+ *
+ *   Claude-lineage → each token must be in CLAUDE_KNOWN_TOOLS OR match
+ *                    the MCP pattern (mcp__<server>__<tool>).
+ *   Other runtimes → only the basic per-token format check runs, so grok /
+ *                    codex / opencode tools flow through unchanged and get
+ *                    validated by their own downstream layers.
+ *
+ * Throws on the first offense with a message naming the bad token and,
+ * for Claude-side violations, the expected set. Never returns a
+ * partially-cleaned list — a typo must surface, not silently reshape the
+ * persisted profile.
+ */
+export declare function parseAndValidateTools(raw: string, runtime: Runtime): string[];
+/** Minimal --model validation: non-empty after trim, no whitespace inside.
+ *
+ * We do NOT enforce a known-model allowlist — models are vendor-defined,
+ * evolve independently, and a strict list would break the first time
+ * MiniMax/DeepSeek/GLM/etc. ships a new variant. This catches the obvious
+ * user-side typos (`--model " claude-3 " `, `--model ""`) without
+ * over-restricting legitimate values. Vendor-side model resolution
+ * (defaultCodexModelForRuntime etc.) already validates its own contract.
+ */
+export declare function validateModel(raw: string): string;
+export {};

package/dist/src/unsafe-package-path-reason.d.ts

@@ -0,0 +1,31 @@
+export interface PathModeFacts {
+    /** Owner uid of the path. */
+    uid: number;
+    /** Permission bits (st_mode & 0o777). */
+    mode: number;
+    /** uid of the process doing the check. */
+    processUid: number;
+}
+export type UnsafePathReason = "owner" | "group-writable" | "world-writable" | null;
+/** Which condition makes this path unsafe to execute from, if any. */
+export declare function classifyUnsafePath(facts: PathModeFacts): UnsafePathReason;
+export declare function describeUnsafePath(path: string, facts: PathModeFacts): string;
+export interface DirectoryModeFacts {
+    uid: number;
+    /** Full st_mode (the sticky bit 0o1000 matters here). */
+    mode: number;
+    processUid: number;
+    /** Is this the package root itself or one of its ancestors? Only changes the wording. */
+    ancestorOf?: string;
+}
+/**
+ * #535 (audit P1-2) — the DIRECTORY branch of the agent-node package check used
+ * to throw a bare "unsafe ownership or mode" with no path at all. In the audit
+ * the offender was an ANCESTOR, `/tmp` (1777), because the npx cache lived
+ * under a HOME in /tmp — and nothing in the message said so.
+ *
+ * Names the exact directory, what is wrong with it, and the command that fixes
+ * it. For a sticky world-writable directory (/tmp-like) the fix is NOT chmod —
+ * changing /tmp breaks the machine — but moving the npm cache out from under it.
+ */
+export declare function describeUnsafeDirectory(path: string, facts: DirectoryModeFacts): string;

package/dist/src/upgrade-channel.d.ts

@@ -0,0 +1,31 @@
+export type ReleaseChannel = "preview" | "latest";
+export interface DistTags {
+    latest?: string | null;
+    preview?: string | null;
+}
+export type ChannelResolution = {
+    ok: true;
+    channel: ReleaseChannel;
+    source: "flag" | "detected";
+    reason: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface ResolveUpgradeChannelInput {
+    /** Installed anet version (full string, prerelease preserved). */
+    installed: string | null | undefined;
+    /** Value of `--channel`. `"true"` means the flag was given without a value. */
+    flag?: string | null;
+    /** dist-tags of @sleep2agi/agent-network, or null when the lookup failed. */
+    distTags: DistTags | null;
+}
+interface ParsedSemver {
+    core: [number, number, number];
+    pre: string[];
+}
+export declare function parseSemver(version: string | null | undefined): ParsedSemver | null;
+/** semver §11 precedence. Returns <0, 0, >0. */
+export declare function compareSemver(a: ParsedSemver, b: ParsedSemver): number;
+export declare function resolveUpgradeChannel(input: ResolveUpgradeChannelInput): ChannelResolution;
+export {};

package/dist/src/win-launcher.d.ts

@@ -0,0 +1,20 @@
+import { type ExecFileSyncOptions, type ExecFileSyncOptionsWithStringEncoding, type SpawnOptions } from "child_process";
+/** Windows needs a command interpreter to run a .cmd; POSIX runs the file. */
+export declare function launcherNeedsShell(platform?: NodeJS.Platform): boolean;
+/**
+ * Quote one argument for `cmd.exe /c`.
+ *
+ * cmd's rules are not the shell's: a double quote is escaped by doubling it,
+ * and the metacharacters below must be quoted or cmd will act on them. Anything
+ * safe is left bare, so the common case stays readable in a process listing.
+ */
+export declare function quoteForCmd(arg: string): string;
+/** The argv to hand to execFile/spawn so `cmd args…` runs on this platform. */
+export declare function launcherArgv(cmd: string, args: readonly string[], platform?: NodeJS.Platform, comspec?: string | undefined): {
+    file: string;
+    argv: string[];
+};
+export declare function runLauncherSync(cmd: string, args: readonly string[], options: ExecFileSyncOptionsWithStringEncoding): string;
+export declare function runLauncherSync(cmd: string, args: readonly string[], options?: ExecFileSyncOptions): Buffer;
+/** spawn for a launcher, correct on Windows. */
+export declare function spawnLauncher(cmd: string, args: readonly string[], options?: SpawnOptions): import("node:child_process").ChildProcess;

package/dist/src/windows-codex-copresence.d.ts

@@ -0,0 +1,60 @@
+export type WindowsCopresenceRole = "appsrv" | "bridge";
+export interface WindowsManagedProcess {
+    role: WindowsCopresenceRole;
+    pid: number;
+    creationDate: string;
+    logPath: string;
+}
+export interface WindowsCopresenceRecord {
+    version: 1 | 2;
+    nodeId: string;
+    createdAt: string;
+    marker?: string;
+    processes: WindowsManagedProcess[];
+}
+export declare function windowsCopresenceRecordPath(nodesDir: string, nodeId: string): string;
+export declare function windowsCopresenceLogPath(nodesDir: string, nodeId: string, role: WindowsCopresenceRole): string;
+export declare function openPrivateAppendLog(path: string): number;
+/** Protect credential-bearing state with native Windows ACLs. */
+export declare function ensureWindowsPrivateDirectory(path: string): void;
+export declare function closeLog(fd: number): void;
+export type CreationDateProbe = (pid: number) => string | null;
+/** Uses CIM instead of locale-dependent tasklist output. */
+export declare function probeWindowsCreationDate(pid: number): string | null;
+/**
+ * Attribute an ESTABLISHED loopback connection to the launched TUI process
+ * tree. This is deliberately stronger than counting listeners/connections:
+ * an unrelated local client cannot satisfy it.
+ */
+export declare function probeWindowsOwnedLoopbackConnection(rootPid: number, expectedCreationDate: string, port: number, runPowerShell?: (script: string) => string): boolean;
+/**
+ * #1342 —— 只在健康检查**即将失败**时跑一次,用来回答一个此前没人量过的问题:
+ * 那 10.5 秒到底花在 **PowerShell 启动**上,还是花在 `Get-CimInstance Win32_Process`
+ * 这个全表查询上?
+ *
+ * 实测背景(由 #1628/#1637 加的 probeMs 量到,2026-08-31):
+ *   probes=1  waited=10897ms  probeMsLast=10490   ← 单次探测吃掉 96% 的预算
+ * 而 #1636 把全表枚举提到循环外之后这个数**没有变小**(9963 → 10490),
+ * 说明成本不在"重复枚举",而在那一次调用本身。但"那一次调用"包含两段:
+ * 起一个 powershell 进程,和在里面跑 CIM 查询。**这两段要查的东西完全不同** ——
+ * 前者是 runner/镜像的问题,后者是查询写法的问题。
+ *
+ * 🔴 这里跑的是一个**什么都不做**的脚本(`'x'`),所以它测到的就是启动那一段的下界。
+ *    只在失败路径调用一次,不进探测循环 —— 不给正常路径增加任何成本,
+ *    也**不可能**改变探测的返回值。
+ *
+ * 拿不到就返回 null(未知),不返回 0 —— 0 会被读成「启动不花时间」。
+ */
+export declare function measurePowerShellStartupMs(): number | null;
+export declare function writeWindowsCopresenceRecord(nodesDir: string, nodeId: string, processes: WindowsManagedProcess[], marker?: string): void;
+export declare function readWindowsCopresenceRecord(nodesDir: string, nodeId: string): WindowsCopresenceRecord | null;
+export interface WindowsStopDecision {
+    safe: WindowsManagedProcess[];
+    refused: Array<{
+        process: WindowsManagedProcess;
+        reason: "missing" | "pid-reused";
+    }>;
+}
+/** PID alone is never authority: Windows reuses PIDs, so CreationDate must match. */
+export declare function decideWindowsManagedStop(record: WindowsCopresenceRecord, probe: CreationDateProbe): WindowsStopDecision;
+export declare function taskkillWindowsProcessTree(pid: number): void;