teamclaws 2.0.7 → 2.0.8

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:
 
@@ -239,6 +240,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
@@ -306,6 +320,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.8";
 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/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.8",
   "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: