teamclaws 2.0.6 → 2.0.8

package/README.md

@@ -5,6 +5,9 @@ with a TeamClaws workspace and stores the resulting Clawgate credential on that
 computer. The command-line client and its agent skills ship together in this
 package.
 
+Pairing connects this computer to the workspace. It does not add a person as a
+workspace user; user membership is a separate privilege.
+
 ## Requirements
 
 - Node.js 22 or newer
@@ -14,6 +17,13 @@ package.
 
 ## Installation
 
+Check `node --version` first. If it is below 22, upgrade Node.js to version 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:
 
 ```text
@@ -230,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
@@ -297,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.6";
+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/machine-key.js

@@ -73,7 +73,9 @@ export class OsMachineKeyProvider {
             await assertPrivateDirectory(directory);
             return directory;
         }
-        catch {
+        catch (error) {
+            if (error instanceof TeamClawsError)
+                throw error;
             throw keyUnavailable();
         }
     }
@@ -158,7 +160,9 @@ export class OsMachineKeyProvider {
                 dsaEncoding: "ieee-p1363",
             }).toString("base64url");
         }
-        catch {
+        catch (error) {
+            if (error instanceof TeamClawsError)
+                throw error;
             throw keyUnavailable();
         }
     }
@@ -167,9 +171,11 @@ async function assertPrivateDirectory(path) {
     const info = await lstat(path);
     if (!info.isDirectory() ||
         info.isSymbolicLink() ||
-        info.uid !== process.getuid?.() ||
-        (info.mode & 0o777) !== 0o700)
+        info.uid !== process.getuid?.())
         throw keyUnavailable();
+    const mode = info.mode & 0o777;
+    if (mode !== 0o700)
+        throw new TeamClawsError("machine_key_unavailable", `The machine-key directory ${JSON.stringify(path)} has mode ${mode.toString(8).padStart(4, "0")}; mode 0700 is required. Run chmod 700 '${path.replaceAll("'", "'\\''")}' and retry.`, { exitCode: 9 });
 }
 async function assertPrivateFile(path) {
     const info = await lstat(path);

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/startup.js

@@ -1,6 +1,13 @@
 import { parseArguments, run } from "./app.js";
 import { checkRelease, releaseNotice } from "./update.js";
+import { TeamClawsError } from "./errors.js";
+import { Output } from "./output.js";
 export async function runCli(args, dependencies = {}, signal, check = checkRelease) {
+    if (Number(process.versions.node.split(".")[0]) < 22) {
+        const error = new TeamClawsError("unsupported_runtime", `TeamClaws requires Node.js 22 or newer; this runtime is ${process.versions.node}. Upgrade Node.js, then run npm install -g teamclaws@latest.`, { exitCode: 9 });
+        new Output(args.includes("--json"), dependencies.io?.stdout, dependencies.io?.stderr).error(error);
+        return error.exitCode;
+    }
     // No persistent cache: every executable invocation checks before dispatch.
     let releaseCheck;
     try {

package/dist/storage.js

@@ -118,6 +118,13 @@ export class CredentialStore {
             dirname(directory),
             directory,
         ]) {
+            const info = await lstat(path);
+            if (this.platform !== "win32" &&
+                info.isDirectory() &&
+                !info.isSymbolicLink() &&
+                info.uid === process.getuid?.() &&
+                (info.mode & 0o077) !== 0)
+                throw conversationStorageError(`Directory ${JSON.stringify(path)} has mode ${(info.mode & 0o777).toString(8).padStart(4, "0")}; mode 0700 is required. Run chmod 700 '${path.replaceAll("'", "'\\''")}' and retry. `);
             await this.assertPrivateDirectory(path);
         }
     }
@@ -150,7 +157,10 @@ export class CredentialStore {
             }
             return records.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
         }
-        catch {
+        catch (error) {
+            if (error instanceof TeamClawsError &&
+                error.code === "chat_reference_storage_failed")
+                throw error;
             throw conversationStorageError();
         }
     }
@@ -460,6 +470,6 @@ function parseConversationReference(value, credential) {
         updated_at: value.updated_at,
     };
 }
-function conversationStorageError() {
-    return new TeamClawsError("chat_reference_storage_failed", "The local conversation references could not be read or saved safely. Retain any returned session/request identifiers; do not resend the message automatically.", { exitCode: 9 });
+function conversationStorageError(detail = "") {
+    return new TeamClawsError("chat_reference_storage_failed", `${detail}The local conversation references could not be read or saved safely. Retain any returned session/request identifiers; do not resend the message automatically.`, { exitCode: 9 });
 }

package/dist/update.js

@@ -143,7 +143,9 @@ export async function npmRunner(nodeExecutable = process.execPath, platform = pr
             return async (args, timeout, signal) => {
                 const env = { ...process.env };
                 for (const key of Object.keys(env)) {
-                    if (/^npm_config_/i.test(key) ||
+                    if ((/^npm_config_/i.test(key) &&
+                        !(args[0] === "prefix" &&
+                            /^npm_config_(prefix|userconfig|globalconfig)$/i.test(key))) ||
                         /^(NODE_OPTIONS|NODE_PATH)$/i.test(key))
                         delete env[key];
                 }

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.6",
+  "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:

package/skills/teamclaws-login/SKILL.md

@@ -16,6 +16,9 @@ pairing approval come next when they are connecting a workspace. 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.
 
+Pairing connects this computer to the workspace. It does not add a person as a
+workspace user; user membership is a separate privilege.
+
 Use the official executable:
 
 ```text

package/skills/teamclaws-onboard/SKILL.md

@@ -37,6 +37,9 @@ or add another permission question for an already authorized step. Describe the
 separate server environment accurately; inspect an existing workspace before
 promising it is empty or that a particular isolation mechanism is configured.
 
+Pairing connects this computer to the workspace. It does not add a person as a
+workspace user; user membership is a separate privilege.
+
 ## Sign in
 
 Run `teamclaws auth status --json`. If signed in, confirm the returned account

package/skills/teamclaws-onboard/references/workspace-uses.md

@@ -122,6 +122,9 @@ and the selected access behavior before providing a working URL.
 
 ## Share work with other people
 
+Pairing connects this computer to the workspace. It does not add a person as a
+workspace user; user membership is a separate privilege.
+
 Distinguish inviting someone to a workspace from sharing a project's web
 address. Workspace collaboration depends on the supported TeamClaws sharing
 controls and the recipient's assigned access. A public app URL is available

package/skills/teamclaws-pair/SKILL.md

@@ -11,6 +11,9 @@ For the full install-and-connect conversation, follow
 Use the official `teamclaws` executable. Do not implement pairing inside this
 skill.
 
+Pairing connects this computer to the workspace. It does not add a person as a
+workspace user; user membership is a separate privilege.
+
 ## Required boundary
 
 - If workspace discovery was performed through a model context protocol client,

package/skills/teamclaws-project/SKILL.md

@@ -20,6 +20,9 @@ carry that task through instead of restarting a generic onboarding conversation.
 Inspect the destination's instructions, available runtimes, resources, network
 access, and account permissions through the paired shell before choosing a setup.
 
+Pairing connects this computer to the workspace. It does not add a person as a
+workspace user; user membership is a separate privilege.
+
 ## Jobs, services, and external systems
 
 For a complete job, place its code and authorized inputs in a dedicated directory,