@fulldivevr/workcord-cli 1.6.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @fulldivevr/workcord-cli
 
-TypeScript CLI for talking to WorkCord agents through persistent Hermes tenant
+TypeScript CLI for talking to WorkCord agents through persistent Autoworker Hub tenant
 chat and using the WorkCord API. **One invocation = one user action.** Designed
 for automated agents such as Claude Code: ask the user's Assistant for the
 outcome you need, let that tenant manage its own instructions, skills, and
@@ -149,7 +149,7 @@ workcord [--as <userId>] <namespace> <command> [flags]
 ### Agent-first customization
 
 To change agent behavior, create or update a skill, or maintain a flavor, talk
-to the owning agent through Hermes tenant chat. Do not edit prompts or tenant
+to the owning agent through Hub tenant chat. Do not edit prompts or tenant
 files directly. With no `--agent`, the user's non-deletable Assistant is the
 target and becomes the default owner of anything it creates:
 
@@ -164,7 +164,7 @@ Use the returned `chatId` for follow-up, verification, or rollback:
 workcord agent chat send --chat "$CHAT_ID" --message "Verify the change, list the versions you created, and explain how to roll it back."
 ```
 
-Both commands wait up to two minutes by default and return the durable Hermes
+Both commands wait up to two minutes by default and return the durable Hub
 message document. Use `--async` for a queued response, then continue with its
 `messageId`:
 
@@ -184,8 +184,8 @@ workcord agent chat new --agent "$AGENT_ID" --message "Create and maintain a fin
 
 The Assistant or selected agent works within its tenant's Hub permissions. It
 can safely validate changes and report what it activated. `agent chat` uses
-Hermes' native durable `hub_chat` transport; it is not raw A2A wire traffic.
-A2A remains available for external agent peers. Direct `hermes` commands are
+the Hub's native durable `hub_chat` transport; it is not raw A2A wire traffic.
+A2A remains available for external agent peers. Direct `hub` commands are
 advanced diagnostics and recovery tools, not the normal customization workflow.
 
 - `workcord --help` lists namespaces.
@@ -321,22 +321,25 @@ workcord --as $U dm send-text --to $OTHER --text "hey"
 # → composite: opens (or finds) the DM room, sends the message, returns both
 ```
 
-## Advanced Hermes diagnostics and recovery (`hermes` namespace)
+## Advanced Hub diagnostics and recovery (`hub` namespace)
 
-WorkCord provisions a **Hermes Hub tenant** for each room-agent, Hermes custom
+WorkCord provisions an **Autoworker Hub tenant** for each room-agent, custom
 agent, and room-scoped marketplace flavor install. 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. Normal changes should be
-requested with `workcord agent chat`; the `hermes` namespace exists for direct
+requested with `workcord agent chat`; the `hub` namespace exists for direct
 inspection, diagnostics, and recovery.
 
 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
+goes to the WorkCord API; `hub` uses the WorkCord API only to reveal the
 tenant key, then calls the Hub's `/v1/tenant-api/*` routes with it.
 
+`workcord hub ...` is a hidden alias of `workcord hub ...`, kept for one
+release. New scripts should use `hub`.
+
 ### Target selection
 
-Every `hermes` command takes exactly one of:
+Every `hub` command takes exactly one of:
 
 | Flag | Meaning |
 | --- | --- |
@@ -355,11 +358,16 @@ 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 |
+| `WORKCORD_HUB_KEY` | tenant key, used verbatim; requires `WORKCORD_HUB_URL` |
+| `WORKCORD_HUB_URL` | Hub origin (bare origin, no path); requires `WORKCORD_HUB_KEY` |
+| `WORKCORD_HUB_TENANT_ID` | tenant id for the tenant-scoped routes, alongside the two above |
+| `WORKCORD_HUB_MANAGED` | `1` enables managed mode (see below) |
+
+The older `WORKCORD_HERMES_KEY`, `WORKCORD_HERMES_HUB_URL`,
+`WORKCORD_HERMES_TENANT_ID` and `WORKCORD_HERMES_MANAGED` names still work and
+take precedence when both are set.
 
