teamclaws 1.0.1 → 1.0.3

package/README.md

@@ -51,10 +51,14 @@ Existing event names and schema version remain unchanged. The
 login keeps running. Signed-out `auth_status` includes the non-executing
 `login_command: "teamclaws login --json"`; status never starts device authorization.
 
-`servers list` requests `GET /api/cli/v1/servers/?include_inventory=1`. Updated
+`servers list` requests `GET /api/cli/v1/servers/?include_inventory=1&include_description=1&include_editable_metadata=1`. Updated
 brokers return `servers` and `workspace_count`: the count of all non-deleted
 owned and eligible shared workspaces, including those without a hostname yet.
 Individual server entries retain aliases, stable IDs, status and `pairing_ready`.
+When supported, they also include the server description. Older brokers may
+omit descriptions; nonempty descriptions appear under each readable list entry.
+The editing opt-in adds `custom_alias` (the owner's saved name, distinct from a
+fallback display name) and `can_edit_metadata`. Older brokers may omit these.
 Older brokers may omit the count; the CLI reports it as null and never infers
 an empty account from an empty filtered list.
 
@@ -67,6 +71,28 @@ purchase a workspace. Existing owners whose machines are being prepared do not
 need another purchase. Targetless pairing requires explicit selection even for
 one result; agents present aliases and pass only user-selected stable IDs.
 
