teamclaws 2.0.1 → 2.0.3

package/README.md

@@ -213,6 +213,30 @@ 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.
 
+## Read chat history without a browser
+
+```text
+teamclaws chat history <target> --json
+teamclaws chat messages <target> --chat-id <chat-public-uuid> --json
+teamclaws chat messages <target> --chat-id <chat-public-uuid> --after-message-id <last-read-id> --json
+```
+
+The first command lists chats from the workspace; the messages command reads
+their content and later follow-ups. Both commands automatically read every page.
+Use `chat_id` from the list or `chat_public_id` from a conversation URL. Save
+`latest_message_id` to read only later messages next time.
+
+This access is standard for new and existing pairings. The workspace owner's
+agents can read every user's chats on the workspace. Other users' agents,
+including superusers' agents, can read every chat belonging to their own user.
+Archived, deleted, empty, and browser-created chats are included. There is no
+optional history grant or model requirement. These commands do not create chats,
+send messages, or mark conversations viewed. Clawgate must include the history
+endpoints; older servers return an error rather than an empty history.
+
+`chat list` only lists local request references. `chat watch` only reads responses
+to a specific request, so neither command checks for later conversation turns.
+
 ## Host shell commands
 
 For authorized workspace administration, first check pairing status with

package/dist/app.js

@@ -146,6 +146,10 @@ export async function run(arguments_, dependencies = {}, signal) {
             }
             case "chat_list":
                 return await externalChat.list(parsePairingTarget(parsed.target), signal);
+            case "chat_history":
+                return await externalChat.history(parsePairingTarget(parsed.target), signal);
+            case "chat_messages":
+                return await externalChat.messages(parsePairingTarget(parsed.target), parsed.chatId, parsed.afterId, signal);
             case "chat_capabilities":
                 return await externalChat.capabilities(parsePairingTarget(parsed.target), signal);
             case "chat_start":
