@zswarm/core 0.1.6 → 0.1.8

package/dist/ops/serve.d.ts

@@ -1,14 +1,87 @@
+import { type Server, type Socket } from "node:net";
+import { type NetworkInterfacesFn, type ServeBindDeps, type TailscaleStatusRunner } from "./serve-bind.js";
 import type { OpsResult } from "./types.js";
 export declare const DEFAULT_SERVE_LISTEN = "127.0.0.1:9419";
 export declare const SERVE_TASK_NAME = "zswarm-serve";
 /** One JSONL request; a client that never sends newline cannot grow forever. */
 export declare const SERVE_MAX_REQUEST_BYTES: number;
+/**
+ * Zellij `execFile` capture budget (`maxBuffer`). `dump --max 0` can return
+ * that much pane text; serve JSONL is UTF-8 and may expand (newlines → `\n`).
+ */
+export declare const SERVE_CAPTURE_BUDGET_BYTES: number;
+/**
+ * Ordinary JSONL reply cap, UTF-8 bytes of the complete frame including the
+ * terminating newline. Sized for an 8MiB capture with newline escaping (2×)
+ * plus envelope slack. Not a silent truncate: over-cap fails with
+ * `serve_protocol`. Override with `ZSWARM_SERVE_MAX_REPLY_BYTES`.
+ */
+export declare const SERVE_MAX_REPLY_BYTES: number;
+/** Hello is a small control reply; keep it independent of dump-sized ops. */
+export declare const SERVE_MAX_HELLO_BYTES: number;
 /** Drop a socket that never finishes a JSONL line. */
 export declare const SERVE_IDLE_TIMEOUT_MS = 30000;
 /** Concurrent TCP clients, including in-flight wait ops. */
 export declare const SERVE_MAX_CONNECTIONS = 32;
 /** Wait/await allow 15 minutes; this is that plus slack. */
 export declare const SERVE_CALL_TIMEOUT_CAP_MS: number;