+Owners can edit their server's user-defined name and description:
+
+```text
+teamclaws servers update <server-id> --name "My server" --description "What this server is for"
+```
+
+Provide either flag or both. Omitted fields stay unchanged; an empty string
+clears a field. The name updates the server alias, preserving its system name
+and workspace address. Names are limited to 100 characters and new descriptions
+to 2000. The API enforces ownership; shared access, staff, and superuser roles
+do not grant editing rights to someone else's server.
+
+When `servers list` or targetless pairing first discovers an owned server with
+no user-defined name or description, the CLI asks once whether to set them and
+explains the command to edit them later. This prompt is remembered per owner and
+server across devices, including a decline. In `--json` mode, the CLI emits a
+`server_metadata_prompt` event for the agent to show the user, followed by the
+normal result. Agents must ask the question and wait for the user's answer
+before running the edit command. Plain-text commands without an interactive
+terminal do not consume the prompt. The backend atomically claims the prompt;
+a crash after that claim may consume it before it is displayed.
+
 ## Commands
 
 ```text

package/dist/app.js

@@ -9,7 +9,7 @@ import { PairingClient } from "./pairing.js";
 import { runShell, shellFetch } from "./shell.js";
 import { CredentialStore } from "./storage.js";
 import { installRelease } from "./update.js";
-import { parsePairingTarget } from "./validation.js";
+import { normalizeUuid, parsePairingTarget } from "./validation.js";
 export async function run(arguments_, dependencies = {}, signal) {
     let parsed;
     try {
@@ -120,9 +120,15 @@ export async function run(arguments_, dependencies = {}, signal) {
             }
             case "servers_list": {
                 const inventory = await broker.servers(token, signal);
+                await offerServerMetadata(inventory.servers, broker, token, parsed.json, output, dependencies.io, signal);
                 output.servers(inventory.servers, inventory.workspace_count);
                 return 0;
             }
+            case "servers_update": {
+                const server = await broker.updateServerMetadata(token, parsed.serverId, parsed.updates, signal);
+                output.serverMetadataUpdated(server);
+                return 0;
+            }
             case "pair": {
                 const target = parsed.target
                     ? parsePairingTarget(parsed.target)
@@ -154,6 +160,34 @@ export async function run(arguments_, dependencies = {}, signal) {
     }
 }
 export function parseArguments(arguments_) {
+    if (arguments_[0] === "servers" && arguments_[1] === "update") {
+        const serverId = normalizeUuid(requiredPositional(arguments_, 2));
+        const updates = {};
+        let json = false;
+        for (let index = 3; index < arguments_.length; index += 1) {
+            const option = arguments_[index];
+            if (option === "--name" && updates.alias === undefined) {
+                const value = arguments_[++index];
+                if (value === undefined)
+                    throw usageError();
+                updates.alias = value;
+            }
+            else if (option === "--description" &&
+                updates.description === undefined) {
+                const value = arguments_[++index];
+                if (value === undefined)
+                    throw usageError();
+                updates.description = value;
+            }
+            else if (option === "--json" && !json)
+                json = true;
+            else
+                throw usageError();
+        }
+        if (Object.keys(updates).length === 0)
+            throw usageError();
+        return { action: "servers_update", serverId, updates, json };
+    }
     if (arguments_[0] === "shell") {
         const target = requiredPositional(arguments_, 1);
         let command;
@@ -350,6 +384,7 @@ function nonNegativeInteger(value) {
 }
 async function discoverTarget(broker, token, json, output, io, signal) {
     const inventory = await broker.servers(token, signal);
+    await offerServerMetadata(inventory.servers, broker, token, json, output, io, signal);
     const servers = inventory.servers.filter((server) => server.pairing_ready);
     if (servers.length === 0) {
         throw new TeamClawsError("no_pairing_ready_workspaces", inventory.workspace_count === 0
@@ -364,6 +399,49 @@ async function discoverTarget(broker, token, json, output, io, signal) {
     const selected = await promptForServer(servers, io?.input ?? process.stdin, io?.stdout ?? process.stdout);
     return { server_id: selected.server_id };
 }
+async function offerServerMetadata(servers, broker, token, json, output, io, signal) {
+    const interactive = io?.interactive ?? (process.stdin.isTTY && process.stdout.isTTY);
+    if (!json && !interactive)
+        return;
+    for (const server of servers) {
+        if (server.can_edit_metadata !== true ||
+            server.custom_alias === undefined ||
+            server.description === undefined ||
+            (server.custom_alias.trim() !== "" && server.description.trim() !== ""))
+            continue;
+        const claimed = await broker.claimMetadataPrompt(token, server.server_id, signal);
+        Object.assign(server, claimed.server);
+        if (!claimed.should_prompt)
+            continue;
+        output.serverMetadataPrompt(server);
+        if (json)
+            continue;
+        const terminal = createInterface({
+            input: io?.input ?? process.stdin,
+            output: (io?.stdout ?? process.stdout),
+        });
+        try {
+            const answer = await terminal.question("Set the name and description now? [y/N] ");
+            if (!/^y(?:es)?$/iu.test(answer.trim()))
+                continue;
+            const name = await terminal.question(`Name (Enter to keep ${JSON.stringify(server.custom_alias || server.alias)}): `);
+            const description = await terminal.question("Description (Enter to keep the current description): ");
+            const updates = {};
+            if (name.trim())
+                updates.alias = name;
+            if (description.trim())
+                updates.description = description;
+            if (Object.keys(updates).length > 0) {
+                const updated = await broker.updateServerMetadata(token, server.server_id, updates, signal);
+                Object.assign(server, updated);
+                output.serverMetadataUpdated(updated);
+            }
+        }
+        finally {
+            terminal.close();
+        }
+    }
+}
 async function promptForServer(servers, input, output) {
     const terminal = createInterface({
         input,
@@ -389,5 +467,5 @@ function usageError() {
     });
 }
 export function helpText() {
-    return `TeamClaws ${PACKAGE_VERSION}\n\nUsage:\n  teamclaws update [--json]\n  teamclaws shell <target> --command <text> [--json]\n  teamclaws login [email] [--json]\n  teamclaws auth status [--json]\n  teamclaws logout [--json]\n  teamclaws servers list [--json]\n  teamclaws pair status <server-identifier-or-canonical-workspace-address> [--json]\n  teamclaws pair [server-identifier-or-canonical-workspace-address] [--no-open] [--json]\n  teamclaws chat list <target> [--json]\n  teamclaws chat capabilities <target> [--json]\n  teamclaws chat start <target> --message <text> [selection options] [--json]\n  teamclaws chat send <target> --session-id <uuid> --message <text> [--json]\n  teamclaws chat watch <target> --session-id <uuid> --request-id <uuid> [resume cursors] [--json]\n\nPair status performs one bounded direct verification and stops. Pairing grants the standard host-issued credential. Chat commands use that credential directly against the selected workspace.\n`;
+    return `TeamClaws ${PACKAGE_VERSION}\n\nUsage:\n  teamclaws update [--json]\n  teamclaws shell <target> --command <text> [--json]\n  teamclaws login [email] [--json]\n  teamclaws auth status [--json]\n  teamclaws logout [--json]\n  teamclaws servers list [--json]\n  teamclaws servers update <server-id> [--name <text>] [--description <text>] [--json]\n  teamclaws pair status <server-identifier-or-canonical-workspace-address> [--json]\n  teamclaws pair [server-identifier-or-canonical-workspace-address] [--no-open] [--json]\n  teamclaws chat list <target> [--json]\n  teamclaws chat capabilities <target> [--json]\n  teamclaws chat start <target> --message <text> [selection options] [--json]\n  teamclaws chat send <target> --session-id <uuid> --message <text> [--json]\n  teamclaws chat watch <target> --session-id <uuid> --request-id <uuid> [resume cursors] [--json]\n\nPair status performs one bounded direct verification and stops. Pairing grants the standard host-issued credential. Chat commands use that credential directly against the selected workspace.\n`;
 }

package/dist/broker.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { API_BASE, CLIENT_NAME, CONTRACT_VERSION, MAX_CLIENT_LABEL_LENGTH, MAX_DEVICE_NAME_LENGTH, PACKAGE_VERSION, } from "./constants.js";
 import { TeamClawsError } from "./errors.js";
 import { errorFromResponse, requestJson } from "./http.js";
-import { parsePendingPairing, parseWorkspaceInventory } from "./validation.js";
+import { assertExactKeys, isObject, normalizeUuid, parsePendingPairing, parseWorkspaceInventory, requireString, } from "./validation.js";
 export class BrokerClient {
     fetcher;
     deviceName;
@@ -15,7 +15,7 @@ export class BrokerClient {
         return normalizedDeviceName(this.deviceName());
     }
     async servers(accessToken, signal) {
-        const response = await requestJson(this.fetcher, `${API_BASE}servers/?include_inventory=1`, {
+        const response = await requestJson(this.fetcher, `${API_BASE}servers/?include_inventory=1&include_description=1&include_editable_metadata=1`, {
             headers: requestHeaders(accessToken),
             ...(signal ? { signal } : {}),
         });
@@ -29,6 +29,47 @@ export class BrokerClient {
         }
         return parseWorkspaceInventory(response.body);
     }
+    async updateServerMetadata(accessToken, serverId, updates, signal) {
+        if (Object.keys(updates).length === 0 ||
+            (updates.alias !== undefined && [...updates.alias.trim()].length > 100) ||
+            (updates.description !== undefined &&
+                [...updates.description.trim()].length > 2_000)) {
+            throw new TeamClawsError("invalid_server_metadata", "Provide a name of 100 characters or fewer and/or a description of 2000 characters or fewer.", { exitCode: 2 });
+        }
+        const id = normalizeUuid(serverId);
+        const response = await requestJson(this.fetcher, `${API_BASE}servers/${id}/metadata/`, {
+            method: "POST",
+            headers: requestHeaders(accessToken),
+            body: updates,
+            ...(signal ? { signal } : {}),
+        });
+        if (response.status < 200 || response.status >= 300)
+            throw errorFromResponse(response, "server_metadata_update_failed");
+        if (!isObject(response.body))
+            throw invalidMetadataResponse();
+        assertExactKeys(response.body, ["server"], [], "server metadata response");
+        return editableServer(response.body.server, id);
+    }
+    async claimMetadataPrompt(accessToken, serverId, signal) {
+        const id = normalizeUuid(serverId);
+        const response = await requestJson(this.fetcher, `${API_BASE}servers/${id}/metadata-prompt/claim/`, {
+            method: "POST",
+            headers: requestHeaders(accessToken),
+            body: {},
+            ...(signal ? { signal } : {}),
+        });
+        if (response.status < 200 || response.status >= 300)
+            throw errorFromResponse(response, "server_metadata_prompt_failed");
+        if (!isObject(response.body))
+            throw invalidMetadataResponse();
+        assertExactKeys(response.body, ["should_prompt", "server"], [], "server metadata prompt response");
+        if (typeof response.body.should_prompt !== "boolean")
+            throw invalidMetadataResponse();
+        return {
+            should_prompt: response.body.should_prompt,
+            server: editableServer(response.body.server, id),
+        };
+    }
     async startPairing(target, accessToken, signal) {
         const request = pairingStartRequest(target, this.currentDeviceName());
         const response = await requestJson(this.fetcher, `${API_BASE}pairing/start/`, {
@@ -51,6 +92,28 @@ export class BrokerClient {
         return pending;
     }
 }
+function invalidMetadataResponse() {
+    return new TeamClawsError("invalid_response", "TeamClaws returned invalid server metadata.", { exitCode: 9 });
+}
+function editableServer(value, expectedId) {
+    if (!isObject(value))
+        throw invalidMetadataResponse();
+    assertExactKeys(value, ["id", "alias", "description", "custom_alias", "can_edit_metadata"], [], "server metadata");
+    const id = normalizeUuid(value.id);
+    if (id !== expectedId ||
+        value.can_edit_metadata !== true ||
+        typeof value.custom_alias !== "string" ||
+        [...value.custom_alias].length > 100 ||
+        typeof value.description !== "string")
+        throw invalidMetadataResponse();
+    return {
+        server_id: id,
+        alias: requireString(value.alias, "server alias", 200),
+        description: value.description,
+        custom_alias: value.custom_alias,
+        can_edit_metadata: true,
+    };
+}
 export function pairingStartRequest(target, deviceName) {
     return {
         contract_version: CONTRACT_VERSION,

package/dist/constants.js

@@ -1,5 +1,5 @@
 export const PACKAGE_NAME = "teamclaws";
-export const PACKAGE_VERSION = "1.0.1";
+export const PACKAGE_VERSION = "1.0.3";
 export const CLIENT_NAME = "teamclaws-cli";
 export const CONTRACT_VERSION = 1;
 export const OUTPUT_SCHEMA_VERSION = 1;

package/dist/output.js

@@ -107,9 +107,36 @@ export class Output {
             }
             servers.forEach((server, index) => {
                 this.stdout.write(`${index + 1}. ${server.alias} — ${server.server_id} — ${server.workspace_url} — ${server.pairing_ready ? "ready to pair" : "not ready to pair"}\n`);
+                if (server.description)
+                    this.stdout.write(`   ${server.description}\n`);
             });
         }
     }
+    serverMetadataPrompt(server) {
+        const updateCommand = `teamclaws servers update ${server.server_id} --name "Your server name" --description "What this server is for"`;
+        const guidance = `You can always change the name and description later with: ${updateCommand}`;
+        const question = "Would you like to set the server name and description now?";
+        this.event({
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            event: "server_metadata_prompt",
+            server,
+            question,
+            message: `Your server ${JSON.stringify(server.alias)} is missing a user-defined name or description. ${question} ${guidance}`,
+            update_command: updateCommand,
+        });
+        if (!this.json)
+            this.stdout.write(`Your server ${JSON.stringify(server.alias)} is missing a user-defined name or description.\n${guidance}\n`);
+    }
+    serverMetadataUpdated(server) {
+        this.event({
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            event: "server_metadata_updated",
+            status: "success",
+            server,
+        });
+        if (!this.json)
+            this.stdout.write(`Updated server details for ${server.alias}.\n`);
+    }
     pairingComplete(serverId, origin, displayName, externalChatHandoff, capabilities, generatedAt) {
         const workspace = {
             server_id: serverId,

package/dist/validation.js

@@ -353,15 +353,35 @@ export function parseServersResponse(value) {
                 exitCode: 9,
             });
         }
-        assertExactKeys(server, ["id", "alias", "workspace_url", "status", "pairing_ready"], [], "server");
+        assertExactKeys(server, ["id", "alias", "workspace_url", "status", "pairing_ready"], ["description", "custom_alias", "can_edit_metadata"], "server");
         if (typeof server.pairing_ready !== "boolean") {
             throw new TeamClawsError("invalid_response", "TeamClaws returned an invalid server.", {
                 exitCode: 9,
             });
         }
+        if (server.description !== undefined &&
+            typeof server.description !== "string") {
+            throw new TeamClawsError("invalid_response", "TeamClaws returned an invalid server description.", { exitCode: 9 });
+        }
+        if ((server.custom_alias !== undefined &&
+            (typeof server.custom_alias !== "string" ||
+                [...server.custom_alias].length > 100)) ||
+            (server.can_edit_metadata !== undefined &&
+                typeof server.can_edit_metadata !== "boolean")) {
+            throw new TeamClawsError("invalid_response", "TeamClaws returned invalid server editing permissions.", { exitCode: 9 });
+        }
         return {
             server_id: normalizeUuid(server.id),
             alias: requireString(server.alias, "server alias", 200),
+            ...(typeof server.description === "string"
+                ? { description: server.description }
+                : {}),
+            ...(typeof server.custom_alias === "string"
+                ? { custom_alias: server.custom_alias }
+                : {}),
+            ...(typeof server.can_edit_metadata === "boolean"
+                ? { can_edit_metadata: server.can_edit_metadata }
+                : {}),
             workspace_url: canonicalWorkspaceUrl(server.workspace_url),
             status: requireString(server.status, "server status", 40),
             pairing_ready: server.pairing_ready,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamclaws",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Official TeamClaws command-line client and agent skills",
   "license": "PolyForm-Shield-1.0.0",
   "homepage": "https://teamclaws.com",

package/skills/teamclaws-onboard/SKILL.md

@@ -36,6 +36,15 @@ Run `teamclaws servers list --json`. Use only a successful `servers_list` event;
 errors are not empty inventories. Display aliases, retaining `server_id` for
 commands. Explain readiness separately from ownership.
 
+If discovery emits `server_metadata_prompt`, show its question and explain that
+the owner can always change the server's name and description later. Ask for the
+desired values if the user wants to edit them; run `teamclaws servers update
+<server-id> --name <text> --description <text> --json` only after their answer.
+Either flag may be omitted to keep that field unchanged. This question is
+remembered once per owner and server across devices, including a decline, so
+deliver it when received. Never offer this edit for a shared server whose
+`can_edit_metadata` is false, and never infer ownership from an alias or role.
+
 - `discovery_state: no_workspaces` means the broker confirmed zero workspaces
   accessible for pairing, including owned workspaces still being prepared.
   Direct the user to https://teamclaws.com/app/ to purchase a workspace, then