@@ -257,6 +261,29 @@ export function parseArguments(arguments_) {
     if (args[0] === "chat" && args[1] === "list" && args.length === 3) {
         return { action: "chat_list", json, target: requiredPositional(args, 2) };
     }
+    if (args[0] === "chat" && args[1] === "history" && args.length === 3) {
+        return {
+            action: "chat_history",
+            json,
+            target: requiredPositional(args, 2),
+        };
+    }
+    if (args[0] === "chat" && args[1] === "messages") {
+        const target = requiredPositional(args, 2);
+        const options = parseNamedOptions(args.slice(3), {
+            values: ["--chat-id", "--after-message-id"],
+            booleans: [],
+        });
+        if (!options.values["--chat-id"])
+            throw usageError();
+        return {
+            action: "chat_messages",
+            json,
+            target,
+            chatId: normalizeUuid(options.values["--chat-id"]),
+            afterId: nonNegativeInteger(options.values["--after-message-id"]),
+        };
+    }
     if (args[0] === "chat" && args[1] === "capabilities" && args.length === 3) {
         return { action: "chat_capabilities", json, target: args[2] };
     }
@@ -471,5 +498,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 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 [--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.1";
+export const PACKAGE_VERSION = "2.0.3";
 export const CLIENT_NAME = "teamclaws-cli";
 export const CONTRACT_VERSION = 1;
 export const OUTPUT_SCHEMA_VERSION = 1;

package/dist/external-chat.js

@@ -172,6 +172,84 @@ export class ExternalChatClient {
         const requestId = validUuid(options.requestId);
         return this.poll(context, { requestId, sessionId }, options.knownRevision, options.responseCursor, signal);
     }
+    async historyCredential(target, signal) {
+        const credential = await this.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 this.request(`${credential.origin}/teamclaws-admin/api/device-pairings/me/`, credential, {}, [200], signal);
+        parseVerifiedDevice(response.body, credential.device_id);
+        return credential;
+    }
+    async history(target, signal) {
+        const credential = await this.historyCredential(target, signal);
+        let afterId = 0;
+        while (true) {
+            const response = await this.request(`${credential.origin}/teamclaws-admin/api/device-chat/v1/chats/?after_id=${afterId}`, credential, {}, [200], signal);
+            const body = response.body;
+            if (!isObject(body) || !Array.isArray(body.chats))
+                throw invalidChatResponse();
+            const chats = body.chats.map((chat) => {
+                if (!isObject(chat))
+                    throw invalidChatResponse();
+                const url = requireHttpsUrl(chat.owner_conversation_url, "conversation address");
+                if (url.origin !== credential.origin)
+                    throw invalidChatResponse();
+                return {
+                    chat_id: validUuid(chat.chat_id),
+                    name: historyText(chat.name),
+                    surface: historyText(chat.surface),
+                    created_at: historyText(chat.created_at),
+                    updated_at: historyText(chat.updated_at),
+                    archived_at: chat.archived_at === null ? null : historyText(chat.archived_at),
+                    deleted_at: chat.deleted_at === null ? null : historyText(chat.deleted_at),
+                    owner_conversation_url: url.toString(),
+                };
+            });
+            const next = body.next_after_id === null
+                ? null
+                : requireInteger(body.next_after_id, "history cursor", afterId + 1, Number.MAX_SAFE_INTEGER);
+            if (next !== null && chats.length === 0)
+                throw invalidChatResponse();
+            this.output.chatHistory(chats, next);
+            if (next === null)
+                return 0;
+            afterId = next;
+        }
+    }
+    async messages(target, chatId, afterId, signal) {
+        chatId = validUuid(chatId);
+        const credential = await this.historyCredential(target, signal);
+        while (true) {
+            const response = await this.request(`${credential.origin}/teamclaws-admin/api/device-chat/v1/chats/${chatId}/messages/?after_id=${afterId}`, credential, {}, [200], signal);
+            const body = response.body;
+            if (!isObject(body) ||
+                body.chat_id !== chatId ||
+                !Array.isArray(body.messages) ||
+                typeof body.has_more !== "boolean")
+                throw invalidChatResponse();
+            let previousId = afterId;
+            const messages = body.messages.map((message) => {
+                if (!isObject(message))
+                    throw invalidChatResponse();
+                const id = requireInteger(message.id, "message identifier", previousId + 1, Number.MAX_SAFE_INTEGER);
+                previousId = id;
+                return {
+                    id,
+                    role: historyText(message.role),
+                    body_text: historyText(message.body_text),
+                    status: historyText(message.status),
+                    created_at: historyText(message.created_at),
+                };
+            });
+            const latest = requireInteger(body.latest_message_id, "message cursor", afterId, Number.MAX_SAFE_INTEGER);
+            if (latest !== previousId || (body.has_more && messages.length === 0))
+                throw invalidChatResponse();
+            this.output.chatMessages(chatId, messages, latest, body.has_more);
+            if (!body.has_more)
+                return 0;
+            afterId = latest;
+        }
+    }
     async list(target, signal) {
         const credential = await this.store.findWorkspace(target);
         if (!credential)
@@ -568,6 +646,11 @@ function requireOwnerUrl(value, origin) {
 function validUuid(value) {
     return normalizeUuid(value, "identifier");
 }
+function historyText(value) {
+    if (typeof value !== "string")
+        throw invalidChatResponse();
+    return value;
+}
 function invalidChatResponse() {
     return new TeamClawsError("invalid_external_chat_response", "The workspace returned an invalid external chat response.", { exitCode: 9 });
 }

package/dist/output.js

@@ -233,6 +233,34 @@ export class Output {
             ? `Snapshot generated: ${generatedAt}.\n`
             : "Generation time is not supplied by the capabilities endpoint.\n");
     }
+    chatHistory(chats, nextAfterId) {
+        this.event({
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            event: "chat_history",
+            status: "success",
+            source: "workspace",
+            chats,
+            next_after_id: nextAfterId,
+        });
+        if (!this.json)
+            for (const chat of chats)
+                this.stdout.write(`${chat.chat_id} — ${chat.name} — ${chat.owner_conversation_url}\n`);
+    }
+    chatMessages(chatId, messages, latestMessageId, hasMore) {
+        this.event({
+            schema_version: OUTPUT_SCHEMA_VERSION,
+            event: "chat_messages",
+            status: "success",
+            source: "workspace",
+            chat_id: chatId,
+            messages,
+            latest_message_id: latestMessageId,
+            has_more: hasMore,
+        });
+        if (!this.json)
+            for (const message of messages)
+                this.stdout.write(`${message.id} ${message.role}: ${message.body_text}\n`);
+    }
     chatSessionsList(workspace, records) {
         const sessions = records.map((record) => ({
             session_id: record.session_id,

package/dist/pairing.js

@@ -153,6 +153,7 @@ export class PairingClient {
             const response = await requestJson(this.fetcher, pollUrl, {
                 method: "POST",
                 body: { device_code: pending.device_code },
+                timeoutMs: Math.max(1, deadline - this.now()),
                 ...(signal ? { signal } : {}),
             });
             if (response.status >= 200 && response.status < 300) {

package/package.json

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

package/skills/teamclaws-chat/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: teamclaws-chat
-description: Start, continue, or resume one external-agent TCChat through the official TeamClaws CLI after this computer is paired with the exact workspace.
+description: Read workspace chat history or start, continue, and resume an external-agent TCChat through the official TeamClaws CLI after this computer is paired with the exact workspace.
 ---
 
 # TeamClaws external chat
@@ -20,6 +20,37 @@ transport, idempotency, and durable request polling.
 - Treat the newline-delimited JSON as an allowlisted protocol. Never expose raw
   HTTP responses or provider-native identifiers.
 
+## Read chats and follow-up messages without a browser
+
+For conversation history, new messages, or follow-ups, use these read-only commands:
+
+```text
+teamclaws chat history <target> --json
+teamclaws chat messages <target> --chat-id <chat-public-uuid> --json
+teamclaws chat messages <target> --chat-id <chat-public-uuid> --after-message-id <last-read-id> --json
+```
+
+`chat history` queries the workspace and emits `chat_history` pages containing
+`chats`, including browser-created, archived, empty, and deleted chats. Use the
+returned `chat_id`, or the `chat_public_id` in the user's conversation URL, with
+`chat messages`. It emits `chat_messages` pages containing every returned role
+and message body, including owner follow-ups and subsequent agent replies.
+Both commands fetch every page automatically. Save the final
+`latest_message_id` to check for later messages. A successful empty messages
+result means no messages after that cursor in that chat at the time of the read.
+
+History access is standard for existing and new valid pairings. There is no
+optional history permission, browser approval, model selection, or new pairing
+step. The workspace owner's paired agents can read every user's chats on that
+workspace. Other paired agents, including superusers' agents, can read every
+chat belonging to their own user. The workspace enforces this distinction.
+
+`chat list` is a local request-reference index, not a workspace chat inventory.
+`chat watch` reads replies to one request, not later conversation turns. Do not
+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.
+
 ## Start one conversation
 
 Obtain a non-empty user message, then run: