@fulldivevr/workcord-cli 1.2.1 → 1.6.0

package/README.md

@@ -1,9 +1,11 @@
 # @fulldivevr/workcord-cli
 
-TypeScript CLI for the WorkCord API. **One invocation = one user action.**
-Designed for automated agents that emulate real users — wake up, do one
-thing, exit. Route-level commands are generated from the backend's own
-OpenAPI spec; a small set of hand-written semantic commands sits on top.
+TypeScript CLI for talking to WorkCord agents through persistent Hermes 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
+flavors, then inspect its reply. Route-level commands and advanced diagnostics
+remain available.
 
 Lives in the backend repo (`clients/workcord-cli`) so the spec it generates
 from is always the spec this server serves.
@@ -144,6 +146,48 @@ workcord [--as <userId>] <namespace> <command> [flags]
 `--as` is only needed when minting with `WORKCORD_JWT_SECRET`; with
 `WORKCORD_TOKEN` set, omit it everywhere.
 
+### 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
+files directly. With no `--agent`, the user's non-deletable Assistant is the
+target and becomes the default owner of anything it creates:
+
+```bash
+workcord agent chat new --message "Create a skill that prepares a concise weekly sales report and enable it."
+workcord agent chat new --message "Update my default flavor instructions to require sources in research reports."
+```
+
+Use the returned `chatId` for follow-up, verification, or rollback:
+
+```bash
+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
+message document. Use `--async` for a queued response, then continue with its
+`messageId`:
+
+```bash
+workcord agent chat wait --message-id "$MESSAGE_ID" --timeout 10m
+workcord agent chat history --chat "$CHAT_ID"
+```
+
+If a local wait times out, the response has `timedOut: true`; the remote agent
+continues working and can be checked with `chat wait`.
+
+To make another owned agent the explicit owner and conversation target:
+
+```bash
+workcord agent chat new --agent "$AGENT_ID" --message "Create and maintain a finance-specific flavor for yourself."
+```
+
+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
+advanced diagnostics and recovery tools, not the normal customization workflow.
+
 - `workcord --help` lists namespaces.
 - `workcord <namespace> --help` lists that namespace's commands.
 - `workcord <namespace> <command> --help` shows the command's flags.
@@ -161,6 +205,7 @@ workcord <namespace> <command> [--<path-param> <value>] [--body '<json>'] [--que
 ```bash
 workcord auth login --email you@company.com
 workcord --as USER messages send-text --room R --text "hello"
+workcord messages ask-agent --room R --agent INSTALLATION_ID --text "Summarize the decision"
 ```
 
 Semantic aliases cover common agent/admin actions with consistent flags:
@@ -181,6 +226,10 @@ Server auto-extracts mention tokens from visible `@Name` text. Prefer
 member's display name and avoids exposing raw user ids. `auth login` never
 takes `--as` — it is how you obtain a `WORKCORD_TOKEN` in the first place.
 
+`messages ask-agent` posts an ordinary visible `@Agent` request, then waits for
+that installed agent's visible reply in the room or request thread. Pass the
+`installationId` returned by Home to `--agent`.
+
 ### Error handling
 
 Every error is **a single JSON line on stderr**, with a non-zero exit code:
@@ -206,7 +255,7 @@ workcord --as USER rooms discover --search "ai" --tags ai,tools --limit 20
 workcord --as USER rooms create-with-message --name "ops" --public --tags ai,news --text "First post."
 workcord --as USER rooms members --room R
 workcord --as USER rooms upload-icon-file --room R --file ./icon.png
-workcord --as USER custom-agents create-hosted --name "Helper" --description "Room helper" --prompt-file ./prompt.txt --tools web_search
+workcord --as USER agent chat new --message "Create a room helper that can research the web."
 workcord --as USER room-agents install-hosted --room R --agent system-wizeup
 workcord --as USER messages react --room R --message M --emoji 👍
 workcord --as USER dm send-text --to USER_B --text "hi"
@@ -272,12 +321,14 @@ 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)
+## Advanced Hermes diagnostics and recovery (`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.
+WorkCord provisions a **Hermes Hub tenant** for each room-agent, Hermes 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
+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
@@ -291,8 +342,11 @@ Every `hermes` command takes exactly one of:
 | --- | --- |
 | `--agent <id>` | a custom agent id, used verbatim |
 | `--room-agent <id>` | a room agent id, resolved as `workcord-room-agent:<id>` |
