grok-bot-sdk 0.1.0 → 0.75.8

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.75.8
+
+Protocol surface matched to the Grok Bot 0.75.8 desktop client. The package stays ESM, with no runtime dependencies.
+
+- Default `x-cursor-client-version` is `0.75.8`.
+- Login polling stops on HTTP 403 `{ "error": "sign_in_policy_violation" }` and throws `SIGN_IN_POLICY_VIOLATION`.
+- Roster reads optional `role` and `addedTeamAgentsOnly`, and returns Slack and Teams connection records plus the additional `GrokBotAgent` scalars present in 0.75.8.
+- `sendMessage` accepts `replyToId`, `replyQuote`, `taskId`, `language`, `richText`, and `machineId`. Delivery `4` (`REFUSED`) throws `SEND_REFUSED`.
+- New read methods: `listSessions`, `listTranscript`, `listAgentStatuses`, `getSendStatus`, `listAgentTasks`, `listTasks`, `listSubagents`, `listAgentTodos`, `listAgentSkills`, `listDeletedAgentIds`, `getRuntimeCapabilities`, `getSandBoxRunState`.
+- Watch events add `agent.state`, `computer.actions`, `box.state`, and `page.title.changed`. `bot.state.changed` includes `changedAtMs`.
+- CLI read-only subcommands: `bots`, `sessions`, `transcript`, `tasks`, `capabilities`, `box`.
+- Avatar derivation is unchanged (`grok-bot-0.70.2`). `pumpkin` is accepted as an explicit shape.
+
+The checksum, ghost-mode default, and desktop chat enums `source=1`, `initiator=1`, `sendSource=1` are the same values the 0.75.8 client still sends for desktop chat.
+
+## 0.1.0
+
+First release, matched to the Grok Bot 0.70.2 desktop client. From 0.75.8 on, the package version follows the Grok Bot version it targets.

package/README.md

@@ -8,7 +8,7 @@
 <h1 align="center">grok-bot-sdk</h1>
 
 <p align="center"><strong>Unofficial Node.js SDK for the Grok Bot desktop client protocol</strong></p>
-<p align="center"><em>Browser login · Account and bot roster · Normalized avatars · Send · Connect replies forwarded as SSE</em></p>
+<p align="center"><em>Browser login · Account and bot roster · Sessions, transcript, and tasks · Normalized avatars · Send · Connect replies forwarded as SSE</em></p>
 <p align="center"><a href="https://ronglecat.github.io/grok-bot-sdk/">https://ronglecat.github.io/grok-bot-sdk/</a></p>
 
 <p align="center">
@@ -21,7 +21,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
   <a href="https://github.com/RongleCat/grok-bot-sdk/stargazers"><img src="https://img.shields.io/github/stars/RongleCat/grok-bot-sdk?style=social" alt="GitHub stars" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D22.13-339933?logo=node.js&logoColor=white" alt="Node.js" />
-  <img src="https://img.shields.io/badge/client-Grok%20Bot%200.70.2-lightgrey" alt="Grok Bot 0.70.2" />
+  <img src="https://img.shields.io/badge/client-Grok%20Bot%200.75.8-lightgrey" alt="Grok Bot 0.75.8" />
   <img src="https://img.shields.io/badge/note-unofficial-yellow" alt="Unofficial" />
 </p>
 
@@ -42,7 +42,7 @@
 ---
 
 > [!NOTE]
