@stim-cli/agent-driver 0.0.0 → 1.22.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+
+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,63 @@
 # @stim-cli/agent-driver
 
-Placeholder. Install a version published with the other Stim packages.
+The contract stim-server uses to start the tool a client's coding agent drives
+hosted apps with. stim-server ships the first-party drivers as dependencies and
+selects one with the hosting Mac's `hosting.agentDriver` setting:
+[`@stim-cli/agent-driver-agent-device`](../agent-driver-agent-device/README.md).
+
+Drivers are machine scope. stim-server resolves them from its own
+dependencies, never from a project.
+
+## Writing a driver
+
+A driver package exports:
+
+```js
+export const apiVersion = 1;
+export const id = 'my-tool';
+export function createAgentDriver({ env, stateDir, claimRoot, device }) {
+  return driver;
+}
+export const client = { configFile: 'my-tool-remote.json', access };
+export const actions = { read };
+```
+
+`createAgentDriver` returns a `HostedAgentDriver` named `id`. stim-server
+authenticates the client, its tailnet node and the session before it calls
+`forward`; the driver confines every forwarded request to the one app or
+device it issued the grant for, and refuses with `AgentDriverUnavailable`
+when it cannot. `device` names the hosted simulator or emulator when the driver
+serves one hosted device session; without it the driver serves hosted macOS
+apps.
+
+`client` is optional and runs on the Mac that placed the app. `access` turns a
+grant into the contents of a mode 0600 file and a command that names that file.
+The command never carries the token.
+
+`actions` is optional. `read` returns the driver's recorded agent actions in a
+workspace or archive directory as `agent` log records.
+
+`loadAgentDriverModule` and `loadAgentDriver` never throw. A failed or slow
+import, a module with another `apiVersion` or `id`, or a factory that throws
+resolves to `{ unavailable }` with a one-line reason.
+
+## Contract tests
+
+```js
+import { runAgentDriverContract } from '@stim-cli/agent-driver';
+
+const results = await runAgentDriverContract({
+  id: 'my-tool',
+  load: () => import('my-tool-driver'),
+  unavailableInput: { env: { PATH: '' }, stateDir, claimRoot },
+  app: { client: 'client', session, bundleId: 'dev.example.app', pid: 4242 },
+  clientGrant,
+});
+for (const result of results) {
+  if (!result.passed) throw new Error(`${result.name}: ${result.error}`);
+}
+```
+
+The checks cover the module shape, idempotent `stop` and `revoke`, refusals
+before `start` and without a grant, `AgentDriverUnavailable` when the tool is
+missing, and a client file that keeps the token out of the command.

package/dist/index.d.mts