+| `--marketplace-install <id>` | an isolated marketplace flavor install id or its room agent id |
 
-Passing both, or neither, is an error.
+Passing more than one, or none, is an error. Marketplace install access follows
+current room ownership; transferring room ownership revokes the former
+creator's ability to reveal the tenant credential.
 
 ### Credentials
 
@@ -346,6 +400,7 @@ material.
 
 ```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
@@ -355,15 +410,16 @@ 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
+### 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
+tenant-owned skill and flavor namespaces; ownership defaults to whichever agent
+tenant performs the creation.
 
-`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 direct `flavor publish`, `flavor rollout`, and `skill publish` commands are
+kept for advanced recovery and authorized publisher workflows. They operate as
+the selected tenant and can only mutate namespaces that tenant owns.
 
 The CLI does **not** pack or untar archives. The authoring loop is:
 

package/dist/cli.js

@@ -13,13 +13,16 @@ 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 { registerAgent } from "./commands/agent.js";
+import { registerAgentSkills } from "./commands/agent-skills.js";
+import { registerReflections } from "./commands/reflections.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("CLI for the WorkCord API. One invocation = one user action.")
+    .description("Talk to WorkCord agents through Hermes 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)");
@@ -27,6 +30,7 @@ program.hook("preAction", () => {
     setBaseUrlOverride(program.opts().baseUrl);
 });
 registerWhoami(program);
+registerAgent(program);
 registerAuth(program);
 registerMessages(program);
 registerRooms(program);
@@ -34,6 +38,8 @@ registerDm(program);
 registerUsers(program);
 registerRoomAgents(program);
 registerCustomAgents(program);
+registerAgentSkills(program);
+registerReflections(program);
 registerChallenges(program); // adds regenerate-cards (not in the OpenAPI spec)
 registerHealth(program);
 registerHermes(program);

package/dist/client.js

@@ -1,13 +1,18 @@
 import { resolveAuth } from "./auth.js";
 import { DEFAULT_BASE_URL, readConfig } from "./config.js";
 import { applyQuery, fetchWithRetry, httpError, normalizeBaseUrl, safeJson } from "./http.js";