+/** TCP connect is bounded even when the op wait budget is long. */
+export declare const SERVE_CONNECT_TIMEOUT_MS = 15000;
+/** Hello probe wait is bounded within the overall deadline. */
+export declare const SERVE_HELLO_TIMEOUT_MS = 15000;
+/** Wire protocol number returned by hello. */
+export declare const SERVE_PROTOCOL = 1;
+export declare const SERVE_CONTROL_FIELD = "serveControl";
+export declare const SERVE_HELLO_CONTROL = "hello";
+export declare const SERVE_CAPABILITY_HELLO = "hello";
+/** Per-launch identity for Windows install verification. Additive hello field. */
+export declare const SERVE_LAUNCH_ID_ENV = "ZSWARM_SERVE_LAUNCH_ID";
+/** Package version baked into the Windows logon-task command so upgrades restart. */
+export declare const SERVE_CORE_VERSION: string;
+export type ServePhase = "connect" | "hello" | "request";
+/** Conservative: `uncertain` means a request was written and no complete reply arrived. */
+export type ServeDelivery = "not_sent" | "uncertain" | "replied";
+export type ServeErrorDetails = {
+    phase: ServePhase;
+    endpoint: string;
+    delivery: ServeDelivery;
+    remedy: string;
+};
+export type ServeCapability = typeof SERVE_CAPABILITY_HELLO;
+export type ServeHelloData = {
+    protocol: number;
+    serverId: string;
+    hostname: string;
+    platform: string;
+    version: string;
+    capabilities: string[];
+    /** Present when the process was started with `ZSWARM_SERVE_LAUNCH_ID`. */
+    launchId?: string;
+};
+export type ProbeServeOptions = {
+    token?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+export type CallServeOptions = {
+    timeoutMs?: number;
+    token?: string;
+    signal?: AbortSignal;
+    maxReplyBytes?: number;
+    connectTimeoutMs?: number;
+};
+export declare const SERVE_REMEDY: {
+    readonly connect: "Check that zswarm serve is running and the tunnel still forwards to this endpoint. Serve does not fall back to SSH.";
+    readonly unauthorized: "Set the same ZSWARM_SERVE_TOKEN on the server and this caller.";
+    readonly helloUnsupported: "This endpoint does not speak serve hello (protocol 1). Upgrade zswarm serve. Ordinary commands still work without probing hello first.";
+    readonly incompatible: "This serve protocol is not supported by this client. Upgrade zswarm on both sides.";
+    readonly protocol: "The endpoint returned a malformed or unexpected serve reply. Do not echo or retry blindly.";
+    readonly timeoutConnect: "The TCP connection did not complete in time. Check the tunnel and that zswarm serve is listening.";
+    readonly timeoutHello: "Connected but serve hello did not finish. Check the tunnel; do not treat this as a completed command.";
+    readonly timeoutRequest: "The request was sent but no reply arrived. Treat the remote outcome as uncertain; do not retry automatically.";
+    readonly incomplete: "The connection closed before a complete reply. If a request was already sent, treat the remote outcome as uncertain; do not retry automatically.";
+    readonly cancelled: "The caller cancelled this serve call. If a request was already sent, treat the remote outcome as uncertain; do not retry automatically.";
+};
 export declare function isLoopbackHost(host: string): boolean;
 export declare function formatListenLabel(host: string, port: number): string;
 export declare function parseListenAddress(raw: string | undefined): {
@@ -21,38 +94,33 @@ export declare function serveCallTimeout(args: Record<string, unknown>): number;
 /** Env for a serve worker: talk to the local Zellij, never loop back into serve/ssh. */
 export declare function serveChildEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export type ServeDispatch = (args: Record<string, unknown>) => Promise<OpsResult>;
-export type StartServeOptions = {
+export type StartServeOptions = ServeBindDeps & {
     token?: string;
     maxRequestBytes?: number;
     idleTimeoutMs?: number;
     maxConnections?: number;
+    /** Additive hello field; omitted on ordinary foreground `serve --listen`. */
+    launchId?: string;
+    /**
+     * Test seam for the TCP listener. Production uses `node:net` createServer.
+     * Bind failures must surface without falling back to another address.
+     */
+    createServer?: (connectionListener?: (socket: Socket) => void) => Pick<Server, "listen" | "close" | "on" | "address">;
 };
 export declare function startServe(listen: string | undefined, dispatch: ServeDispatch, options?: StartServeOptions): Promise<{
     label: string;
     close: () => Promise<void>;
 }>;
+export type { NetworkInterfacesFn, TailscaleStatusRunner };
+/** Direct host:port / tcp:// only. ssh:// URIs are resolved by serve-tunnel. */
 export declare function parseServeTarget(raw: string): {
     host: string;
     port: number;
 };
-export declare function callServe(target: string, args: Record<string, unknown>, timeoutMs?: number, token?: string): Promise<OpsResult>;
+/** CLI/MCP inherit `process.env`; a positive integer overrides the default reply cap. */
+export declare function serveMaxReplyBytes(env?: NodeJS.ProcessEnv): number;
+export declare function callServe(target: string, args: Record<string, unknown>, timeoutMsOrOptions?: number | CallServeOptions, token?: string, signal?: AbortSignal): Promise<OpsResult>;
+/** Authenticated hello probe. Never reports a legacy or incompatible endpoint as healthy. */
+export declare function probeServe(target: string, options?: ProbeServeOptions): Promise<OpsResult>;
 export declare function redactServeSecret(command: string, token: string): string;
-export declare function serveLogonCommand(execPath: string, scriptPath: string, listen: string, token?: string): string;
-export declare function installServeLogon(input: {
-    listen?: string;
-    execPath?: string;
-    scriptPath?: string;
-    platform?: NodeJS.Platform;
-    token?: string;
-    env?: NodeJS.ProcessEnv;
-}): Promise<{
-    task: string;
-    listen: string;
-    command: string;
-}>;
-export declare function uninstallServeLogon(input?: {
-    platform?: NodeJS.Platform;
-}): Promise<{
-    task: string;
-    cleared: true;
-}>;
+export declare function serveLogonCommand(execPath: string, scriptPath: string, listen: string, token?: string, extraEnv?: Record<string, string>): string;