teamclaws 2.0.7 → 2.0.9

package/README.md

@@ -18,10 +18,11 @@ workspace user; user membership is a separate privilege.
 ## Installation
 
 Check `node --version` first. If it is below 22, upgrade Node.js to version 22
-or newer before installing. npm normally treats the package engine requirement
-as a warning; `npm install -g teamclaws@latest --engine-strict` rejects an
-unsupported Node.js version during installation. The CLI also refuses to run on
-Node.js below 22.
+or newer before installing. The install script rejects Node.js below 22 during
+an ordinary npm install. npm's `--ignore-scripts` or an installer policy that
+disables lifecycle scripts bypasses this install check; the CLI still refuses
+to run on Node.js below 22. `--engine-strict` also enforces the declared engine
+requirement without changing global npm settings.
 
 Install the published CLI:
 
@@ -54,12 +55,16 @@ the existing paired shell. Status-only requests do not start onboarding.
 
 Before any browser authorization, the agent explains the process: sign this
 computer's CLI into the user's TeamClaws account through the browser, choose a
-workspace and approve pairing with that server in the browser, then choose useful
+workspace and pair with that server, then choose useful
 work and set up its environment on the server. It explains the purpose and access
 of each approval before presenting a link, adapting to steps already completed.
 The conversation starts with that context rather than an unexplained request to
 click an authorization link.
 
+Pairing completes automatically when TeamClawsDeploy confirms the account owns
+the workspace or is a superuser in its access group. Browser approval is shown
+only when the target reports that approval is pending.
+
 Agents keep their turn and the original login/pairing process alive while the
 user approves in the browser, monitor its output, and continue automatically
 after terminal success. No "I approved" message is needed. An execution
@@ -88,7 +93,8 @@ 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.
 
-`pairing_browser_required` supplies the safe approval URL and public `user_code`.
+When approval is pending, `pairing_browser_required` supplies the safe approval
+URL and public `user_code`. Automatic pairing emits no browser approval event.
 Some hosts include a validated `agent_action` with the legacy type
 `deliver_and_stop`. The agent displays its approval message and continues
 monitoring the original process; that field does not end the agent's turn. The
@@ -239,6 +245,19 @@ acceptance. Existing memberships and pending invitations are preserved without
 promotion or resend. If a request has an uncertain network outcome, inspect the
 invitation status before trying again; the command does not blindly retry it.
 
+### Inspect users and invitation status
+
+```text
+teamclaws users list <target> --json
+```
+
+This read requires the current machine owner's active paired authorization.
+It lists current members separately from pending and accepted invitation
+records. An accepted invitation is historical evidence of acceptance; current
+membership determines whether the person still has access. An expired pending
+invitation is marked expired. Listing sends no invitations and changes no roles,
+memberships, or invitation state. It requires a workspace with the users-list API.
+
 ## Read chat history without a browser
 
 ```text
@@ -267,7 +286,8 @@ to a specific request, so neither command checks for later conversation turns.
 
 For authorized workspace administration, first check pairing status with
 `teamclaws pair status <target> --json`. If `not_paired`, complete CLI login and pairing
-approval for that workspace before using the shell. A linked AI provider or
+for that workspace before using the shell, following browser approval only when
+requested by the CLI. A linked AI provider or
 TCChat conversation is not required for paired-shell access; remote chat is a
 separate operation.
 
@@ -306,6 +326,12 @@ access is enforced by TeamClaws servers, not by the client license.
 
 ### Provider and model capabilities
 
+If the workspace confirms `no_provider_paired`, open its `/teamclaws-admin/`
+page, choose **Link AI Account**, and connect a provider. For Cursor, choose
+**Cursor**, then **My Subscription**, and complete browser authorization.
+An unavailable provider status or a transport failure does not prove that no
+provider is paired.
+
 Run `teamclaws chat capabilities <target> [--json]` with an existing saved
 workspace pairing. It reads the workspace capabilities endpoint with a shared
 120-second budget, attempts lasting at most 15 seconds, and pauses of up to five

package/dist/app.js

@@ -11,7 +11,7 @@ import { CredentialStore } from "./storage.js";
 import { TargetAuthorization } from "./target-authorization.js";
 import { installRelease } from "./update.js";
 import { normalizeUuid, parsePairingTarget } from "./validation.js";
-import { runUsersAdd } from "./users.js";
+import { runUsersAdd, runUsersList } from "./users.js";
 export async function run(arguments_, dependencies = {}, signal) {
     let parsed;
     try {
@@ -71,6 +71,18 @@ export async function run(arguments_, dependencies = {}, signal) {
     }
     const store = dependencies.store ?? new CredentialStore();
     const targetAuthorization = new TargetAuthorization(store, dependencies.fetcher);
+    if (parsed.action === "users_list") {
+        try {
+            await targetAuthorization.requireGrant();
+            output.usersListResult(await runUsersList(store, dependencies.fetcher ?? fetch, parsed.target, targetAuthorization, signal));
+            return 0;
+        }
+        catch (error) {
+            const safe = safeError(error);
+            output.error(safe);
+            return safe.exitCode;
+        }
+    }
     if (parsed.action === "users_add") {
         try {
             await targetAuthorization.requireGrant();
@@ -231,6 +243,12 @@ export function parseArguments(arguments_) {
     }
     const json = arguments_.includes("--json");
     const args = arguments_.filter((argument) => argument !== "--json");
+    if (args[0] === "users" && args[1] === "list" && args.length === 3)
+        return {
+            action: "users_list",
+            json,
+            target: parsePairingTarget(requiredPositional(args, 2)),
+        };
     if (args[0] === "users" && args[1] === "add") {
         const target = parsePairingTarget(requiredPositional(args, 2));
         const email = requiredPositional(args, 3).trim().toLowerCase();
@@ -532,5 +550,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 users add <target> <email> --role <user|staff|superuser> [--json]\n  teamclaws login [email] [--json]\n  teamclaws auth status [--json]\n  teamclaws logout [--revoke] [--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 history <target> [--json]\n  teamclaws chat messages <target> --chat-id <uuid> [--after-message-id <n>] [--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 users add <target> <email> --role <user|staff|superuser> [--json]\n  teamclaws users list <target> [--json]\n  teamclaws login [email] [--json]\n  teamclaws auth status [--json]\n  teamclaws logout [--revoke] [--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 history <target> [--json]\n  teamclaws chat messages <target> --chat-id <uuid> [--after-message-id <n>] [--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/constants.js

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

package/dist/external-chat.js

@@ -88,6 +88,11 @@ export class ExternalChatClient {
                     });
                 }
                 const inventory = parseCapabilityInventory(response.body);
+                if (inventory.provider_availability?.code === "no_provider_paired") {
+                    if (inventory.providers.length !== 0)
+                        throw invalidChatResponse();
+                    throw new TeamClawsError("no_provider_paired", `No AI provider is paired for this workspace. Open ${credential.origin}/teamclaws-admin/, choose Link AI Account, and connect a provider. For Cursor, choose Cursor, then My Subscription.`, { exitCode: 5 });
+                }
                 if (this.now() >= deadline)
                     break;
                 if (inventory.providers.some((provider) => provider.models.length > 0)) {
@@ -99,7 +104,10 @@ export class ExternalChatClient {
                         external_chat_capabilities: inventory,
                     };
                 }
-                lastFailure = "The workspace returned no provider/model choices.";
+                lastFailure =
+                    inventory.provider_availability?.code === "provider_unavailable"
+                        ? "AI provider status is unavailable."
+                        : "The workspace returned no provider/model choices.";
             }
             catch (error) {
                 canceled();
@@ -121,7 +129,7 @@ export class ExternalChatClient {
                 await this.wait(Math.min(5_000, remaining), signal);
         }
         canceled();
-        throw new TeamClawsError("capabilities_unavailable", `${lastFailure} Log into TeamClaws and ensure the server is running.`, { exitCode: 5, retryable: true });
+        throw new TeamClawsError("capabilities_unavailable", `${lastFailure} Check workspace connectivity or the provider connections at ${credential.origin}/teamclaws-admin/ and retry.`, { exitCode: 5, retryable: true });
     }
     async start(options, signal) {
         const context = await this.context(options.target, signal, true);
@@ -506,8 +514,21 @@ export function parseCapabilityInventory(value) {
         !isObject(value.identity) ||
         !Array.isArray(value.approved_scopes))
         throw invalidChatResponse();
+    let availability;
+    if (value.provider_availability !== undefined) {
+        const state = value.provider_availability;
+        if (!isObject(state) ||
+            !["ready", "no_provider_paired", "provider_unavailable"].includes(String(state.code)) ||
+            state.setup_path !== "/teamclaws-admin/")
+            throw invalidChatResponse();
+        availability = {
+            code: state.code,
+            setup_path: "/teamclaws-admin/",
+        };
+    }
     return {
         contract_version: 1,
+        ...(availability ? { provider_availability: availability } : {}),
         identity: {
             alias: requireString(value.identity.alias, "external identity alias", 200),
         },

package/dist/output.js

@@ -405,6 +405,25 @@ export class Output {
             this.stdout.write(`${messages[result.code]}\n`);
         }
     }
+    usersListResult(result) {
+        this.event({
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            event: "users_list_result",
+            ...result,
+        });
+        if (!this.json) {
+            this.stdout.write("Current members:\n");
+            for (const member of result.members)
+                this.stdout.write(`${member.email}: ${member.role}${member.is_owner ? " (owner)" : ""}\n`);
+            if (!result.members.length)
+                this.stdout.write("No members returned.\n");
+            this.stdout.write("Invitations:\n");
+            for (const invite of result.invites)
+                this.stdout.write(`${invite.email}: ${invite.status}${invite.is_expired && invite.status === "pending" ? " (expired)" : ""} — ${invite.role}\n`);
+            if (!result.invites.length)
+                this.stdout.write("No pending or accepted invitations.\n");
+        }
+    }
     event(event) {
         if (this.json)
             this.stdout.write(`${JSON.stringify(event)}\n`);

package/dist/pairing.js

@@ -76,12 +76,9 @@ export class PairingClient {
         }
     }
     async complete(pending, deviceName, noOpen, signal) {
-        this.output.pairingBrowser(pending.verification_uri_complete, pending.user_code, pending.agent_action);
-        if (!noOpen)
-            await this.openBrowser(pending.verification_uri_complete);
         let credential;
         try {
-            credential = await this.poll(pending, signal);
+            credential = await this.poll(pending, noOpen, signal);
             const grant = await this.authorization.requireGrant();
             if (credential.pairing_id !== credential.device_id ||
                 credential.origin !== pending.target.origin ||
@@ -142,9 +139,10 @@ export class PairingClient {
             void credential;
         }
     }
-    async poll(pending, signal) {
+    async poll(pending, noOpen, signal) {
         const deadline = this.now() + pending.expires_in * 1_000;
         let intervalSeconds = pending.interval;
+        let approvalShown = false;
         const pollUrl = directTargetUrl(pending.target, pending.target.token_poll_path);
         while (this.now() < deadline) {
             if (signal?.aborted)
@@ -158,6 +156,12 @@ export class PairingClient {
             if (response.status >= 200 && response.status < 300) {
                 if (response.status === 202) {
                     intervalSeconds = pendingInterval(response, intervalSeconds);
+                    if (!approvalShown) {
+                        this.output.pairingBrowser(pending.verification_uri_complete, pending.user_code, pending.agent_action);
+                        approvalShown = true;
+                        if (!noOpen)
+                            await this.openBrowser(pending.verification_uri_complete);
+                    }
                     await this.wait(intervalSeconds * 1_000, signal);
                     continue;
                 }

package/dist/users.js

@@ -19,6 +19,78 @@ const failureMessages = {
     invite_delivery_failed: "The invitation could not be delivered. Check its status before retrying.",
     outcome_unverified: "The invitation outcome could not be verified. Check its status before retrying.",
 };
+export async function runUsersList(store, fetcher, target, authorization, signal) {
+    const credential = await store.findWorkspace(target);
+    if (!credential)
+        throw new TeamClawsError("re_pair_required", "No saved pairing was found for this workspace. Pair it first.", { exitCode: 3 });
+    const response = await requestTargetJson(fetcher, authorization, `${credential.origin}/teamclaws-admin/api/device-users/v1/list/`, credential, { ...(signal ? { signal } : {}) });
+    const body = response.body;
+    if (response.status !== 200 || (isObject(body) && body.ok === false)) {
+        const messages = {
+            invalid_actor_token: failureMessages.invalid_actor_token,
+            unauthorized: failureMessages.unauthorized,
+            owner_required: "Only the current machine owner can inspect users and invitations.",
+            forbidden: "The paired identity is not authorized to inspect users and invitations.",
+            actor_machine_mismatch: failureMessages.actor_machine_mismatch,
+            actor_authorization_unavailable: failureMessages.actor_authorization_unavailable,
+            authorization_unavailable: failureMessages.authorization_unavailable,
+            machine_auth_failed: failureMessages.machine_auth_failed,
+            machine_ip_rejected: failureMessages.machine_ip_rejected,
+        };
+        const rawCode = isObject(body) ? body.code : undefined;
+        const code = typeof rawCode === "string" && Object.hasOwn(messages, rawCode)
+            ? rawCode
+            : [404, 405].includes(response.status)
+                ? "users_list_unavailable"
+                : "users_list_failed";
+        throw new TeamClawsError(code, messages[code] ??
+            (code === "users_list_unavailable"
+                ? "User and invitation status inspection is unavailable on this workspace."
+                : "The workspace could not retrieve user and invitation status. Retry the read request."), {
+            exitCode: response.status === 401 ? 3 : response.status === 429 ? 5 : 1,
+        });
+    }
+    const invalid = () => new TeamClawsError("invalid_response", "The workspace returned invalid user or invitation status.", { exitCode: 9 });
+    if (!isObject(body) ||
+        body.ok !== true ||
+        body.action !== "list" ||
+        body.scope !== "access_group" ||
+        !Array.isArray(body.members) ||
+        !Array.isArray(body.invites))
+        throw invalid();
+    const validEmail = (value) => typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 254 &&
+        ![...value].some((character) => character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f);
+    const roles = ["user", "staff", "superuser"];
+    const members = body.members.map((row) => {
+        if (!isObject(row) ||
+            !validEmail(row.email) ||
+            !roles.includes(String(row.role)) ||
+            typeof row.is_owner !== "boolean")
+            throw invalid();
+        return {
+            email: row.email,
+            role: row.role,
+            is_owner: row.is_owner,
+        };
+    });
+    const invites = body.invites.map((row) => {
+        if (!isObject(row) ||
+            !validEmail(row.email) ||
+            !roles.includes(String(row.role)) ||
+            !["pending", "accepted"].includes(String(row.status)) ||
+            typeof row.is_expired !== "boolean")
+            throw invalid();
+        return {
+            email: row.email,
+            role: row.role,
+            status: row.status,
+            is_expired: row.is_expired,
+        };
+    });
+    return { ok: true, action: "list", scope: "access_group", members, invites };
+}
 export async function runUsersAdd(store, fetcher, target, email, role, authorization, signal) {
     const credential = await store.findWorkspace(target);
     if (!credential)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teamclaws",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "Official TeamClaws command-line client and agent skills",
   "license": "PolyForm-Shield-1.0.0",
   "homepage": "https://teamclaws.com",
@@ -17,12 +17,14 @@
     "teamclaws": "./dist/cli.js"
   },
   "files": [
+    "scripts/check-node.mjs",
     "dist/",
     "skills/",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
+    "preinstall": "node scripts/check-node.mjs",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint .",

package/scripts/check-node.mjs

@@ -0,0 +1,8 @@
+import process from "node:process";
+
+if (Number(process.versions.node.split(".")[0]) < 22) {
+  process.stderr.write(
+    `TeamClaws requires Node.js 22 or newer; this runtime is ${process.versions.node}. Upgrade Node.js before installing TeamClaws.\n`,
+  );
+  process.exitCode = 1;
+}

package/skills/teamclaws-chat/SKILL.md

@@ -51,6 +51,12 @@ use either as evidence that a conversation has no follow-ups. Never send a
 message, start another chat, or use the browser just to read history. An HTTP
 error or incomplete pagination is not evidence of an empty history.
 
+On `no_provider_paired`, explain that no AI provider is paired for this workspace.
+Open the verified workspace's `/teamclaws-admin/` page and choose **Link AI
+Account**. For Cursor, choose **Cursor**, then **My Subscription**, and complete
+browser authorization. Do not describe an unavailable inventory or a transport
+failure as proof that no provider is paired.
+
 ## Start one conversation
 
 Obtain a non-empty user message, then run:

package/skills/teamclaws-login/SKILL.md

@@ -11,8 +11,9 @@ A status-only request runs only `teamclaws auth status --json` and stops.
 
 Before starting browser login, explain that the user will sign this computer's
 TeamClaws command-line client into their TeamClaws account through the browser.
-This connects the client to their account; workspace selection and browser
-pairing approval come next when they are connecting a workspace. If onboarding
+This connects the client to their account; workspace selection and pairing come
+next when they are connecting a workspace. Pairing may complete automatically;
+show browser approval only if the CLI requests it. If onboarding
 already explained the process, use a short transition into this step. Give the
 approval link with that context, never as an unexplained authorization request.
 

package/skills/teamclaws-onboard/SKILL.md

@@ -22,7 +22,9 @@ user's work and any steps already completed:
 1. First, we'll sign this computer into your TeamClaws account using your browser.
    This lets the TeamClaws command-line client here connect to your account.
 2. Next, you'll choose a workspace, and we'll pair this computer with that server.
-   You'll approve that connection in your browser too. Pairing gives this computer
+   Pairing completes automatically when TeamClawsDeploy confirms you own the
+   workspace or are a superuser in its access group. Follow browser approval
+   only if the CLI requests it. Pairing gives this computer
    access to run commands and work with files on the workspace.
 3. Then we'll find the best work to move there and set up a clean environment for
    it, separate from your laptop. That could be a complete job, an agent, a service

package/skills/teamclaws-pair/SKILL.md

@@ -56,7 +56,7 @@ teamclaws pair <stable-server-identifier> --json
 ```
 
 Use `--no-open` only when automatic browser opening is undesirable. The
