@fulldivevr/workcord-cli 1.1.1 → 1.2.0

package/README.md

@@ -281,6 +281,115 @@ workcord --as $U dm send-text --to $OTHER --text "hey"
 # → composite: opens (or finds) the DM room, sends the message, returns both
 ```
 
+## Hermes Hub (`hermes` namespace)
+
+WorkCord provisions a **Hermes Hub tenant** for each room-agent and each Hermes
+custom agent. That tenant is where the agent actually runs: its chats, runs,
+files, skills, flavor pin, A2A peers and eval runs all live on the Hub, not in
+WorkCord. The `hermes` namespace drives that tenant directly.
+
+This is the one namespace that talks to a **second origin**. Every other command
+goes to the WorkCord API; `hermes` uses the WorkCord API only to reveal the
+tenant key, then calls the Hub's `/v1/tenant-api/*` routes with it.
+
+### Target selection
+
+Every `hermes` command takes exactly one of:
+
+| Flag | Meaning |
+| --- | --- |
+| `--agent <id>` | a custom agent id, used verbatim |
+| `--room-agent <id>` | a room agent id, resolved as `workcord-room-agent:<id>` |
+
+Passing both, or neither, is an error.
+
+### Credentials
+
+The tenant key is resolved in one place (`resolveHermesKey` in `src/auth.ts`)
+and is **never** accepted as a flag:
+
+| Env var | Meaning |
+| --- | --- |
+| `WORKCORD_HERMES_KEY` | tenant key, used verbatim; requires `WORKCORD_HERMES_HUB_URL` |
+| `WORKCORD_HERMES_HUB_URL` | Hub origin (bare origin, no path); requires `WORKCORD_HERMES_KEY` |
+| `WORKCORD_HERMES_TENANT_ID` | tenant id for the tenant-scoped routes, alongside the two above |
+
+Setting only one of `WORKCORD_HERMES_KEY` / `WORKCORD_HERMES_HUB_URL` is an
+error — the CLI will not half-guess a hub.
+
+With none of them set, the CLI calls
+`POST /api/v1/agents/{id}/hermes-cli-key/reveal` on WorkCord (as the acting
+user, so ownership is enforced server-side) and gets back the key, tenant id and
+hub origin.
+
+Revealed credentials are cached per agent ref in `~/.workcord/config.json`
+under `hermes`, alongside the saved login. The file is written `0600` inside a
+`0700` directory. Two flags control it:
+
+| Flag | Effect |
+| --- | --- |
+| `--refresh` | ignore the cached entry, re-reveal, rewrite the cache |
+| `--no-cache` | neither read nor write the cache for this invocation |
+
+Env credentials always win over the cache. `hermes key` prints the resolved
+credentials on stdout — that is its whole job; no other command emits key
+material.
+
+### Commands
+
+| Group | What |
+| --- | --- |
+| `hermes key` / `whoami` / `runtime` | reveal credentials, show the tenant, show its runtime |
+| `hermes agent status\|start\|stop\|restart\|card` | tenant agent lifecycle |
+| `hermes chat list\|create\|get\|messages\|send\|message\|stream\|stop\|approve` | chats and chat messages (`stream` is SSE) |
+| `hermes run create\|get\|stream\|stop\|approve` | runs |
+| `hermes files ls\|cat\|download` | tenant-visible files |
+| `hermes share groups\|ls\|read\|stat\|grep\|find\|write\|mkdir\|move\|rm` | share-group filesystem |
+| `hermes skills list\|enable\|disable\|files\|cat` | skills installed on this tenant |
+| `hermes flavor current\|catalog\|get\|set\|subscribe\|checkout\|publish\|rollout` | flavor marketplace and this tenant's pin |
+| `hermes skill catalog\|get\|checkout\|publish` | skill marketplace |
+| `hermes eval suites\|run\|list\|get\|cancel` | flavor eval suites and runs |
+| `hermes peers list\|get\|call\|find` | A2A peers |
+| `hermes conversations list\|get\|messages` | A2A conversations |
+| `hermes sessions list`, `hermes artifacts` | agent sessions and artifacts |
+
+```bash
+workcord hermes whoami --room-agent $RA
+workcord hermes chat send --room-agent $RA --chat $CHAT --text "status?"
+workcord hermes flavor current --agent $AGENT
+workcord hermes peers find --agent $AGENT --query "translation" --limit 5
+```
+
+Version flags are named `--flavor-version` and `--skill-version`, not
+`--version`: commander's program-level `.version()` matches `--version`
+anywhere in argv, prints the CLI version and exits before the subcommand runs.
+
+### Authoring flavors and skills
+
+`flavor publish`, `flavor rollout` and `skill publish` are **owner-gated on the
+Hub**. A WorkCord agent tenant is provisioned as a *consumer* and owns no flavor
+or skill namespace, so these will 403 out of the box. Ownership is
+admin-assigned only (`PUT /v1/flavors/{id}/owner`, likewise for skills) and
+there is **no self-service bootstrap** — a hub operator has to assign the
+namespace to your tenant first. The CLI turns that 403 into an explicit error
+naming the tenant and the namespace so you know exactly what to ask for.
+
+The CLI does **not** pack or untar archives. The authoring loop is:
+
+```bash
+workcord hermes flavor checkout --agent $AGENT --flavor-version 1.4.0 --out flavor.tgz
+# unpack, edit, and repack with hermes-hub's own tooling
+workcord hermes flavor publish --agent $AGENT --archive flavor.tgz
+```
+
+`--archive` must already be a gzipped package built beforehand; anything over
+32 MiB is rejected locally before upload.
+
+`flavor set` warns (and refuses without `--force`) on a downgrade or a
+deprecated target. `flavor rollout` defaults to the policy-respecting automatic
+rollout; `--all-matching` re-pins every tenant on the Hub pinned to that flavor
+id regardless of their own update policy, and therefore requires `--force`.
+
 ## Development
 
 ```bash
@@ -310,8 +419,12 @@ without running `regen` if you don't need the latest server changes.
 ```
 src/
 ├── cli.ts                  commander entry, global --as flag
-├── auth.ts                 auth resolution: WORKCORD_TOKEN vs minted --as JWT
-├── client.ts               fetch wrapper (JSON + multipart)
+├── auth.ts                 auth resolution: WORKCORD_TOKEN vs minted --as JWT,
+│                           plus Hermes Hub key resolution
+├── http.ts                 shared fetch primitives (retry, errors, query)
+├── client.ts               WorkCord fetch wrapper (JSON + multipart)
+├── hermes-client.ts        Hermes Hub fetch wrapper (JSON, upload, SSE, binary)
+├── hermes-guards.ts        rollout/ownership/archive guards, version compare
 ├── commands/               hand-written semantic commands
 └── generated/              auto-generated from openapi.json
     ├── index.ts

package/dist/auth.js

@@ -1,4 +1,5 @@
 import jwt from "jsonwebtoken";
+import { readConfig, saveHermesEntry } from "./config.js";
 export function actingUserId(program) {
     return program.opts().as;
 }
@@ -27,6 +28,48 @@ export function resolveAuth(asUserId, env = process.env, config = {}) {
     }
     throw new Error("No credentials. Run `workcord auth login --email <address> --save`, or set WORKCORD_TOKEN. For privileged impersonation, set WORKCORD_JWT_SECRET and pass --as <userId>.");
 }
+async function revealHermesKey(agentRef, asUserId) {
+    const { call } = await import("./client.js");
+    const res = (await call({
+        method: "POST",
+        path: `/api/v1/agents/${encodeURIComponent(agentRef)}/hermes-cli-key/reveal`,
+        asUserId,
+    }));
+    if (!res?.key) {
+        throw new Error(`Reveal for ${agentRef} returned no Hermes key`);
+    }
+    if (!res.hubBaseUrl) {
+        throw new Error(`Reveal for ${agentRef} returned no hubBaseUrl. Set WORKCORD_HERMES_HUB_URL (with WORKCORD_HERMES_KEY) to target the hub explicitly.`);
+    }
+    return { key: res.key, tenantId: res.tenantId ?? "", hubBaseUrl: res.hubBaseUrl };
+}
+export async function resolveHermesKey(agentRef, opts = {}) {
+    const env = opts.env ?? process.env;
+    const envKey = env.WORKCORD_HERMES_KEY?.trim() || undefined;
+    const envHub = env.WORKCORD_HERMES_HUB_URL?.trim() || undefined;
+    if (envKey) {
+        if (!envHub) {
+            throw new Error("WORKCORD_HERMES_KEY is set but WORKCORD_HERMES_HUB_URL is not. Set both, or unset the key to reveal it from WorkCord.");
+        }
+        return { key: envKey, tenantId: env.WORKCORD_HERMES_TENANT_ID?.trim() || "", hubBaseUrl: envHub, source: "env" };
+    }
+    if (envHub && !envKey) {
+        throw new Error("WORKCORD_HERMES_HUB_URL is set but WORKCORD_HERMES_KEY is not. Set both, or unset the hub URL to reveal both from WorkCord.");
+    }
+    const useCache = opts.cache !== false;
+    const config = opts.config ?? (await readConfig());
+    if (useCache && !opts.refresh) {
+        const cached = config.hermes?.[agentRef];
+        if (cached?.key && cached.hubBaseUrl) {
+            return { key: cached.key, tenantId: cached.tenantId, hubBaseUrl: cached.hubBaseUrl, source: "cache" };
+        }
+    }
+    const revealed = await (opts.reveal ?? revealHermesKey)(agentRef, opts.asUserId);
+    if (useCache) {
+        await (opts.save ?? saveHermesEntry)(agentRef, { ...revealed, revealedAt: new Date().toISOString() });
+    }
+    return { ...revealed, source: "reveal" };
+}
 export function decodeJwtPayload(token) {
     const parts = token.split(".");
     if (parts.length !== 3)

package/dist/cli.js

@@ -12,6 +12,7 @@ import { registerRoomAgents } from "./commands/room-agents.js";
 import { registerCustomAgents } from "./commands/custom-agents.js";
 import { registerChallenges } from "./commands/challenges.js";
 import { registerHealth } from "./commands/health.js";
+import { registerHermes } from "./commands/hermes.js";
 import { registerAll as registerGenerated } from "./generated/index.js";
 const program = new Command();
 const require = createRequire(import.meta.url);
@@ -35,6 +36,7 @@ registerRoomAgents(program);
 registerCustomAgents(program);
 registerChallenges(program); // adds regenerate-cards (not in the OpenAPI spec)
 registerHealth(program);
+registerHermes(program);
 registerGenerated(program);
 program.parseAsync().catch((err) => {
     const out = { error: err.message ?? String(err) };

package/dist/client.js

@@ -1,5 +1,6 @@
 import { resolveAuth } from "./auth.js";
 import { DEFAULT_BASE_URL, readConfig } from "./config.js";
+import { applyQuery, fetchWithRetry, httpError, normalizeBaseUrl, safeJson } from "./http.js";
 let baseUrlOverride;
 export function setBaseUrlOverride(url) {
     baseUrlOverride = url;
@@ -8,50 +9,6 @@ export async function getBaseUrl() {
     const config = await readConfig();
     return normalizeBaseUrl(baseUrlOverride || process.env.WORKCORD_API_URL || config.baseUrl || DEFAULT_BASE_URL);
 }
-function normalizeBaseUrl(raw) {
-    const trimmed = raw.replace(/\/+$/, "");
-    let parsed;
-    try {
-        parsed = new URL(trimmed);
-    }
-    catch {
-        throw new Error(`Invalid API base URL: ${raw}`);
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new Error(`API base URL must be http or https: ${raw}`);
-    }
-    if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
-        throw new Error(`API base URL must be an origin with no path, query or fragment: ${raw}`);
-    }
-    return parsed.origin;
-}
-const RETRY_MAX = Number(process.env.WORKCORD_RETRY_MAX ?? 3);
-const RETRY_BACKOFF_MS = Number(process.env.WORKCORD_RETRY_BACKOFF_MS ?? 200);
-const RETRY_STATUSES = new Set([408, 429, 502, 503, 504]);
-async function fetchWithRetry(build) {
-    let lastErr;
-    for (let attempt = 0; attempt <= RETRY_MAX; attempt++) {
-        try {
-            const { url, init } = build();
-            const res = await fetch(url, init);
-            if (!RETRY_STATUSES.has(res.status))
-                return res;
-            lastErr = res;
-            if (attempt >= RETRY_MAX)
-                return res;
-        }
-        catch (err) {
-            lastErr = err;
-            if (attempt >= RETRY_MAX)
-                throw err;
-        }
-        const delay = RETRY_BACKOFF_MS * Math.pow(3, attempt);
-        await new Promise((r) => setTimeout(r, delay));
-    }
-    if (lastErr instanceof Response)
-        return lastErr;
-    throw lastErr;
-}
 export async function call({ method = "GET", path, query, body, headers, asUserId }) {
     const config = await readConfig();
     const { bearer } = resolveAuth(asUserId, process.env, config);
@@ -62,13 +19,7 @@ export async function callPublic({ method = "GET", path, query, body, headers })
 }
 async function request({ method = "GET", path, query, body, headers, bearer }) {
     const base = await getBaseUrl();
-    const url = new URL(base + path);
-    if (query) {
-        for (const [k, v] of Object.entries(query)) {
-            if (v !== undefined && v !== null)
-                url.searchParams.set(k, String(v));
-        }
-    }
+    const url = applyQuery(new URL(base + path), query);
     const res = await fetchWithRetry(() => ({
         url,
         init: {
@@ -83,22 +34,10 @@ async function request({ method = "GET", path, query, body, headers, bearer }) {
     }));
     const text = await res.text();
     const data = text ? safeJson(text) : null;
-    if (!res.ok) {
-        const err = new Error(`${method} ${path} -> ${res.status}`);
-        err.status = res.status;
-        err.body = data;
-        throw err;
-    }
+    if (!res.ok)
+        throw httpError(`${method} ${path}`, res.status, data);
     return data;
 }
-function safeJson(s) {
-    try {
-        return JSON.parse(s);
-    }
-    catch {
-        return s;
-    }
-}
 export async function callMultipart({ path, asUserId, fields, file }) {
     const config = await readConfig();
     const { bearer } = resolveAuth(asUserId, process.env, config);
@@ -123,12 +62,8 @@ export async function callMultipart({ path, asUserId, fields, file }) {
     });
     const text = await res.text();
     const data = text ? safeJson(text) : null;
-    if (!res.ok) {
-        const err = new Error(`POST ${path} -> ${res.status}`);
-        err.status = res.status;
-        err.body = data;
-        throw err;
-    }
+    if (!res.ok)
+        throw httpError(`POST ${path}`, res.status, data);
     return data;
 }
 //# sourceMappingURL=client.js.map