-Setting only one of `WORKCORD_HERMES_KEY` / `WORKCORD_HERMES_HUB_URL` is an
+Setting only one of `WORKCORD_HUB_KEY` / `WORKCORD_HUB_URL` is an
 error — the CLI will not half-guess a hub.
 
 With none of them set, the CLI calls
@@ -376,34 +384,56 @@ under `hermes`, alongside the saved login. The file is written `0600` inside a
 | `--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
+Env credentials always win over the cache. `hub key` prints the resolved
 credentials on stdout — that is its whole job; no other command emits key
 material.
 
+### Managed mode
+
+A personal Shadow tenant runs this CLI with a WorkCord token that WorkCord
+resolves to the owner user. It must use the same `hub` commands, but with a
+per-call reveal and nothing on disk. Managed mode is enabled by
+`WORKCORD_HUB_MANAGED=1` (or `WORKCORD_HERMES_MANAGED=1`), or per invocation
+with `--managed`. In managed mode the CLI:
+
+- always reveals the key through `POST /api/v1/agents/{id}/hermes-cli-key/reveal`,
+- never reads or writes `~/.workcord/config.json` for hub credentials,
+- ignores `WORKCORD_HUB_KEY` / `WORKCORD_HERMES_KEY`,
+- rejects `--as` with an error,
+- never prints the key (`hub key` prints only `tenantId` and `hubBaseUrl`).
+
+```bash
+export WORKCORD_TOKEN=...            # the owner user's token
+export WORKCORD_HUB_MANAGED=1
+workcord hub flavor set --agent $AGENT --flavor-version 1.4.0
+workcord hub flavor subscribe --agent $AGENT --policy stable
+workcord hub agent restart --agent $AGENT
+```
+
 ### 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 |
+| `hub key` / `whoami` / `runtime` | reveal credentials, show the tenant, show its runtime |
+| `hub agent status\|start\|stop\|restart\|card` | tenant agent lifecycle |
+| `hub chat list\|create\|get\|messages\|send\|message\|stream\|stop\|approve` | chats and chat messages (`stream` is SSE) |
+| `hub run create\|get\|stream\|stop\|approve` | runs |
+| `hub files ls\|cat\|download` | tenant-visible files |
+| `hub share groups\|ls\|read\|stat\|grep\|find\|write\|mkdir\|move\|rm` | share-group filesystem |
+| `hub skills list\|enable\|disable\|files\|cat` | skills installed on this tenant |
+| `hub flavor current\|catalog\|get\|set\|subscribe\|checkout\|publish\|rollout` | flavor marketplace and this tenant's pin |
+| `hub skill catalog\|get\|checkout\|publish` | skill marketplace |
+| `hub eval suites\|run\|list\|get\|cancel` | flavor eval suites and runs |
+| `hub peers list\|get\|call\|find` | A2A peers |
+| `hub conversations list\|get\|messages` | A2A conversations |
+| `hub sessions list`, `hub artifacts` | agent sessions and artifacts |
 
 ```bash
-workcord hermes whoami --room-agent $RA
-workcord hermes whoami --marketplace-install $MARKETPLACE_INSTALL
-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
+workcord hub whoami --room-agent $RA
+workcord hub whoami --marketplace-install $MARKETPLACE_INSTALL
+workcord hub chat send --room-agent $RA --chat $CHAT --text "status?"
+workcord hub flavor current --agent $AGENT
+workcord hub peers find --agent $AGENT --query "translation" --limit 5
 ```
 
 Version flags are named `--flavor-version` and `--skill-version`, not
@@ -413,7 +443,7 @@ anywhere in argv, prints the CLI version and exits before the subcommand runs.
 ### Direct flavor and skill recovery
 
 For normal work, ask the Assistant or another owned agent to create, update,
-validate, or activate its own flavor and skills. Hermes Hub supports
+validate, or activate its own flavor and skills. Autoworker Hub supports
 tenant-owned skill and flavor namespaces; ownership defaults to whichever agent
 tenant performs the creation.
 
@@ -424,9 +454,9 @@ the selected tenant and can only mutate namespaces that tenant owns.
 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
+workcord hub flavor checkout --agent $AGENT --flavor-version 1.4.0 --out flavor.tgz
+# unpack, edit, and repack with the Hub's own tooling
+workcord hub flavor publish --agent $AGENT --archive flavor.tgz
 ```
 
 `--archive` must already be a gzipped package built beforehand; anything over
