@tetsuo-ai/agenc 0.2.0 → 0.3.0

package/src/launcher.mjs

@@ -0,0 +1,246 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_READY_TIMEOUT_MS = 2000;
+const DEFAULT_POLL_MS = 25;
+const READY_TIMEOUT_ENV = "AGENC_DAEMON_READY_TIMEOUT_MS";
+const AUTOSTART_ENV = "AGENC_DAEMON_AUTOSTART";
+
+const requireFromLauncher = createRequire(import.meta.url);
+
+export function shouldAutostartDaemon(env = process.env) {
+  const raw = env[AUTOSTART_ENV]?.trim().toLowerCase();
+  if (raw === undefined || raw.length === 0) return true;
+  return raw !== "0" && raw !== "false" && raw !== "off";
+}
+
+export function resolveReadyTimeoutMs(env = process.env) {
+  const raw = env[READY_TIMEOUT_ENV]?.trim();
+  if (raw === undefined || raw.length === 0) return DEFAULT_READY_TIMEOUT_MS;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || String(parsed) !== raw || parsed <= 0) {
+    throw new Error(`${READY_TIMEOUT_ENV} must be a positive integer`);
+  }
+  return parsed;
+}
+
+export function resolveAgenCHome(env = process.env, userHome = homedir()) {
+  const configured = env.AGENC_HOME?.trim();
+  return configured && configured.length > 0
+    ? configured
+    : join(userHome, ".agenc");
+}
+
+export function resolveDaemonPidPath(env = process.env, userHome = homedir()) {
+  return join(resolveAgenCHome(env, userHome), "daemon.pid");
+}
+
+export function resolveDaemonCookiePath(env = process.env, userHome = homedir()) {
+  return join(resolveAgenCHome(env, userHome), "daemon.cookie");
+}
+
+export async function readDaemonPid(pidPath, readText = readFile) {
+  try {
+    const raw = (await readText(pidPath, "utf8")).trim();
+    if (!/^\d+$/.test(raw)) return null;
+    const pid = Number.parseInt(raw, 10);
+    return pid > 0 ? pid : null;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export function isPidRunning(pid, signalPid = process.kill) {
+  try {
+    signalPid(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+export function isDaemonCommand(argv) {
+  return argv[0] === "daemon";
+}
+
+// Dev path: the `file:`-linked @tetsuo-ai/runtime resolves locally. Returns
+// null in a published install where runtime is NOT an npm dependency (it's the
+// downloaded GitHub-Releases artifact instead).
+export function resolveRuntimeBin(requireFn = requireFromLauncher) {
+  try {
+    const runtimeEntry = requireFn.resolve("@tetsuo-ai/runtime");
+    return resolve(dirname(runtimeEntry), "../bin/agenc");
+  } catch (error) {
+    if (
+      error?.code === "MODULE_NOT_FOUND" ||
+      error?.code === "ERR_MODULE_NOT_FOUND"
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// Resolve the runtime entry for either mode: prefer the dev file:-link, else
+// ensure (download + verify + extract) the published per-platform runtime.
+export async function resolveRuntimeBinAsync({
+  requireFn = requireFromLauncher,
+  ensureFn,
+} = {}) {
+  const dev = resolveRuntimeBin(requireFn);
+  if (dev !== null) return dev;
+  const ensureRuntime =
+    ensureFn ?? (await import("../lib/runtime-manager.mjs")).ensureRuntime;
+  return ensureRuntime();
+}
+
+export async function spawnNodeScript(
+  scriptPath,
+  args,
+  {
+    env = process.env,
+    cwd = process.cwd(),
+    stdio = "inherit",
+    spawnFn = spawn,
+  } = {},
+) {
+  return new Promise((resolveExit, reject) => {
+    const child = spawnFn(process.execPath, [scriptPath, ...args], {
+      cwd,
+      env,
+      stdio,
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal !== null) {
+        reject(new Error(`agenc runtime exited from signal ${signal}`));
+        return;
+      }
+      resolveExit(code ?? 1);
+    });
+  });
+}
+
+export async function spawnDaemon(runtimeBin, options = {}) {
+  const exitCode = await spawnNodeScript(runtimeBin, ["daemon", "start"], {
+    ...options,
+    stdio: ["ignore", "ignore", "inherit"],
+  });
+  if (exitCode !== 0) {
+    throw new Error(`AgenC daemon start failed with exit code ${exitCode}`);
+  }
+}
+
+export async function isDaemonReady(
+  {
+    env = process.env,
+    userHome = homedir(),
+    readText = readFile,
+    signalPid = process.kill,
+  } = {},
+) {
+  const pidPath = resolveDaemonPidPath(env, userHome);
+  const cookiePath = resolveDaemonCookiePath(env, userHome);
+  const pid = await readDaemonPid(pidPath, readText);
+  if (pid === null || !isPidRunning(pid, signalPid)) return false;
+  try {
+    return (await readText(cookiePath, "utf8")).trim().length > 0;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function waitForDaemonReady(options = {}) {
+  const timeoutMs = options.timeoutMs ?? resolveReadyTimeoutMs(options.env);
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const startedAt = Date.now();
+  const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await isDaemonReady(options)) return true;
+    await sleep(pollMs);
+  }
+  return isDaemonReady(options);
+}
+
+export async function ensureDaemonForLaunch({
+  argv = process.argv.slice(2),
+  env = process.env,
+  cwd = process.cwd(),
+  runtimeBin = resolveRuntimeBin(),
+  userHome = homedir(),
+  readText = readFile,
+  signalPid = process.kill,
+  spawnDaemonFn = spawnDaemon,
+  waitForReadyFn = waitForDaemonReady,
+} = {}) {
+  if (isDaemonCommand(argv)) return { status: "skipped-daemon-command" };
+  if (!shouldAutostartDaemon(env)) return { status: "disabled" };
+
+  if (
+    await waitForReadyFn({
+      env,
+      userHome,
+      readText,
+      signalPid,
+      timeoutMs: 1,
+      pollMs: 1,
+      sleep: async () => {},
+    })
+  ) {
+    return { status: "already-running" };
+  }
+
+  await spawnDaemonFn(runtimeBin, { env, cwd });
+  const ready = await waitForReadyFn({ env, userHome, readText, signalPid });
+  if (!ready) {
+    throw new Error("AgenC daemon did not become ready before timeout");
+  }
+  return { status: "started" };
+}
+
+export async function main(
+  argv = process.argv.slice(2),
+  {
+    env = process.env,
+    cwd = process.cwd(),
+    runtimeBin,
+    userHome = homedir(),
+  } = {},
+) {
+  // Resolve (and, in a published install, download + verify) the runtime before
+  // anything tries to spawn it. Sync default is avoided: it returns null when
+  // runtime isn't an npm dep, which is the normal published case.
+  let resolvedBin = runtimeBin;
+  try {
+    resolvedBin ??= await resolveRuntimeBinAsync();
+  } catch (error) {
+    process.stderr.write(
+      `agenc: could not obtain runtime: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`,
+    );
+    return 1;
+  }
+  try {
+    await ensureDaemonForLaunch({ argv, env, cwd, runtimeBin: resolvedBin, userHome });
+  } catch (error) {
+    process.stderr.write(
+      `agenc: daemon autostart failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`,
+    );
+    return 1;
+  }
+  return spawnNodeScript(resolvedBin, argv, { env, cwd, stdio: "inherit" });
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  process.exitCode = await main();
+}

package/README.md

@@ -1,144 +0,0 @@
-# agenc
-
-Public CLI and launcher for the AgenC framework.
-
-This package owns the user-facing global install surface:
-
-```bash
-npm install -g @tetsuo-ai/agenc
-agenc onboard
-agenc start
-agenc
-agenc ui
-```
-
-`agenc onboard` is the canonical first-run path. It opens an interactive
-terminal onboarding flow that:
-
-- validates an xAI API key
-- lets the operator shape the agent name, mission, role, soul, and tool posture
-- writes the canonical config at `~/.agenc/config.json`
-- generates the curated workspace markdown profile under `~/.agenc/workspace/`
-
-It does not expose the runtime source tree directly. Instead, it installs and
-launches the matching AgenC runtime artifact for the current supported
-platform.
-
-The supported npm install identity is `@tetsuo-ai/agenc`. The unscoped
-`agenc` package name is not part of the supported public release contract.
-
-Current public support is intentionally narrow:
-
-- Linux `x64`
-- Node `>=18.0.0`
-
-Current validated release-gate lanes:
-
-- Node `18` minimum floor
-- Node `20` mainline lane
-
-Production release channel:
-
-- npm package: `@tetsuo-ai/agenc`
-- runtime artifact host: GitHub Releases on `tetsuo-ai/agenc-core`
-- trust: embedded signed manifest + embedded public key + embedded trust policy
-
-After the matching runtime artifact is installed, `agenc` can continue to run
-offline against the local install. The npm package name is scoped, but the CLI
-binary remains `agenc`.
-
-`agenc` exposes two primary local operator surfaces against the same daemon:
-
-- `agenc` attaches the terminal operator console
-- `agenc ui` opens or prints the local dashboard URL on `/ui/`
-
-For automation or remote shells, use:
-
-```bash
-agenc ui --no-open
-```
-
-## First-party connector lifecycle
-
-The first V1 connector is Telegram. It is managed through the same daemon as the
-CLI and dashboard; there is no separate connector service to start.
-
-```bash
-agenc connector list
-agenc connector status telegram
-agenc connector add telegram --bot-token-env TELEGRAM_BOT_TOKEN
-agenc connector remove telegram
-```
-
-For non-interactive shells or secret managers, you can pipe the bot token on
-stdin instead:
-
-```bash
-printf '%s' "$TELEGRAM_BOT_TOKEN" | agenc connector add telegram --bot-token-stdin
-```
-
-Connector health and pending-restart state are exposed through both:
-
-- `agenc connector status telegram`
-- `agenc ui` on the dashboard status view
-
-## Wrapper-local runtime management
-
-```bash
-agenc runtime where
-agenc runtime install
-agenc runtime update
-agenc runtime uninstall
-```
-
-## First-use devnet marketplace rehearsal
-
-For public release-path docs and operator rehearsal, use the top-level `agenc`
-commands. `agenc-runtime` remains available as a compatibility alias after the
-runtime is installed, but it is not the primary public wrapper path.
-
-Supported release-path boundary:
-
-- Linux `x64`
-- Node `>=18.0.0`
-
-Manual prerequisites that still live outside the wrapper:
-
-- Solana CLI available on `PATH`
-- funded devnet keypair at `SOLANA_KEYPAIR_PATH` or `~/.config/solana/id.json`
-- `--rpc` or `AGENC_RUNTIME_RPC_URL`
-- optional `--program-id` or `AGENC_RUNTIME_PROGRAM_ID` when testing a non-default deployment
-- a second funded signer plus a second agent registration if you want a separate worker identity for `claim` and `complete`
-
-Minimal creator flow:
-
-```bash
-export AGENC_RUNTIME_RPC_URL=https://api.devnet.solana.com
-agenc onboard
-agenc runtime install
-agenc start
-agenc agent register --rpc "$AGENC_RUNTIME_RPC_URL"
-agenc market tasks create --description "public task" --reward 50000000 --rpc "$AGENC_RUNTIME_RPC_URL"
-agenc market tasks list --rpc "$AGENC_RUNTIME_RPC_URL"
-agenc market tui --rpc "$AGENC_RUNTIME_RPC_URL"
-```
-
-Claim and complete from a worker signer:
-
-```bash
-export SOLANA_KEYPAIR_PATH=/path/to/worker.json
-agenc agent register --rpc "$AGENC_RUNTIME_RPC_URL"
-agenc market tasks claim <taskPda> --rpc "$AGENC_RUNTIME_RPC_URL"
-agenc market tasks complete <taskPda> --result-data "completed via public wrapper" --rpc "$AGENC_RUNTIME_RPC_URL"
-```
-
-Notes:
-
-- `tasks claim|complete|dispute` require the signer wallet to already control a registered agent.
-- `disputes resolve` is not part of the public first-use rehearsal; it requires the protocol authority wallet.
-
-## Development
-
-The embedded runtime manifest in `generated/` is produced by the `agenc-core`
-artifact preparation scripts. Local smoke tests use the same packaged manifest
-flow as publish/release preparation.

package/bin/agenc-runtime.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-import { runAgencRuntimeWrapper } from "../lib/cli.js";
-
-const exitCode = await runAgencRuntimeWrapper();
-process.exitCode = exitCode;

package/bin/agenc.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-import { runAgencWrapper } from "../lib/cli.js";
-
-const exitCode = await runAgencWrapper();
-process.exitCode = exitCode;

package/generated/agenc-runtime-manifest.json.sig

@@ -1 +0,0 @@
-nyIC/iBXuyr5jy7GThy5GsYjD9GgmmnSnbD54CpupYwr97qdAhmRuxrA0cqxOegFwN1pAu6Lu+qOYHyaePBEAw==

package/generated/agenc-runtime-public-key.pem

@@ -1,3 +0,0 @@
------BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEAIMA9t7a75CBcuD4UTUkwjxThcPLZZO53Qg/zfpiwm4c=
------END PUBLIC KEY-----

package/generated/agenc-runtime-trust-policy.json

@@ -1,9 +0,0 @@
-{
-  "wrapperVersion": "0.2.0",
-  "keyId": "agenc-v0.2.0",
-  "releaseChannel": "github-releases",
-  "releaseRepository": "tetsuo-ai/agenc-core",
-  "releaseTag": "agenc-v0.2.0",
-  "revokedManifestDigests": [],
-  "revokedRuntimeVersions": []
-}

package/lib/cli.js

@@ -1,261 +0,0 @@
-import process from "node:process";
-import {
-  describeRuntimeInstall,
-  ensureRuntimeFromSource,
-  ensureRuntimeInstalled,
-  RuntimeInstallError,
-  spawnInstalledRuntimeBin,
-  spawnInstalledRuntimeBinFromSource,
-  uninstallRuntime,
-} from "./runtime-manager.js";
-
-function writeLine(stream, value) {
-  stream.write(`${value}\n`);
-}
-
-function buildAgencHelp() {
-  return [
-    "agenc [runtime-command] [options]",
-    "agenc runtime <where|install|update|uninstall>",
-    "",
-    "Examples:",
-    "  agenc onboard",
-    "  agenc ui",
-    "  agenc start",
-    "  agenc status",
-    "  agenc logs",
-    "  agenc runtime where",
-    "",
-    "Marketplace / devnet examples:",
-    "  agenc agent register --rpc https://api.devnet.solana.com",
-    "  agenc market tasks create --description 'public task' --reward 50000000 --rpc https://api.devnet.solana.com",
-    "  agenc market tui",
-    "",
-    "Supported public wrapper tuple:",
-    "  Linux x64, Node >=18.0.0",
-    "",
-    "Compatibility alias:",
-    "  agenc-runtime remains available after install, but public docs should use agenc.",
-    "",
-    "Dev / from-source:",
-    "  agenc start --from-source",
-    "  agenc start --from-source --source-dir /path/to/agenc-core/runtime",
-    "    Builds runtime/dist locally and points ~/.agenc/runtime/current at it.",
-  ].join("\n");
-}
-
-function buildAgencRuntimeHelp() {
-  return [
-    "agenc-runtime [runtime-command] [options]",
-    "",
-    "Compatibility alias for the installed AgenC runtime CLI.",
-    "",
-    "Dev flags:",
-    "  --from-source              build the local agenc-core/runtime tree",
-    "                             and run the daemon from there",
-    "  --source-dir <path>        explicit runtime/ source path",
-  ].join("\n");
-}
-
-async function runRuntimeAdmin(argv, io, deps, runtimeOptions) {
-  const command = argv[0];
-  const force = argv.includes("--force");
-  if (!command || command === "help" || command === "--help" || command === "-h") {
-    writeLine(
-      io.stdout,
-      "agenc runtime <where|install|update|uninstall> [--force]",
-    );
-    return 0;
-  }
-
-  if (command === "where") {
-    const description = await deps.describeRuntimeInstall(runtimeOptions);
-    writeLine(
-      io.stdout,
-      JSON.stringify(
-        {
-          runtimeHome: description.runtimeHome,
-          installed: description.installed,
-          releaseDir: description.releaseDir,
-          currentDir: description.currentDir,
-          manifestSource: description.manifestSource,
-          manifestDigest: description.manifestDigest,
-          trustPolicy: description.trustPolicy
-            ? {
-                wrapperVersion: description.trustPolicy.wrapperVersion,
-                keyId: description.trustPolicy.keyId,
-                releaseChannel: description.trustPolicy.releaseChannel ?? null,
-                releaseRepository:
-                  description.trustPolicy.releaseRepository ?? null,
-                releaseTag: description.trustPolicy.releaseTag ?? null,
-                revokedManifestDigests:
-                  description.trustPolicy.revokedManifestDigests,
-                revokedRuntimeVersions:
-                  description.trustPolicy.revokedRuntimeVersions,
-              }
-            : null,
-          selectedArtifact: description.selectedArtifact
-            ? {
-                runtimeVersion: description.selectedArtifact.runtimeVersion,
-                platform: description.selectedArtifact.platform,
-                arch: description.selectedArtifact.arch,
-                nodeRange: description.selectedArtifact.nodeRange,
-              }
-            : null,
-        },
-        null,
-        2,
-      ),
-    );
-    return 0;
-  }
-
-  if (command === "install" || command === "update") {
-    const installation = await deps.ensureRuntimeInstalled({
-      ...runtimeOptions,
-      force: command === "update",
-    });
-    writeLine(
-      io.stdout,
-      `Installed AgenC runtime ${installation.selectedArtifact.runtimeVersion} at ${installation.releaseDir}`,
-    );
-    return 0;
-  }
-
-  if (command === "uninstall") {
-    const result = await deps.uninstallRuntime({ ...runtimeOptions, force });
-    writeLine(
-      io.stdout,
-      result.removed
-        ? `Removed AgenC runtime at ${result.releaseDir}\nPreserved: ${result.preservedPaths.join(", ")}`
-        : "No installed AgenC runtime found for the current platform",
-    );
-    return 0;
-  }
-
-  writeLine(io.stderr, `Unknown agenc runtime command: ${command}`);
-  return 2;
-}
-
-const DEFAULT_DEPS = {
-  ensureRuntimeInstalled,
-  ensureRuntimeFromSource,
-  describeRuntimeInstall,
-  uninstallRuntime,
-  spawnInstalledRuntimeBin,
-  spawnInstalledRuntimeBinFromSource,
-};
-
-/**
- * Cut 6.1: detect and strip the `--from-source` flag (and the optional
- * `--source-dir <path>`) from the wrapper argv. Returns the remaining argv
- * plus the parsed flag values so the rest of the dispatcher can continue
- * to operate on a clean argument list.
- */
-function extractFromSourceFlags(argv) {
-  const remaining = [];
-  let fromSource = false;
-  let sourceDir;
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--from-source") {
-      fromSource = true;
-      continue;
-    }
-    if (arg === "--source-dir" && i + 1 < argv.length) {
-      sourceDir = argv[++i];
-      fromSource = true;
-      continue;
-    }
-    if (typeof arg === "string" && arg.startsWith("--source-dir=")) {
-      sourceDir = arg.slice("--source-dir=".length);
-      fromSource = true;
-      continue;
-    }
-    remaining.push(arg);
-  }
-  return { argv: remaining, fromSource, sourceDir };
-}
-
-function formatRuntimeInstallError(error) {
-  if (error instanceof RuntimeInstallError) {
-    return error.message;
-  }
-  return error instanceof Error ? error.message : String(error);
-}
-
-export async function runAgencWrapper(options = {}, deps = DEFAULT_DEPS) {
-  const rawArgv = options.argv ?? process.argv.slice(2);
-  const { argv, fromSource, sourceDir } = extractFromSourceFlags(rawArgv);
-  const stdout = options.stdout ?? process.stdout;
-  const stderr = options.stderr ?? process.stderr;
-  const runtimeOptions = {
-    env: options.env ?? process.env,
-    cwd: options.cwd ?? process.cwd(),
-    homeDir: options.homeDir,
-    packageRoot: options.packageRoot,
-    sourceDir,
-  };
-
-  try {
-    if (argv[0] === "runtime") {
-      return await runRuntimeAdmin(
-        argv.slice(1),
-        { stdout, stderr },
-        deps,
-        runtimeOptions,
-      );
-    }
-    if (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
-      writeLine(stdout, buildAgencHelp());
-      return 0;
-    }
-    if (fromSource) {
-      return await deps.spawnInstalledRuntimeBinFromSource(
-        "agenc",
-        argv,
-        runtimeOptions,
-      );
-    }
-    return await deps.spawnInstalledRuntimeBin("agenc", argv, runtimeOptions);
-  } catch (error) {
-    writeLine(stderr, formatRuntimeInstallError(error));
-    return 1;
-  }
-}
-
-export async function runAgencRuntimeWrapper(options = {}, deps = DEFAULT_DEPS) {
-  const rawArgv = options.argv ?? process.argv.slice(2);
-  const { argv, fromSource, sourceDir } = extractFromSourceFlags(rawArgv);
-  const stdout = options.stdout ?? process.stdout;
-  const stderr = options.stderr ?? process.stderr;
-  const runtimeOptions = {
-    env: options.env ?? process.env,
-    cwd: options.cwd ?? process.cwd(),
-    homeDir: options.homeDir,
-    packageRoot: options.packageRoot,
-    sourceDir,
-  };
-
-  try {
-    if (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
-      writeLine(stdout, buildAgencRuntimeHelp());
-      return 0;
-    }
-    if (fromSource) {
-      return await deps.spawnInstalledRuntimeBinFromSource(
-        "agenc-runtime",
-        argv,
-        runtimeOptions,
-      );
-    }
-    return await deps.spawnInstalledRuntimeBin(
-      "agenc-runtime",
-      argv,
-      runtimeOptions,
-    );
-  } catch (error) {
-    writeLine(stderr, formatRuntimeInstallError(error));
-    return 1;
-  }
-}