@agentproto/browser-process 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy André and agentproto contributors
+
+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/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { ChildProcess } from 'node:child_process';
+
+/**
+ * Shared primitive for launching and health-waiting browser service processes.
+ *
+ * Two exports:
+ *   - `waitHealthy`         — poll a health URL until it responds OK or timeout.
+ *   - `ensureBrowserProcess` — idempotent: probe once, skip spawn if already up,
+ *                              else launch via spec.launch() and wait for health.
+ */
+
+interface BrowserProcessSpec {
+    kind: string;
+    healthUrl: string;
+    /**
+     * Spawn the service and return its ChildProcess, OR return null if the
+     * process is externally managed (e.g. launchd) — in that case `pid` in the
+     * result will be `undefined`.
+     */
+    launch(): ChildProcess | null;
+    timeoutMs?: number;
+    intervalMs?: number;
+    log?: (msg: string) => void;
+}
+interface BrowserProcessResult {
+    baseUrl: string;
+    wasAlreadyRunning: boolean;
+    pid?: number;
+    stop?: () => Promise<void>;
+}
+/**
+ * Poll `healthUrl` until it returns an OK response, then return that Response.
+ * Throws if `timeoutMs` (default 60 000) elapses before a healthy response.
+ */
+declare function waitHealthy(healthUrl: string, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+    log?: (s: string) => void;
+}): Promise<Response>;
+/**
+ * Idempotent service launcher.
+ * 1. Probes `spec.healthUrl` — if already healthy, returns `{ wasAlreadyRunning: true }`.
+ * 2. Calls `spec.launch()` (may return `null` for externally managed services).
+ * 3. Polls health until `spec.timeoutMs` — returns `{ pid, wasAlreadyRunning: false }`.
+ */
+declare function ensureBrowserProcess(spec: BrowserProcessSpec): Promise<BrowserProcessResult>;
+
+export { type BrowserProcessResult, type BrowserProcessSpec, ensureBrowserProcess, waitHealthy };

package/dist/index.mjs