-> **About this SDK.** grok-bot-sdk reproduces the browser login and the read, send, and reply-stream calls used by the Grok Bot **0.70.2** desktop client. It is an independent open-source library by [铁柱AGI](https://x.com/cgnot996). It is **not an xAI product, not a Cursor product, and not the official Grok Bot SDK**.
+> **About this SDK.** grok-bot-sdk reproduces the browser login and the read, send, and reply-stream calls used by the Grok Bot **0.75.8** desktop client. It is an independent open-source library by [铁柱AGI](https://x.com/cgnot996). It is **not an xAI product, not a Cursor product, and not the official Grok Bot SDK**.
 >
 > The same author also builds [Grok App](https://github.com/RongleCat/grok-app), a desktop workbench for the local Grok Build CLI. Grok App and this SDK are different programs.
 
@@ -155,15 +155,17 @@ return client.botEventsSSE({
 
 ## What this release includes
 
-Verified against Grok Bot 0.70.2 on 14 October 2026:
+Verified against Grok Bot 0.75.8:
 
 - One browser login continued into account read and the cloud bot roster.
 - The same read path works with the Mac client's existing session.
-- Roster records come back with one avatar shape, whether the server sent the fields or the SDK derived them.
+- Roster records come back with one avatar shape, whether the server sent the fields or the SDK derived them. The avatar hash is still `grok-bot-0.70.2`. `pumpkin` is explicit only.
 - `WatchGrokBotTranscripts` connects with Connect JSON, and an existing reply was forwarded through `botEventsSSE`.
-- Offline tests cover login URL shape, avatar vectors, frame parsing, cursors, cancellation, SSE framing, and send results.
+- Read calls: `listSessions`, `listTranscript`, `listAgentStatuses`, `getSendStatus`, `listAgentTasks`, `listTasks`, `listSubagents`, `listAgentTodos`, `listAgentSkills`, `listDeletedAgentIds`, `getRuntimeCapabilities`, and `getSandBoxRunState`.
+- Watch events also include `agent.state`, `computer.actions`, `box.state`, and `page.title.changed`.
+- Offline tests cover login URL shape, avatar vectors, frame parsing, cursors, cancellation, SSE framing, send results, and the new read records.
 
-The default client version string is `0.70.2`. Pass `version` when you know the client you are matching.
+The default client version string is `0.75.8`. Pass `version` when you know the client you are matching. The CLI also has read-only subcommands: `bots`, `sessions`, `transcript`, `tasks`, `capabilities`, and `box`.
 
 ## Notes you should read
 

package/README_ZH.md

@@ -8,7 +8,7 @@
 <h1 align="center">grok-bot-sdk</h1>
 
 <p align="center"><strong>Grok Bot 桌面客户端协议的非官方 Node.js SDK</strong></p>
-<p align="center"><em>浏览器登录 · 账号与 Bot 名单 · 统一头像 · 发送 · Connect 回复转发为 SSE</em></p>
+<p align="center"><em>浏览器登录 · 账号与 Bot 名单 · 会话、转录与任务 · 统一头像 · 发送 · Connect 回复转发为 SSE</em></p>
 <p align="center"><a href="https://ronglecat.github.io/grok-bot-sdk/zh/">https://ronglecat.github.io/grok-bot-sdk/zh/</a></p>
 
 <p align="center">
@@ -21,7 +21,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
   <a href="https://github.com/RongleCat/grok-bot-sdk/stargazers"><img src="https://img.shields.io/github/stars/RongleCat/grok-bot-sdk?style=social" alt="GitHub stars" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D22.13-339933?logo=node.js&logoColor=white" alt="Node.js" />
-  <img src="https://img.shields.io/badge/client-Grok%20Bot%200.70.2-lightgrey" alt="Grok Bot 0.70.2" />
+  <img src="https://img.shields.io/badge/client-Grok%20Bot%200.75.8-lightgrey" alt="Grok Bot 0.75.8" />
   <img src="https://img.shields.io/badge/note-unofficial-yellow" alt="非官方" />
 </p>
 
@@ -42,7 +42,7 @@
 ---
 
 > [!NOTE]
-> **关于这个 SDK。** grok-bot-sdk 复现 Grok Bot **0.70.2** 桌面客户端使用的浏览器登录，以及读取账号、读取名单、发送消息和订阅回复。作者是 [铁柱AGI](https://x.com/cgnot996)。它**不是 xAI 官方产品，不是 Cursor 官方产品，也不是 Grok Bot 官方 SDK**。
+> **关于这个 SDK。** grok-bot-sdk 复现 Grok Bot **0.75.8** 桌面客户端使用的浏览器登录，以及读取账号、读取名单、发送消息和订阅回复。作者是 [铁柱AGI](https://x.com/cgnot996)。它**不是 xAI 官方产品，不是 Cursor 官方产品，也不是 Grok Bot 官方 SDK**。
 >
 > 同一作者的 [Grok App](https://github.com/RongleCat/grok-app) 是本机 Grok Build CLI 的桌面工作台。Grok App 和这个 SDK 是两个程序。
 
@@ -155,15 +155,17 @@ return client.botEventsSSE({
 
 ## 这一版包含什么
 
-2026-10-14 对照 Grok Bot 0.70.2 核对过：
+对照 Grok Bot 0.75.8 核对过：
 
 - 一次浏览器登录可以接着读账号和云端 Bot 名单。
 - 用 Mac 客户端里已有的会话，可以走同一条读取路径。
-- 名单里的每条记录都带回同一种头像结构。服务端带了字段就用字段，缺了就按 UUID 推算。
+- 名单里的每条记录都带回同一种头像结构。服务端带了字段就用字段，缺了就按 UUID 推算。头像哈希仍是 `grok-bot-0.70.2`。`pumpkin` 只在显式指定时出现。
 - `WatchGrokBotTranscripts` 以 Connect JSON 接通，既有回复可以经 `botEventsSSE` 转发。
-- 离线测试覆盖登录 URL、头像向量、帧解析、游标、取消、SSE 帧和发送结果。
+- 只读调用：`listSessions`、`listTranscript`、`listAgentStatuses`、`getSendStatus`、`listAgentTasks`、`listTasks`、`listSubagents`、`listAgentTodos`、`listAgentSkills`、`listDeletedAgentIds`、`getRuntimeCapabilities`、`getSandBoxRunState`。
+- 订阅事件还包含 `agent.state`、`computer.actions`、`box.state` 和 `page.title.changed`。
+- 离线测试覆盖登录 URL、头像向量、帧解析、游标、取消、SSE 帧、发送结果，以及新增的只读记录。
 
-默认客户端版本字符串是 `0.70.2`。你知道自己要匹配的客户端版本时，传入 `version`。
+默认客户端版本字符串是 `0.75.8`。你知道自己要匹配的客户端版本时，传入 `version`。CLI 还有只读子命令：`bots`、`sessions`、`transcript`、`tasks`、`capabilities`、`box`。
 
 ## 使用前要知道的事
 

package/avatar.mjs

@@ -1,8 +1,11 @@
-// Parameter derivation verified against Grok Bot 0.70.2 static client code.
-// This module does not load or execute the official renderer or its assets.
+// Parameter derivation verified against Grok Bot 0.70.2 and again against 0.75.8.
+// 0.75.8 keeps the same hash, salts, default shapes, and palette. It adds one
+// explicit shape, pumpkin, behind the sand_pumpkin_2026 picker gate. Pumpkin is
+// not part of the default hash set. This module does not load or execute the
+// official renderer or its assets.
 export const AVATAR_ALGORITHM_VERSION='grok-bot-0.70.2';
 export const DEFAULT_SHAPES=Object.freeze(['blob','pebble','squircle','tablet','wedge','hex','cloud','teardrop']);
-export const VALID_SHAPES=Object.freeze(['blob','pebble','bean','egg','squircle','tablet','capsule','cylinder','hex','gem','crystal','wedge','shield','dome','arch','cloud','teardrop','leaf','square','sparkle','clover','flower','heart','house','star']);
+export const VALID_SHAPES=Object.freeze(['blob','pebble','bean','egg','squircle','tablet','capsule','cylinder','hex','gem','crystal','wedge','shield','dome','arch','cloud','teardrop','leaf','square','sparkle','clover','flower','heart','house','star','pumpkin']);
 export const DEFAULT_COLORS=Object.freeze(['brown','red','orange','yellow','green','cyan','blue','violet','magenta','gray']);
 const PALETTE=Object.freeze(Object.fromEntries([
   ['black','#000000','#000000','#FFFFFF'],

package/bin/grok-bot-sdk.mjs

@@ -19,10 +19,17 @@ const failed = code => {
 function usage() {
   console.log(`grok-bot-sdk login [--no-open] --out <file>
 grok-bot-sdk whoami [--token-file <file>]
+grok-bot-sdk bots [--token-file <file>]
+grok-bot-sdk sessions --bot <id> [--token-file <file>]
+grok-bot-sdk transcript --bot <id> [--session <id>] [--limit <n>] [--token-file <file>]
+grok-bot-sdk tasks --bot <id> [--session <id>] [--token-file <file>]
+grok-bot-sdk capabilities [--token-file <file>]
+grok-bot-sdk box [--token-file <file>]
 
 login opens the browser, waits for approval, and writes the session to <file> (mode 0600).
 The command prints the login page URL and a redacted summary. It does not print tokens.
-whoami reads GROK_BOT_ACCESS_TOKEN, or the accessToken field inside --token-file, and prints only whether account fields exist.`);
+whoami reads GROK_BOT_ACCESS_TOKEN, or the accessToken field inside --token-file, and prints only whether account fields exist.
+The other commands are read-only. They print roster, session, transcript, task, capability, or box fields for the saved token.`);
   process.exitCode = 2;
 }
 
@@ -73,13 +80,17 @@ async function loadToken() {
   return { accessToken, version: process.env.GROK_BOT_CLIENT_VERSION };
 }
 
-async function whoami() {
+async function clientFromToken() {
   const loaded = await loadToken();
-  const client = new GrokBotClient({
+  return new GrokBotClient({
     accessToken: loaded.accessToken,
     ...loaded.version ? { version: loaded.version } : {},
     ...loaded.teamId !== undefined ? { teamId: loaded.teamId } : {},
   });
+}
+
+async function whoami() {
+  const client = await clientFromToken();
   const me = await client.getMe();
   console.log(JSON.stringify({
     status: 'ok',
@@ -89,9 +100,105 @@ async function whoami() {
   }));
 }
 
+function requireBot() {
+  const bot = option('--bot');
+  if (!bot || bot.startsWith('-')) {
+    usage();
+    return undefined;
+  }
+  return bot;
+}
+
+async function bots() {
+  const roster = await (await clientFromToken()).listBots();
+  console.log(JSON.stringify({
+    status: 'ok',
+    count: roster.bots.length,
+    truncated: roster.truncated,
+    slackConnectionCount: roster.slackConnections.length,
+    teamsConnectionCount: roster.teamsConnections.length,
+    bots: roster.bots.map(bot => ({
+      id: bot.id,
+      name: bot.name,
+      kind: bot.kind,
+      role: bot.role,
+      sessionId: bot.sessionId,
+    })),
+  }));
+}
+
+async function sessions() {
+  const bot = requireBot();
+  if (!bot) return;
+  const result = await (await clientFromToken()).listSessions(bot);
+  console.log(JSON.stringify({ status: 'ok', count: result.sessions.length, sessions: result.sessions }));
+}
+
+async function transcript() {
+  const bot = requireBot();
+  if (!bot) return;
+  const limitText = option('--limit');
+  const limit = limitText === undefined ? 20 : Number(limitText);
+  const result = await (await clientFromToken()).listTranscript({
+    botId: bot,
+    sessionId: option('--session') ?? '',
+    limit,
+  });
+  console.log(JSON.stringify({
+    status: 'ok',
+    generation: result.generation,
+    count: result.entries.length,
+    cloudAgentPeerIdsKnown: result.cloudAgentPeerIdsKnown,
+    peerCount: result.cloudAgentPeerIds.length,
+    unreadAnchor: result.unreadAnchor,
+    entries: result.entries.map(entry => ({
+      seq: entry.seq,
+      updatedSeq: entry.updatedSeq,
+      entryId: entry.entryId,
+      entryKind: entry.entryKind,
+      bodyOmitted: entry.bodyOmitted,
+      bodyKind: typeof entry.body?.kind === 'string' ? entry.body.kind : null,
+    })),
+  }));
+}
+
+async function tasks() {
+  const bot = requireBot();
+  if (!bot) return;
+  const client = await clientFromToken();
+  const sessionId = option('--session') ?? '';
+  const [agentTasks, taskList] = await Promise.all([
+    client.listAgentTasks({ botId: bot }),
+    client.listTasks({ botId: bot, sessionId }),
+  ]);
+  console.log(JSON.stringify({
+    status: 'ok',
+    agentTaskCount: agentTasks.tasks.length,
+    taskCount: taskList.tasks.length,
+    agentTasks: agentTasks.tasks,
+    tasks: taskList.tasks,
+  }));
+}
+
+async function capabilities() {
+  const result = await (await clientFromToken()).getRuntimeCapabilities();
+  console.log(JSON.stringify({ status: 'ok', ...result }));
+}
+
+async function box() {
+  const result = await (await clientFromToken()).getSandBoxRunState();
+  console.log(JSON.stringify({ status: 'ok', ...result }));
+}
+
 try {
   if (command === 'login') await login();
   else if (command === 'whoami') await whoami();
+  else if (command === 'bots') await bots();
+  else if (command === 'sessions') await sessions();
+  else if (command === 'transcript') await transcript();
+  else if (command === 'tasks') await tasks();
+  else if (command === 'capabilities') await capabilities();
+  else if (command === 'box') await box();
   else usage();
 } catch (error) {
   const code = error instanceof Error && /^[A-Z_]{1,80}$/.test(error.message) ? error.message : 'COMMAND_FAILED';

package/core.mjs

@@ -73,7 +73,8 @@ export async function requestJSON(url,{method='POST',headers={},body,fetchImpl=f
     if(Buffer.byteLength(text)>8*1024*1024) return {ok:false,httpStatus:response.status,code:'RESPONSE_TOO_LARGE'};
     let data;
     try {data=JSON.parse(text);} catch {return {ok:false,httpStatus:response.status,code:'NON_JSON_RESPONSE'};}
-    if(!response.ok) return {ok:false,httpStatus:response.status,code:typeof data?.code==='string' && /^[a-z_]{1,48}$/.test(data.code)?data.code:'HTTP_ERROR'};
+    const rawCode=typeof data?.code==='string'?data.code:typeof data?.error==='string'?data.error:'';
+    if(!response.ok) return {ok:false,httpStatus:response.status,code:/^[a-z_]{1,48}$/.test(rawCode)?rawCode:'HTTP_ERROR'};
     return {ok:true,httpStatus:response.status,data};
   } catch {return {ok:false,code:'NETWORK_OR_TLS_ERROR'};}
 }
@@ -125,6 +126,7 @@ export async function pollLogin(flow,{fetchImpl=fetch,sleep=delay,maxAttempts=15
   for(let attempt=0;attempt<maxAttempts;attempt++){
     const result=await requestJSON(url,{method:'GET',headers:{'content-type':'application/json'},fetchImpl});
     if(result.ok && typeof result.data.accessToken==='string' && typeof result.data.refreshToken==='string')return result.data;
+    if(result.httpStatus===403 && result.code==='sign_in_policy_violation')throw fixedError('SIGN_IN_POLICY_VIOLATION');
     if(result.httpStatus===404){errors=0;onPending(attempt+1);}
     else if(++errors>=3)throw fixedError('LOGIN_POLL_FAILED');
     await sleep(Math.min(1000*1.2**attempt,10000));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "grok-bot-sdk",
-  "version": "0.1.0",
-  "description": "Unofficial Node.js SDK for the Grok Bot 0.70.2 desktop client protocol: login, roster, avatars, send, and Connect-to-SSE replies.",
+  "version": "0.75.8",
+  "description": "Unofficial Node.js SDK for the Grok Bot 0.75.8 desktop client protocol: login, roster, sessions, transcript, tasks, send, and Connect-to-SSE replies.",
   "license": "MIT",
   "type": "module",
   "author": "RongleCat (铁柱AGI)",
@@ -22,7 +22,7 @@
     "node": ">=22.13"
   },
   "bin": {
-    "grok-bot-sdk": "bin/grok-bot-sdk.mjs"
+    "grok-bot-sdk": "./bin/grok-bot-sdk.mjs"
   },
   "exports": {
     ".": {
@@ -45,6 +45,7 @@
     "bin",
     "README.md",
     "README_ZH.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/sdk.d.mts

@@ -12,6 +12,7 @@ export interface ClientOptions {
 export interface Bot {
   id: string;
   serverId: string | null;
+  legacyAgentId: string;
   name: string;
   description: string;
   title: string;
@@ -19,11 +20,188 @@ export interface Bot {
   avatarColor: string;
   avatar: ResolvedAvatar;
   harness: string;
+  role: string;
   kind: string;
+  visibility: string;
   sessionId: string;
   teamId: number | null;
   viewerIsOwner: boolean;
   viewerCanManage: boolean;
+  teamDefaultForViewer: boolean;
+  ownerDisplayName: string;
+  draftingDisabled: boolean;
+  accessGrantsOnly: boolean;
+  memberAgentIds: string[];
+  viewerAllowedActions: string[];
+  createdAtMs: string | null;
+  updatedAtMs: string | null;
+  voiceId: string;
+  voiceSpeed: number | null;
+  voiceLanguage: string;
+}
+export interface SlackConnection {
+  agentId: string;
+  connected: boolean;
+  workspaceName: string | null;
+  installUrl: string | null;
+  unavailableReason: string | null;
+  pendingAdminApproval: boolean;
+  needsManifestUpdate: boolean;
+  reinstallUrl: string | null;
+  approvalDenied: boolean;
+  appUnreachable: boolean;
+  removedInSlack: boolean;
+  approvalRequestUnsent: boolean;
+}
+export interface TeamsInstalledTeam {
+  teamId: string;
+  displayName: string;
+  rscGranted: boolean;
+  installedAtMs: string | null;
+}
+export interface TeamsConnection {
+  agentId: string;
+  installState: string;
+  tenantId: string | null;
+  tenantDisplayName: string | null;
+  installedTeamCount: number;
+  installedTeams: TeamsInstalledTeam[];
+}
+export interface BotSession {
+  agentId: string;
+  sessionId: string;
+  kind: string;
+  createdAtMs: string | null;
+  updatedAtMs: string | null;
+  lastActivityAtMs: string | null;
+}
+export interface TranscriptEntry {
+  seq: string;
+  updatedSeq: string;
+  entryId: string | null;
+  entryKind: string;
+  bodyOmitted: boolean;
+  blobHash: string | null;
+  body: Record<string, unknown> | null;
+}
+export interface UnreadAnchor {
+  hasNewerRows: boolean;
+  entryId: string;
+  seq: string | null;
+  newerRows: number;
+}
+export interface AgentLiveState {
+  agentId: string;
+  sessionId: string;
+  isRunning: boolean;
+  isComposingMessage: boolean;
+  isRetrying: boolean;
+  updatedAtMs: string | null;
+  staleAfterMs: string | null;
+  hasRunningSubagents: boolean;
+  surfaceTaskId: string;
+  workingTaskIds: string[];
+  activityKind: string;
+}
+export interface AgentClientState {
+  agentId: string;
+  lastViewedAtMs: string | null;
+  unreadCount: number;
+  lastActivityAtMs: string | null;
+  lastEntryId: string;
+  lastEntryKind: string;
+  lastMessageId: string;
+  lastMessagePreview: string;
+  notificationsEnabled: boolean;
+  notifyOnUpdatesEnabled: boolean;
+  hiddenFromSidebar: boolean;
+  updatedAtMs: string | null;
+  lastMessageTaskId: string;
+  removedFromSidebar: boolean;
+}
+export interface AgentStatus {
+  agentId: string;
+  isRunning: boolean;
+  live: AgentLiveState | null;
+  client: AgentClientState | null;
+}
+export interface AgentTask {
+  id: string;
+  name: string;
+  description: string;
+  status: string;
+  updatedAtMs: string | null;
+  unreadEntryId: string | null;
+  unreadPreview: string | null;
+  unreadAtMs: string | null;
+  pinnedAtMs: string | null;
+  subagentIds: string[];
+}
+export interface BotTask {
+  id: string;
+  title: string;
+  state: string;
+  note: string;
+  createdAtMs: string | null;
+  doneAtMs: string | null;
+  seenDoneAtMs: string | null;
+}
+export interface RunningSubagent {
+  subagentId: string;
+  subagentType: string;
+  title: string;
+  startedAtMs: string | null;
+  freshUntilMs: string | null;
+}
+export interface AgentTodo {
+  id: string;
+  content: string;
+  status: string;
+  createdAtMs: string | null;
+  updatedAtMs: string | null;
+  dependencies: string[];
+}
+export interface AgentSkill {
+  id: string;
+  name: string;
+  description: string;
+  body: string;
+  source: string;
+}
+export interface RuntimeCapabilities {
+  durableIdentityEnabled: boolean;
+  durableIdentityWritesEnabled: boolean;
+  temporalCreationEnabled: boolean;
+  agentMessagingEnabled: boolean;
+  serverRoomsEnabled: boolean;
+}
+export interface SandBoxImageInfo {
+  registryTag: string | null;
+  staticSnapshotPath: string | null;
+}
+export interface SandBoxRunState {
+  runState: string;
+  imageUpdateAvailable: boolean;
+  egressTunnelOwnership: boolean;
+  image: SandBoxImageInfo | null;
+}
+export interface BoxState {
+  runState: string;
+  recreateInFlight: boolean;
+  imageUpdateAvailable: boolean;
+  hostVersion: string | null;
+  hostUpdateAvailable: boolean;
+  diskPressure: string;
+  updatedAtMs: string | null;
+}
+export interface ComputerAction {
+  agentId: string;
+  type: string;
+  x: number | null;
+  y: number | null;
+  button: string;
+  count: number;
+  atMs: string | null;
 }
 export interface BotCursor { generation: number; afterUpdatedSeq: string; }
 export interface WatchOptions {
@@ -53,8 +231,12 @@ export type BotEvent =
   | { type: 'reset'; id: string; data: { botId: string; generation: number } }
   | { type: 'resync-required'; data: { botId: string; generation: number } }
   | { type: 'turn.failed'; data: { botId: string; turnId: string; code: number | string; summary: string } }
-  | { type: 'bot.state.changed'; data: { botId: string; families: string[] } }
-  | { type: 'bot.updated'; data: { botId: string; changedFields: Array<string | number>; bot: Bot | null } };
+  | { type: 'bot.state.changed'; data: { botId: string; families: string[]; changedAtMs: string | null } }
+  | { type: 'bot.updated'; data: { botId: string; changedFields: Array<string | number>; bot: Bot | null } }
+  | { type: 'agent.state'; data: { botId: string; sessionId: string; snapshot: boolean; live: AgentLiveState[]; client: AgentClientState[] } }
+  | { type: 'computer.actions'; data: { botId: string; actions: ComputerAction[] } }
+  | { type: 'box.state'; data: { botId: string; snapshot: boolean; state: BoxState | null } }
+  | { type: 'page.title.changed'; data: { botId: string; storeId: string; canvasId: string | null; documentId: string | null; title: string; changedAtMs: string | null } };
 export interface SendOptions {
   botId: string;
   text: string;
@@ -62,6 +244,20 @@ export interface SendOptions {
   messageId?: string;
   attachmentPaths?: string[];
   attachmentNames?: string[];
+  replyToId?: string;
+  replyQuote?: string;
+  taskId?: string;
+  language?: string;
+  richText?: string;
+  machineId?: string;
+}
+export interface TranscriptQuery {
+  botId: string;
+  sessionId?: string;
+  limit?: number;
+  generation?: number;
+  beforeSeq?: string;
+  unreadBoundaryMs?: string;
 }
 export class SDKError extends Error {
   code: string;
@@ -72,8 +268,20 @@ export function normalizeBot(agent: CloudAvatarRecord): Bot;
 export class GrokBotClient {
   constructor(options: ClientOptions);
   getMe(): Promise<Record<string, unknown>>;
-  listBots(options?: { includeTeamAgents?: boolean }): Promise<{ bots: Bot[]; truncated: boolean }>;
+  listBots(options?: { includeTeamAgents?: boolean; role?: string; addedTeamAgentsOnly?: boolean }): Promise<{ bots: Bot[]; truncated: boolean; slackConnections: SlackConnection[]; teamsConnections: TeamsConnection[] }>;
   sendMessage(options: SendOptions): Promise<{ botId: string; messageId: string; delivery: 'accepted-box' | 'accepted-temporal' | 'duplicate'; dispatched: boolean }>;
+  listSessions(botId: string): Promise<{ sessions: BotSession[] }>;
+  listTranscript(options: TranscriptQuery): Promise<{ generation: number; entries: TranscriptEntry[]; cloudAgentPeerIds: string[]; cloudAgentPeerIdsKnown: boolean; unreadAnchor: UnreadAnchor | null }>;
+  listAgentStatuses(agentIds?: string[]): Promise<{ statuses: AgentStatus[] }>;
+  getSendStatus(options: { botId: string; messageId: string; sessionId?: string; firstSentAgeMs?: string }): Promise<{ status: string; echoEntryId: string | null; rejectionCode: string | null; acceptedAtMs: string | null }>;
+  listAgentTasks(options: { botId: string; includeRecentlyDone?: boolean }): Promise<{ tasks: AgentTask[] }>;
+  listTasks(options: { botId: string; sessionId?: string }): Promise<{ tasks: BotTask[] }>;
+  listSubagents(botId: string): Promise<{ subagents: RunningSubagent[] }>;
+  listAgentTodos(botId: string): Promise<{ todos: AgentTodo[] }>;
+  listAgentSkills(botId: string): Promise<{ skills: AgentSkill[] }>;
+  listDeletedAgentIds(agentIds?: string[]): Promise<{ agentIds: string[] }>;
+  getRuntimeCapabilities(): Promise<RuntimeCapabilities>;
+  getSandBoxRunState(): Promise<SandBoxRunState>;
   watchBot(options: WatchOptions): AsyncGenerator<BotEvent, void, unknown>;
   botEventsSSE(options: WatchOptions & { keepAliveMs?: number }): Response;
 }

package/sdk.mjs

@@ -9,7 +9,19 @@ export {createLogin,pollLogin} from './core.mjs';
 export {deriveDefaultAvatar,resolveAgentAvatar} from './avatar.mjs';
 export {SDKError} from './errors.mjs';
 
+const CLIENT_VERSION='0.75.8';
+const SEND_STATUS={0:'unspecified',1:'not-found',2:'accepted',3:'rejected',4:'pending',5:'unknown-durability',GROK_BOT_SEND_STATUS_UNSPECIFIED:'unspecified',GROK_BOT_SEND_STATUS_NOT_FOUND:'not-found',GROK_BOT_SEND_STATUS_ACCEPTED:'accepted',GROK_BOT_SEND_STATUS_REJECTED:'rejected',GROK_BOT_SEND_STATUS_PENDING:'pending',GROK_BOT_SEND_STATUS_UNKNOWN_DURABILITY:'unknown-durability'};
+const RUN_STATE={0:'unspecified',1:'absent',2:'hibernated',3:'running',4:'starting',SAND_BOX_RUN_STATE_UNSPECIFIED:'unspecified',SAND_BOX_RUN_STATE_ABSENT:'absent',SAND_BOX_RUN_STATE_HIBERNATED:'hibernated',SAND_BOX_RUN_STATE_RUNNING:'running',SAND_BOX_RUN_STATE_STARTING:'starting'};
+
 function botKey(value){if(typeof value!=='string'||!value.length||value.length>128||!/^[A-Za-z0-9_-]+$/.test(value))throw new SDKError('BOT_ID_REQUIRED');return value;}
+function botIds(values,{allowEmpty=false}={}){if(!Array.isArray(values)||(!allowEmpty&&!values.length))throw new SDKError('BOT_ID_REQUIRED');return values.map(botKey);}
+function asText(value){return typeof value==='string'?value:'';}
+function wireText(value){if(typeof value==='string')return value;if(typeof value==='number'&&Number.isFinite(value))return String(value);return '';}
+function msText(value){if(typeof value==='string'&&/^-?\d{1,20}$/.test(value))return value;if(typeof value==='number'&&Number.isSafeInteger(value))return String(value);return null;}
+function stringList(value){return Array.isArray(value)?value.filter(item=>typeof item==='string'):[];}
+function wireList(value){return Array.isArray(value)?value.map(wireText).filter(item=>item.length>0):[];}
+function mappedEnum(value,table){if(Object.hasOwn(table,value))return table[value];return wireText(value)||'unspecified';}
+function objectRows(value){return Array.isArray(value)?value.filter(row=>row&&typeof row==='object'&&!Array.isArray(row)):[];}
 function uint64(value){
   if(typeof value==='number'&&!Number.isSafeInteger(value))throw new SDKError('CURSOR_INVALID');
   const text=String(value??0);if(!/^\d{1,20}$/.test(text)||BigInt(text)>18446744073709551615n)throw new SDKError('CURSOR_INVALID');return String(BigInt(text));
@@ -27,38 +39,84 @@ function decodeEntry(entry){
   try{const body=JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(Buffer.from(entry.body,'base64')));return body&&typeof body==='object'&&!Array.isArray(body)?body:null;}catch{return null;}
 }
 
+function normalizeSlackConnection(row){
+  return {agentId:asText(row.agentId),connected:row.connected===true,workspaceName:typeof row.workspaceName==='string'?row.workspaceName:null,installUrl:typeof row.installUrl==='string'?row.installUrl:null,unavailableReason:typeof row.unavailableReason==='string'?row.unavailableReason:null,pendingAdminApproval:row.pendingAdminApproval===true,needsManifestUpdate:row.needsManifestUpdate===true,reinstallUrl:typeof row.reinstallUrl==='string'?row.reinstallUrl:null,approvalDenied:row.approvalDenied===true,appUnreachable:row.appUnreachable===true,removedInSlack:row.removedInSlack===true,approvalRequestUnsent:row.approvalRequestUnsent===true};
+}
+function normalizeInstalledTeam(row){
+  if(!row||typeof row!=='object'||Array.isArray(row))return null;
+  return {teamId:asText(row.teamId),displayName:asText(row.displayName),rscGranted:row.rscGranted===true,installedAtMs:msText(row.installedAtMs)};
+}
+function normalizeTeamsConnection(row){
+  return {agentId:asText(row.agentId),installState:wireText(row.installState),tenantId:typeof row.tenantId==='string'?row.tenantId:null,tenantDisplayName:typeof row.tenantDisplayName==='string'?row.tenantDisplayName:null,installedTeamCount:Number.isInteger(row.installedTeamCount)?row.installedTeamCount:0,installedTeams:objectRows(row.installedTeams).map(normalizeInstalledTeam).filter(Boolean)};
+}
+function normalizeSession(row){
+  return {agentId:asText(row.agentId),sessionId:asText(row.sessionId),kind:wireText(row.kind),createdAtMs:msText(row.createdAtMs),updatedAtMs:msText(row.updatedAtMs),lastActivityAtMs:msText(row.lastActivityAtMs)};
+}
+function normalizeTranscriptEntry(entry){
+  return {seq:uint64(entry?.seq),updatedSeq:uint64(entry?.updatedSeq??entry?.seq),entryId:typeof entry?.entryId==='string'?entry.entryId:null,entryKind:asText(entry?.entryKind),bodyOmitted:entry?.bodyOmitted===true,blobHash:typeof entry?.blobHash==='string'?entry.blobHash:null,body:decodeEntry(entry??{})};
+}
+function normalizeUnreadAnchor(anchor){
+  if(!anchor||typeof anchor!=='object'||Array.isArray(anchor))return null;
+  return {hasNewerRows:anchor.hasNewerRows===true,entryId:asText(anchor.entryId),seq:msText(anchor.seq),newerRows:Number.isInteger(anchor.newerRows)?anchor.newerRows:0};
+}
+function normalizeLiveState(row){
+  return {agentId:asText(row.agentId),sessionId:asText(row.sessionId),isRunning:row.isRunning===true,isComposingMessage:row.isComposingMessage===true,isRetrying:row.isRetrying===true,updatedAtMs:msText(row.updatedAtMs),staleAfterMs:msText(row.staleAfterMs),hasRunningSubagents:row.hasRunningSubagents===true,surfaceTaskId:asText(row.surfaceTaskId),workingTaskIds:stringList(row.workingTaskIds),activityKind:asText(row.activity?.kind)};
+}
+function normalizeClientState(row){
+  return {agentId:asText(row.agentId),lastViewedAtMs:msText(row.lastViewedAtMs),unreadCount:Number.isInteger(row.unreadCount)?row.unreadCount:0,lastActivityAtMs:msText(row.lastActivityAtMs),lastEntryId:asText(row.lastEntryId),lastEntryKind:asText(row.lastEntryKind),lastMessageId:asText(row.lastMessageId),lastMessagePreview:asText(row.lastMessagePreview),notificationsEnabled:row.notificationsEnabled===true,notifyOnUpdatesEnabled:row.notifyOnUpdatesEnabled===true,hiddenFromSidebar:row.hiddenFromSidebar===true,updatedAtMs:msText(row.updatedAtMs),lastMessageTaskId:asText(row.lastMessageTaskId),removedFromSidebar:row.removedFromSidebar===true};
+}
+function normalizeBoxState(state){
+  if(!state||typeof state!=='object'||Array.isArray(state))return null;
+  return {runState:mappedEnum(state.runState,RUN_STATE),recreateInFlight:state.recreateInFlight===true,imageUpdateAvailable:state.imageUpdateAvailable===true,hostVersion:typeof state.hostVersion==='string'?state.hostVersion:null,hostUpdateAvailable:state.hostUpdateAvailable===true,diskPressure:wireText(state.diskPressure),updatedAtMs:msText(state.updatedAtMs)};
+}
+function normalizeComputerAction(row){
+  const number=value=>typeof value==='number'&&Number.isFinite(value)?value:null;
+  return {agentId:asText(row.agentId),type:asText(row.type),x:number(row.x),y:number(row.y),button:asText(row.button),count:Number.isInteger(row.count)?row.count:0,atMs:msText(row.atMs)};
+}
+
 export function normalizeBot(agent){
   if(!agent||typeof agent.agentId!=='string'||!agent.agentId)throw new SDKError('INVALID_BOT_RECORD');
   const avatar=resolveAgentAvatar(agent);
-  const text=value=>typeof value==='string'?value:'';
-  return {id:agent.agentId,serverId:typeof agent.id==='string'?agent.id:null,name:text(agent.name),description:text(agent.description),title:text(agent.title),avatarShape:avatar.character.shape,avatarColor:avatar.character.color,avatar,harness:text(agent.harness),kind:text(agent.kind),sessionId:text(agent.viewerSessionId),teamId:Number.isInteger(agent.teamId)?agent.teamId:null,viewerIsOwner:agent.viewerIsOwner===true,viewerCanManage:agent.viewerCanManage===true};
+  return {id:agent.agentId,serverId:typeof agent.id==='string'?agent.id:null,legacyAgentId:asText(agent.legacyAgentId),name:asText(agent.name),description:asText(agent.description),title:asText(agent.title),avatarShape:avatar.character.shape,avatarColor:avatar.character.color,avatar,harness:asText(agent.harness),role:asText(agent.role),kind:wireText(agent.kind),visibility:wireText(agent.visibility),sessionId:asText(agent.viewerSessionId),teamId:Number.isInteger(agent.teamId)?agent.teamId:null,viewerIsOwner:agent.viewerIsOwner===true,viewerCanManage:agent.viewerCanManage===true,teamDefaultForViewer:agent.teamDefaultForViewer===true,ownerDisplayName:asText(agent.ownerDisplayName),draftingDisabled:agent.draftingDisabled===true,accessGrantsOnly:agent.accessGrantsOnly===true,memberAgentIds:stringList(agent.memberAgentIds),viewerAllowedActions:wireList(agent.viewerAllowedActions),createdAtMs:msText(agent.createdAtMs),updatedAtMs:msText(agent.updatedAtMs),voiceId:asText(agent.voiceId),voiceSpeed:typeof agent.voiceSpeed==='number'&&Number.isFinite(agent.voiceSpeed)?agent.voiceSpeed:null,voiceLanguage:asText(agent.voiceLanguage)};
 }
 
 export class GrokBotClient{
   #options;
   constructor(options){
     if(typeof options?.accessToken!=='string'||!options.accessToken)throw new SDKError('MISSING_ACCESS_TOKEN');
-    this.#options={...options,version:options.version??'0.70.2'};
+    this.#options={...options,version:options.version??CLIENT_VERSION};
   }
   async #rpc(service,method,body,signal){
     return requestJSON(`${API_ORIGIN}/aiserver.v1.${service}/${method}`,{headers:clientHeaders(this.#options),body,fetchImpl:this.#options.fetchImpl,signal});
   }
+  async #data(service,method,body){
+    const response=await this.#rpc(service,method,body);
+    if(!response.ok)throw new SDKError('RPC_FAILED',response.httpStatus);
+    return response.data??{};
+  }
   async getMe(){
     const response=await this.#rpc('DashboardService','GetMe',{});
     if(!response.ok||!(response.data?.authId||response.data?.userId))throw new SDKError('ACCOUNT_AUTH_FAILED',response.httpStatus);
     return response.data;
   }
-  async listBots({includeTeamAgents=true}={}){
-    const response=await this.#rpc('GrokBotService','ListGrokBotAgents',{includeTeamAgents});
+  async listBots({includeTeamAgents=true,role,addedTeamAgentsOnly}={}){
+    const body={includeTeamAgents};
+    if(role!==undefined){if(typeof role!=='string')throw new SDKError('MESSAGE_INVALID');body.role=role;}
+    if(addedTeamAgentsOnly!==undefined)body.addedTeamAgentsOnly=addedTeamAgentsOnly===true;
+    const response=await this.#rpc('GrokBotService','ListGrokBotAgents',body);
     if(!response.ok)throw new SDKError('RPC_FAILED',response.httpStatus);
     if(!Array.isArray(response.data?.agents))throw new SDKError('INVALID_ROSTER_RESPONSE');
-    return {bots:response.data.agents.map(normalizeBot),truncated:response.data.truncated===true};
+    return {bots:response.data.agents.map(normalizeBot),truncated:response.data.truncated===true,slackConnections:objectRows(response.data.slackConnections).map(normalizeSlackConnection),teamsConnections:objectRows(response.data.teamsConnections).map(normalizeTeamsConnection)};
   }
 
-  async sendMessage({botId,text,sessionId='',messageId=randomUUID(),attachmentPaths=[],attachmentNames=[]}={}){
+  async sendMessage({botId,text,sessionId='',messageId=randomUUID(),attachmentPaths=[],attachmentNames=[],replyToId,replyQuote,taskId,language,richText,machineId}={}){
     botKey(botId);
     if(typeof text!=='string'||!text.trim()||typeof sessionId!=='string'||typeof messageId!=='string'||!messageId||!Array.isArray(attachmentPaths)||!Array.isArray(attachmentNames)||attachmentPaths.length!==attachmentNames.length||[...attachmentPaths,...attachmentNames].some(value=>typeof value!=='string'||!value))throw new SDKError('MESSAGE_INVALID');
-    const response=await this.#rpc('GrokBotService','SendGrokBotUserMessage',{agentId:botId,text,sessionId,messageId,attachmentPaths,attachmentNames,sentAtMs:String(Date.now()),isFork:false,source:1,initiator:1,sendSource:1});
+    const extra={};
+    const put=(key,value)=>{if(value===undefined)return;if(typeof value!=='string'||!value)throw new SDKError('MESSAGE_INVALID');extra[key]=value;};
+    put('replyToId',replyToId);put('replyQuote',replyQuote);put('taskId',taskId);put('language',language);put('machineId',machineId);
+    if(richText!==undefined){if(typeof richText!=='string')throw new SDKError('MESSAGE_INVALID');extra.richText=richText;}
+    const response=await this.#rpc('GrokBotService','SendGrokBotUserMessage',{agentId:botId,text,sessionId,messageId,attachmentPaths,attachmentNames,sentAtMs:String(Date.now()),isFork:false,source:1,initiator:1,sendSource:1,...extra});
     if(!response.ok)throw new SDKError('SEND_UNCONFIRMED',response.httpStatus);
     const deliveries={1:'accepted-box',2:'accepted-temporal',3:'duplicate',GROK_BOT_USER_MESSAGE_DELIVERY_ACCEPTED_BOX:'accepted-box',GROK_BOT_USER_MESSAGE_DELIVERY_ACCEPTED_TEMPORAL:'accepted-temporal',GROK_BOT_USER_MESSAGE_DELIVERY_DUPLICATE:'duplicate'};
     const delivery=deliveries[response.data?.delivery];
@@ -66,6 +124,99 @@ export class GrokBotClient{
     return {botId,messageId,delivery,dispatched:response.data.dispatched===true};
   }
 
+  async listSessions(botId){
+    botKey(botId);
+    const data=await this.#data('GrokBotService','ListGrokBotAgentSessions',{agentId:botId});
+    if(!Array.isArray(data.sessions))throw new SDKError('RPC_FAILED');
+    return {sessions:objectRows(data.sessions).map(normalizeSession)};
+  }
+
+  async listTranscript({botId,sessionId='',limit=50,generation:generationValue,beforeSeq,unreadBoundaryMs}={}){
+    botKey(botId);
+    if(typeof sessionId!=='string'||sessionId.length>256||!Number.isInteger(limit)||limit<1||limit>4294967295)throw new SDKError('CURSOR_INVALID');
+    const body={agentId:botId,sessionId,limit};
+    if(generationValue!==undefined)body.generation=generation(generationValue);
+    if(beforeSeq!==undefined)body.beforeSeq=uint64(beforeSeq);
+    if(unreadBoundaryMs!==undefined)body.unreadBoundaryMs=uint64(unreadBoundaryMs);
+    const data=await this.#data('GrokBotService','ListGrokBotTranscriptEntries',body);
+    if(!Array.isArray(data.entries))throw new SDKError('RPC_FAILED');
+    return {generation:generation(data.generation),entries:data.entries.map(normalizeTranscriptEntry),cloudAgentPeerIds:stringList(data.cloudAgentPeerIds),cloudAgentPeerIdsKnown:data.cloudAgentPeerIdsKnown===true,unreadAnchor:normalizeUnreadAnchor(data.unreadAnchor)};
+  }
+
+  async listAgentStatuses(agentIds=[]){
+    const ids=botIds(agentIds,{allowEmpty:true});
+    const data=await this.#data('GrokBotService','ListGrokBotAgentStatuses',{agentIds:ids});
+    if(!Array.isArray(data.statuses))throw new SDKError('RPC_FAILED');
+    return {statuses:objectRows(data.statuses).map(row=>({agentId:asText(row.agentId),isRunning:row.isRunning===true,live:row.live&&typeof row.live==='object'&&!Array.isArray(row.live)?normalizeLiveState(row.live):null,client:row.client&&typeof row.client==='object'&&!Array.isArray(row.client)?normalizeClientState(row.client):null}))};
+  }
+
+  async getSendStatus({botId,messageId,sessionId='',firstSentAgeMs}={}){
+    botKey(botId);
+    if(typeof messageId!=='string'||!messageId||typeof sessionId!=='string')throw new SDKError('MESSAGE_INVALID');
+    const body={agentId:botId,messageId,sessionId};
+    if(firstSentAgeMs!==undefined)body.firstSentAgeMs=uint64(firstSentAgeMs);
+    const data=await this.#data('GrokBotService','GetGrokBotSendStatus',body);
+    return {status:mappedEnum(data.status,SEND_STATUS),echoEntryId:typeof data.echoEntryId==='string'?data.echoEntryId:null,rejectionCode:typeof data.rejectionCode==='string'?data.rejectionCode:null,acceptedAtMs:msText(data.acceptedAtMs)};
+  }
+
+  async listAgentTasks({botId,includeRecentlyDone}={}){
+    botKey(botId);
+    const body={agentId:botId};
+    if(includeRecentlyDone!==undefined)body.includeRecentlyDone=includeRecentlyDone===true;
+    const data=await this.#data('GrokBotService','ListGrokBotAgentTasks',body);
+    if(!Array.isArray(data.tasks))throw new SDKError('RPC_FAILED');
+    return {tasks:objectRows(data.tasks).map(row=>({id:asText(row.id),name:asText(row.name),description:asText(row.description),status:asText(row.status),updatedAtMs:msText(row.updatedAtMs),unreadEntryId:typeof row.unreadEntryId==='string'?row.unreadEntryId:null,unreadPreview:typeof row.unreadPreview==='string'?row.unreadPreview:null,unreadAtMs:msText(row.unreadAtMs),pinnedAtMs:msText(row.pinnedAtMs),subagentIds:stringList(row.subagentIds)}))};
+  }
+
+  async listTasks({botId,sessionId=''}={}){
+    botKey(botId);
+    if(typeof sessionId!=='string'||sessionId.length>256)throw new SDKError('CURSOR_INVALID');
+    const data=await this.#data('GrokBotService','ListGrokBotTasks',{agentId:botId,sessionId});
+    if(!Array.isArray(data.tasks))throw new SDKError('RPC_FAILED');
+    return {tasks:objectRows(data.tasks).map(row=>({id:asText(row.id),title:asText(row.title),state:wireText(row.state),note:asText(row.note),createdAtMs:msText(row.createdAtMs),doneAtMs:msText(row.doneAtMs),seenDoneAtMs:msText(row.seenDoneAtMs)}))};
+  }
+
+  async listSubagents(botId){
+    botKey(botId);
+    const data=await this.#data('GrokBotService','ListGrokBotSubagents',{agentId:botId});
+    if(!Array.isArray(data.subagents))throw new SDKError('RPC_FAILED');
+    return {subagents:objectRows(data.subagents).map(row=>({subagentId:asText(row.subagentId),subagentType:asText(row.subagentType),title:asText(row.title),startedAtMs:msText(row.startedAtMs),freshUntilMs:msText(row.freshUntilMs)}))};
+  }
+
+  async listAgentTodos(botId){
+    botKey(botId);
+    const data=await this.#data('GrokBotService','ListGrokBotAgentTodos',{agentId:botId});
+    if(!Array.isArray(data.todos))throw new SDKError('RPC_FAILED');
+    return {todos:objectRows(data.todos).map(row=>({id:asText(row.id),content:asText(row.content),status:wireText(row.status),createdAtMs:msText(row.createdAt),updatedAtMs:msText(row.updatedAt),dependencies:stringList(row.dependencies)}))};
+  }
+
+  async listAgentSkills(botId){
+    botKey(botId);
+    const data=await this.#data('GrokBotService','ListGrokBotAgentSkills',{agentId:botId});
+    if(!Array.isArray(data.skills))throw new SDKError('RPC_FAILED');
+    return {skills:objectRows(data.skills).map(row=>({id:asText(row.id),name:asText(row.name),description:asText(row.description),body:asText(row.body),source:asText(row.source)}))};
+  }
+
+  async listDeletedAgentIds(agentIds=[]){
+    const ids=botIds(agentIds,{allowEmpty:true});
+    const data=await this.#data('GrokBotService','ListDeletedGrokBotAgentIds',{agentIds:ids});
+    if(!Array.isArray(data.agentIds))throw new SDKError('RPC_FAILED');
+    return {agentIds:stringList(data.agentIds)};
+  }
+
+  async getRuntimeCapabilities(){
+    const data=await this.#data('GrokBotService','GetGrokBotRuntimeCapabilities',{});
+    const caps=data.capabilities;
+    if(!caps||typeof caps!=='object'||Array.isArray(caps))throw new SDKError('RPC_FAILED');
+    return {durableIdentityEnabled:caps.durableIdentityEnabled===true,durableIdentityWritesEnabled:caps.durableIdentityWritesEnabled===true,temporalCreationEnabled:caps.temporalCreationEnabled===true,agentMessagingEnabled:caps.agentMessagingEnabled===true,serverRoomsEnabled:caps.serverRoomsEnabled===true};
+  }
+
+  async getSandBoxRunState(){
+    const data=await this.#data('GrokBotService','GetSandBoxRunState',{});
+    const image=data.image&&typeof data.image==='object'&&!Array.isArray(data.image)?{registryTag:typeof data.image.registryTag==='string'?data.image.registryTag:null,staticSnapshotPath:typeof data.image.staticSnapshotPath==='string'?data.image.staticSnapshotPath:null}:null;
+    return {runState:mappedEnum(data.state,RUN_STATE),imageUpdateAvailable:data.imageUpdateAvailable===true,egressTunnelOwnership:data.egressTunnelOwnership===true,image};
+  }
+
   async *watchBot({botId,sessionId='',cursor,resumeFrom,signal,inlineBodyMaxBytes=262144}={}){
     botKey(botId);
     if(typeof sessionId!=='string'||sessionId.length>256||cursor&&resumeFrom)throw new SDKError('CURSOR_INVALID');
@@ -113,8 +264,12 @@ export class GrokBotClient{
         if(frame.cleared?.agentId===botId&&(frame.cleared.sessionId??'')===sessionId){state={generation:generation(frame.cleared.newGeneration),afterUpdatedSeq:'0'};yield {type:'reset',id:cursorID(botId,sessionId,state),data:{botId,generation:state.generation}};}
         if(frame.cursorTooOld?.agentId===botId&&(frame.cursorTooOld.sessionId??'')===sessionId){yield {type:'resync-required',data:{botId,generation:generation(frame.cursorTooOld.generation)}};return;}
         if(frame.turnFailed?.agentId===botId&&(frame.turnFailed.sessionId??'')===sessionId)yield {type:'turn.failed',data:{botId,turnId:frame.turnFailed.turnId??'',code:frame.turnFailed.code??0,summary:frame.turnFailed.summary??''}};
-        if(frame.agentStateChanged?.agentId===botId)yield {type:'bot.state.changed',data:{botId,families:frame.agentStateChanged.families??[]}};
+        if(frame.agentStateChanged?.agentId===botId)yield {type:'bot.state.changed',data:{botId,families:stringList(frame.agentStateChanged.families),changedAtMs:msText(frame.agentStateChanged.changedAtMs)}};
         if(frame.rosterChanged?.agentId===botId){const changed=frame.rosterChanged;if(!changed.agent||changed.agent.agentId===botId)yield {type:'bot.updated',data:{botId,changedFields:changed.changedFields??[],bot:changed.agent?normalizeBot(changed.agent):null}};}
+        if(frame.agentState){const live=objectRows(frame.agentState.live).filter(row=>row.agentId===botId&&asText(row.sessionId)===sessionId).map(normalizeLiveState);const client=objectRows(frame.agentState.client).filter(row=>row.agentId===botId).map(normalizeClientState);if(frame.agentState.snapshot===true||live.length||client.length)yield {type:'agent.state',data:{botId,sessionId,snapshot:frame.agentState.snapshot===true,live,client}};}
+        if(frame.computerActions){const actions=objectRows(frame.computerActions.actions).filter(row=>row.agentId===botId).map(normalizeComputerAction);if(actions.length)yield {type:'computer.actions',data:{botId,actions}};}
+        if(frame.boxState)yield {type:'box.state',data:{botId,snapshot:frame.boxState.snapshot===true,state:normalizeBoxState(frame.boxState.state)}};
+        if(frame.pageTitleChanged){const page=frame.pageTitleChanged;const wrapped=page.page&&typeof page.page==='object'?page.page:null;yield {type:'page.title.changed',data:{botId,storeId:asText(page.storeId),canvasId:wrapped?.case==='canvasId'?asText(wrapped.value):typeof page.canvasId==='string'?page.canvasId:null,documentId:wrapped?.case==='documentId'?asText(wrapped.value):typeof page.documentId==='string'?page.documentId:null,title:asText(page.title),changedAtMs:msText(page.changedAtMs)}};}
       }
     }catch(error){
       if(signal?.aborted)return;