@@ -467,10 +497,10 @@ 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,
-│                           plus Hermes Hub key resolution
+│                           plus Autoworker 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-client.ts        Autoworker 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

package/dist/auth.js

@@ -28,7 +28,22 @@ 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) {
+export function resolveMachineCredential(env = process.env, file) {
+    const envKey = env.WORKCORD_MACHINE_KEY?.trim();
+    if (envKey)
+        return { key: envKey, machineId: undefined, baseUrl: file?.baseUrl || undefined, source: "env" };
+    if (file?.key)
+        return { key: file.key, machineId: file.machineId, baseUrl: file.baseUrl || undefined, source: "file" };
+    throw new Error("No machine key. Run `workcord machine pair` (or `workcord machine enroll`) first, or set WORKCORD_MACHINE_KEY.");
+}
+function envFlag(value) {
+    const v = value?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+export function isManagedHubMode(env = process.env) {
+    return envFlag(env.WORKCORD_HERMES_MANAGED) || envFlag(env.WORKCORD_HUB_MANAGED);
+}
+export async function revealHermesKey(agentRef, asUserId) {
     const { call } = await import("./client.js");
     const res = (await call({
         method: "POST",
@@ -36,25 +51,34 @@ async function revealHermesKey(agentRef, asUserId) {
         asUserId,
     }));
     if (!res?.key) {
-        throw new Error(`Reveal for ${agentRef} returned no Hermes key`);
+        throw new Error(`Reveal for ${agentRef} returned no hub tenant 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.`);
+        throw new Error(`Reveal for ${agentRef} returned no hubBaseUrl. Set WORKCORD_HUB_URL (with WORKCORD_HUB_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;
+    const managed = opts.managed ?? isManagedHubMode(env);
+    if (managed) {
+        if (opts.asUserId) {
+            throw new Error("--as is not allowed in managed hub mode (WORKCORD_HUB_MANAGED): the hub key is always revealed for the token's own user.");
+        }
+        const revealed = await (opts.reveal ?? revealHermesKey)(agentRef);
+        return { ...revealed, source: "reveal" };
+    }
+    const envKey = env.WORKCORD_HERMES_KEY?.trim() || env.WORKCORD_HUB_KEY?.trim() || undefined;
+    const envHub = env.WORKCORD_HERMES_HUB_URL?.trim() || env.WORKCORD_HUB_URL?.trim() || undefined;
+    const envTenant = env.WORKCORD_HERMES_TENANT_ID?.trim() || env.WORKCORD_HUB_TENANT_ID?.trim() || "";
     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.");
+            throw new Error("WORKCORD_HUB_KEY (WORKCORD_HERMES_KEY) is set but WORKCORD_HUB_URL (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" };
+        return { key: envKey, tenantId: envTenant, 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.");
+        throw new Error("WORKCORD_HUB_URL (WORKCORD_HERMES_HUB_URL) is set but WORKCORD_HUB_KEY (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());

package/dist/cli.js

@@ -12,17 +12,18 @@ 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 { registerHub } from "./commands/hub.js";
 import { registerAgent } from "./commands/agent.js";
 import { registerAgentSkills } from "./commands/agent-skills.js";
 import { registerReflections } from "./commands/reflections.js";
+import { registerMachine } from "./commands/machine.js";
 import { registerAll as registerGenerated } from "./generated/index.js";
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 program
     .name("workcord")
-    .description("Talk to WorkCord agents through Hermes tenant chat, with advanced API diagnostics.")
+    .description("Talk to WorkCord agents through Autoworker Hub tenant chat, with advanced API diagnostics.")
     .version(version)
     .option("--as <userId>", "user to act as")
     .option("--base-url <url>", "API base URL (overrides WORKCORD_API_URL and saved configuration)");
@@ -42,7 +43,8 @@ registerAgentSkills(program);
 registerReflections(program);
 registerChallenges(program); // adds regenerate-cards (not in the OpenAPI spec)
 registerHealth(program);
-registerHermes(program);
+registerHub(program);
+registerMachine(program);
 registerGenerated(program);
 program.parseAsync().catch((err) => {
     const out = { error: err.message ?? String(err) };