agentpal 0.1.0

package/Cargo.toml

@@ -0,0 +1,30 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/host",
+    "crates/protocol",
+    "crates/relay",
+]
+
+[workspace.package]
+edition = "2024"
+license = "MIT"
+version = "0.1.0"
+
+[workspace.dependencies]
+agentpal-protocol = { path = "crates/protocol" }
+anyhow = "1.0.100"
+axum = { version = "0.8.9", features = ["ws"] }
+clap = { version = "4.5.53", features = ["derive", "env"] }
+futures-util = "0.3.31"
+local-ip-address = "0.6.13"
+qrcode = { version = "0.14.1", default-features = false }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.145"
+time = { version = "0.3.44", features = ["serde", "formatting", "macros", "parsing"] }
+tokio = { version = "1.48.0", features = ["macros", "net", "process", "rt-multi-thread", "signal", "sync", "time"] }
+tokio-tungstenite = "0.29.0"
+tracing = "0.1.41"
+tracing-subscriber = { version = "0.3.22", features = ["env-filter"] }
+url = "2.5.7"
+uuid = { version = "1.19.0", features = ["serde", "v4", "v7"] }

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LnYo-Cly
+
+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

@@ -0,0 +1,43 @@
+# AgentPal
+
+AgentPal connects a local coding-agent host to the AgentPal mobile app through a Cloud Relay pairing flow.
+
+This first npm release is a source-based CLI package: it runs the packaged Rust host and relay through `cargo run`.
+
+## Install
+
+Run without installing:
+
+```bash
+npx agentpal@latest pair
+```
+
+Or install globally:
+
+```bash
+npm install -g agentpal
+agentpal pair
+```
+
+## Commands
+
+```bash
+agentpal pair
+agentpal pair --workspace .
+agentpal relay --host 0.0.0.0 --port 8790
+agentpal host codex connect --workspace .
+```
+
+`agentpal pair` uses the current directory as the default workspace and the public Cloud Relay by default. For local development, pass a local Relay URL:
+
+```bash
+agentpal pair --workspace . --relay-url ws://127.0.0.1:8790/ws
+```
+
+## Requirements
+
+- Node.js
+- Rust toolchain with `cargo`
+- Codex CLI available as `codex` for live host sessions
+
+The npm package currently builds and runs the Rust host/relay from source through `cargo run`.

package/bin/agentpal.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const DEFAULT_PUBLIC_RELAY_URL = "wss://openagentpal-production.up.railway.app/ws";
+const UPDATE_CHECK_URL = "https://registry.npmjs.org/agentpal/latest";
+const UPDATE_CHECK_TIMEOUT_MS = 900;
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const callerCwd = process.cwd();
+const defaultCargoTargetDir = join(homedir(), ".agentpal", "cargo-target");
+const packageMetadata = readPackageMetadata();
+
+const args = process.argv.slice(2);
+const command = args[0] ?? "help";
+
+if (command === "help" || command === "--help" || command === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === "pair") {
+  await maybeShowUpdateNotice();
+  runCargo([
+    "run",
+    "-p",
+    "agentpal-host",
+    "--",
+    "codex",
+    "connect",
+    "--create-pair",
+    ...defaultRelayArgs(args.slice(1)),
+    ...withDefaultWorkspaceArgs(args.slice(1))
+  ]);
+} else if (command === "relay") {
+  await maybeShowUpdateNotice();
+  runCargo(["run", "-p", "agentpal-relay", "--", ...args.slice(1)]);
+} else if (command === "host") {
+  await maybeShowUpdateNotice();
+  runCargo(["run", "-p", "agentpal-host", "--", ...normalizeHostArgs(args.slice(1))]);
+} else {
+  console.error(`Unknown agentpal command: ${command}`);
+  console.error("");
+  printHelp();
+  process.exit(2);
+}
+
+function defaultRelayArgs(passThrough) {
+  if (hasFlagValue(passThrough, "--relay-url")) {
+    return [];
+  }
+  const relayUrl = process.env.AGENTPAL_RELAY_URL ?? DEFAULT_PUBLIC_RELAY_URL;
+  return ["--relay-url", relayUrl];
+}
+
+function hasFlagValue(items, flag) {
+  return items.some((item) => item === flag || item.startsWith(`${flag}=`));
+}
+
+function normalizeWorkspaceArgs(items) {
+  const normalized = [];
+  for (let index = 0; index < items.length; index += 1) {
+    const item = items[index];
+    if (item === "--workspace" && index + 1 < items.length) {
+      normalized.push(item, resolveWorkspaceValue(items[index + 1]));
+      index += 1;
+      continue;
+    }
+    if (item.startsWith("--workspace=")) {
+      normalized.push(`--workspace=${resolveWorkspaceValue(item.slice("--workspace=".length))}`);
+      continue;
+    }
+    normalized.push(item);
+  }
+  return normalized;
+}
+
+function withDefaultWorkspaceArgs(items) {
+  const normalized = normalizeWorkspaceArgs(items);
+  if (hasFlagValue(normalized, "--workspace")) {
+    return normalized;
+  }
+  return [...normalized, "--workspace", callerCwd];
+}
+
+function normalizeHostArgs(items) {
+  const normalized = normalizeWorkspaceArgs(items);
+  if (hostCommandNeedsDefaultWorkspace(normalized) && !hasFlagValue(normalized, "--workspace")) {
+    return [...normalized, "--workspace", callerCwd];
+  }
+  return normalized;
+}
+
+function hostCommandNeedsDefaultWorkspace(items) {
+  return items[0] === "codex" && (items[1] === "probe" || items[1] === "connect");
+}
+
+function resolveWorkspaceValue(value) {
+  if (!value) {
+    return value;
+  }
+  return resolve(callerCwd, value);
+}
+
+async function maybeShowUpdateNotice() {
+  if (process.env.AGENTPAL_NO_UPDATE_CHECK === "1") {
+    return;
+  }
+
+  const latest = await fetchLatestVersion().catch(() => null);
+  const current = packageMetadata.version;
+  if (!latest || !current || !isVersionGreater(latest, current)) {
+    return;
+  }
+
+  console.error(`AgentPal ${latest} is available. Update with: npm install -g agentpal@latest`);
+}
+
+async function fetchLatestVersion() {
+  const url = process.env.AGENTPAL_UPDATE_CHECK_URL ?? UPDATE_CHECK_URL;
+  const response = await fetchJson(url, UPDATE_CHECK_TIMEOUT_MS);
+  const version = typeof response.version === "string" ? response.version.trim() : "";
+  return version || null;
+}
+
+function fetchJson(url, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    const transport = parsed.protocol === "http:" ? http : https;
+    const request = transport.get(parsed, { headers: { accept: "application/json" } }, (response) => {
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`unexpected status ${response.statusCode}`));
+        return;
+      }
+
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        body += chunk;
+        if (body.length > 64 * 1024) {
+          request.destroy(new Error("response too large"));
+        }
+      });
+      response.on("end", () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error("update check timed out"));
+    });
+    request.on("error", reject);
+  });
+}
+
+function readPackageMetadata() {
+  try {
+    return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function isVersionGreater(candidate, current) {
+  const candidateParts = parseVersion(candidate);
+  const currentParts = parseVersion(current);
+  if (!candidateParts || !currentParts) {
+    return false;
+  }
+
+  for (let index = 0; index < 3; index += 1) {
+    if (candidateParts[index] > currentParts[index]) {
+      return true;
+    }
+    if (candidateParts[index] < currentParts[index]) {
+      return false;
+    }
+  }
+  return false;
+}
+
+function parseVersion(version) {
+  const match = String(version).trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function runCargo(cargoArgs) {
+  const env = { ...process.env };
+  env.CARGO_TARGET_DIR ??= defaultCargoTargetDir;
+
+  const child = spawn("cargo", cargoArgs, {
+    cwd: packageRoot,
+    env,
+    stdio: "inherit"
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+
+  child.on("error", (error) => {
+    console.error(`Failed to start cargo: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+function printHelp() {
+  console.log(`AgentPal CLI
+
+Usage:
+  agentpal pair [options]
+  agentpal relay [agentpal-relay options]
+  agentpal host [agentpal-host options]
+
+Commands:
+  pair   Start the Codex Host, create a Cloud Relay pairing, and print URL + QR.
+  relay  Run the local relay service.
+  host   Pass through to the Rust host CLI.
+
+Defaults:
+  agentpal pair uses AGENTPAL_RELAY_URL when set, otherwise ${DEFAULT_PUBLIC_RELAY_URL}.
+  agentpal pair uses the current directory as --workspace unless one is supplied.
+  Local development can pass --relay-url ws://127.0.0.1:8790/ws.
+
+Examples:
+  agentpal relay --host 0.0.0.0 --port 8790
+  agentpal pair
+  agentpal pair --workspace .
+  agentpal pair --workspace . --relay-url ws://127.0.0.1:8790/ws
+  agentpal host codex connect --workspace .
+`);
+}

package/crates/host/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "agentpal-host"
+edition.workspace = true
+license.workspace = true
+version.workspace = true
+
+[dependencies]
+agentpal-protocol.workspace = true
+anyhow.workspace = true
+clap.workspace = true
+futures-util.workspace = true
+local-ip-address.workspace = true
+qrcode.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+time.workspace = true
+tokio.workspace = true
+tokio-tungstenite.workspace = true
+url.workspace = true
+uuid.workspace = true