@tetsuo-ai/agenc 0.1.0 → 0.2.0

package/README.md

@@ -12,6 +12,14 @@ 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.
@@ -83,6 +91,52 @@ 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`

package/generated/agenc-runtime-manifest.json

@@ -1,19 +1,19 @@
 {
   "manifestVersion": 1,
-  "wrapperVersion": "0.1.0",
-  "keyId": "local-dev",
-  "generatedAt": "2026-03-19T03:15:47.658Z",
+  "wrapperVersion": "0.2.0",
+  "keyId": "agenc-v0.2.0",
+  "generatedAt": "2026-04-12T08:17:12.539Z",
   "releaseChannel": "github-releases",
   "releaseRepository": "tetsuo-ai/agenc-core",
-  "releaseTag": "v0.1.0",
+  "releaseTag": "agenc-v0.2.0",
   "artifacts": [
     {
       "platform": "linux",
       "arch": "x64",
       "nodeRange": ">=18.0.0",
-      "runtimeVersion": "0.1.0",
-      "url": "https://github.com/tetsuo-ai/agenc-core/releases/download/v0.1.0/agenc-runtime-0.1.0-linux-x64.tar.gz",
-      "sha256": "61fa09ac0332ab0d2e989cb35362f2b0b066b9b1eb5f64d224727ca46cc04c2c",
+      "runtimeVersion": "0.2.0",
+      "url": "https://github.com/tetsuo-ai/agenc-core/releases/download/agenc-v0.2.0/agenc-runtime-0.2.0-linux-x64.tar.gz",
+      "sha256": "67de5ba2c5bced79893414e226547016325d423dd630a25ff579b8cc6abbb76d",
       "bins": {
         "agenc": "node_modules/@tetsuo-ai/runtime/dist/bin/agenc.js",
         "agenc-runtime": "node_modules/@tetsuo-ai/runtime/dist/bin/agenc-runtime.js",

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

@@ -1 +1 @@
-iFOPHEatEGfaMVQhLsENy9CEenablWaZLG6G5V2u37hN44hvIwTtgoK6ihiHQL3aIJXmBEM2VRdSPInlJBtMAg==
+nyIC/iBXuyr5jy7GThy5GsYjD9GgmmnSnbD54CpupYwr97qdAhmRuxrA0cqxOegFwN1pAu6Lu+qOYHyaePBEAw==

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

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

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

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

package/lib/cli.js

@@ -1,9 +1,11 @@
 import process from "node:process";
 import {
   describeRuntimeInstall,
+  ensureRuntimeFromSource,
   ensureRuntimeInstalled,
   RuntimeInstallError,
   spawnInstalledRuntimeBin,
+  spawnInstalledRuntimeBinFromSource,
   uninstallRuntime,
 } from "./runtime-manager.js";
 
@@ -23,6 +25,22 @@ function buildAgencHelp() {
     "  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");
 }
 
@@ -31,6 +49,11 @@ function buildAgencRuntimeHelp() {
     "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");
 }
 
@@ -116,11 +139,44 @@ async function runRuntimeAdmin(argv, io, deps, runtimeOptions) {
 
 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;
@@ -129,7 +185,8 @@ function formatRuntimeInstallError(error) {
 }
 
 export async function runAgencWrapper(options = {}, deps = DEFAULT_DEPS) {
-  const argv = options.argv ?? process.argv.slice(2);
+  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 = {
@@ -137,6 +194,7 @@ export async function runAgencWrapper(options = {}, deps = DEFAULT_DEPS) {
     cwd: options.cwd ?? process.cwd(),
     homeDir: options.homeDir,
     packageRoot: options.packageRoot,
+    sourceDir,
   };
 
   try {
@@ -152,6 +210,13 @@ export async function runAgencWrapper(options = {}, deps = DEFAULT_DEPS) {
       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));
@@ -160,7 +225,8 @@ export async function runAgencWrapper(options = {}, deps = DEFAULT_DEPS) {
 }
 
 export async function runAgencRuntimeWrapper(options = {}, deps = DEFAULT_DEPS) {
-  const argv = options.argv ?? process.argv.slice(2);
+  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 = {
@@ -168,6 +234,7 @@ export async function runAgencRuntimeWrapper(options = {}, deps = DEFAULT_DEPS)
     cwd: options.cwd ?? process.cwd(),
     homeDir: options.homeDir,
     packageRoot: options.packageRoot,
+    sourceDir,
   };
 
   try {
@@ -175,6 +242,13 @@ export async function runAgencRuntimeWrapper(options = {}, deps = DEFAULT_DEPS)
       writeLine(stdout, buildAgencRuntimeHelp());
       return 0;
     }
+    if (fromSource) {
+      return await deps.spawnInstalledRuntimeBinFromSource(
+        "agenc-runtime",
+        argv,
+        runtimeOptions,
+      );
+    }
     return await deps.spawnInstalledRuntimeBin(
       "agenc-runtime",
       argv,

package/lib/runtime-manager.js

@@ -1,7 +1,8 @@
 import { createHash, verify } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import {
   copyFile,
+  lstat,
   mkdir,
   mkdtemp,
   open,
@@ -36,6 +37,27 @@ export class RuntimeInstallError extends Error {
   }
 }
 
+/**
+ * Remove a filesystem path regardless of whether it's a symlink, a
+ * regular file, or a directory. `fs.rm` with `recursive: true`
+ * follows symlinks to directories (removing the TARGET, not the
+ * link), so we `lstat` first and use `unlink` for the symlink case.
+ */
+async function removePathSafe(targetPath) {
+  let info;
+  try {
+    info = await lstat(targetPath);
+  } catch (error) {
+    if ((error && error.code) === "ENOENT") return;
+    throw error;
+  }
+  if (info.isSymbolicLink() || info.isFile()) {
+    await unlink(targetPath);
+    return;
+  }
+  await rm(targetPath, { recursive: true, force: true });
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -829,3 +851,261 @@ export async function prefetchRuntimeOnInstall(options = {}) {
   });
   return { prefetched: true };
 }
+
+// ---------------------------------------------------------------------------
+// Cut 6.1: --from-source dev mode
+//
+// The published-tarball install path lives above. This block adds a parallel
+// path that builds the runtime from a local source checkout and points
+// `~/.agenc/runtime/current` at it. Without this, the only way to land
+// changes on the running daemon is to publish a new tarball — which is
+// exactly the failure mode that left a 2-month silent-failure window in
+// place. The dev path is opt-in via `--from-source` and never runs by
+// default.
+// ---------------------------------------------------------------------------
+
+const FROM_SOURCE_PLATFORM_ARCH = "from-source";
+
+function resolveSourceRoot({
+  env = process.env,
+  cwd = process.cwd(),
+  explicit,
+} = {}) {
+  const candidates = [];
+  if (typeof explicit === "string" && explicit.trim().length > 0) {
+    candidates.push(path.resolve(explicit.trim()));
+  }
+  const envValue = env?.AGENC_RUNTIME_SOURCE_DIR;
+  if (typeof envValue === "string" && envValue.trim().length > 0) {
+    candidates.push(path.resolve(envValue.trim()));
+  }
+  // Walk upward from cwd looking for `runtime/package.json` whose name is
+  // `@tetsuo-ai/runtime` — that's the agenc-core monorepo root.
+  let current = path.resolve(cwd);
+  for (let i = 0; i < 8; i++) {
+    candidates.push(path.join(current, "runtime"));
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const pkgPath = path.join(candidate, "package.json");
+      const raw = readFileSync(pkgPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.name === "@tetsuo-ai/runtime") {
+        return candidate;
+      }
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+async function readJsonSafe(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function runBuildScript(sourceRoot, env) {
+  const result = spawn("npm", ["run", "build"], {
+    cwd: sourceRoot,
+    stdio: ["ignore", "inherit", "inherit"],
+    env: { ...env },
+  });
+  return new Promise((resolvePromise, rejectPromise) => {
+    result.on("error", rejectPromise);
+    result.on("exit", (code) => {
+      if (code === 0) {
+        resolvePromise();
+      } else {
+        rejectPromise(
+          new RuntimeInstallError(
+            `from-source build failed with exit code ${code}`,
+            "from_source_build_failed",
+          ),
+        );
+      }
+    });
+  });
+}
+
+async function readBuildVersion(sourceRoot) {
+  const versionPath = path.join(sourceRoot, "dist", "VERSION");
+  return await readJsonSafe(versionPath);
+}
+
+function buildFromSourceArtifactDescriptor(sourceRoot, packageJson, versionFile) {
+  const runtimeVersion =
+    typeof packageJson?.version === "string" ? packageJson.version : "0.0.0";
+  const distRoot = path.join(sourceRoot, "dist");
+  const bins = {
+    agenc: "bin/agenc.js",
+    "agenc-runtime": "bin/agenc-runtime.js",
+    daemon: "bin/daemon.js",
+    "agenc-watch": "bin/agenc-watch.js",
+  };
+  return {
+    runtimeVersion,
+    platform: FROM_SOURCE_PLATFORM_ARCH,
+    arch: "local",
+    bins,
+    sha256: versionFile?.commit ?? "from-source",
+    distRoot,
+  };
+}
+
+async function ensureFromSourceCurrentPointer({
+  homeDir = os.homedir(),
+  distRoot,
+}) {
+  const runtimeHome = getWrapperRuntimeHome(homeDir);
+  const releaseDir = path.join(
+    runtimeHome,
+    "releases",
+    "from-source",
+    FROM_SOURCE_PLATFORM_ARCH,
+  );
+  const currentDir = path.join(runtimeHome, "current");
+  const statePath = path.join(runtimeHome, "install-state.json");
+
+  await mkdir(path.dirname(releaseDir), { recursive: true });
+  await removePathSafe(releaseDir);
+  await mkdir(path.dirname(releaseDir), { recursive: true });
+
+  // The release dir is a directory containing a single symlink (`dist`)
+  // pointing back at the local source dist. The wrapper's bin paths look
+  // for `<releaseDir>/bin/<binName>`, so we lay out the same shape using
+  // a symlink for the entire `dist` tree.
+  await symlink(distRoot, releaseDir, "dir");
+
+  // Use removePathSafe (lstat-based) so we delete the SYMLINK at
+  // `currentDir`, not the target it points at. The previous `rm
+  // recursive` call followed the symlink and either failed silently
+  // or removed the target dir contents while leaving the link intact,
+  // causing the from-source flag to silently keep pointing at a
+  // stale release.
+  await removePathSafe(currentDir);
+  await symlink(releaseDir, currentDir, "dir");
+
+  await mkdir(path.dirname(statePath), { recursive: true });
+  await writeFile(
+    statePath,
+    `${JSON.stringify(
+      {
+        installedAt: new Date().toISOString(),
+        manifestSource: "from-source",
+        runtimeVersion: path.basename(distRoot),
+        platform: FROM_SOURCE_PLATFORM_ARCH,
+        arch: "local",
+        releaseDir,
+        currentDir,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+
+  return { runtimeHome, releaseDir, currentDir, statePath };
+}
+
+export async function ensureRuntimeFromSource(options = {}) {
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir ?? os.homedir();
+  const cwd = options.cwd ?? process.cwd();
+  const sourceRoot = resolveSourceRoot({
+    env,
+    cwd,
+    explicit: options.sourceDir,
+  });
+  if (!sourceRoot) {
+    throw new RuntimeInstallError(
+      "could not locate the agenc-core runtime source directory; pass --source-dir <path> or set AGENC_RUNTIME_SOURCE_DIR",
+      "from_source_root_not_found",
+    );
+  }
+  const distRoot = path.join(sourceRoot, "dist");
+  const skipBuild =
+    options.skipBuild === true || env?.AGENC_FROM_SOURCE_SKIP_BUILD === "1";
+
+  if (!skipBuild) {
+    await runBuildScript(sourceRoot, env);
+  }
+  if (!existsSync(distRoot)) {
+    throw new RuntimeInstallError(
+      `from-source build did not produce ${distRoot}`,
+      "from_source_dist_missing",
+    );
+  }
+
+  const packageJson = await readJsonSafe(path.join(sourceRoot, "package.json"));
+  const versionFile = await readBuildVersion(sourceRoot);
+  const selectedArtifact = buildFromSourceArtifactDescriptor(
+    sourceRoot,
+    packageJson,
+    versionFile,
+  );
+
+  const installPaths = await ensureFromSourceCurrentPointer({
+    homeDir,
+    distRoot,
+  });
+
+  return {
+    releaseDir: installPaths.releaseDir,
+    currentDir: installPaths.currentDir,
+    runtimeHome: installPaths.runtimeHome,
+    statePath: installPaths.statePath,
+    manifestSource: "from-source",
+    selectedArtifact,
+    fromSource: true,
+    sourceRoot,
+    versionFile,
+    bins: {
+      agenc: path.join(installPaths.currentDir, selectedArtifact.bins.agenc),
+      "agenc-runtime": path.join(
+        installPaths.currentDir,
+        selectedArtifact.bins["agenc-runtime"],
+      ),
+      daemon: path.join(installPaths.currentDir, selectedArtifact.bins.daemon),
+      watch: path.join(
+        installPaths.currentDir,
+        selectedArtifact.bins["agenc-watch"],
+      ),
+    },
+  };
+}
+
+export async function spawnInstalledRuntimeBinFromSource(
+  binName,
+  args,
+  options = {},
+) {
+  const runtime = await ensureRuntimeFromSource(options);
+  const scriptPath = runtime.bins[binName];
+  if (!scriptPath) {
+    throw new RuntimeInstallError(
+      `from-source runtime does not expose ${binName}`,
+      "missing_runtime_bin",
+    );
+  }
+  const env = {
+    ...(options.env ?? process.env),
+    AGENC_WRAPPER_ACTIVE: "1",
+    AGENC_WRAPPER_RUNTIME_HOME: runtime.runtimeHome,
+    AGENC_WRAPPER_RELEASE_DIR: runtime.releaseDir,
+    AGENC_WRAPPER_CURRENT_DIR: runtime.currentDir,
+    AGENC_WRAPPER_FROM_SOURCE: "1",
+    AGENC_WRAPPER_SOURCE_ROOT: runtime.sourceRoot,
+    AGENC_DAEMON_ENTRY: runtime.bins.daemon,
+    AGENC_WATCH_ENTRY: runtime.bins.watch,
+  };
+  return spawnNodeScript(scriptPath, args, env, options.cwd);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetsuo-ai/agenc",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Public CLI and launcher for the AgenC framework",
   "type": "module",
   "bin": {