@agent-device/proxy 0.0.0-stage → 0.21.23

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Callstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @agent-device/proxy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The proxy behind `agent-device proxy`, as a library. Embed it in your own gateway to give remote
+`agent-device` clients access to a daemon on another machine, over whichever transport you choose.
+
+The proxy:
+
+- authenticates clients with a token you choose, and never exposes the daemon's own token;
+- forwards only the routes a remote client needs: `/health`, `/rpc`, uploads, artifacts, and
+  request diagnostics;
+- refuses install sources that name a file on the daemon host;
+- rewrites upload tickets so clients upload through the proxy, not to the daemon directly.
+
+Requires Node.js 22.12 or later.
+
+## Install
+
+```bash
+npm install @agent-device/proxy
+```
+
+Keep its version close to the daemon behind it. Clients refuse a proxy whose daemon speaks a
+different RPC protocol version, before any command runs.
+
+## Serve the proxy over HTTP
+
+```ts
+import { createDaemonProxyServer } from '@agent-device/proxy';
+
+const server = createDaemonProxyServer({
+  upstreamBaseUrl: 'http://127.0.0.1:4310',
+  upstreamToken: process.env.AGENT_DEVICE_DAEMON_TOKEN!,
+  clientToken: process.env.GATEWAY_CLIENT_TOKEN!,
+});
+server.listen(8080);
+```
+
+Clients connect with `agent-device connect proxy --daemon-base-url https://gateway.example.com/agent-device`
+and `AGENT_DEVICE_DAEMON_AUTH_TOKEN` set to `clientToken`.
+
+To mount the proxy in an existing `node:http` or `node:https` server, use
+`createDaemonProxyRequestListener(createDaemonProxy(options))`.
+
+## Bring your own transport
+
+`createDaemonProxy` has no server of its own. It answers standard `Request` objects with standard
+`Response` objects, so any Node.js-compatible runtime or framework that speaks the Fetch API can
+host it:
+
+```ts
+import { createDaemonProxy } from '@agent-device/proxy';
+
+const proxy = createDaemonProxy({
+  upstreamBaseUrl: 'http://127.0.0.1:4310',
+  upstreamToken: daemonToken,
+  clientToken,
+});
+
+// A fetch-style server entry, as used by Bun and by Hono on Node.js
+export default { fetch: proxy.handle };
+```
+
+For a WebSocket or other message transport, turn each incoming message into a `Request` and send
+the `Response` back. Three things the proxy relies on:
+
+- `request.url` is the URL the client used. Upload tickets point clients at its origin. An
+  `x-forwarded-proto` header overrides the scheme.
+- `request.signal` aborts when the client goes away. The proxy then cancels the daemon request, so
+  work the client stopped waiting for does not keep running.
+- Response bodies stream. Artifact downloads can be large, so forward the body as it arrives.
+
+`handle` never rejects. Errors come back as JSON responses with a 4xx or 5xx status, except a route
+the proxy does not serve, which gets a plain `Not found` 404.
+
+### Reach the daemon over your own transport
+
+By default the proxy calls the daemon with the global `fetch`. Pass `upstreamFetch` when the daemon
+is only reachable some other way, such as a tunnel the device host opened to your gateway:
+
+```ts
+const proxy = createDaemonProxy({
+  upstreamBaseUrl: 'http://device-host-17.internal',
+  upstreamToken: daemonToken,
+  clientToken,
+  upstreamFetch: (request) => deviceHostTunnel.send(request),
+});
+```
+
+`upstreamFetch` receives a `Request` addressed to `upstreamBaseUrl` and must resolve with the
+daemon's `Response`. Abort the exchange when `request.signal` aborts.
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `upstreamBaseUrl` | required | Base URL of the daemon's HTTP server. |
+| `upstreamToken` | required | The daemon's auth token. |
+| `clientToken` | required | Token clients must send as their daemon auth token. |
+| `upstreamFetch` | global `fetch` | Sends one request to the daemon. |
+| `maxRpcBodyBytes` | 1 MiB | Larger `/rpc` bodies get a 400 response. |
+| `upstreamTimeoutMs` | 5 minutes | Longest time one daemon request may take, including its body. |
+
+## Health and restarts
+
+`GET /health` (also served as `/agent-device/health`) needs no token. It reports the proxy's version and `instanceId`, and
+includes the daemon's own health under `upstream`. A new `createDaemonProxy` call gets a new
+`instanceId`, so connected clients notice the restart and re-check the connection before sending
+more commands.

package/dist/errors.mjs

@@ -0,0 +1,304 @@
+//#region ../kernel/src/redaction.ts
+const SENSITIVE_KEY_RE = /(token|secret|password|authorization|cookie|api[_-]?key|access[_-]?key|private[_-]?key|user[_-]?code|device[_-]?code|refresh[_-]?credential)/i;
+const SECRET_TOKEN_RE = /\b(?:bearer\s+[a-z0-9._-]+|adc_(?:agent|live|refresh|cli)_[a-z0-9._-]+)\b/gi;
+const SENSITIVE_ASSIGNMENT_RE = /\b([a-z0-9_-]*(?:api[_-]?key|token|secret|password|user[_-]?code|device[_-]?code|refresh[_-]?credential)[a-z0-9_-]*)(\s*[=:]\s*)("[^"]*"|'[^']*'|\S+)/gi;
+const URL_RE = /https?:\/\/[^\s"'<>]+/gi;
+const REDACTED_STRING_MAX_LENGTH = 400;
+const REDACTED_STDERR_MAX_LENGTH = 8192;
+const TRUNCATION_SUFFIX = "...<truncated>";
+function redactDiagnosticData(input) {
+	return redactValue(input, /* @__PURE__ */ new WeakSet());
+}
+/** Sanitizes an untrusted structured cause before it crosses a process or client boundary. */
+function sanitizeErrorCause(cause) {
+	if (!cause || typeof cause !== "object") return void 0;
+	const candidate = cause;
+	if (typeof candidate.message !== "string" || candidate.message.length === 0) return void 0;
+	return redactDiagnosticData({
+		message: candidate.message,
+		...typeof candidate.code === "string" && candidate.code.length > 0 ? { code: candidate.code } : {}
+	});
+}
+function redactValue(value, seen, keyHint) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "string") return redactString(value, keyHint);
+	if (typeof value !== "object") return value;
+	if (seen.has(value)) return "[Circular]";
+	seen.add(value);
+	if (Array.isArray(value)) return value.map((entry) => redactValue(entry, seen));
+	const output = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (SENSITIVE_KEY_RE.test(key)) {
+			output[key] = "[REDACTED]";
+			continue;
+		}
+		output[key] = redactValue(entry, seen, key);
+	}
+	return output;
+}
+function redactString(value, keyHint) {
+	const trimmed = value.trim();
+	if (!trimmed) return boundRedactedString(value, keyHint);
+	if (keyHint && SENSITIVE_KEY_RE.test(keyHint)) return "[REDACTED]";
+	let output = redactUrls(trimmed);
+	output = output.replace(SECRET_TOKEN_RE, "[REDACTED]");
+	output = output.replace(SENSITIVE_ASSIGNMENT_RE, (match, key, separator, rawValue, offset, input) => {
+		if (isSafeSetupUrlAssignment({
+			key,
+			separator,
+			rawValue,
+			offset,
+			input
+		})) return match;
+		if (isDocumentedTokenPlaceholder(rawValue)) return match;
+		return `${key}${separator}[REDACTED]`;
+	});
+	return boundRedactedString(output, keyHint);
+}
+function boundRedactedString(value, keyHint) {
+	if (keyHint === "stderr") {
+		if (value.length <= REDACTED_STDERR_MAX_LENGTH) return value;
+		const marker = `\n${TRUNCATION_SUFFIX}\n`;
+		const retainedLength = REDACTED_STDERR_MAX_LENGTH - marker.length;
+		const headLength = Math.ceil(retainedLength / 2);
+		return `${value.slice(0, headLength)}${marker}${value.slice(-(retainedLength - headLength))}`;
+	}
+	if (value.length <= REDACTED_STRING_MAX_LENGTH) return value;
+	return `${value.slice(0, 386)}${TRUNCATION_SUFFIX}`;
+}
+function redactUrls(value) {
+	return value.replace(URL_RE, (url) => redactUrl(url) ?? url);
+}
+function isDocumentedTokenPlaceholder(value) {
+	return /^adc_(?:agent|live|refresh|cli)_\.\.\.$/i.test(value);
+}
+function isSafeSetupUrlAssignment(options) {
+	if (options.key.toLowerCase() !== "token") return false;
+	if (!options.separator.includes(":")) return false;
+	try {
+		if (new URL(options.rawValue).pathname.replace(/\/+$/, "") !== "/api-keys") return false;
+		return /(?:^|\b)(?:service\/)?api\s+$/i.test(options.input.slice(0, options.offset));
+	} catch {
+		return false;
+	}
+}
+function redactUrl(value) {
+	try {
+		const parsed = new URL(value);
+		if (parsed.search) parsed.search = "?REDACTED";
+		if (parsed.username || parsed.password) {
+			parsed.username = "REDACTED";
+			parsed.password = "REDACTED";
+		}
+		return parsed.toString();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region ../kernel/src/errors.ts
+/**
+* The known error codes as a value, so gates can enumerate them: every code
+* here must resolve a hint through `defaultHintForCode`, and every code
+* `retriableForErrorCode` classifies must have a recovery quiz in the help
+* benchmark (scripts/__tests__/help-conformance-error-recovery-coverage.test.ts).
+* `KnownAppErrorCode` is derived from this array, so a new code cannot be added
+* to the type without entering the enumeration.
+*/
+const KNOWN_APP_ERROR_CODES = [
+	"INVALID_ARGS",
+	"DEVICE_NOT_FOUND",
+	"DEVICE_IN_USE",
+	"TOOL_MISSING",
+	"APP_NOT_INSTALLED",
+	"UNSUPPORTED_PLATFORM",
+	"UNSUPPORTED_OPERATION",
+	"NOT_IMPLEMENTED",
+	"COMMAND_FAILED",
+	"SESSION_NOT_FOUND",
+	"UNAUTHORIZED",
+	"AMBIGUOUS_MATCH",
+	"REPLAY_DIVERGENCE",
+	"REPAIR_SESSION_EXPIRED",
+	"REPAIR_COMMIT_FAILED",
+	"UNKNOWN"
+];
+var AppError = class extends Error {
+	code;
+	details;
+	cause;
+	constructor(code, message, details, cause) {
+		super(message);
+		this.code = code;
+		this.details = details;
+		this.cause = cause;
+	}
+};
+/**
+* `details.reason` of a request its requester abandoned — an explicit cancel or
+* a client disconnect. One definition, so every layer that must let a
+* cancellation through untouched (retry loops, provider adapters, runner
+* transports) dispatches on the same typed reason.
+*/
+const REQUEST_CANCELED_REASON = "request_canceled";
+const REQUEST_CANCELED_MESSAGE = "request canceled";
+const REQUEST_CANCELED_HINT = "The request was canceled intentionally (explicit cancel or client disconnect) — no retry is needed unless the cancellation was unintended.";
+/**
+* The canceled-request error. `details` may add evidence (what was released,
+* which command was interrupted) or override the hint; the reason itself is
+* not overridable, so a caller cannot build one this predicate misses.
+*/
+function createRequestCanceledError(details, cause) {
+	return new AppError("COMMAND_FAILED", REQUEST_CANCELED_MESSAGE, {
+		hint: REQUEST_CANCELED_HINT,
+		...details,
+		reason: REQUEST_CANCELED_REASON
+	}, cause);
+}
+function asAppError(err, fallbackCode = "UNKNOWN") {
+	if (err instanceof AppError) return err;
+	if (err instanceof Error) return new AppError(fallbackCode, err.message, void 0, err);
+	return new AppError(fallbackCode, "Unknown error", { err });
+}
+function normalizeError(err, context = {}) {
+	const appErr = asAppError(err);
+	const details = appErr.details ? redactDiagnosticData(appErr.details) : void 0;
+	const diagnosticId = stringDetail(details, "diagnosticId") ?? context.diagnosticId;
+	const logPath = stringDetail(details, "logPath") ?? context.logPath;
+	const logPathUnavailable = stringDetail(details, "logPathUnavailable");
+	const diagnosticsRecord = readDiagnosticsRecordRef(details?.diagnosticsRecord) ?? context.diagnosticsRecord;
+	const hint = stringDetail(details, "hint") ?? defaultHintForCode(appErr.code);
+	const retriable = booleanDetail(details, "retriable") ?? retriableForErrorCode(appErr.code);
+	const supportedOn = stringDetail(details, "supportedOn");
+	const cleanDetails = stripDiagnosticMeta(details);
+	const message = maybeEnrichCommandFailedMessage(appErr.code, appErr.message, details);
+	const cause = sanitizeErrorCause(appErr.cause);
+	return {
+		code: appErr.code,
+		message,
+		...cause !== void 0 ? { cause } : {},
+		hint,
+		diagnosticId,
+		logPath,
+		...logPathUnavailable !== void 0 ? { logPathUnavailable } : {},
+		...diagnosticsRecord !== void 0 ? { diagnosticsRecord } : {},
+		...retriable !== void 0 ? { retriable } : {},
+		...supportedOn !== void 0 ? { supportedOn } : {},
+		details: cleanDetails
+	};
+}
+const GENERIC_EXIT_MESSAGE = /^\S+ exited with code -?\d+$/;
+function maybeEnrichCommandFailedMessage(code, message, details) {
+	if (code !== "COMMAND_FAILED") return message;
+	if (details?.processExitError !== true) return message;
+	const excerpt = firstStderrLine(typeof details?.stderr === "string" ? details.stderr : "");
+	if (!excerpt) return message;
+	if (GENERIC_EXIT_MESSAGE.test(message)) return excerpt;
+	if (message.includes(excerpt)) return message;
+	return `${message}: ${excerpt}`;
+}
+const STDERR_SKIP_PATTERNS = [
+	/^an error was encountered processing the command/i,
+	/^underlying error\b/i,
+	/^simulator device failed to complete the requested operation/i
+];
+const STDERR_NOISE_PREFIX = /^(?:(?:adb|xcrun|simctl):\s*)?(?:error:\s*)?/i;
+function firstStderrLine(stderr) {
+	for (const rawLine of stderr.split("\n")) {
+		const line = rawLine.trim();
+		if (!line) continue;
+		if (STDERR_SKIP_PATTERNS.some((pattern) => pattern.test(line))) continue;
+		const excerpt = line.replace(STDERR_NOISE_PREFIX, "").trim();
+		if (!excerpt) continue;
+		return excerpt.length > 200 ? `${excerpt.slice(0, 200)}...` : excerpt;
+	}
+	return null;
+}
+function stringDetail(details, key) {
+	const value = details?.[key];
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* Narrows an untrusted `diagnosticsRecord` — off the wire or out of a details
+* bag — to the locator type, or `undefined`. One reader, so a daemon payload
+* and a details bag can never be accepted on different terms.
+*/
+function readDiagnosticsRecordRef(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const { session, requestId } = value;
+	if (typeof session !== "string" || typeof requestId !== "string") return void 0;
+	if (session.length === 0 || requestId.length === 0) return void 0;
+	return {
+		session,
+		requestId
+	};
+}
+function booleanDetail(details, key) {
+	const value = details?.[key];
+	return typeof value === "boolean" ? value : void 0;
+}
+/**
+* Facts a publisher leaves for a later catch in the same process, never for a caller: whether a rule
+* row named this failure, and whether the host's own deadline ended the command behind it. Both
+* describe our machinery rather than the caller's problem, and the caller was already handed the
+* verdict those facts produced as `reason` and `hint` (#2690 review).
+*/
+const INTERNAL_PLUMBING_DETAIL_KEYS = ["startupRuleMatched", "startupHostDeadlineHit"];
+function stripDiagnosticMeta(details) {
+	if (!details) return void 0;
+	const output = { ...details };
+	for (const key of INTERNAL_PLUMBING_DETAIL_KEYS) delete output[key];
+	delete output.hint;
+	delete output.diagnosticId;
+	delete output.logPath;
+	delete output.logPathUnavailable;
+	delete output.diagnosticsRecord;
+	delete output.retriable;
+	delete output.supportedOn;
+	return Object.keys(output).length > 0 ? output : void 0;
+}
+/**
+* Conservative retriability policy for the Phase 2 typed-error graft. A code is
+* listed only when the verdict is clear (a retry can succeed without the caller
+* changing anything, or it definitely cannot); unlisted codes stay `undefined`
+* so the error wire shape is unchanged unless we have a confident answer.
+*
+* Keyed by `KnownAppErrorCode`, so a verdict cannot be given to a code the
+* registry does not enumerate — that would classify a code as retriable while
+* escaping the gate that requires a recovery quiz for it.
+*/
+const RETRIABILITY_BY_CODE = { DEVICE_IN_USE: true };
+function isKnownAppErrorCode(code) {
+	return KNOWN_APP_ERROR_CODES.includes(code);
+}
+/**
+* The retriability verdict for a code, or `undefined` when there is none —
+* including for every daemon/runner-originated code outside
+* `KNOWN_APP_ERROR_CODES`, which cannot carry a verdict at all.
+*/
+function retriableForErrorCode(code) {
+	return isKnownAppErrorCode(code) ? RETRIABILITY_BY_CODE[code] : void 0;
+}
+function defaultHintForCode(code) {
+	switch (code) {
+		case "INVALID_ARGS": return "Check command arguments and run --help for usage examples.";
+		case "SESSION_NOT_FOUND": return "Run open first or pass an explicit device selector.";
+		case "TOOL_MISSING": return "Install required platform tooling and ensure it is available in PATH.";
+		case "DEVICE_NOT_FOUND": return "Verify the target device is booted/connected and selectors match.";
+		case "APP_NOT_INSTALLED": return "Run apps to discover the exact installed package or bundle id, or install the app before open.";
+		case "UNSUPPORTED_OPERATION": return "This command is not available for the selected platform/device.";
+		case "UNSUPPORTED_PLATFORM": return "This platform is not supported for the requested operation; run devices to inspect available targets.";
+		case "AMBIGUOUS_MATCH": return "Multiple candidates matched. Narrow the query or pass an exact identifier.";
+		case "DEVICE_IN_USE": return "The device is busy with another agent-device request; retry once it frees up.";
+		case "REPLAY_DIVERGENCE": return "Read details.divergence (screen/suggestions) for repair context, or rerun with --json for the full report.";
+		case "REPAIR_SESSION_EXPIRED": return "The --save-script repair session was reaped before it was finalized; re-run replay <script> --save-script from the start.";
+		case "REPAIR_COMMIT_FAILED": return "The repair transaction completed, but committing its healed script failed at teardown (no-clobber refusal or a filesystem error); inspect the target path/permissions, then re-run replay <script> --save-script to retry.";
+		case "NOT_IMPLEMENTED": return "This command is part of the planned API but is not implemented yet.";
+		case "COMMAND_FAILED": return "Retry with --debug and inspect diagnostics log for details.";
+		case "UNAUTHORIZED": return "Refresh daemon metadata and retry the command.";
+		case "UNKNOWN": return "Unexpected internal error. Retry with --debug and report the diagnostics log if it persists.";
+		default: return "Retry with --debug and inspect diagnostics log for details.";
+	}
+}
+//#endregion
+export { redactDiagnosticData as i, createRequestCanceledError as n, normalizeError as r, AppError as t };

package/dist/index.d.mts

@@ -0,0 +1,36 @@
+import http from "node:http";
+//#region src/daemon-proxy.d.ts
+/**
+ * Carries one request to the upstream daemon and resolves with its response. The default is the
+ * global `fetch`; supply your own to reach the daemon over another transport, such as a
+ * WebSocket tunnel. Abort the exchange when `request.signal` aborts.
+ */
+type DaemonProxyUpstreamFetch = (request: Request) => Promise<Response>;
+type DaemonProxyOptions = {
+  /** Base URL of the upstream agent-device daemon HTTP server. */
+  upstreamBaseUrl: string;
+  /** Auth token of the upstream daemon. Never leaves the proxy. */
+  upstreamToken: string;
+  /** Token proxy clients must present as their daemon auth token. */
+  clientToken: string;
+  maxRpcBodyBytes?: number;
+  upstreamTimeoutMs?: number;
+  upstreamFetch?: DaemonProxyUpstreamFetch;
+};
+type DaemonProxy = {
+  /** Identifies this proxy instance in its health payload, so clients notice a restart. */
+  readonly instanceId: string;
+  /**
+   * Answers one client request. `request.url` must be the URL the client used, because upload
+   * tickets are rewritten to its origin; an `x-forwarded-proto` header overrides its scheme.
+   * Abort `request.signal` when the client goes away so in-flight daemon work is cancelled.
+   * Resolves with an error response rather than rejecting.
+   */
+  handle(request: Request): Promise<Response>;
+};
+declare function createDaemonProxy(options: DaemonProxyOptions): DaemonProxy;
+declare function createDaemonProxyServer(options: DaemonProxyOptions): http.Server;
+/** Serves a proxy from any `node:http` or `node:https` server; upload tickets follow its scheme. */
+declare function createDaemonProxyRequestListener(proxy: DaemonProxy): http.RequestListener;
+//#endregion
+export { type DaemonProxy, type DaemonProxyOptions, type DaemonProxyUpstreamFetch, createDaemonProxy, createDaemonProxyRequestListener, createDaemonProxyServer };