clario-agent 0.1.0 → 0.2.0

package/README.md

@@ -7,55 +7,44 @@ and commit (e.g. `graphite · feat/missions · a1b2c3d`). The badge clears when
 
 ## Setup (one command)
 
-Make an account at [clario.games](https://www.clario.games) first, then run this inside the
-project you want to share:
-
-```bash
-npx clario-agent setup
-```
-
-It does three things:
-
-1. **Saves an agent key** in `~/.clario/agent.json` (readable only by you). It asks for your
-   Clario email and password once (sent only to the Clario server). The key lasts 180 days and
-   can only post agent activity: it can't sign in, open a space or change anything else.
-2. **Installs the hook** at `~/.clario/hook.mjs`.
-3. **Registers it with Claude Code** for this project only, in `.claude/settings.local.json`.
-   Add `--global` to use it in every project (`~/.claude/settings.json`) instead.
-
-Then open your Clario space, give Claude a task in that project, and click your avatar.
-Teammates who do the same and join your space show up on their avatars too.
-
-It uses the live server at `https://api.clario.games`. Running Clario yourself? Add
-`--api-url http://localhost:3001` (or your own server's address); setup remembers it.
-
-Running `setup` again keeps a key that still has more than 14 days left, updates the hook
-and never registers it twice. Your other Claude Code settings and hooks are left as they
-are, and the previous file is saved next to it as `*.clario-backup`.
+1. Open your space on [clario.games](https://www.clario.games) and click **Agent** in the
+   left menu. It shows your setup command, with a key made for you:
+   ```bash
+   npx clario-agent setup --key YOUR_KEY
+   ```
+2. Copy it and run it in the terminal, inside the project you want to share.
+
+That's it: the Agent button disappears once your agent has connected. Setup:
+
+- **Checks the key** with the Clario server and saves it in `~/.clario/agent.json` (readable
+  only by you). It's your own key and it stays the same: the Agent button always shows the
+  same command for you. It can only post agent activity: it can't sign in, open a space or
+  change anything else. No password is ever typed in the terminal.
+- **Installs the hook** at `~/.clario/hook.mjs`.
+- **Registers it with Claude Code** for this project only, in `.claude/settings.local.json`.
+  Add `--global` to use it in every project (`~/.claude/settings.json`) instead.
+
+Then give Claude a task in that project and click your avatar. Teammates who do the same and
+join your space show up on their avatars too.
+
+To add another project later, run `npx clario-agent setup` there: it reuses your saved key.
+Setup never registers the hook twice, leaves your other Claude Code settings and hooks as
+they are, and saves the previous file next to it as `*.clario-backup`.
 
 ```bash
 npx clario-agent status      # server, key expiry, where the hook is registered
 npx clario-agent uninstall   # remove the hook from this project (add --global for all)
 ```
 
-Used the older `viora-agent` package? Run `setup` once: it reuses the key from `~/.viora` and
-replaces the old hook, so it never runs twice. You can delete `~/.viora` afterwards.
-
-From a checkout of this repo, `node tools/agent-hook/setup.mjs` does the same as `setup`.
-For scripts, `CLARIO_EMAIL` and `CLARIO_PASSWORD` are read instead of prompting.
-
-<details>
-<summary>Manual alternative: a 7-day login token</summary>
+It uses the live server at `https://api.clario.games`. Running Clario yourself? The Agent
+button on your own site adds `--api-url` to the command for you.
 
-Sign in, open DevTools → Console on your Clario site and run
-`copy(localStorage.getItem("metaverse:token"))`, then save it as `"token"` in
-`~/.clario/agent.json` next to `"apiUrl"`. It expires after 7 days. If you then run
-`setup`, it uses that token to create the agent key without asking for your password.
-</details>
+Used the older `viora-agent` package? Run `npx clario-agent setup` once: it reuses the key
+from `~/.viora` and replaces the old hook. You can delete `~/.viora` afterwards.
 
-> An agent key can't be cancelled on its own before it expires. If one leaks, delete it
-> from `~/.clario/agent.json` and change the server's `JWT_SECRET` (this signs everyone out).
-> The server needs the `/api/v1/agent-key` endpoint from this repo's `apps/server`.
+> Keep the setup command private: anyone with your key can post activity as your agent (and
+> nothing else). If it leaks, delete `~/.clario/agent.json`; the server's owner can cancel
+> every key by changing `JWT_SECRET` (this signs everyone out).
 
 ## How it behaves
 

package/cli.mjs

@@ -2,20 +2,21 @@
 /**
  * clario-agent: show what your Claude Code agent is doing on your Clario avatar.
  *
- *   npx clario-agent setup [--api-url URL] [--global]   agent key + hook, once
- *   npx clario-agent status                              what is set up
- *   npx clario-agent uninstall [--global]                remove the hook
+ *   npx clario-agent setup --key KEY [--api-url URL] [--global]   key + hook, once
+ *   npx clario-agent status                                        what is set up
+ *   npx clario-agent uninstall [--global]                          remove the hook
  *
- * setup saves a 180-day agent key in ~/.clario/agent.json (it can only post agent
- * activity), copies the hook to ~/.clario/hook.mjs and registers it in this project's
- * .claude/settings.local.json, or in ~/.claude/settings.json with --global.
+ * The key comes from the website: the Agent button in a Clario space shows the whole
+ * setup command. setup checks the key with the server, saves it in ~/.clario/agent.json
+ * (one key per user that stays the same; it can only post agent activity), copies the hook to
+ * ~/.clario/hook.mjs and registers it in this project's .claude/settings.local.json,
+ * or in ~/.claude/settings.json with --global.
  */
 
 import { execFileSync } from "node:child_process";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 
 const DIR = join(homedir(), ".clario");
@@ -27,7 +28,8 @@ const OLD_CONFIG_PATH = join(homedir(), ".viora", "agent.json");
 // The live Clario server; pass --api-url http://localhost:3001 for a local one.
 const DEFAULT_API_URL = "https://api.clario.games";
 const HOOK_EVENTS = ["PreToolUse", "PostToolUse", "Stop", "SessionEnd"];
-const RENEW_DAYS = 14; // setup makes a new key when the saved one has less time left than this
+const WARN_DAYS = 14; // setup reminds you to get a new key when the saved one has less time left than this
+const GET_A_KEY = "Open your Clario space at https://www.clario.games, click Agent in the left menu, and run the setup command it shows.";
 
 class CliError extends Error {}
 const fail = (message) => {
@@ -57,16 +59,26 @@ function writeJson(file, value, { mode } = {}) {
   if (mode) chmodSync(file, mode);
 }
 
-/** Days until a JWT expires, or null when it can't be read. */
-function daysLeft(token) {
+/** The readable part of a key (a JWT), or null. The server checks the signature. */
+function keyPayload(token) {
   try {
-    const { exp } = JSON.parse(Buffer.from(String(token).split(".")[1], "base64url").toString());
-    return typeof exp === "number" ? (exp * 1000 - Date.now()) / 86_400_000 : null;
+    const payload = JSON.parse(Buffer.from(String(token).split(".")[1], "base64url").toString());
+    return payload && typeof payload === "object" ? payload : null;
   } catch {
     return null;
   }
 }
 
+/** Days until a key expires: Infinity for one that doesn't (today's keys), null when it can't be read. */
+function daysLeft(token) {
+  const payload = keyPayload(token);
+  if (!payload) return null;
+  return typeof payload.exp === "number" ? (payload.exp * 1000 - Date.now()) / 86_400_000 : Infinity;
+}
+
+const expiryText = (days) =>
+  Number.isFinite(days) ? `works until ${new Date(Date.now() + days * 86_400_000).toDateString()}` : "it doesn't expire";
+
 async function post(apiUrl, path, body, token) {
   let res;
   try {
@@ -81,44 +93,25 @@ async function post(apiUrl, path, body, token) {
   return { status: res.status, json: await res.json().catch(() => null) };
 }
 
-/** Email and password from the terminal (the password isn't echoed), or CLARIO_EMAIL / CLARIO_PASSWORD. */
-async function askCredentials() {
-  if (process.env.CLARIO_EMAIL && process.env.CLARIO_PASSWORD) {
-    return { email: process.env.CLARIO_EMAIL, password: process.env.CLARIO_PASSWORD };
-  }
-  if (!process.stdin.isTTY) fail("No terminal to ask for your email and password; set CLARIO_EMAIL and CLARIO_PASSWORD.");
-  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
-  const ask = (text) => new Promise((resolve) => rl.question(text, resolve));
-  const email = (await ask("Clario email: ")).trim();
-  const answer = ask("Password: ");
-  const write = rl._writeToOutput;
-  rl._writeToOutput = () => {}; // hide the password as it's typed
-  const password = await answer;
-  rl._writeToOutput = write;
-  rl.close();
-  process.stdout.write("\n");
-  return { email, password };
+/** A key from the website, checked with the server before it's saved. */
+async function checkKey(key, apiUrl) {
+  const payload = keyPayload(key);
+  if (!payload || typeof payload.userId !== "string") fail(`That isn't a Clario agent key. ${GET_A_KEY}`);
+  if (payload.scope !== "agent") fail(`That's a login token, not an agent key. ${GET_A_KEY}`);
+  const days = daysLeft(key);
+  if (days === null || days <= 0) fail(`That key has expired. ${GET_A_KEY}`);
+  // A "done" update changes nothing anyone sees, and tells the server the hook is set up.
+  const res = await post(apiUrl, "/agent-activity", { text: "", state: "done" }, key);
+  if (res.status === 403) fail(`The server at ${apiUrl} doesn't accept this key. ${GET_A_KEY}`);
+  if (res.status !== 200) fail(`Could not check the key with ${apiUrl} (HTTP ${res.status}).`);
+  return { key, days, reused: false };
 }
 
-/** A usable agent key: the saved one if it has time left, else a new one from the server. */
-async function ensureAgentKey(config, apiUrl) {
-  const left = daysLeft(config.agentKey);
-  if (config.agentKey && config.apiUrl === apiUrl && left !== null && left > RENEW_DAYS) {
-    return { key: config.agentKey, days: left, reused: true };
-  }
-  // A login token from the manual setup (README) is enough to create the key.
-  let res = config.token ? await post(apiUrl, "/agent-key", {}, config.token) : null;
-  if (!res || res.status !== 200) {
-    if (res?.status !== 404) {
-      const { email, password } = await askCredentials();
-      const signin = await post(apiUrl, "/signin", { email, password });
-      if (!signin.json?.token) fail("Sign-in failed. Check your email and password.");
-      res = await post(apiUrl, "/agent-key", {}, signin.json.token);
-    }
-  }
-  if (res.status === 404) fail(`The server at ${apiUrl} has no /api/v1/agent-key yet. Restart it so it runs the latest code.`);
-  if (res.status !== 200 || !res.json?.key) fail(`Could not create an agent key (HTTP ${res.status}).`);
-  return { key: res.json.key, days: daysLeft(res.json.key), reused: false };
+/** The key from an earlier setup, when it still works for this server (e.g. to add another project). */
+function savedKey(config, apiUrl) {
+  const days = daysLeft(config.agentKey);
+  if (config.agentKey && config.apiUrl === apiUrl && days !== null && days > 0) return { key: config.agentKey, days, reused: true };
+  fail(`No agent key yet. ${GET_A_KEY}`);
 }
 
 // ---- Claude Code settings -------------------------------------------------------
@@ -175,10 +168,11 @@ function gitIgnored(file) {
 
 async function setup(opts) {
   const { value: config = readJson(OLD_CONFIG_PATH).value ?? {} } = readJson(CONFIG_PATH);
-  const apiUrl = String(opts.apiUrl || config.apiUrl || DEFAULT_API_URL).replace(/\/+$/, "");
-  const { key, days, reused } = await ensureAgentKey(config, apiUrl);
+  // A new key comes from the live site unless --api-url says otherwise; re-running setup keeps the saved server.
+  const apiUrl = String(opts.apiUrl || (opts.key ? DEFAULT_API_URL : config.apiUrl) || DEFAULT_API_URL).replace(/\/+$/, "");
+  const { key, days, reused } = opts.key ? await checkKey(opts.key, apiUrl) : savedKey(config, apiUrl);
 
-  // The 7-day login token isn't needed any more; everything else (shareGit…) stays.
+  // An old 7-day login token isn't needed any more; everything else (shareGit…) stays.
   const { token: _loginToken, ...rest } = config;
   writeJson(CONFIG_PATH, { ...rest, apiUrl, agentKey: key }, { mode: 0o600 });
   mkdirSync(DIR, { recursive: true, mode: 0o700 });
@@ -187,8 +181,8 @@ async function setup(opts) {
   const file = settingsFile(opts.global);
   registerHooks(file);
 
-  const until = new Date(Date.now() + days * 86_400_000).toDateString();
-  console.log(`${reused ? "Kept your agent key" : "Saved a new agent key"} in ${CONFIG_PATH} (works until ${until}).`);
+  console.log(`${reused ? "Kept your agent key" : "Saved your agent key"} in ${CONFIG_PATH} (${expiryText(days)}).`);
+  if (reused && days < WARN_DAYS) console.log(`It runs out in ${Math.ceil(days)} days. ${GET_A_KEY}`);
   console.log(`Hook registered in ${file}${opts.global ? " for every project" : " for this project only"}.`);
   if (!opts.global && gitIgnored(file) === false) {
     console.log("Note: .claude/settings.local.json isn't git-ignored here. It holds no secrets, but you may want to ignore it.");
@@ -202,7 +196,7 @@ function status() {
   console.log(`Server:  ${config.apiUrl ?? "not set"}`);
   console.log(
     config.agentKey || config.token
-      ? `Key:     ${config.agentKey ? "agent key" : "7-day login token"}, ${left === null ? "unreadable" : left > 0 ? `${Math.floor(left)} days left` : "EXPIRED (run setup)"}`
+      ? `Key:     ${config.agentKey ? "agent key" : "7-day login token"}, ${left === null ? "unreadable" : left === Infinity ? "doesn't expire" : left > 0 ? `${Math.floor(left)} days left` : "EXPIRED (run setup)"}`
       : "Key:     none (run setup)",
   );
   console.log(`Hook:    ${existsSync(HOOK_PATH) ? HOOK_PATH : "not installed (run setup)"}`);
@@ -227,17 +221,22 @@ function uninstall(opts) {
 
 const HELP = `clario-agent: show what your Claude Code agent is doing on your Clario avatar
 
-  clario-agent setup [--api-url URL] [--global]   save an agent key and register the hook
-  clario-agent status                              show what is set up
-  clario-agent uninstall [--global]                remove the hook
+  clario-agent setup --key KEY [--api-url URL] [--global]   save your key and register the hook
+  clario-agent status                                        show what is set up
+  clario-agent uninstall [--global]                          remove the hook
 
+Get the setup command (with your key) from the Agent button in your Clario space.
 Without --global the hook is registered only for the project you run it in.
---api-url defaults to the saved server, then ${DEFAULT_API_URL}.`;
+Without --key, setup reuses the key you saved before. The server is ${DEFAULT_API_URL}
+unless you pass --api-url.`;
 
 export async function run(argv) {
   const [command = "help", ...rest] = argv;
-  const i = rest.indexOf("--api-url");
-  const opts = { global: rest.includes("--global"), apiUrl: i > -1 ? rest[i + 1] : undefined };
+  const value = (flag) => {
+    const i = rest.indexOf(flag);
+    return i > -1 ? rest[i + 1] : undefined;
+  };
+  const opts = { global: rest.includes("--global"), apiUrl: value("--api-url"), key: value("--key") };
   try {
     if (command === "setup") await setup(opts);
     else if (command === "status") status();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clario-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Show what your Claude Code agent is doing (project, branch, commit) on your Clario avatar.",
   "type": "module",
   "bin": {