@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/control-client.js

@@ -0,0 +1,792 @@
+import { open } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { isDaemonCoreCompatible, parseDaemonStatus, } from "@rynx-ai/protocol/remote-runtime";
+import { parseRemoteRuntimeRpcRequest, parseRemoteRuntimeRpcResponseForMethod, REMOTE_RUNTIME_RPC_MAX_FRAME_BYTES, REMOTE_RUNTIME_RPC_METHOD_METADATA, } from "@rynx-ai/protocol/remote-runtime-rpc";
+import { parsePairingOffer, } from "@rynx-ai/protocol/direct-runtime";
+import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_ENV, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_CONTEXT_FILE_ENV, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_SESSION_ID_ENV, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, parseRuntimeBrowserEndpointDescriptor, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+import { parseRuntimeBrowserStateGetParams } from "@rynx-ai/protocol/runtime-browser";
+import { ensureDaemonControlEndpoint } from "./control-endpoint.js";
+export { connectResidentDesktopBrowserHost, } from "./desktop-browser-host-client.js";
+const IDENTITY_TIMEOUT_MS = 5_000;
+const RUNTIME_STATUS_TIMEOUT_MS = 5_000;
+const PLUGIN_CLI_TIMEOUT_MS = 120_000;
+const PLUGIN_CLI_BODY_MAX_BYTES = 512 * 1024;
+const PLUGIN_CLI_STDIN_MAX_BYTES = 256 * 1024;
+const PLUGIN_CLI_ARG_MAX_BYTES = 4 * 1024;
+const PLUGIN_CLI_ARGS_TOTAL_MAX_BYTES = 32 * 1024;
+const PLUGIN_CLI_ARGS_MAX_COUNT = 64;
+const IDENTITY_RESPONSE_MAX_BYTES = 16 * 1024;
+const RUNTIME_STATUS_RESPONSE_MAX_BYTES = 64 * 1024;
+const REMOTE_RUNTIME_ADMIN_RESPONSE_MAX_BYTES = 64 * 1024;
+const RUNTIME_TARGET_RESPONSE_MAX_BYTES = 128 * 1024;
+const RUNTIME_TARGET_REQUEST_MAX_BYTES = 64 * 1024;
+const RUNTIME_TARGET_TIMEOUT_MS = 30_000;
+const RESIDENT_RUNTIME_CALL_TIMEOUT_MS = 135_000;
+const RESIDENT_RUNTIME_CALL_RESPONSE_MAX_BYTES = REMOTE_RUNTIME_RPC_MAX_FRAME_BYTES;
+const RUNTIME_BROWSER_BOOTSTRAP_TIMEOUT_MS = 5_000;
+const RUNTIME_BROWSER_BOOTSTRAP_RESPONSE_MAX_BYTES = 16 * 1_024;
+const RUNTIME_BROWSER_CONTEXT_MAX_BYTES = 4 * 1_024;
+const RUNTIME_BROWSER_CONTEXT_PATH_MAX_CHARS = 4_096;
+const PLUGIN_CLI_RESPONSE_MAX_BYTES = 4 * 1024 * 1024;
+const INSTALLATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PLUGIN_ID_PATTERN = /^[a-z][a-z0-9-]{0,62}$/;
+/** Stable error returned by the resident daemon's typed Runtime gateway. */
+export class ResidentRuntimeCallError extends Error {
+    code;
+    status;
+    outcome;
+    constructor(code, message, status, options) {
+        super(message, options);
+        this.code = code;
+        this.status = status;
+        this.name = "ResidentRuntimeCallError";
+        this.outcome = options?.outcome;
+    }
+}
+/** Connect to the one resident daemon, starting its supervisor when absent. */
+export async function ensureResidentDaemon() {
+    const endpoint = await ensureDaemonControlEndpoint();
+    return { origin: endpoint.origin };
+}
+/** Read the stable public identity of the single resident daemon. */
+export async function getResidentDaemonIdentity() {
+    const endpoint = await ensureDaemonControlEndpoint();
+    assertLoopbackOrigin(endpoint.origin);
+    const response = await fetch(`${endpoint.origin}/api/internal/daemon/identity`, {
+        headers: managementHeaders(endpoint.managementToken),
+        signal: AbortSignal.timeout(IDENTITY_TIMEOUT_MS),
+    });
+    const body = await readBoundedResponse(response, IDENTITY_RESPONSE_MAX_BYTES);
+    if (!response.ok)
+        throw daemonRequestError("daemon identity request", response.status, body);
+    const parsed = parseJsonObject(body, "daemon returned an invalid identity response");
+    if (!INSTALLATION_ID_PATTERN.test(readString(parsed.installationId)) ||
+        parsed.algorithm !== "Ed25519" ||
+        !/^[A-Za-z0-9_-]+$/.test(readString(parsed.publicKey)) ||
+        readString(parsed.publicKey).length > 512) {
+        throw new Error("daemon returned an invalid identity response");
+    }
+    return {
+        installationId: parsed.installationId,
+        algorithm: "Ed25519",
+        publicKey: parsed.publicKey,
+    };
+}
+/** Read the transport-independent status of the resident daemon process. */
+export async function getResidentDaemonRuntimeStatus() {
+    const endpoint = await ensureDaemonControlEndpoint();
+    assertLoopbackOrigin(endpoint.origin);
+    const response = await fetch(`${endpoint.origin}/api/internal/daemon/runtime-status`, {
+        headers: managementHeaders(endpoint.managementToken),
+        signal: AbortSignal.timeout(RUNTIME_STATUS_TIMEOUT_MS),
+    });
+    const body = await readBoundedResponse(response, RUNTIME_STATUS_RESPONSE_MAX_BYTES);
+    if (!response.ok)
+        throw daemonRequestError("daemon Runtime status request", response.status, body);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new Error("daemon returned an invalid Remote Runtime status response");
+    }
+    const status = parseDaemonStatus(parsed);
+    if (!isDaemonCoreCompatible(status)) {
+        throw new Error(`resident daemon Remote Runtime Core protocol range ` +
+            `[${status.minimumCompatibleCoreVersion}, ${status.coreProtocolVersion}] is incompatible`);
+    }
+    return status;
+}
+/** Create one pairing offer on the resident daemon for a selected reachable route. */
+export async function createResidentRemoteRuntimePairingOffer(input = {}) {
+    const endpoint = await ensureDaemonControlEndpoint();
+    assertLoopbackOrigin(endpoint.origin);
+    const response = await fetch(`${endpoint.origin}/api/internal/remote-runtime/pairing-offers`, {
+        method: "POST",
+        headers: {
+            ...managementHeaders(endpoint.managementToken),
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(input),
+        signal: AbortSignal.timeout(RUNTIME_STATUS_TIMEOUT_MS),
+    });
+    const body = await readBoundedResponse(response, REMOTE_RUNTIME_ADMIN_RESPONSE_MAX_BYTES);
+    if (!response.ok)
+        throw daemonRequestError("pairing offer request", response.status, body);
+    try {
+        return parsePairingOffer(JSON.parse(body));
+    }
+    catch (error) {
+        throw new Error(`daemon returned an invalid Remote Runtime pairing offer: ${messageOf(error)}`);
+    }
+}
+/** List redacted client grants accepted by the resident daemon. */
+export async function listResidentRemoteRuntimeClients() {
+    const endpoint = await ensureDaemonControlEndpoint();
+    assertLoopbackOrigin(endpoint.origin);
+    const response = await fetch(`${endpoint.origin}/api/internal/remote-runtime/clients`, {
+        headers: managementHeaders(endpoint.managementToken),
+        signal: AbortSignal.timeout(RUNTIME_STATUS_TIMEOUT_MS),
+    });
+    const body = await readBoundedResponse(response, REMOTE_RUNTIME_ADMIN_RESPONSE_MAX_BYTES);
+    if (!response.ok)
+        throw daemonRequestError("Remote Runtime clients request", response.status, body);
+    const parsed = parseJsonObject(body, "daemon returned an invalid Remote Runtime clients response");
+    if (!Array.isArray(parsed.clients)) {
+        throw new Error("daemon returned an invalid Remote Runtime clients response");
+    }
+    return parsed.clients.map(parseRemoteRuntimeClientGrant);
+}
+/** Revoke one resident-daemon client grant and close its active channels. */
+export async function revokeResidentRemoteRuntimeClient(grantId) {
+    if (!OPAQUE_ID_PATTERN.test(grantId) || grantId.length > 256) {
+        throw new Error("invalid Remote Runtime grant id");
+    }
+    const endpoint = await ensureDaemonControlEndpoint();
+    assertLoopbackOrigin(endpoint.origin);
+    const response = await fetch(`${endpoint.origin}/api/internal/remote-runtime/clients/${encodeURIComponent(grantId)}`, {
+        method: "DELETE",
+        headers: managementHeaders(endpoint.managementToken),
+        signal: AbortSignal.timeout(RUNTIME_STATUS_TIMEOUT_MS),
+    });
+    const body = await readBoundedResponse(response, REMOTE_RUNTIME_ADMIN_RESPONSE_MAX_BYTES);
+    if (!response.ok)
+        throw daemonRequestError("Remote Runtime client revoke", response.status, body);
+    const parsed = parseJsonObject(body, "daemon returned an invalid client revoke response");
+    if (parsed.revoked !== true ||
+        !Number.isSafeInteger(parsed.closedConnections) ||
+        parsed.closedConnections < 0) {
+        throw new Error("daemon returned an invalid client revoke response");
+    }
+    return { revoked: true, closedConnections: parsed.closedConnections };
+}
+/** List local and paired Runtime targets through the resident daemon BFF. */
+export async function listResidentRuntimeTargets() {
+    const response = await runtimeTargetRequest("/api/internal/runtimes", { method: "GET" });
+    const parsed = parseJsonObject(response, "daemon returned an invalid Runtime target list");
+    if (!Array.isArray(parsed.runtimes)) {
+        throw new Error("daemon returned an invalid Runtime target list");
+    }
+    return parsed.runtimes.map(parseRuntimeTargetView);
+}
+/** Pair a target; the offer remains inside the loopback management request. */
+export async function pairResidentRuntimeTarget(offer, displayName) {
+    const body = JSON.stringify({ offer, ...(displayName ? { displayName } : {}) });
+    if (Buffer.byteLength(body, "utf8") > RUNTIME_TARGET_REQUEST_MAX_BYTES) {
+        throw new Error(`Runtime target pairing request exceeds ${RUNTIME_TARGET_REQUEST_MAX_BYTES} bytes`);
+    }
+    const response = await runtimeTargetRequest("/api/internal/runtimes/pair", {
+        method: "POST",
+        body,
+    });
+    return parseRuntimeTargetResult(response, "pairing");
+}
+export async function testResidentRuntimeTarget(selector) {
+    const normalized = validRuntimeSelector(selector);
+    const response = await runtimeTargetRequest(`/api/internal/runtimes/${encodeURIComponent(normalized)}/test`, { method: "POST", body: "{}" });
+    return parseRuntimeTargetResult(response, "test");
+}
+export async function forgetResidentRuntimeTarget(daemonId) {
+    const normalized = validRuntimeSelector(daemonId);
+    const response = await runtimeTargetRequest(`/api/internal/runtimes/${encodeURIComponent(normalized)}`, { method: "DELETE" });
+    const parsed = parseJsonObject(response, "daemon returned an invalid Runtime forget response");
+    if (parsed.forgotten !== true) {
+        throw new Error("daemon returned an invalid Runtime forget response");
+    }
+    return { forgotten: true };
+}
+/**
+ * Invoke one typed Runtime method through the single resident daemon.
+ *
+ * The short-lived CLI process never reads Direct credentials or opens a
+ * remote socket. The resident daemon owns target resolution, Local/Direct
+ * connection reuse, authorization and no-retry outcome semantics.
+ */
+export async function callResidentRuntime(selectorInput, method, params, options = {}) {
+    let selector;
+    try {
+        selector = validRuntimeSelector(selectorInput);
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError("invalid_target", "Runtime target selector is invalid", undefined, { cause: error, outcome: "not_started" });
+    }
+    let request;
+    try {
+        request = parseRemoteRuntimeRpcRequest({
+            type: "rpc.request",
+            id: "resident-runtime-call",
+            method,
+            params,
+        });
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError("invalid_request", `Runtime ${method} parameters are invalid`, undefined, { cause: error, outcome: "not_started" });
+    }
+    const body = JSON.stringify({ method: request.method, params: request.params });
+    if (Buffer.byteLength(body, "utf8") > REMOTE_RUNTIME_RPC_MAX_FRAME_BYTES) {
+        throw new ResidentRuntimeCallError("invalid_request", `Runtime request exceeds ${REMOTE_RUNTIME_RPC_MAX_FRAME_BYTES} bytes`, undefined, { outcome: "not_started" });
+    }
+    if (options.signal?.aborted) {
+        throw new ResidentRuntimeCallError("cancelled", "Runtime call was cancelled before it started", undefined, { cause: options.signal.reason, outcome: "not_started" });
+    }
+    const timeoutSignal = AbortSignal.timeout(RESIDENT_RUNTIME_CALL_TIMEOUT_MS);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, timeoutSignal])
+        : timeoutSignal;
+    let endpoint;
+    try {
+        endpoint = await ensureDaemonControlEndpoint({ signal });
+        signal.throwIfAborted();
+    }
+    catch (error) {
+        if (options.signal?.aborted) {
+            throw new ResidentRuntimeCallError("cancelled", "Runtime call was cancelled before it started", undefined, { cause: error, outcome: "not_started" });
+        }
+        throw new ResidentRuntimeCallError(timeoutSignal.aborted ? "deadline_exceeded" : "unreachable", timeoutSignal.aborted
+            ? "Resident daemon startup exceeded the Runtime call deadline"
+            : "Resident daemon is unavailable", undefined, { cause: error, outcome: "not_started" });
+    }
+    try {
+        assertLoopbackOrigin(endpoint.origin);
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError("protocol_error", "Resident daemon control endpoint is not loopback-only", undefined, { cause: error, outcome: "not_started" });
+    }
+    let response;
+    try {
+        response = await fetch(`${endpoint.origin}/api/internal/runtimes/${encodeURIComponent(selector)}/rpc`, {
+            method: "POST",
+            headers: {
+                ...managementHeaders(endpoint.managementToken),
+                "content-type": "application/json",
+            },
+            body,
+            signal,
+        });
+    }
+    catch (error) {
+        const neverRetry = REMOTE_RUNTIME_RPC_METHOD_METADATA[method].retryPolicy === "never";
+        if (options.signal?.aborted) {
+            throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : "cancelled", neverRetry
+                ? `Runtime may have applied ${method} before local cancellation`
+                : `Runtime ${method} was cancelled`, undefined, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+        }
+        if (isRequestTimeout(error) || timeoutSignal.aborted) {
+            throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : "deadline_exceeded", neverRetry
+                ? `Runtime may have applied ${method} before the local request timed out`
+                : `Runtime ${method} exceeded the local request deadline`, undefined, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+        }
+        throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : "unreachable", neverRetry
+            ? `Runtime may have applied ${method} before the local connection failed`
+            : "Resident Runtime request could not reach the selected target", undefined, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+    }
+    const neverRetry = REMOTE_RUNTIME_RPC_METHOD_METADATA[method].retryPolicy === "never";
+    let responseBody;
+    try {
+        responseBody = await readBoundedResponse(response, RESIDENT_RUNTIME_CALL_RESPONSE_MAX_BYTES);
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : "protocol_error", neverRetry
+            ? `Runtime may have applied ${method}, but its response was incomplete`
+            : "daemon returned an unreadable Runtime call response", response.status, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+    }
+    if (!response.ok)
+        throw parseResidentRuntimeCallError(response.status, responseBody);
+    try {
+        const envelope = parseJsonObject(responseBody, "daemon returned an invalid Runtime call response");
+        if (Object.keys(envelope).length !== 1 || !Object.hasOwn(envelope, "result")) {
+            throw new Error("Runtime result envelope is invalid");
+        }
+        const parsed = parseRemoteRuntimeRpcResponseForMethod({
+            type: "rpc.result",
+            id: "resident-runtime-call",
+            result: envelope.result,
+        }, method);
+        if (parsed.type !== "rpc.result")
+            throw new Error("expected a Runtime result");
+        return parsed.result;
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : "protocol_error", neverRetry
+            ? `Runtime may have applied ${method}, but its result was invalid`
+            : "daemon returned an invalid Runtime call result", response.status, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+    }
+}
+/** Read the current managed Session credential without exposing it in output. */
+export async function readManagedRuntimeBrowserCredential(env = process.env) {
+    const contextFile = env[RUNTIME_BROWSER_CONTEXT_FILE_ENV];
+    if (!contextFile) {
+        try {
+            return parseRuntimeBrowserBootstrapCredential({
+                sessionId: env[RUNTIME_BROWSER_SESSION_ID_ENV],
+                capability: env[RUNTIME_BROWSER_CAPABILITY_ENV],
+            });
+        }
+        catch (error) {
+            throw new Error("This command must run inside a managed Rynx Session", { cause: error });
+        }
+    }
+    if (contextFile.length > RUNTIME_BROWSER_CONTEXT_PATH_MAX_CHARS ||
+        contextFile.includes("\0") ||
+        !isAbsolute(contextFile)) {
+        throw new Error("Managed Runtime Browser context path is invalid");
+    }
+    const file = await open(contextFile, "r");
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > RUNTIME_BROWSER_CONTEXT_MAX_BYTES) {
+            throw new Error("Managed Runtime Browser context file is invalid");
+        }
+        const raw = await file.readFile({ encoding: "utf8" });
+        if (Buffer.byteLength(raw, "utf8") > RUNTIME_BROWSER_CONTEXT_MAX_BYTES) {
+            throw new Error("Managed Runtime Browser context file is too large");
+        }
+        try {
+            return parseRuntimeBrowserBootstrapCredential(JSON.parse(raw));
+        }
+        catch (error) {
+            throw new Error("Managed Runtime Browser context is invalid", { cause: error });
+        }
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Return undefined only when the process has no managed Session context at all. */
+export async function readOptionalManagedRuntimeBrowserCredential(env = process.env) {
+    if (env[RUNTIME_BROWSER_CONTEXT_FILE_ENV] === undefined &&
+        env[RUNTIME_BROWSER_SESSION_ID_ENV] === undefined &&
+        env[RUNTIME_BROWSER_CAPABILITY_ENV] === undefined)
+        return undefined;
+    return readManagedRuntimeBrowserCredential(env);
+}
+const MANAGED_BROWSER_RPC_METHODS = new Set([
+    "browser.state.get",
+    "browser.open",
+    "browser.close",
+    "browser.page.create",
+    "browser.page.close",
+    "browser.page.activate",
+    "browser.page.navigate",
+    "browser.page.back",
+    "browser.page.forward",
+    "browser.page.reload",
+]);
+/**
+ * Invoke Browser control for the caller's own managed Session. Unlike the
+ * operator Runtime gateway, this path never reads or sends daemon management
+ * authority and cannot select a remote Runtime or another Session.
+ */
+export async function callManagedRuntimeBrowser(credential, method, params, options = {}) {
+    const validatedCredential = parseRuntimeBrowserBootstrapCredential(credential);
+    let request;
+    try {
+        request = parseRemoteRuntimeRpcRequest({
+            type: "rpc.request",
+            id: "managed-session-browser",
+            method,
+            params,
+        });
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError("invalid_request", `Runtime ${method} parameters are invalid`, undefined, { cause: error, outcome: "not_started" });
+    }
+    if (!MANAGED_BROWSER_RPC_METHODS.has(request.method) ||
+        !("sessionId" in request.params) ||
+        request.params.sessionId !== validatedCredential.sessionId) {
+        throw new ResidentRuntimeCallError("unauthorized", "Managed Browser control is limited to the caller's own Session", undefined, { outcome: "not_started" });
+    }
+    const timeoutSignal = AbortSignal.timeout(RESIDENT_RUNTIME_CALL_TIMEOUT_MS);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, timeoutSignal])
+        : timeoutSignal;
+    const endpoint = await ensureDaemonControlEndpoint({ signal });
+    assertLoopbackOrigin(endpoint.origin);
+    let response;
+    try {
+        response = await fetch(`${endpoint.origin}${RUNTIME_BROWSER_RPC_PATH}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                [RUNTIME_BROWSER_SESSION_ID_HEADER]: validatedCredential.sessionId,
+                [RUNTIME_BROWSER_CAPABILITY_HEADER]: validatedCredential.capability,
+            },
+            body: JSON.stringify({ method: request.method, params: request.params }),
+            signal,
+        });
+    }
+    catch (error) {
+        const neverRetry = REMOTE_RUNTIME_RPC_METHOD_METADATA[method].retryPolicy === "never";
+        throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : timeoutSignal.aborted ? "deadline_exceeded" : "unreachable", neverRetry
+            ? `Runtime may have applied ${method} before the local connection failed`
+            : timeoutSignal.aborted
+                ? `Runtime ${method} exceeded the local request deadline`
+                : "Resident daemon is unavailable", undefined, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+    }
+    const neverRetry = REMOTE_RUNTIME_RPC_METHOD_METADATA[method].retryPolicy === "never";
+    let body;
+    try {
+        body = await readBoundedResponse(response, RESIDENT_RUNTIME_CALL_RESPONSE_MAX_BYTES);
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : "protocol_error", neverRetry
+            ? `Runtime may have applied ${method}, but its response was incomplete`
+            : "daemon returned an unreadable Runtime call response", response.status, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+    }
+    if (!response.ok)
+        throw parseResidentRuntimeCallError(response.status, body);
+    try {
+        const envelope = parseJsonObject(body, "daemon returned an invalid Runtime call response");
+        if (Object.keys(envelope).length !== 1 || !Object.hasOwn(envelope, "result")) {
+            throw new Error("Runtime result envelope is invalid");
+        }
+        const parsed = parseRemoteRuntimeRpcResponseForMethod({
+            type: "rpc.result",
+            id: "managed-session-browser",
+            result: envelope.result,
+        }, method);
+        if (parsed.type !== "rpc.result")
+            throw new Error("expected a Runtime result");
+        return parsed.result;
+    }
+    catch (error) {
+        throw new ResidentRuntimeCallError(neverRetry ? "outcome_unknown" : "protocol_error", neverRetry
+            ? `Runtime may have applied ${method}, but its result was invalid`
+            : "daemon returned an invalid Runtime call result", response.status, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
+    }
+}
+/** Resolve native CDP for the caller's own Session on this Runtime only. */
+export async function getResidentRuntimeLocalBrowserEndpoint(options = {}) {
+    const credential = options.sessionId === undefined
+        ? await readManagedRuntimeBrowserCredential(options.env)
+        : undefined;
+    const explicitSessionId = options.sessionId === undefined
+        ? undefined
+        : parseRuntimeBrowserStateGetParams({ sessionId: options.sessionId }).sessionId;
+    const timeoutSignal = AbortSignal.timeout(RUNTIME_BROWSER_BOOTSTRAP_TIMEOUT_MS);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, timeoutSignal])
+        : timeoutSignal;
+    const endpoint = await ensureDaemonControlEndpoint({ signal });
+    assertLoopbackOrigin(endpoint.origin);
+    const path = credential
+        ? RUNTIME_BROWSER_BOOTSTRAP_PATH
+        : `${RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX}/${encodeURIComponent(explicitSessionId)}/endpoint`;
+    const response = await fetch(`${endpoint.origin}${path}`, {
+        headers: credential
+            ? {
+                [RUNTIME_BROWSER_SESSION_ID_HEADER]: credential.sessionId,
+                [RUNTIME_BROWSER_CAPABILITY_HEADER]: credential.capability,
+            }
+            : managementHeaders(endpoint.managementToken),
+        signal,
+    });
+    const body = await readBoundedResponse(response, RUNTIME_BROWSER_BOOTSTRAP_RESPONSE_MAX_BYTES);
+    if (!response.ok) {
+        throw daemonRequestError("Runtime Browser endpoint request", response.status, body);
+    }
+    let descriptor;
+    try {
+        descriptor = parseRuntimeBrowserEndpointDescriptor(JSON.parse(body));
+    }
+    catch (error) {
+        throw new Error("daemon returned an invalid Runtime Browser endpoint", { cause: error });
+    }
+    if (descriptor.sessionId !== (credential?.sessionId ?? explicitSessionId)) {
+        throw new Error("daemon returned a Runtime Browser endpoint for another Session");
+    }
+    return descriptor;
+}
+/** Invoke one command declared by an installed plugin through the resident daemon. */
+export async function invokeResidentPluginCommand(pluginId, args, options = {}) {
+    validatePluginInvocation(pluginId, args, options.stdin);
+    const requestSignal = options.signal
+        ? AbortSignal.any([options.signal, AbortSignal.timeout(PLUGIN_CLI_TIMEOUT_MS)])
+        : AbortSignal.timeout(PLUGIN_CLI_TIMEOUT_MS);
+    requestSignal.throwIfAborted();
+    const endpoint = await ensureDaemonControlEndpoint({ signal: requestSignal });
+    requestSignal.throwIfAborted();
+    assertLoopbackOrigin(endpoint.origin);
+    const requestBody = JSON.stringify({
+        args,
+        ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
+    });
+    if (Buffer.byteLength(requestBody, "utf8") > PLUGIN_CLI_BODY_MAX_BYTES) {
+        throw new Error(`plugin command request exceeds ${PLUGIN_CLI_BODY_MAX_BYTES} bytes`);
+    }
+    const response = await fetch(`${endpoint.origin}/api/internal/plugins/${encodeURIComponent(pluginId)}/cli`, {
+        method: "POST",
+        headers: {
+            ...managementHeaders(endpoint.managementToken),
+            "content-type": "application/json",
+        },
+        body: requestBody,
+        signal: requestSignal,
+    });
+    const body = await readBoundedResponse(response, PLUGIN_CLI_RESPONSE_MAX_BYTES);
+    if (!response.ok)
+        throw daemonRequestError("plugin command request", response.status, body);
+    const parsed = parseJsonObject(body, "daemon returned an invalid plugin command response");
+    if (!Number.isInteger(parsed.code) ||
+        parsed.code < 0 ||
+        parsed.code > 255 ||
+        typeof parsed.stdout !== "string" ||
+        typeof parsed.stderr !== "string" ||
+        typeof parsed.truncated !== "boolean") {
+        throw new Error("daemon returned an invalid plugin command response");
+    }
+    return {
+        code: parsed.code,
+        stdout: parsed.stdout,
+        stderr: parsed.stderr,
+        truncated: parsed.truncated,
+    };
+}
+function managementHeaders(token) {
+    return { "x-rynx-management-token": token };
+}
+function assertLoopbackOrigin(origin) {
+    const hostname = new URL(origin).hostname;
+    if (hostname !== "127.0.0.1" && hostname !== "[::1]" && hostname !== "::1") {
+        throw new Error("resident daemon control endpoint is not loopback-only");
+    }
+}
+function validatePluginInvocation(pluginId, args, stdin) {
+    if (!PLUGIN_ID_PATTERN.test(pluginId))
+        throw new Error("invalid plugin id");
+    if (args.length === 0)
+        throw new Error("plugin command args must not be empty");
+    if (args.length > PLUGIN_CLI_ARGS_MAX_COUNT) {
+        throw new Error(`plugin command args exceed ${PLUGIN_CLI_ARGS_MAX_COUNT} entries`);
+    }
+    let totalBytes = 0;
+    for (const arg of args) {
+        if (typeof arg !== "string" || arg.includes("\0")) {
+            throw new Error("plugin command args must be strings without NUL bytes");
+        }
+        const bytes = Buffer.byteLength(arg, "utf8");
+        if (bytes > PLUGIN_CLI_ARG_MAX_BYTES) {
+            throw new Error(`plugin command arg exceeds ${PLUGIN_CLI_ARG_MAX_BYTES} bytes`);
+        }
+        totalBytes += bytes;
+    }
+    if (totalBytes > PLUGIN_CLI_ARGS_TOTAL_MAX_BYTES) {
+        throw new Error(`plugin command args exceed ${PLUGIN_CLI_ARGS_TOTAL_MAX_BYTES} bytes`);
+    }
+    if (stdin !== undefined && typeof stdin !== "string")
+        throw new Error("plugin command stdin must be a string");
+    if (stdin !== undefined && Buffer.byteLength(stdin, "utf8") > PLUGIN_CLI_STDIN_MAX_BYTES) {
+        throw new Error(`plugin command stdin exceeds ${PLUGIN_CLI_STDIN_MAX_BYTES} bytes`);
+    }
+}
+async function readBoundedResponse(response, maxBytes) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > maxBytes) {
+                await reader.cancel();
+                throw new Error(`daemon response exceeds ${maxBytes} bytes`);
+            }
+            chunks.push(Buffer.from(value));
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, bytes).toString("utf8");
+}
+function parseJsonObject(body, message) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall through to the stable protocol error below.
+    }
+    throw new Error(message);
+}
+function daemonRequestError(operation, status, body) {
+    let detail = body.trim().slice(0, 2_000);
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed.error === "string")
+            detail = parsed.error.slice(0, 2_000);
+    }
+    catch {
+        // A bounded plain-text error is still useful for local diagnostics.
+    }
+    return new Error(`${operation} failed (${status})${detail ? `: ${detail}` : ""}`);
+}
+const RESIDENT_RUNTIME_CALL_ERROR_CODES = new Set([
+    "invalid_target",
+    "invalid_request",
+    "not_found",
+    "conflict",
+    "failed_precondition",
+    "method_not_found",
+    "deadline_exceeded",
+    "unreachable",
+    "tls_error",
+    "identity_mismatch",
+    "incompatible",
+    "authentication_failed",
+    "protocol_error",
+    "operation_failed",
+    "outcome_unknown",
+    "cancelled",
+    "unauthorized",
+    "closed",
+    "internal",
+    "internal_error",
+]);
+function parseResidentRuntimeCallError(status, body) {
+    let code = "internal_error";
+    let outcome;
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed.error === "string" &&
+            RESIDENT_RUNTIME_CALL_ERROR_CODES.has(parsed.error)) {
+            code = parsed.error;
+        }
+        if (parsed.outcome === "not_started" || parsed.outcome === "unknown") {
+            outcome = parsed.outcome;
+        }
+    }
+    catch {
+        // Keep the stable internal_error fallback; never expose a daemon body.
+    }
+    return new ResidentRuntimeCallError(code, `Runtime call failed (${status}): ${code}`, status, { ...(outcome ? { outcome } : code === "outcome_unknown" ? { outcome: "unknown" } : {}) });
+}
+function isRequestTimeout(error) {
+    return error instanceof Error &&
+        (error.name === "TimeoutError" || error.name === "AbortError");
+}
+function readString(value) {
+    return typeof value === "string" ? value : "";
+}
+const OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/;
+function parseRemoteRuntimeClientGrant(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("daemon returned an invalid Remote Runtime client grant");
+    }
+    const record = value;
+    for (const field of ["grantId", "clientId"]) {
+        if (typeof record[field] !== "string" ||
+            record[field].length > 256 ||
+            !OPAQUE_ID_PATTERN.test(record[field])) {
+            throw new Error("daemon returned an invalid Remote Runtime client grant");
+        }
+    }
+    if (record.clientLabel !== null && typeof record.clientLabel !== "string" ||
+        typeof record.clientKeyFingerprint !== "string" ||
+        !record.clientKeyFingerprint.startsWith("SHA256:") ||
+        !Array.isArray(record.authorities) ||
+        record.authorities.length !== 1 ||
+        record.authorities[0] !== "daemon.full" ||
+        typeof record.createdAt !== "string" ||
+        !Number.isFinite(Date.parse(record.createdAt)) ||
+        record.revokedAt !== null &&
+            (typeof record.revokedAt !== "string" || !Number.isFinite(Date.parse(record.revokedAt))) ||
+        record.lastUsedAt !== null &&
+            (typeof record.lastUsedAt !== "string" || !Number.isFinite(Date.parse(record.lastUsedAt)))) {
+        throw new Error("daemon returned an invalid Remote Runtime client grant");
+    }
+    return {
+        grantId: record.grantId,
+        clientId: record.clientId,
+        clientLabel: record.clientLabel,
+        clientKeyFingerprint: record.clientKeyFingerprint,
+        authorities: ["daemon.full"],
+        createdAt: record.createdAt,
+        revokedAt: record.revokedAt,
+        lastUsedAt: record.lastUsedAt,
+    };
+}
+async function runtimeTargetRequest(pathname, input) {
+    const endpoint = await ensureDaemonControlEndpoint();
+    assertLoopbackOrigin(endpoint.origin);
+    const response = await fetch(`${endpoint.origin}${pathname}`, {
+        method: input.method,
+        headers: {
+            ...managementHeaders(endpoint.managementToken),
+            ...(input.body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(input.body === undefined ? {} : { body: input.body }),
+        signal: AbortSignal.timeout(RUNTIME_TARGET_TIMEOUT_MS),
+    });
+    const body = await readBoundedResponse(response, RUNTIME_TARGET_RESPONSE_MAX_BYTES);
+    if (!response.ok)
+        throw daemonRequestError("Runtime target request", response.status, body);
+    return body;
+}
+function parseRuntimeTargetResult(body, operation) {
+    const parsed = parseJsonObject(body, `daemon returned an invalid Runtime target ${operation} response`);
+    try {
+        return {
+            target: parseRuntimeTargetView(parsed.target),
+            status: parseDaemonStatus(parsed.status),
+        };
+    }
+    catch (error) {
+        throw new Error(`daemon returned an invalid Runtime target ${operation} response: ${messageOf(error)}`);
+    }
+}
+function parseRuntimeTargetView(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("invalid Runtime target view");
+    }
+    const record = value;
+    const selector = validRuntimeSelector(record.selector);
+    const daemonId = validRuntimeSelector(record.daemonId);
+    if (typeof record.displayName !== "string" ||
+        record.displayName.length === 0 ||
+        record.displayName.length > 128 ||
+        (record.binding !== "local" && record.binding !== "direct") ||
+        (record.endpoint !== undefined && typeof record.endpoint !== "string") ||
+        (record.identityKeyFingerprint !== undefined &&
+            (typeof record.identityKeyFingerprint !== "string" ||
+                !record.identityKeyFingerprint.startsWith("SHA256:"))) ||
+        (record.createdAt !== undefined &&
+            (typeof record.createdAt !== "string" || !Number.isFinite(Date.parse(record.createdAt))))) {
+        throw new Error("invalid Runtime target view");
+    }
+    if (record.binding === "local" && selector !== "local") {
+        throw new Error("invalid local Runtime target selector");
+    }
+    if (record.binding === "direct" && (selector !== daemonId || typeof record.endpoint !== "string")) {
+        throw new Error("invalid Direct Runtime target view");
+    }
+    return {
+        selector,
+        daemonId,
+        displayName: record.displayName,
+        binding: record.binding,
+        ...(record.endpoint === undefined ? {} : { endpoint: record.endpoint }),
+        ...(record.identityKeyFingerprint === undefined
+            ? {}
+            : { identityKeyFingerprint: record.identityKeyFingerprint }),
+        ...(record.createdAt === undefined ? {} : { createdAt: record.createdAt }),
+    };
+}
+function validRuntimeSelector(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 256 ||
+        !OPAQUE_ID_PATTERN.test(value)) {
+        throw new Error("invalid Runtime target selector");
+    }
+    return value;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}