teamclaws 2.0.4 → 2.0.7

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,12 @@ package.
 
 ## 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.
+
 Install the published CLI:
 
 ```text
@@ -172,6 +181,7 @@ npx teamclaws pair status <server-identifier-or-canonical-workspace-address>
 npx teamclaws pair
 npx teamclaws pair <server-identifier-or-canonical-workspace-address> [--no-open]
 npx teamclaws shell <target> --command <text> [--json]
+npx teamclaws users add <target> <email> --role <user|staff|superuser> [--json]
 npx teamclaws chat start <target> --message <text>
 npx teamclaws chat send <target> --session-id <uuid> --message <text>
 npx teamclaws chat watch <target> --session-id <uuid> --request-id <uuid>
@@ -213,6 +223,22 @@ Python helper. Use `--client-request-id <uuid>` to safely repeat an uncertain
 create request, and use the watch cursors printed in JSON events to resume
 monitoring without creating another turn.
 
+## Add a workspace user directly
+
+`teamclaws users add <target> <email> --role user --json` sends a direct request
+using the saved paired machine credential and its bound authorization. The role
+is required; supported roles are `user`, `staff`, and `superuser`. The server
+verifies current owner authority and the shared six-calendar-month machine
+authorization deadline. Initial CLI login and pairing remain the normal setup.
+
+This operation requires no agent, AI provider, chat, shell, skill, or browser
+session. Missing or inactive credentials return an error without opening a browser.
+The result's `requested_role` is the requested access, not a change to an existing
+member's role. `invited` means an invitation was sent; access starts after
+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.
+
 ## Read chat history without a browser
 
 ```text

package/dist/app.js

@@ -11,6 +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";
 export async function run(arguments_, dependencies = {}, signal) {
     let parsed;
     try {
@@ -70,6 +71,19 @@ export async function run(arguments_, dependencies = {}, signal) {
     }
     const store = dependencies.store ?? new CredentialStore();
     const targetAuthorization = new TargetAuthorization(store, dependencies.fetcher);
+    if (parsed.action === "users_add") {
+        try {
+            await targetAuthorization.requireGrant();
+            const result = await runUsersAdd(store, dependencies.fetcher ?? fetch, parsed.target, parsed.email, parsed.role, targetAuthorization, signal);
+            output.usersAddResult(result);
+            return 0;
+        }
+        catch (error) {
+            const safe = safeError(error);
+            output.error(safe);
+            return safe.exitCode;
+        }
+    }
     const auth = new AuthService({
         store,
         output,
@@ -217,6 +231,26 @@ export function parseArguments(arguments_) {
     }
     const json = arguments_.includes("--json");
     const args = arguments_.filter((argument) => argument !== "--json");
+    if (args[0] === "users" && args[1] === "add") {
+        const target = parsePairingTarget(requiredPositional(args, 2));
+        const email = requiredPositional(args, 3).trim().toLowerCase();
+        const options = parseNamedOptions(args.slice(4), {
+            values: ["--role"],
+            booleans: [],
+        });
+        const role = options.values["--role"];
+        if (!email ||
+            email.length > 254 ||
+            !["user", "staff", "superuser"].includes(role ?? ""))
+            throw usageError();
+        return {
+            action: "users_add",
+            json,
+            target,
+            email,
+            role: role,
+        };
+    }
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h")
         return { action: "help", json };
     if (args[0] === "--version" || args[0] === "-v")
@@ -498,5 +532,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 [--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 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.4";
+export const PACKAGE_VERSION = "2.0.7";
 export const CLIENT_NAME = "teamclaws-cli";
 export const CONTRACT_VERSION = 1;
 export const OUTPUT_SCHEMA_VERSION = 1;

package/dist/external-chat.js

@@ -63,7 +63,7 @@ export class ExternalChatClient {
             const remainingAttempt = deadline - this.now();
             if (remainingAttempt < 1)
                 break;
-            const timeoutMs = Math.max(1, Math.floor(Math.min(15_000, remainingAttempt)));
+            const timeoutMs = Math.max(1, Math.floor(Math.min(60_000, remainingAttempt)));
             const timeout = AbortSignal.timeout(timeoutMs);
             const attemptSignal = signal
                 ? AbortSignal.any([timeout, signal])
@@ -297,7 +297,7 @@ export class ExternalChatClient {
                 capabilities: parseCapabilities(result.external_chat_capabilities, true),
             };
         }
-        const capabilityResponse = await this.request(new URL(handoff.capabilities_url, `${credential.origin}/`).toString(), credential, {}, [200], signal);
+        const capabilityResponse = await this.request(new URL(handoff.capabilities_url, `${credential.origin}/`).toString(), credential, { timeoutMs: 60_000 }, [200], signal);
         return {
             credential,
             capabilities: parseCapabilities(capabilityResponse.body),
@@ -375,6 +375,7 @@ export class ExternalChatClient {
         for (let attempt = 0; attempt < 3; attempt += 1) {
             try {
                 const response = await requestTargetJson(this.fetcher, this.authorization, url, credential, {
+                    ...(options.method === "POST" ? { timeoutMs: 60_000 } : {}),
                     ...options,
                     headers: {
                         ...options.headers,

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

@@ -389,6 +389,22 @@ export class Output {
         else
             this.stderr.write(`Error: ${error.message}\n`);
     }
+    usersAddResult(result) {
+        this.event({
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            event: "users_add_result",
+            ...result,
+        });
+        if (!this.json) {
+            const messages = {
+                invited: `Invitation sent for ${result.requested_role} access. Access begins after acceptance.`,
+                already_pending: "An invitation is already pending; it was not resent.",
+                already_member: "Already a member; access unchanged.",
+                already_owner: "Already the owner; access unchanged.",
+            };
+            this.stdout.write(`${messages[result.code]}\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

@@ -0,0 +1,78 @@
+import { TeamClawsError } from "./errors.js";
+import { requestTargetJson, } from "./target-authorization.js";
+import { isObject } from "./validation.js";
+const failureMessages = {
+    invalid_actor_token: "The machine authorization is invalid, expired, paused, or revoked.",
+    unauthorized: "The workspace rejected the paired machine credential.",
+    target_proof_expired: "The request proof expired before user addition.",
+    forbidden: "The paired identity is not authorized to add users.",
+    owner_required: "Only the current machine owner can add users.",
+    actor_machine_mismatch: "The authorization does not match this machine or its paired identity.",
+    actor_authorization_unavailable: "Machine authorization could not be verified. Try again later.",
+    authorization_unavailable: "Machine authorization could not be verified. Try again later.",
+    machine_auth_failed: "The workspace's machine authentication was rejected.",
+    machine_ip_rejected: "The workspace's machine address was rejected.",
+    mfa_required: "The owner must meet the existing MFA policy before adding users.",
+    invalid_email: "Enter a valid email address.",
+    invalid_role: "Choose user, staff, or superuser access.",
+    invalid_request: "The workspace rejected the add-user request.",
+    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 runUsersAdd(store, fetcher, target, email, role, 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 });
+    let response;
+    try {
+        response = await requestTargetJson(fetcher, authorization, `${credential.origin}/teamclaws-admin/api/device-users/v1/add/`, credential, {
+            method: "POST",
+            body: { email, role },
+            timeoutMs: 60_000,
+            ...(signal ? { signal } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof TeamClawsError &&
+            ["network_error", "network_timeout"].includes(error.code))
+            throw new TeamClawsError("outcome_unverified", failureMessages.outcome_unverified);
+        throw error;
+    }
+    const body = response.body;
+    if (response.status < 200 ||
+        response.status >= 300 ||
+        (isObject(body) && body.ok === false)) {
+        const rawCode = isObject(body)
+            ? (body.code ?? (isObject(body.error) ? body.error.code : body.error))
+            : undefined;
+        const code = typeof rawCode === "string" && Object.hasOwn(failureMessages, rawCode)
+            ? rawCode
+            : response.status === 404 || response.status === 405
+                ? "users_add_unavailable"
+                : "outcome_unverified";
+        throw new TeamClawsError(code, failureMessages[code] ??
+            (code === "users_add_unavailable"
+                ? "Direct user addition is unavailable on this workspace."
+                : "The workspace could not verify the add-user result."), {
+            exitCode: response.status === 401 ? 3 : response.status === 429 ? 5 : 1,
+        });
+    }
+    if (!isObject(body) ||
+        body.ok !== true ||
+        body.action !== "add" ||
+        body.scope !== "access_group" ||
+        body.email !== email ||
+        body.requested_role !== role ||
+        !((response.status === 201 && body.code === "invited") ||
+            (response.status === 200 &&
+                ["already_pending", "already_member", "already_owner"].includes(String(body.code)))))
+        throw new TeamClawsError("invalid_response", "The workspace returned an invalid add-user result. Check the invitation status before retrying.", { exitCode: 9 });
+    return {
+        ok: true,
+        code: body.code,
+        action: "add",
+        scope: "access_group",
+        email,
+        requested_role: role,
+    };
+}

package/package.json

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

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,