@@ -0,0 +1,147 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { HostedAgentIssuedGrant, NdjsonRecord } from "@stim-cli/core/state";
+//#region driver.d.ts
+declare const AGENT_DRIVER_API_VERSION: 1;
+declare const AGENT_DRIVER_LOAD_TIMEOUT_MS = 1e4;
+type HostedAgentDevice = {
+  session: string;
+} & ({
+  udid: string;
+  serial?: never;
+  avdName?: never;
+} | {
+  serial: string;
+  avdName: string;
+  udid?: never;
+});
+/** One installed hosted app and its process or owned device. */
+type HostedAgentApp = {
+  client: string;
+  session: string;
+  bundleId: string;
+} & ({
+  pid: number;
+  udid?: never;
+  serial?: never;
+  avdName?: never;
+} | (HostedAgentDevice & {
+  pid?: never;
+}));
+/**
+ * The host side of one driving tool. stim-server's `HostedAgentHost` calls it; a driver never decides which
+ * client or session may use it.
+ */
+interface HostedAgentDriver {
+  /** The module's `id`. */
+  readonly name: string;
+  /** Starts the host daemon under an ownership claim whose child is the daemon; idempotent. */
+  start(): Promise<void>;
+  /** Stops the daemon with identity-checked signals and releases its claim; resolves only once it is gone. */
+  stop(): Promise<void>;
+  /** Issues a grant scoped to exactly one hosted app. Refuses with `AgentDriverUnavailable` when it cannot scope. */
+  issue(app: HostedAgentApp): Promise<HostedAgentIssuedGrant>;
+  /** Invalidates a session's grant and lease. */
+  revoke(session: string): Promise<void>;
+  /** Forwards one request the host already authenticated to the loopback daemon. */
+  forward(session: string, request: IncomingMessage, response: ServerResponse): void;
+  /** Calls `listener` once for each daemon run that exits without `stop()`; a driver keeps one listener. */
+  onExit(listener: () => void): void;
+}
+/** The driver cannot run or cannot scope an app; the message is safe to show a client. */
+declare class AgentDriverUnavailable extends Error {}
+declare const AGENT_ROUTE_PREFIX = "/device-host/agent/";
+declare function agentRoute(session: string): string;
+/** A 256-bit bearer secret in the alphabet `parseHostedAgentGrant` accepts. */
+declare function newAgentToken(): string;
+/**
+ * What stim-server hands a driver factory. `stateDir` and `claimRoot` are the driver's own, under the server
+ * home for hosted macOS apps or under the session's area for one hosted device, which `device` then names.
+ */
+interface AgentDriverInput {
+  env: NodeJS.ProcessEnv;
+  stateDir: string;
+  claimRoot: string;
+  device?: HostedAgentDevice;
+}
+interface AgentClientAccessInput {
+  /** A grant naming this driver, as the client parsed it. */
+  grant: HostedAgentIssuedGrant;
+  /** `https://<host>[:<port>]` followed by the grant's path. */
+  baseUrl: string;
+  /** Where the client writes `config`, with mode 0600. */
+  file: string;
+  platform: "macos" | "ios" | "android";
+}
+/** The client's file holding the grant's secret, and the command line that addresses the hosted app through it. */
+interface AgentClientAccess {
+  config: string;
+  command: string;
+}
+/**
+ * The client side of a driver, run by the Stim CLI on the Mac that placed the app. `access` returns null for a
+ * grant it cannot use on `platform`; `command` must name `file` and never carry the token.
+ */
+interface AgentDriverClient {
+  /** The file name the client writes in the placement's state directory. */
+  configFile: string;
+  access(input: AgentClientAccessInput): AgentClientAccess | null;
+}
+/** Reads the driver's recorded agent actions from a workspace or archive directory, as `agent` log records. */
+interface AgentDriverActions {
+  read(input: {
+    workspaceDir: string;
+  }): NdjsonRecord[];
+}
+/** The module shape a driver package exports. The loader rejects any other `apiVersion`. */
+interface AgentDriverModule {
+  apiVersion: typeof AGENT_DRIVER_API_VERSION;
+  id: string;
+  createAgentDriver(input: AgentDriverInput): HostedAgentDriver;
+  client?: AgentDriverClient;
+  actions?: AgentDriverActions;
+}
+type LoadAgentDriverModuleResult = {
+  module: AgentDriverModule;
+} | {
+  unavailable: string;
+};
+type LoadAgentDriverResult = {
+  driver: HostedAgentDriver;
+} | {
+  unavailable: string;
+};
+/**
+ * Imports a driver module and checks its shape. Never throws: a failed or slow import, or a module that is not
+ * a version 1 driver named `id`, resolves to `{ unavailable }` with a one-line reason.
+ */
+declare function loadAgentDriverModule(id: string, load: () => Promise<unknown>, timeoutMs?: number): Promise<LoadAgentDriverModuleResult>;
+/** Loads a driver module and creates its driver. Never throws; see `loadAgentDriverModule`. */
+declare function loadAgentDriver(id: string, load: () => Promise<unknown>, input: AgentDriverInput, timeoutMs?: number): Promise<LoadAgentDriverResult>;
+//#endregion
+//#region contract.d.ts
+interface AgentDriverContractResult {
+  name: string;
+  passed: boolean;
+  error?: string;
+}
+interface AgentDriverContractOptions {
+  /** Imports the driver module, for example `() => import('@stim-cli/agent-driver-x')`. */
+  load: () => Promise<unknown>;
+  id: string;
+  /** Factory input for a host whose driving tool is not installed. */
+  unavailableInput: AgentDriverInput;
+  /** An app the driver would scope a grant to. */
+  app: HostedAgentApp;
+  /** A grant this driver issues, for the client checks. Required when the module has a client capability. */
+  clientGrant?: HostedAgentIssuedGrant;
+  checkTimeoutMs?: number;
+}
+declare const AGENT_DRIVER_CONTRACT_CHECK_TIMEOUT_MS = 1e4;
+/**
+ * Loads a driver module the way stim-server does and runs the host-independent checks every driver must pass:
+ * shape, idempotent stop and revoke, refusals before start and without a grant, `AgentDriverUnavailable` when
+ * its tool is missing, and, with a client capability, a client file that keeps the token out of the command.
+ */
+declare function runAgentDriverContract(options: AgentDriverContractOptions): Promise<AgentDriverContractResult[]>;
+//#endregion
+export { AGENT_DRIVER_API_VERSION, AGENT_DRIVER_CONTRACT_CHECK_TIMEOUT_MS, AGENT_DRIVER_LOAD_TIMEOUT_MS, AGENT_ROUTE_PREFIX, AgentClientAccess, AgentClientAccessInput, AgentDriverActions, AgentDriverClient, AgentDriverContractOptions, AgentDriverContractResult, AgentDriverInput, AgentDriverModule, AgentDriverUnavailable, HostedAgentApp, HostedAgentDevice, HostedAgentDriver, LoadAgentDriverModuleResult, LoadAgentDriverResult, agentRoute, loadAgentDriver, loadAgentDriverModule, newAgentToken, runAgentDriverContract };

package/dist/index.mjs

@@ -0,0 +1,253 @@
+import { randomBytes } from "node:crypto";
+import { createServer, request } from "node:http";
+//#region driver.ts
+const AGENT_DRIVER_API_VERSION = 1;
+const AGENT_DRIVER_LOAD_TIMEOUT_MS = 1e4;
+/** The driver cannot run or cannot scope an app; the message is safe to show a client. */
+var AgentDriverUnavailable = class extends Error {};
+const AGENT_ROUTE_PREFIX = "/device-host/agent/";
+function agentRoute(session) {
+	return `${AGENT_ROUTE_PREFIX}${session}/`;
+}
+/** A 256-bit bearer secret in the alphabet `parseHostedAgentGrant` accepts. */
+function newAgentToken() {
+	return randomBytes(32).toString("base64url");
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function reason(error) {
+	return (error instanceof Error ? error.message : String(error)).replace(/\n[\s\S]*$/, "").trim() || "unknown error";
+}
+function moduleError(candidate, id) {
+	if (!isRecord(candidate) || candidate.apiVersion !== 1) return `expected apiVersion 1, found ${JSON.stringify(isRecord(candidate) ? candidate.apiVersion : candidate)}`;
+	if (candidate.id !== id) return `expected id ${JSON.stringify(id)}, found ${JSON.stringify(candidate.id)}`;
+	if (typeof candidate.createAgentDriver !== "function") return "the module does not export createAgentDriver()";
+	const client = candidate.client;
+	if (client !== void 0 && (!isRecord(client) || typeof client.configFile !== "string" || typeof client.access !== "function")) return "the client capability must name configFile and implement access()";
+	const actions = candidate.actions;
+	if (actions !== void 0 && (!isRecord(actions) || typeof actions.read !== "function")) return "the actions capability must implement read()";
+	return null;
+}
+function driverError(driver, id) {
+	if (!isRecord(driver)) return "createAgentDriver() did not return a driver object";
+	if (driver.name !== id) return `the driver is named ${JSON.stringify(driver.name)}, not ${JSON.stringify(id)}`;
+	for (const method of [
+		"start",
+		"stop",
+		"issue",
+		"revoke",
+		"forward",
+		"onExit"
+	]) if (typeof driver[method] !== "function") return `the driver does not implement ${method}()`;
+	return null;
+}
+/**
+* Imports a driver module and checks its shape. Never throws: a failed or slow import, or a module that is not
+* a version 1 driver named `id`, resolves to `{ unavailable }` with a one-line reason.
+*/
+async function loadAgentDriverModule(id, load, timeoutMs = AGENT_DRIVER_LOAD_TIMEOUT_MS) {
+	let timer;
+	const expired = new Promise((resolve) => {
+		timer = setTimeout(() => resolve({ unavailable: `the module did not load within ${timeoutMs}ms` }), timeoutMs);
+	});
+	const loaded = Promise.resolve().then(load).then((namespace) => {
+		const candidate = isRecord(namespace) && !("apiVersion" in namespace) && "default" in namespace ? namespace.default : namespace;
+		const invalid = moduleError(candidate, id);
+		return invalid ? { unavailable: invalid } : { module: candidate };
+	}).catch((error) => ({ unavailable: reason(error) }));
+	try {
+		return await Promise.race([loaded, expired]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** Loads a driver module and creates its driver. Never throws; see `loadAgentDriverModule`. */
+async function loadAgentDriver(id, load, input, timeoutMs) {
+	const loaded = await loadAgentDriverModule(id, load, timeoutMs);
+	if ("unavailable" in loaded) return loaded;
+	let driver;
+	let invalid;
+	try {
+		driver = loaded.module.createAgentDriver(input);
+		if (driver instanceof Promise) {
+			driver.catch(() => void 0);
+			return { unavailable: "createAgentDriver() must return the driver, not a promise" };
+		}
+		invalid = driverError(driver, id);
+	} catch (error) {
+		return { unavailable: `createAgentDriver() failed: ${reason(error)}` };
+	}
+	return invalid ? { unavailable: invalid } : { driver };
+}
+//#endregion
+//#region contract.ts
+const AGENT_DRIVER_CONTRACT_CHECK_TIMEOUT_MS = 1e4;
+const UNKNOWN_SESSION = "00000000-0000-4000-8000-000000000000";
+function assert(condition, message) {
+	if (!condition) throw new Error(message);
+}
+async function rejects(call) {
+	try {
+		await call();
+	} catch (error) {
+		return error;
+	}
+	throw new Error("the call resolved");
+}
+function forwardStatus(driver, session, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const server = createServer((request, response) => {
+			try {
+				driver.forward(session, request, response);
+			} catch (error) {
+				finish(() => reject(error));
+			}
+		});
+		const timer = setTimeout(() => finish(() => reject(/* @__PURE__ */ new Error(`forward() did not answer within ${timeoutMs}ms`))), timeoutMs);
+		let done = false;
+		function finish(settle) {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			server.closeAllConnections();
+			server.close(() => settle());
+		}
+		server.once("error", (error) => finish(() => reject(error)));
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			const port = address && typeof address === "object" ? address.port : 0;
+			const request$1 = request({
+				host: "127.0.0.1",
+				port,
+				method: "POST",
+				path: `${agentRoute(session)}rpc`
+			}, (response) => {
+				response.resume();
+				response.once("end", () => finish(() => resolve(response.statusCode ?? 0)));
+			});
+			request$1.once("error", (error) => finish(() => reject(error)));
+			request$1.end("{}");
+		});
+	});
+}
+async function withDeadline(work, timeoutMs) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((_, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`the check did not finish within ${timeoutMs}ms`)), timeoutMs);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function checks(module, options) {
+	const fresh = () => module.createAgentDriver(options.unavailableInput);
+	const list = [
+		{
+			name: "the driver carries the module id",
+			run: async () => {
+				assert(fresh().name === options.id, `the driver is named ${JSON.stringify(fresh().name)}`);
+			}
+		},
+		{
+			name: "stop before start resolves",
+			run: async () => {
+				await fresh().stop();
+			}
+		},
+		{
+			name: "revoking an unknown session resolves",
+			run: async () => {
+				await fresh().revoke(UNKNOWN_SESSION);
+			}
+		},
+		{
+			name: "issuing before start refuses",
+			run: async () => {
+				await rejects(() => fresh().issue(options.app));
+			}
+		},
+		{
+			name: "forwarding without a grant answers with an error status",
+			run: async () => {
+				const status = await forwardStatus(fresh(), UNKNOWN_SESSION, options.checkTimeoutMs ?? 1e4);
+				assert(status >= 400, `the forward answered ${status}`);
+			}
+		},
+		{
+			name: "start refuses with AgentDriverUnavailable when the tool is missing, then stops",
+			run: async () => {
+				const driver = fresh();
+				const error = await rejects(() => driver.start());
+				assert(error instanceof AgentDriverUnavailable, `start failed with ${String(error)}`);
+				await driver.stop();
+			}
+		}
+	];
+	const client = module.client;
+	if (client) {
+		const grant = options.clientGrant;
+		const input = (granted) => ({
+			grant: granted,
+			baseUrl: `https://host.example.ts.net${granted.path}`,
+			file: `/tmp/stim-contract/${client.configFile}`,
+			platform: options.app.udid !== void 0 ? "ios" : options.app.serial !== void 0 ? "android" : "macos"
+		});
+		list.push({
+			name: "client access names its file and keeps the token out of the command",
+			run: async () => {
+				assert(grant, "clientGrant is required for a module with a client capability");
+				const access = client.access(input(grant));
+				assert(access, "the client refused its own grant");
+				assert(access.command.includes(input(grant).file), "the command does not name the config file");
+				assert(!access.command.includes(grant.token), "the command carries the token");
+			}
+		}, {
+			name: "client access refuses a grant for another driver",
+			run: async () => {
+				assert(grant, "clientGrant is required for a module with a client capability");
+				const other = {
+					...grant,
+					driver: `${options.id}-other`,
+					token: newAgentToken()
+				};
+				assert(client.access(input(other)) === null, "accepted");
+			}
+		});
+	}
+	return list;
+}
+/**
+* Loads a driver module the way stim-server does and runs the host-independent checks every driver must pass:
+* shape, idempotent stop and revoke, refusals before start and without a grant, `AgentDriverUnavailable` when
+* its tool is missing, and, with a client capability, a client file that keeps the token out of the command.
+*/
+async function runAgentDriverContract(options) {
+	const loaded = await loadAgentDriverModule(options.id, options.load);
+	if ("unavailable" in loaded) return [{
+		name: "the module loads",
+		passed: false,
+		error: loaded.unavailable
+	}];
+	const results = [{
+		name: "the module loads",
+		passed: true
+	}];
+	for (const check of checks(loaded.module, options)) try {
+		await withDeadline(check.run(), options.checkTimeoutMs ?? 1e4);
+		results.push({
+			name: check.name,
+			passed: true
+		});
+	} catch (error) {
+		results.push({
+			name: check.name,
+			passed: false,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return results;
+}
+//#endregion
+export { AGENT_DRIVER_API_VERSION, AGENT_DRIVER_CONTRACT_CHECK_TIMEOUT_MS, AGENT_DRIVER_LOAD_TIMEOUT_MS, AGENT_ROUTE_PREFIX, AgentDriverUnavailable, agentRoute, loadAgentDriver, loadAgentDriverModule, newAgentToken, runAgentDriverContract };

package/package.json

@@ -1,11 +1,35 @@
 {
   "name": "@stim-cli/agent-driver",
-  "version": "0.0.0",
-  "description": "Placeholder. The first real version is published by the Stim release workflow.",
+  "version": "1.22.0",
+  "description": "Hosted agent driver contract for stim-server.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/appandflow/stim.git",
     "directory": "packages/agent-driver"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "module-sync": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@stim-cli/core": "^1.22.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown"
   }
-}
+}