@@ -0,0 +1,60 @@
+/**
+ * @agentproto/browser-process v0.1.0-alpha
+ * Shared primitive for launching and health-waiting browser service processes.
+ */
+
+// src/index.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function probe(healthUrl) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), 3e3);
+  try {
+    const r = await fetch(healthUrl, { signal: ac.signal });
+    return r.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(t);
+  }
+}
+async function waitHealthy(healthUrl, opts) {
+  const timeoutMs = opts?.timeoutMs ?? 6e4;
+  const intervalMs = opts?.intervalMs ?? 1e3;
+  const log = opts?.log;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), 3e3);
+    try {
+      const r = await fetch(healthUrl, { signal: ac.signal });
+      if (r.ok) return r;
+    } catch {
+    } finally {
+      clearTimeout(t);
+    }
+    log?.(`waiting for ${healthUrl}\u2026`);
+  }
+  throw new Error(
+    `service at ${healthUrl} did not become healthy within ${timeoutMs / 1e3}s`
+  );
+}
+async function ensureBrowserProcess(spec) {
+  const baseUrl = new URL(spec.healthUrl).origin;
+  if (await probe(spec.healthUrl)) {
+    return { baseUrl, wasAlreadyRunning: true };
+  }
+  const child = spec.launch();
+  const res = await waitHealthy(spec.healthUrl, {
+    timeoutMs: spec.timeoutMs,
+    intervalMs: spec.intervalMs,
+    log: spec.log
+  });
+  await res.body?.cancel().catch(() => {
+  });
+  return { baseUrl, pid: child?.pid, wasAlreadyRunning: false };
+}
+
+export { ensureBrowserProcess, waitHealthy };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAWA,IAAM,KAAA,GAAQ,CAAC,EAAA,KAAe,IAAI,QAAc,CAAA,CAAA,KAAK,UAAA,CAAW,CAAA,EAAG,EAAE,CAAC,CAAA;AAuBtE,eAAe,MAAM,SAAA,EAAqC;AACxD,EAAA,MAAM,EAAA,GAAK,IAAI,eAAA,EAAgB;AAC/B,EAAA,MAAM,IAAI,UAAA,CAAW,MAAM,EAAA,CAAG,KAAA,IAAS,GAAI,CAAA;AAC3C,EAAA,IAAI;AACF,IAAA,MAAM,CAAA,GAAI,MAAM,KAAA,CAAM,SAAA,EAAW,EAAE,MAAA,EAAQ,EAAA,CAAG,QAAQ,CAAA;AACtD,IAAA,OAAO,CAAA,CAAE,EAAA;AAAA,EACX,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT,CAAA,SAAE;AACA,IAAA,YAAA,CAAa,CAAC,CAAA;AAAA,EAChB;AACF;AAMA,eAAsB,WAAA,CACpB,WACA,IAAA,EAKmB;AACnB,EAAA,MAAM,SAAA,GAAY,MAAM,SAAA,IAAa,GAAA;AACrC,EAAA,MAAM,UAAA,GAAa,MAAM,UAAA,IAAc,GAAA;AACvC,EAAA,MAAM,MAAM,IAAA,EAAM,GAAA;AAClB,EAAA,MAAM,QAAA,GAAW,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAC9B,EAAA,OAAO,IAAA,CAAK,GAAA,EAAI,GAAI,QAAA,EAAU;AAC5B,IAAA,MAAM,MAAM,UAAU,CAAA;AACtB,IAAA,MAAM,EAAA,GAAK,IAAI,eAAA,EAAgB;AAC/B,IAAA,MAAM,IAAI,UAAA,CAAW,MAAM,EAAA,CAAG,KAAA,IAAS,GAAI,CAAA;AAC3C,IAAA,IAAI;AACF,MAAA,MAAM,CAAA,GAAI,MAAM,KAAA,CAAM,SAAA,EAAW,EAAE,MAAA,EAAQ,EAAA,CAAG,QAAQ,CAAA;AACtD,MAAA,IAAI,CAAA,CAAE,IAAI,OAAO,CAAA;AAAA,IACnB,CAAA,CAAA,MAAQ;AAAA,IAER,CAAA,SAAE;AACA,MAAA,YAAA,CAAa,CAAC,CAAA;AAAA,IAChB;AACA,IAAA,GAAA,GAAM,CAAA,YAAA,EAAe,SAAS,CAAA,MAAA,CAAG,CAAA;AAAA,EACnC;AACA,EAAA,MAAM,IAAI,KAAA;AAAA,IACR,CAAA,WAAA,EAAc,SAAS,CAAA,+BAAA,EAAkC,SAAA,GAAY,GAAI,CAAA,CAAA;AAAA,GAC3E;AACF;AAQA,eAAsB,qBACpB,IAAA,EAC+B;AAC/B,EAAA,MAAM,OAAA,GAAU,IAAI,GAAA,CAAI,IAAA,CAAK,SAAS,CAAA,CAAE,MAAA;AAExC,EAAA,IAAI,MAAM,KAAA,CAAM,IAAA,CAAK,SAAS,CAAA,EAAG;AAC/B,IAAA,OAAO,EAAE,OAAA,EAAS,iBAAA,EAAmB,IAAA,EAAK;AAAA,EAC5C;AAEA,EAAA,MAAM,KAAA,GAAQ,KAAK,MAAA,EAAO;AAE1B,EAAA,MAAM,GAAA,GAAM,MAAM,WAAA,CAAY,IAAA,CAAK,SAAA,EAAW;AAAA,IAC5C,WAAW,IAAA,CAAK,SAAA;AAAA,IAChB,YAAY,IAAA,CAAK,UAAA;AAAA,IACjB,KAAK,IAAA,CAAK;AAAA,GACX,CAAA;AACD,EAAA,MAAM,GAAA,CAAI,IAAA,EAAM,MAAA,EAAO,CAAE,MAAM,MAAM;AAAA,EAAC,CAAC,CAAA;AAEvC,EAAA,OAAO,EAAE,OAAA,EAAS,GAAA,EAAK,KAAA,EAAO,GAAA,EAAK,mBAAmB,KAAA,EAAM;AAC9D","file":"index.mjs","sourcesContent":["/**\n * Shared primitive for launching and health-waiting browser service processes.\n *\n * Two exports:\n *   - `waitHealthy`         — poll a health URL until it responds OK or timeout.\n *   - `ensureBrowserProcess` — idempotent: probe once, skip spawn if already up,\n *                              else launch via spec.launch() and wait for health.\n */\n\nimport type { ChildProcess } from \"node:child_process\"\n\nconst sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms))\n\nexport interface BrowserProcessSpec {\n  kind: string\n  healthUrl: string\n  /**\n   * Spawn the service and return its ChildProcess, OR return null if the\n   * process is externally managed (e.g. launchd) — in that case `pid` in the\n   * result will be `undefined`.\n   */\n  launch(): ChildProcess | null\n  timeoutMs?: number\n  intervalMs?: number\n  log?: (msg: string) => void\n}\n\nexport interface BrowserProcessResult {\n  baseUrl: string\n  wasAlreadyRunning: boolean\n  pid?: number\n  stop?: () => Promise<void>\n}\n\nasync function probe(healthUrl: string): Promise<boolean> {\n  const ac = new AbortController()\n  const t = setTimeout(() => ac.abort(), 3000)\n  try {\n    const r = await fetch(healthUrl, { signal: ac.signal })\n    return r.ok\n  } catch {\n    return false\n  } finally {\n    clearTimeout(t)\n  }\n}\n\n/**\n * Poll `healthUrl` until it returns an OK response, then return that Response.\n * Throws if `timeoutMs` (default 60 000) elapses before a healthy response.\n */\nexport async function waitHealthy(\n  healthUrl: string,\n  opts?: {\n    timeoutMs?: number\n    intervalMs?: number\n    log?: (s: string) => void\n  }\n): Promise<Response> {\n  const timeoutMs = opts?.timeoutMs ?? 60_000\n  const intervalMs = opts?.intervalMs ?? 1_000\n  const log = opts?.log\n  const deadline = Date.now() + timeoutMs\n  while (Date.now() < deadline) {\n    await sleep(intervalMs)\n    const ac = new AbortController()\n    const t = setTimeout(() => ac.abort(), 3000)\n    try {\n      const r = await fetch(healthUrl, { signal: ac.signal })\n      if (r.ok) return r\n    } catch {\n      // not yet healthy — keep polling\n    } finally {\n      clearTimeout(t)\n    }\n    log?.(`waiting for ${healthUrl}…`)\n  }\n  throw new Error(\n    `service at ${healthUrl} did not become healthy within ${timeoutMs / 1000}s`\n  )\n}\n\n/**\n * Idempotent service launcher.\n * 1. Probes `spec.healthUrl` — if already healthy, returns `{ wasAlreadyRunning: true }`.\n * 2. Calls `spec.launch()` (may return `null` for externally managed services).\n * 3. Polls health until `spec.timeoutMs` — returns `{ pid, wasAlreadyRunning: false }`.\n */\nexport async function ensureBrowserProcess(\n  spec: BrowserProcessSpec\n): Promise<BrowserProcessResult> {\n  const baseUrl = new URL(spec.healthUrl).origin\n\n  if (await probe(spec.healthUrl)) {\n    return { baseUrl, wasAlreadyRunning: true }\n  }\n\n  const child = spec.launch()\n\n  const res = await waitHealthy(spec.healthUrl, {\n    timeoutMs: spec.timeoutMs,\n    intervalMs: spec.intervalMs,\n    log: spec.log,\n  })\n  await res.body?.cancel().catch(() => {})\n\n  return { baseUrl, pid: child?.pid, wasAlreadyRunning: false }\n}\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@agentproto/browser-process",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/browser-process — shared primitive for launching and health-waiting browser service processes (Camofox, Bureau, Chromium). Idempotent: skips spawn if already healthy. Usable by both agentproto browser adapters and app-layer launchers.",
+  "keywords": [
+    "agentproto",
+    "browser",
+    "camofox",
+    "health-check",
+    "process",
+    "launcher"
+  ],
+  "homepage": "https://agentproto.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/browser-process"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}