-`pairing_browser_required` event still provides the safe approval address.
+`pairing_browser_required` event provides the safe approval address when approval is needed.
 
 When no selected stable identifier is known, run `teamclaws servers list --json`,
 show each server's display name (`alias`), returned `description`, and readiness,
@@ -71,11 +71,13 @@ workspaces; use the onboarding skill's discovery rules.
 
 ## Wait for approval and continue automatically
 
-Before starting the command, explain that the next browser approval pairs this
-computer with the selected workspace. Name that workspace and explain that the
+Before starting the command, explain that pairing connects this computer with
+the selected workspace. TeamClawsDeploy authorizes automatic pairing for its
+owner or a superuser in the workspace's access group. Follow browser approval
+only if the CLI requests it. Name that workspace and explain that the
 connection gives this computer access to run commands and work with its files.
 Connect the step to the user's intended work, and say you'll keep waiting and
-continue automatically after approval. Use a short transition if onboarding
+continue automatically after pairing. Use a short transition if onboarding
 already introduced the process; the approval link should never arrive without
 an explanation of what the user is authorizing.
 
@@ -145,7 +147,7 @@ teamclaws pair status <stable-server-identifier-or-canonical-workspace-address>
 ```
 
 If it reports `not_paired`, follow the login and pairing flow above for that
-selected workspace; pairing requires the normal browser and owner approval. Do not use
+selected workspace; follow browser approval only if `pairing_browser_required` is emitted. Do not use
 another workspace's pairing or bypass approval. After `paired` is verified,
 authorized host commands can use the existing paired shell: