@agenvo/codex-app-server 0.1.0 → 0.2.0-rc.1

package/README.md

@@ -5,11 +5,11 @@
 Connect to an independently running Codex app-server over a Unix socket or loopback WebSocket. Connector shutdown and updates leave the native service and its turns running.
 
 ```sh
-npm install --global @agenvo/codex-app-server@0.1.0
+npm install --global @agenvo/codex-app-server@0.2.0-rc.1
 ```
 
-For AI agents: follow the [installation guide](https://github.com/Xuanwo/agenvo/blob/v0.1.0/docs/installation.md) for relay deployment, device pairing, and client authorization.
+For AI agents: follow the [installation guide](https://github.com/Xuanwo/agenvo/blob/v0.2.0-rc.1/docs/installation.md) for relay deployment, device pairing, and client authorization.
 
 Requires Node.js 24.13+. Installing a Connector does not install Herdr or Codex.
 
-[Usage and deployment](https://github.com/Xuanwo/agenvo/blob/v0.1.0/docs/usage.md)
+[Usage and deployment](https://github.com/Xuanwo/agenvo/blob/v0.2.0-rc.1/docs/usage.md)

package/README.zh-CN.md

@@ -5,11 +5,11 @@
 通过 Unix socket 或 loopback WebSocket 连接独立运行的 Codex app-server。关闭或更新 Connector 不会停止原生服务及其轮次。
 
 ```sh
-npm install --global @agenvo/codex-app-server@0.1.0
+npm install --global @agenvo/codex-app-server@0.2.0-rc.1
 ```
 
-AI Agent 请按照[安装指南](https://github.com/Xuanwo/agenvo/blob/v0.1.0/docs/installation.zh-CN.md)完成中继部署、设备配对和客户端授权。
+AI Agent 请按照[安装指南](https://github.com/Xuanwo/agenvo/blob/v0.2.0-rc.1/docs/installation.zh-CN.md)完成中继部署、设备配对和客户端授权。
 
 需要 Node.js 24.13+。安装 Connector 不会安装 Herdr 或 Codex。
 
-[使用与部署说明](https://github.com/Xuanwo/agenvo/blob/v0.1.0/docs/usage.zh-CN.md)
+[使用与部署说明](https://github.com/Xuanwo/agenvo/blob/v0.2.0-rc.1/docs/usage.zh-CN.md)

package/dist/cli.js

@@ -5,15 +5,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// ../../packages/connector/src/cli/main.ts
-import { parseArgs } from "node:util";
-import { execFile as execFile2, spawn } from "node:child_process";
-import { promisify as promisify2 } from "node:util";
-import { randomBytes } from "node:crypto";
-import { readFile as readFile3, unlink as unlink3, stat as stat2 } from "node:fs/promises";
-import { join as join4 } from "node:path";
-import { hostname as hostname3 } from "node:os";
-
 // ../../node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -19682,6 +19673,64 @@ function date4(params) {
   return _coercedDate(ZodDate, params);
 }
 
+// ../../packages/protocol/src/address.ts
+var RelayAddress = class {
+  baseUrl;
+  origin;
+  prefix;
+  constructor(value) {
+    const url2 = new URL(value);
+    const rawPath = value.replace(/^https:\/\/[^/]+/i, "");
+    if (!/^https:\/\//i.test(value) || /[\s\x00-\x1f\x7f]/.test(value) || url2.protocol !== "https:" || url2.username || url2.password || value.includes("?") || value.includes("#") || value.includes("\\") || /%2f|%5c/i.test(url2.pathname) || url2.pathname.includes("//") || rawPath.split("/").some((part) => /^(\.|%2e){1,2}$/i.test(part)))
+      throw new Error(
+        "Expected an HTTPS base URL without credentials, query, fragment or ambiguous path segments"
+      );
+    this.origin = url2.origin;
+    this.prefix = url2.pathname.replace(/\/$/, "");
+    this.baseUrl = this.origin + this.prefix;
+  }
+  get authorizationMetadataUrl() {
+    return this.origin + "/.well-known/oauth-authorization-server" + this.prefix;
+  }
+  get resourceMetadataUrl() {
+    return this.origin + "/.well-known/oauth-protected-resource" + this.path("/mcp");
+  }
+  path(route) {
+    return this.prefix + route;
+  }
+  url(route) {
+    return this.baseUrl + route;
+  }
+  /** Undefined means this URL does not belong to this deployment. */
+  route(value) {
+    const url2 = new URL(value);
+    if (url2.origin !== this.origin) return;
+    if (url2.pathname === this.prefix) return "/";
+    if (!url2.pathname.startsWith(this.prefix + "/")) return;
+    return url2.pathname.slice(this.prefix.length);
+  }
+};
+var baseUrlSchema = external_exports.string().transform((value, ctx) => {
+  try {
+    return new RelayAddress(value).baseUrl;
+  } catch {
+    ctx.addIssue({
+      code: "custom",
+      message: "Expected an HTTPS base URL with an optional path prefix"
+    });
+    return external_exports.NEVER;
+  }
+});
+
+// ../../packages/connector/src/cli/main.ts
+import { parseArgs } from "node:util";
+import { execFile as execFile2, spawn } from "node:child_process";
+import { promisify as promisify2 } from "node:util";
+import { randomBytes } from "node:crypto";
+import { readFile as readFile3, unlink as unlink3, stat as stat2 } from "node:fs/promises";
+import { join as join4 } from "node:path";
+import { hostname as hostname3 } from "node:os";
+
 // ../../packages/connector/src/config.ts
 import { homedir } from "node:os";
 import { join, resolve, dirname, isAbsolute } from "node:path";
@@ -19697,9 +19746,10 @@ import {
   unlink
 } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 
 // ../../packages/protocol/src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0-rc.1";
 var PROTOCOL = 1;
 var LIMITS = {
   frame: 64 * 1024,
@@ -19819,10 +19869,7 @@ var commonInstanceFields = {
 };
 var configSchema = (instanceSchema2) => external_exports.strictObject({
   schema: external_exports.literal(1),
-  relay: external_exports.string().url().refine((value) => {
-    const url2 = new URL(value);
-    return url2.protocol === "https:" && url2.origin === value;
-  }, "Relay must be a canonical HTTPS origin").optional(),
+  relay: baseUrlSchema.optional(),
   deviceId: external_exports.string().uuid().optional(),
   name: external_exports.string().max(128),
   instances: external_exports.array(instanceSchema2).max(128)
@@ -19842,7 +19889,19 @@ async function atomicJson(path, value) {
       mode: 384,
       flag: "wx"
     });
-    await rename(temp, path);
+    const deadline = Date.now() + 1e3;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await rename(temp, path);
+        break;
+      } catch (error62) {
+        if (process.platform !== "win32" || !["EACCES", "EPERM", "EBUSY"].includes(
+          error62.code ?? ""
+        ) || Date.now() >= deadline)
+          throw error62;
+        await delay(Math.min(10 * 2 ** attempt, 100, deadline - Date.now()));
+      }
+    }
   } finally {
     await unlink(temp).catch(() => {
     });
@@ -20038,7 +20097,17 @@ async function run(dir, backend2) {
   const save = () => {
     status.updatedAt = Date.now();
     const snapshot = structuredClone(status);
-    saving = saving.then(() => atomicJson(join2(dir, "status.json"), snapshot)).catch(() => {
+    saving = saving.then(() => atomicJson(join2(dir, "status.json"), snapshot)).catch((err) => {
+      connectionLog.error(
+        {
+          event: "connector.status.write_failed",
+          state: snapshot.state,
+          code: err.code,
+          syscall: err.syscall,
+          err
+        },
+        "Failed to publish connector status"
+      );
     });
   };
   const send = (current, packet) => {
@@ -20099,7 +20168,7 @@ async function run(dir, backend2) {
   }
   const connect = () => {
     if (stopped || terminal) return;
-    const url2 = new URL("/connect", target);
+    const url2 = new URL(target + "/connect");
     url2.protocol = url2.protocol === "https:" ? "wss:" : "ws:";
     const current = socket = new WebSocket(url2, {
       headers: {
@@ -20438,21 +20507,22 @@ async function service(dir, action, entry) {
 }
 
 // ../../packages/connector/src/cli/admin-client.ts
-function ownerOrigin(value) {
-  if (!value) throw new Fault("origin_required", "Pass --origin https://RELAY");
-  const url2 = new URL(value);
-  if (url2.protocol !== "https:" || url2.origin !== value)
-    throw new Fault("https_origin_required");
-  return url2.origin;
-}
-async function adminRequest(origin, method, path, body = "") {
+function ownerBaseUrl(value) {
+  if (!value)
+    throw new Fault(
+      "base_url_required",
+      "Pass --base-url https://RELAY[/PREFIX]"
+    );
+  return baseUrlSchema.parse(value);
+}
+async function adminRequest(baseUrl, method, path, body = "") {
   const secret = process.env.AGENVO_ADMIN_SECRET;
   if (!secret)
     throw new Fault(
       "admin_secret_required",
       "Set AGENVO_ADMIN_SECRET for explicit administrator automation, or use the management page."
     );
-  const response = await fetch(origin + path, {
+  const response = await fetch(baseUrl + path, {
     method,
     redirect: "error",
     signal: AbortSignal.timeout(15e3),
@@ -20472,7 +20542,7 @@ async function adminRequest(origin, method, path, body = "") {
 
 // ../../packages/connector/src/cli/admin.ts
 async function adminCommand(action, kind, options) {
-  const origin = ownerOrigin(String(options.origin ?? ""));
+  const baseUrl = ownerBaseUrl(String(options["base-url"] ?? ""));
   let path, body = "", method = "POST";
   if (action === "state") {
     path = "/api/admin/state";
@@ -20496,12 +20566,12 @@ async function adminCommand(action, kind, options) {
       ...options["instance-id"] ? { instanceId: options["instance-id"] } : {}
     });
   } else throw new Fault("invalid_arguments");
-  return adminRequest(origin, method, path, body);
+  return adminRequest(baseUrl, method, path, body);
 }
 
 // ../../packages/connector/src/cli/pairing.ts
 async function pairingCommand(action, code, options) {
-  const origin = ownerOrigin(String(options.origin ?? ""));
+  const baseUrl = ownerBaseUrl(String(options["base-url"] ?? ""));
   if (!["list", "approve"].includes(action))
     throw new Fault("invalid_arguments");
   const method = action === "list" ? "GET" : "POST";
@@ -20512,7 +20582,7 @@ async function pairingCommand(action, code, options) {
       "Pass a pairing code and --fingerprint from the device terminal"
     );
   const body = action === "list" ? "" : JSON.stringify({ code, digest: options.fingerprint });
-  return adminRequest(origin, method, path, body);
+  return adminRequest(baseUrl, method, path, body);
 }
 
 // ../../packages/connector/src/cli/main.ts
@@ -20526,7 +20596,7 @@ async function connectorCli(backend2, entry) {
         "label",
         "binary",
         "cwd",
-        "origin",
+        "base-url",
         "fingerprint",
         "device-id",
         "instance-id",
@@ -20599,11 +20669,11 @@ async function connectorCli(backend2, entry) {
 ${backend2.command} instance add --id ID ${backend2.help}
 ${backend2.command} connect https://RELAY [--name NAME] [--approve | --no-wait --no-browser]
 ${backend2.command} connect --cancel
-${backend2.command} pairing list --origin https://RELAY
-${backend2.command} pairing approve CODE --fingerprint SHA256 --origin https://RELAY
-${backend2.command} admin state --origin https://RELAY
-${backend2.command} admin approve-instance --device-id ID --instance-id ID --fingerprint SHA256 --origin https://RELAY
-${backend2.command} admin revoke device|instance|grant --id ID [--instance-id ID] --origin https://RELAY
+${backend2.command} pairing list --base-url https://RELAY
+${backend2.command} pairing approve CODE --fingerprint SHA256 --base-url https://RELAY
+${backend2.command} admin state --base-url https://RELAY
+${backend2.command} admin approve-instance --device-id ID --instance-id ID --fingerprint SHA256 --base-url https://RELAY
+${backend2.command} admin revoke device|instance|grant --id ID [--instance-id ID] --base-url https://RELAY
 ${backend2.command} run
 ${backend2.command} service install|uninstall
 ${backend2.command} status --json
@@ -20640,7 +20710,7 @@ After changing instances, restart this connector and approve the changed scope.`
         config: join4(dir, "config.json"),
         scope: instance,
         ...c.relay ? {
-          next: "Restart the connector, inspect " + backend2.command + " admin state --origin " + c.relay + ", then use " + backend2.command + " admin approve-instance."
+          next: "Restart the connector, inspect " + backend2.command + " admin state --base-url " + c.relay + ", then use " + backend2.command + " admin approve-instance."
         } : {}
       });
       return;
@@ -20658,9 +20728,7 @@ After changing instances, restart this connector and approve the changed scope.`
         });
         return output2({ cancelled: true });
       }
-      const relay = new URL(subcommand);
-      if (relay.protocol !== "https:" || relay.pathname !== "/" || relay.username || relay.password || relay.search || relay.hash)
-        throw new Fault("https_origin_required");
+      const relay = baseUrlSchema.parse(subcommand);
       const c = await config2();
       if (c.deviceId)
         throw new Fault(
@@ -20670,7 +20738,7 @@ After changing instances, restart this connector and approve the changed scope.`
       let p;
       try {
         p = JSON.parse(await readFile3(join4(dir, "pairing.json"), "utf8"));
-        if (p.relay !== relay.origin)
+        if (p.relay !== relay)
           throw new Fault(
             "pending_pairing",
             "Cancel the existing pairing before choosing a different relay"
@@ -20701,14 +20769,14 @@ After changing instances, restart this connector and approve the changed scope.`
             )
           )
         );
-        p = await post(new URL("/pairings", relay).href, {
+        p = await post(relay + "/pairings", {
           digest: await digest(secret),
           label: String(options.name ?? c.name),
           instances
         });
         p = {
           ...p,
-          relay: relay.origin,
+          relay,
           expires: Date.now() + p.expiresIn * 1e3,
           name: String(options.name ?? c.name),
           configHash: await digest(JSON.stringify(c.instances))
@@ -20723,7 +20791,7 @@ After changing instances, restart this connector and approve the changed scope.`
       if (options["no-wait"]) return;
       if (options.approve) {
         await pairingCommand("approve", p.code, {
-          origin: relay.origin,
+          "base-url": relay,
           fingerprint: p.fingerprint
         });
       } else {
@@ -20732,13 +20800,13 @@ After changing instances, restart this connector and approve the changed scope.`
       const expires = p.expires;
       while (Date.now() < expires) {
         const result = await post(
-          new URL("/pairings/poll", relay).href,
+          relay + "/pairings/poll",
           { code: p.code },
           p.pollSecret
         );
         if (result.status === "approved") {
           c.deviceId = result.deviceId;
-          c.relay = relay.origin;
+          c.relay = relay;
           c.name = p.name;
           await saveConfig(c, dir, backend2.schema);
           await unlink3(join4(dir, "pairing.json"));
@@ -20882,7 +20950,7 @@ After changing instances, restart this connector and approve the changed scope.`
         cloudRevoked,
         serviceUninstalled,
         ...cloudRevoked ? {} : {
-          next: "When connectivity returns, run " + backend2.command + " admin revoke device --id " + revokedDeviceId + " --origin " + c.relay
+          next: "When connectivity returns, run " + backend2.command + " admin revoke device --id " + revokedDeviceId + " --base-url " + c.relay
         }
       });
       return;
@@ -23045,7 +23113,7 @@ var CodexAdapter = class {
       ws.once("close", () => reject(new Fault("runtime_unavailable")));
     });
     const init = await this.rpc("initialize", {
-      clientInfo: { name: "agenvo", version: "0.1.0" },
+      clientInfo: { name: "agenvo", version: VERSION },
       capabilities: { experimentalApi: true }
     });
     if (await realpath2(init.codexHome) !== await realpath2(this.config.home))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenvo/codex-app-server",
-  "version": "0.1.0",
+  "version": "0.2.0-rc.1",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -12,8 +12,8 @@
     "node": ">=24.13.0"
   },
   "devDependencies": {
-    "@agenvo/connector": "0.1.0",
-    "@agenvo/protocol": "0.1.0",
+    "@agenvo/connector": "0.2.0-rc.1",
+    "@agenvo/protocol": "0.2.0-rc.1",
     "zod": "4.6.5"
   },
   "description": "Codex app-server connector for Agenvo",