+import { validateRoomCreateBody } from "./room-types.js";
 let baseUrlOverride;
 export function setBaseUrlOverride(url) {
     baseUrlOverride = url;
 }
 export async function getBaseUrl() {
     const config = await readConfig();
-    return normalizeBaseUrl(baseUrlOverride || process.env.WORKCORD_API_URL || config.baseUrl || DEFAULT_BASE_URL);
+    return normalizeBaseUrl(baseUrlOverride
+        || process.env.WORKCORD_API_URL
+        || process.env.WORKCORD_API_URL_TOKEN
+        || config.baseUrl
+        || DEFAULT_BASE_URL);
 }
 export async function call({ method = "GET", path, query, body, headers, asUserId }) {
     const config = await readConfig();
@@ -18,6 +23,8 @@ export async function callPublic({ method = "GET", path, query, body, headers })
     return request({ method, path, query, body, headers });
 }
 async function request({ method = "GET", path, query, body, headers, bearer }) {
+    if (method === "POST" && path === "/api/v1/rooms")
+        validateRoomCreateBody(body);
     const base = await getBaseUrl();
     const url = applyQuery(new URL(base + path), query);
     const res = await fetchWithRetry(() => ({

package/dist/commands/agent-skills.js

@@ -0,0 +1,127 @@
+import { actingUserId } from "../auth.js";
+import { call } from "../client.js";
+import { getOrCreateGroup } from "./_group.js";
+const SKILL_ID = /^[a-z][a-z0-9_-]{0,63}$/;
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseSkillRef(ref) {
+    const at = ref.lastIndexOf("@");
+    if (at <= 0 || at === ref.length - 1)
+        throw new Error("skill must be ID@VERSION, e.g. web-research@1.0.0");
+    return { id: skillId(ref.slice(0, at)), version: semver(ref.slice(at + 1)) };
+}
+function skillId(id) {
+    if (!SKILL_ID.test(id))
+        throw new Error("skill id must be a lowercase slug");
+    return id;
+}
+function semver(version) {
+    if (!SEMVER.test(version))
+        throw new Error("version must be a semantic version, e.g. 1.0.0");
+    return version;
+}
+function bool(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error("enabled must be true or false");
+}
+function skillPath(path) {
+    const segments = path.split("/");
+    if (segments.some((s) => !s || s === "." || s === ".."))
+        throw new Error("invalid skill file path");
+    return segments.map(encodeURIComponent).join("/");
+}
+// Agent ids are uuids, optionally behind the prefix a room agent is listed under.
+const AGENT_ID = /^(?:workcord-room-agent:|marketplace-install:)?[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$/i;
+/** Pick the one agent named `name` (exact, case-insensitive) from a list-mine response. */
+export function agentIdByName(name, mine) {
+    const agents = (mine?.data ?? []);
+    const wanted = name.toLowerCase();
+    const found = (Array.isArray(agents) ? agents : [])
+        .filter((a) => typeof a?.name === "string" && a.name.toLowerCase() === wanted);
+    if (found.length === 0)
+        throw new Error(`no agent named ${name}`);
+    if (found.length > 1) {
+        throw new Error(`more than one agent named ${name}: ${found.map((a) => `${a.name} (${a.id})`).join(", ")}`);
+    }
+    return String(found[0].id);
+}
+function agentPath(agentId, suffix) {
+    return `/api/v1/agents/${encodeURIComponent(agentId)}/${suffix}`;
+}
+export function registerAgentSkills(program, send = call, output = (value) => process.stdout.write(JSON.stringify(value) + "\n")) {
+    const agents = getOrCreateGroup(program, "custom-agents", "CustomAgents operations");
+    const skills = agents.command("skills").description("Inspect and manage skills on an agent you own");
+    const withActor = (req) => {
+        const asUserId = actingUserId(program);
+        return asUserId ? { ...req, asUserId } : req;
+    };
+    // The server takes ids only, so a name is resolved here against list-mine.
+    const resolve = async (agent) => {
+        if (AGENT_ID.test(agent))
+            return agent;
+        const mine = await send(withActor({ method: "GET", path: "/api/v1/agents/mine", query: { includeShadow: "true" } }));
+        return agentIdByName(agent, mine);
+    };
+    const run = async (agent, req) => {
+        const result = await send(withActor(req(await resolve(agent))));
+        if (result != null)
+            output(result);
+    };
+    agents.command("stop")
+        .description("Stop an agent you own. Its runtime returns to cold-idle.")
+        .argument("<agent>", "agent id or exact name")
+        .action((agent) => run(agent, (id) => ({ method: "POST", path: agentPath(id, "stop") })));
+    skills.command("list")
+        .description("List the agent's skills (core, flavor, private, and market).")
+        .argument("<agent>", "agent id or exact name")
+        .action((agent) => run(agent, (id) => ({ method: "GET", path: agentPath(id, "skills") })));
+    skills.command("files")
+        .description("List the files attached to one skill.")
+        .argument("<agent>", "agent id or exact name")
+        .argument("<category>", "skill category")
+        .argument("<skill>", "skill name")
+        .action((agent, category, skill) => run(agent, (id) => ({
+        method: "GET",
+        path: agentPath(id, `skills/${encodeURIComponent(category)}/${encodeURIComponent(skill)}/files`),
+    })));
+    skills.command("read")
+        .description("Read one skill file.")
+        .argument("<agent>", "agent id or exact name")
+        .argument("<path>", "path relative to the skill root, e.g. research/web-research/SKILL.md")
+        .action((agent, path) => {
+        const file = skillPath(path);
+        return run(agent, (id) => ({ method: "GET", path: agentPath(id, `skill-files/${file}`) }));
+    });
+    skills.command("enabled")
+        .description("Enable or disable one skill.")
+        .argument("<agent>", "agent id or exact name")
+        .argument("<name>", "skill name")
+        .argument("<true|false>", "new state")
+        .action((agent, name, enabled) => {
+        const body = { enabled: bool(enabled) };
+        return run(agent, (id) => ({ method: "PUT", path: agentPath(id, `skills/${encodeURIComponent(name)}/state`), body }));
+    });
+    skills.command("installed")
+        .description("List the market skills installed on the agent.")
+        .argument("<agent>", "agent id or exact name")
+        .action((agent) => run(agent, (id) => ({ method: "GET", path: agentPath(id, "market-skills") })));
+    skills.command("install")
+        .description("Install or update a market skill at an exact version.")
+        .argument("<agent>", "agent id or exact name")
+        .argument("<ID@VERSION>", "market skill and version, e.g. web-research@1.0.0")
+        .action((agent, ref) => {
+        const body = parseSkillRef(ref);
+        return run(agent, (id) => ({ method: "POST", path: agentPath(id, "market-skills"), body }));
+    });
+    skills.command("uninstall")
+        .description("Remove a market skill.")
+        .argument("<agent>", "agent id or exact name")
+        .argument("<id>", "market skill id")
+        .action((agent, id) => {
+        const skill = encodeURIComponent(skillId(id));
+        return run(agent, (agentId) => ({ method: "DELETE", path: agentPath(agentId, `market-skills/${skill}`) }));
+    });
+}
+//# sourceMappingURL=agent-skills.js.map

package/dist/commands/agent.js

@@ -0,0 +1,191 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { actingUserId, resolveHermesKey } from "../auth.js";
+import { call } from "../client.js";
+import { hermesCall } from "../hermes-client.js";
+export function messageText(opts) {
+    if (opts.message !== undefined && opts.messageFile !== undefined) {
+        throw new Error("Use either --message or --message-file, not both.");
+    }
+    const message = opts.messageFile !== undefined ? readFileSync(opts.messageFile, "utf8").trim() : String(opts.message || "").trim();
+    if (!message)
+        throw new Error("One of --message or --message-file is required and must not be blank.");
+    return message;
+}
+export function chatMessageBody(text) {
+    return { parts: [{ type: "text", text }] };
+}
+export function assistantIdFrom(value) {
+    const agents = Array.isArray(value?.data) ? value.data : [];
+    const assistant = agents.find((item) => item?.kind === "shadow");
+    if (!assistant?.id || typeof assistant.id !== "string") {
+        throw new Error("Your default Assistant is not ready. Open WorkCord once to provision it, or pass --agent <id>.");
+    }
+    return assistant.id;
+}
+export function chatIdFrom(value) {
+    const item = value;
+    const id = item?.chatId ?? item?.chat_id ?? item?.contextId ?? item?.context_id ?? item?.id;
+    if (typeof id !== "string" || !id)
+        throw new Error("Hub response did not contain a chat ID.");
+    return id;
+}
+export function messageIdFrom(value) {
+    const item = value;
+    const nested = item?.message;
+    const id = item?.messageId ?? item?.message_id ?? item?.id ?? nested?.messageId ?? nested?.message_id ?? nested?.id;
+    if (typeof id !== "string" || !id)
+        throw new Error("Hub response did not contain a chat message ID.");
+    return id;
+}
+export function messageState(value) {
+    const item = value;
+    const message = item?.message ?? item;
+    const status = message?.status;
+    const state = status && typeof status === "object" ? status.state : status ?? message?.state;
+    return String(state || "").toLowerCase();
+}
+export function messageRevision(value) {
+    const item = value;
+    const nested = item?.message;
+    const revision = Number(nested?.revision ?? item?.revision);
+    return Number.isSafeInteger(revision) && revision >= 0 ? revision : 0;
+}
+export function parseDuration(value = "2m") {
+    const match = /^(\d+)(ms|s|m|h)?$/.exec(value);
+    if (!match)
+        throw new Error(`Invalid duration: ${value}`);
+    const unit = (match[2] || "s");
+    const multiplier = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[unit];
+    const duration = Number(match[1]) * multiplier;
+    if (!Number.isSafeInteger(duration) || duration <= 0)
+        throw new Error("Timeout must be greater than zero.");
+    return duration;
+}
+export async function waitForChatMessage(initial, timeoutMs, getLatest) {
+    let latest = initial;
+    const messageId = messageIdFrom(latest);
+    const terminal = new Set(["completed", "failed", "canceled", "cancelled"]);
+    const deadline = Date.now() + timeoutMs;
+    while (!terminal.has(messageState(latest))) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return { message: latest, timedOut: true };
+        const waitSeconds = Math.max(1, Math.min(30, Math.ceil(remaining / 1000)));
+        latest = await getLatest(messageId, messageRevision(latest), waitSeconds);
+    }
+    return { message: latest, timedOut: false };
+}
+function tenantPath(creds, suffix) {
+    if (!creds.tenantId)
+        throw new Error("Hermes tenant ID is unavailable. Re-run with --refresh.");
+    return `/v1/tenants/${encodeURIComponent(creds.tenantId)}${suffix}`;
+}
+function out(value) {
+    process.stdout.write(JSON.stringify(value) + "\n");
+}
+function chatFlags(command) {
+    return command
+        .option("--agent <agentId>", "explicit alternate owned agent; omit to use your default Assistant")
+        .option("--refresh", "re-reveal the tenant key instead of using the cached one")
+        .option("--no-cache", "do not read or write the local tenant-key cache");
+}
+function messageFlags(command) {
+    return command
+        .option("--message <text>", "message to send to the agent")
+        .option("--message-file <path>", "read the message from a file")
+        .option("--async", "return after Hermes queues the message")
+        .option("--timeout <duration>", "maximum local wait, such as 30s or 5m", "2m")
+        .option("--idempotency-key <key>", "stable retry key; generated when omitted");
+}
+async function selectedAgentId(program, opts) {
+    if (opts.agent?.trim())
+        return opts.agent.trim();
+    return assistantIdFrom(await call({
+        path: "/api/v1/agents/mine",
+        query: { includeShadow: true },
+        asUserId: actingUserId(program),
+    }));
+}
+async function credentials(program, opts) {
+    const agentId = await selectedAgentId(program, opts);
+    const creds = await resolveHermesKey(agentId, {
+        refresh: opts.refresh,
+        cache: opts.cache,
+        asUserId: actingUserId(program),
+    });
+    return { agentId, creds };
+}
+async function sendAndWait(creds, chatId, text, opts) {
+    const queued = await hermesCall({
+        ...creds,
+        method: "POST",
+        path: tenantPath(creds, `/chats/${encodeURIComponent(chatId)}/messages`),
+        headers: { "idempotency-key": opts.idempotencyKey ?? randomUUID() },
+        body: chatMessageBody(text),
+    });
+    if (opts.async)
+        return { message: queued, timedOut: false };
+    return waitForChatMessage(queued, parseDuration(opts.timeout), (messageId, afterRevision, waitSeconds) => hermesCall({
+        ...creds,
+        path: tenantPath(creds, `/chat-messages/${encodeURIComponent(messageId)}`),
+        query: { afterRevision, waitSeconds },
+    }));
+}
+export function registerAgent(program) {
+    const group = program.command("agent").description("Talk to your Assistant or another owned agent through Hermes tenant chat");
+    const chat = group.command("chat").description("Persistent tenant conversations for instructions, skills, flavors, and agent work");
+    messageFlags(chatFlags(chat.command("new").description("Create a chat, send its first message, and wait for the agent.")))
+        .option("--title <title>", "optional chat title")
+        .action(async (opts) => {
+        const text = messageText(opts);
+        const { agentId, creds } = await credentials(program, opts);
+        const created = await hermesCall({
+            ...creds,
+            method: "POST",
+            path: tenantPath(creds, "/chats"),
+            body: opts.title ? { title: opts.title } : {},
+        });
+        const chatId = chatIdFrom(created);
+        const result = await sendAndWait(creds, chatId, text, opts);
+        out({ agentId, chatId, ...result });
+    });
+    messageFlags(chatFlags(chat.command("send").description("Continue an existing chat and wait for the agent.")))
+        .requiredOption("--chat <chatId>", "chat id returned by chat new")
+        .action(async (opts) => {
+        const text = messageText(opts);
+        const { agentId, creds } = await credentials(program, opts);
+        out({ agentId, chatId: opts.chat, ...(await sendAndWait(creds, opts.chat, text, opts)) });
+    });
+    chatFlags(chat.command("list").description("List the selected agent's chats.")).action(async (opts) => {
+        const { agentId, creds } = await credentials(program, opts);
+        out({ agentId, result: await hermesCall({ ...creds, path: tenantPath(creds, "/chats") }) });
+    });
+    chatFlags(chat.command("history").description("List messages in one chat."))
+        .requiredOption("--chat <chatId>", "chat id")
+        .action(async (opts) => {
+        const { agentId, creds } = await credentials(program, opts);
+        out({
+            agentId,
+            chatId: opts.chat,
+            result: await hermesCall({ ...creds, path: tenantPath(creds, `/chats/${encodeURIComponent(opts.chat)}/messages`) }),
+        });
+    });
+    chatFlags(chat.command("wait").description("Wait for one queued chat message to finish."))
+        .requiredOption("--message-id <messageId>", "message id returned by chat new/send --async")
+        .option("--timeout <duration>", "maximum local wait, such as 30s or 5m", "2m")
+        .action(async (opts) => {
+        const { agentId, creds } = await credentials(program, opts);
+        const initial = await hermesCall({ ...creds, path: tenantPath(creds, `/chat-messages/${encodeURIComponent(opts.messageId)}`) });
+        out({
+            agentId,
+            messageId: opts.messageId,
+            ...(await waitForChatMessage(initial, parseDuration(opts.timeout), (messageId, afterRevision, waitSeconds) => hermesCall({
+                ...creds,
+                path: tenantPath(creds, `/chat-messages/${encodeURIComponent(messageId)}`),
+                query: { afterRevision, waitSeconds },
+            }))),
+        });
+    });
+}
+//# sourceMappingURL=agent.js.map

package/dist/commands/custom-agents.js

@@ -29,10 +29,10 @@ function promptFrom(opts) {
     return opts.promptFile ? readFileSync(opts.promptFile, "utf8") : opts.prompt;
 }
 export function registerCustomAgents(program) {
-    const group = getOrCreateGroup(program, "custom-agents", "CustomAgents operations");
+    const group = getOrCreateGroup(program, "custom-agents", "Legacy hosted-agent administration; use agent chat for Hermes agents");
     group
         .command("create-hosted")
-        .description("Create a WorkCord-hosted custom agent with typed flags.")
+        .description("Create a legacy WorkCord-hosted agent directly. For Hermes agents, ask your Assistant instead.")
         .requiredOption("--name <name>", "agent name")
         .requiredOption("--description <text>", "short description")
         .option("--prompt <text>", "system prompt")
@@ -66,7 +66,7 @@ export function registerCustomAgents(program) {
     });
     group
         .command("update-hosted")
-        .description("Update a WorkCord-hosted custom agent with typed flags.")
+        .description("Update a legacy WorkCord-hosted agent directly. For Hermes agents, use agent chat.")
         .requiredOption("--agent <agentId>", "hosted custom agent id")
         .option("--name <name>", "agent name")
         .option("--description <text>", "short description")

package/dist/commands/hermes.js

@@ -7,19 +7,21 @@ import { hermesBinary, hermesCall, hermesStream, hermesUpload } from "../hermes-
 import { assertArchiveSize, flavorSetWarnings, guardOwnership, rolloutBody, } from "../hermes-guards.js";
 import { getOrCreateGroup } from "./_group.js";
 export function agentRef(opts) {
-    if (opts.agent && opts.roomAgent) {
-        throw new Error("Pass exactly one of --agent <id> or --room-agent <id>, not both.");
+    const refs = [opts.agent, opts.roomAgent, opts.marketplaceInstall].filter(Boolean);
+    if (refs.length !== 1) {
+        throw new Error("Pass exactly one of --agent <id>, --room-agent <id>, or --marketplace-install <id>.");
     }
-    if (opts.agent)
-        return opts.agent;
     if (opts.roomAgent)
         return `workcord-room-agent:${opts.roomAgent}`;
-    throw new Error("One of --agent <id> or --room-agent <id> is required.");
+    if (opts.marketplaceInstall)
+        return `marketplace-install:${opts.marketplaceInstall}`;
+    return opts.agent;
 }
 function agentFlags(cmd) {
     return cmd
         .option("--agent <id>", "custom agent id")
         .option("--room-agent <id>", "room agent id (resolved as workcord-room-agent:<id>)")
+        .option("--marketplace-install <id>", "marketplace flavor install id or its room agent id")
         .option("--refresh", "re-reveal the tenant key instead of using the cached one")
         .option("--no-cache", "do not read or write the local tenant-key cache");
 }
@@ -39,6 +41,9 @@ function parseJson(raw, flag) {
 function out(data) {
     process.stdout.write(JSON.stringify(data) + "\n");
 }
+export function hermesChatTextBody(text) {
+    return { parts: [{ type: "text", text }] };
+}
 async function credentials(program, opts) {
     return resolveHermesKey(agentRef(opts), {
         refresh: opts.refresh,
@@ -98,7 +103,7 @@ async function readArchive(archivePath) {
     return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
 }
 export function registerHermes(program) {
-    const group = getOrCreateGroup(program, "hermes", "Hermes Hub operations for a WorkCord agent's tenant");
+    const group = getOrCreateGroup(program, "hermes", "Advanced Hermes Hub diagnostics and recovery for an agent tenant");
     agentFlags(group.command("key").description("Reveal (and cache) the Hermes Hub tenant key for an agent.")).action(async (opts) => {
         const creds = await credentials(program, opts);
         out({ key: creds.key, tenantId: creds.tenantId, hubBaseUrl: creds.hubBaseUrl });
@@ -157,7 +162,7 @@ export function registerHermes(program) {
         .option("--idempotency-key <key>", "Idempotency-Key header (generated when omitted)")
         .action(async (opts) => {
         const creds = await credentials(program, opts);
-        const body = parseJson(opts.body, "--body") ?? (opts.text !== undefined ? { text: opts.text } : undefined);
+        const body = parseJson(opts.body, "--body") ?? (opts.text !== undefined ? hermesChatTextBody(opts.text) : undefined);
         if (body === undefined) {
             throw new Error("One of --text or --body is required.");
         }