pi2web 0.2.1 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi2web",
-  "version": "0.2.1",
+  "version": "0.2.6",
   "description": "Secure remote web client server for Pi coding agent",
   "type": "module",
   "author": "sxwxs",
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist/",
+    "npm-shrinkwrap.json",
     "web/",
     "packages/protocol/",
     "packages/edge-tts-server/src/remote_pi_edge_tts/",
@@ -35,6 +36,8 @@
     "clean": "rm -rf dist",
     "build": "npm run clean && tsc -p tsconfig.json && chmod +x dist/main.js",
     "check": "npm run build",
+    "format": "prettier --write \"src/**/*.ts\" \"web/*.js\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"web/*.js\" \"test/**/*.ts\"",
     "test": "vitest run",
     "dev": "tsx src/main.ts",
     "dev:watch": "tsx watch src/main.ts",
@@ -46,8 +49,14 @@
     "node": ">=22.19.0"
   },
   "dependencies": {
+    "@earendil-works/chord": "1.1.0",
+    "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-codemode": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-mcp": "1.1.0",
+    "@earendil-works/pi-telemetry": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "better-sqlite3": "^12.11.1",
@@ -61,6 +70,7 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.0",
+    "prettier": "3.6.2",
     "tsx": "^4.19.0",
     "typescript": "^5.9.3",
     "vitest": "^3.0.0"

package/packages/protocol/openapi.yaml

@@ -1,5 +1,5 @@
 openapi: 3.1.0
-info: {title: Remote Pi API, version: 1.0.0}
+info: {title: Remote Pi API, version: 2.0.0}
 servers: [{url: /api/v1}]
 security: [{bearerAuth: []}]
 paths:
@@ -19,8 +19,12 @@ paths:
   /agents:
     get: {operationId: listAgents, responses: {'200': {$ref: '#/components/responses/Success'}}}
     post: {operationId: createAgent, requestBody: {$ref: '#/components/requestBodies/Json'}, responses: {'201': {$ref: '#/components/responses/Success'}}}
+  /agents/{id}/timeline:
+    get: {operationId: agentTimeline, description: 'Older history as display items (see timelineItem in websocket.schema.json): about `limit` items before item `before`, never splitting a tool call from its result. Data {sessionId, items, total, start, hasMore}. Viewers get the newest page from the WebSocket focus snapshot. 404 when `before` is not on the current branch.', parameters: [{$ref: '#/components/parameters/Id'}, {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 500, default: 50}}, {name: before, in: query, schema: {type: string}}], responses: {'200': {$ref: '#/components/responses/Success'}}}
+  /agents/{id}/sessions/{sessionId}/items/{itemId}:
+    get: {operationId: agentTimelineItem, description: 'Full body of one timeline item, data {id, body}. Items never change, so it is served with Cache-Control private, max-age=31536000, immutable. 404 when the Agent is no longer on that session or branch.', parameters: [{$ref: '#/components/parameters/Id'}, {name: sessionId, in: path, required: true, schema: {type: string}}, {name: itemId, in: path, required: true, schema: {type: string}}], responses: {'200': {$ref: '#/components/responses/Success'}}}
   /agents/{id}/{action}:
-    get: {operationId: getAgentResource, parameters: [{$ref: '#/components/parameters/Id'}, {name: action, in: path, required: true, schema: {enum: [state,messages,capabilities,session]}}], responses: {'200': {$ref: '#/components/responses/Success'}}}
+    get: {operationId: getAgentResource, parameters: [{$ref: '#/components/parameters/Id'}, {name: action, in: path, required: true, schema: {enum: [state,capabilities,session]}}], responses: {'200': {$ref: '#/components/responses/Success'}}}
     post: {operationId: agentCommand, parameters: [{$ref: '#/components/parameters/Id'}, {name: action, in: path, required: true, schema: {enum: [prompt,steer,follow-up,abort,compact,model,thinking,session-name,navigate,fork,extension-response]}}], requestBody: {$ref: '#/components/requestBodies/Json'}, responses: {'200': {$ref: '#/components/responses/Success'}}}
   /draft:
     post: {operationId: draftText, description: 'Insert text into the currently displayed Web UI input box on this backend, without sending it to an Agent. Body {text, mode?: append|replace, source?}; explicit agent/slot targets are rejected. Pending text is kept in memory until a page acknowledges it.', requestBody: {$ref: '#/components/requestBodies/Json'}, responses: {'200': {$ref: '#/components/responses/Success'}}}

package/packages/protocol/websocket.schema.json

@@ -1,10 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://remote-pi.local/protocol/v1/websocket.schema.json",
-  "title": "Remote Pi WebSocket v1",
+  "$id": "https://remote-pi.local/protocol/v2/websocket.schema.json",
+  "title": "Remote Pi WebSocket v2",
+  "description": "Nothing is replayed. subscribe_all gives every Agent's state, then overview events of every Agent. focus answers with a snapshot of one Agent (newest timeline page, streamed text, dialogs); after it, on this socket and in order, come only appended items, streamed text and shell output of that Agent, or timeline_reset (focus again for a new snapshot). Timeline items never change. HTTP serves only what never changes: older pages (GET /api/v1/agents/{id}/timeline?before=) and item bodies (GET /api/v1/agents/{id}/sessions/{sessionId}/items/{itemId}).",
   "oneOf": [
-    {"$ref":"#/$defs/subscribe"}, {"$ref":"#/$defs/command"}, {"$ref":"#/$defs/subscribed"},
-    {"$ref":"#/$defs/commandResult"}, {"$ref":"#/$defs/agentEvent"}, {"$ref":"#/$defs/agentSnapshot"}, {"$ref":"#/$defs/agentStateUpdate"},
+    {"$ref":"#/$defs/subscribeAll"}, {"$ref":"#/$defs/subscribedAll"}, {"$ref":"#/$defs/focus"}, {"$ref":"#/$defs/watch"},
+    {"$ref":"#/$defs/command"}, {"$ref":"#/$defs/commandResult"}, {"$ref":"#/$defs/agentEvent"}, {"$ref":"#/$defs/agentStateUpdate"},
+    {"$ref":"#/$defs/focusState"}, {"$ref":"#/$defs/focusError"}, {"$ref":"#/$defs/delta"}, {"$ref":"#/$defs/items"}, {"$ref":"#/$defs/timelineReset"}, {"$ref":"#/$defs/toolOutput"},
     {"$ref":"#/$defs/subscribeDrafts"}, {"$ref":"#/$defs/subscribedDrafts"}, {"$ref":"#/$defs/draftAck"}, {"$ref":"#/$defs/draftEvent"}
   ],
   "$defs": {
@@ -12,15 +14,58 @@
     "subscribedDrafts": {"type":"object","required":["type","protocolVersion"],"properties":{"type":{"const":"subscribed_drafts"},"protocolVersion":{"const":1}}},
     "draftAck": {"type":"object","additionalProperties":false,"required":["type","id"],"properties":{"type":{"const":"draft_ack"},"id":{"type":"string"}}},
     "draftEvent": {"type":"object","required":["type","draft"],"properties":{"type":{"const":"draft_event"},"replay":{"type":"boolean"},"draft":{"type":"object","required":["id","text","mode","createdAt"],"properties":{"id":{"type":"string"},"text":{"type":"string"},"mode":{"enum":["append","replace"]},"source":{"type":"string"},"createdAt":{"type":"string"}}}}},
-    "subscribe": {"type":"object","additionalProperties":false,"required":["type","agentId"],"properties":{"type":{"const":"subscribe"},"agentId":{"type":"string"},"lastSequence":{"type":"integer","minimum":0},"fromNow":{"type":"boolean"},"messageLimit":{"type":"integer","minimum":1,"maximum":200}}},
+    "subscribeAll": {"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"const":"subscribe_all"}},"description":"Receive agent_state for every Agent, then overview agent_event messages of every Agent."},
+    "subscribedAll": {"type":"object","required":["type","protocolVersion","serverTime"],"properties":{"type":{"const":"subscribed_all"},"protocolVersion":{"const":2},"serverTime":{"type":"integer","description":"Server epoch milliseconds, to correct clock skew for activity times."}}},
+    "focus": {"type":"object","additionalProperties":false,"required":["type","agentId"],"properties":{"type":{"const":"focus"},"agentId":{"type":["string","null"]},"limit":{"type":"integer","minimum":1,"maximum":500,"description":"Size of the snapshot's page, 50 by default."}},"description":"View one Agent in detail (null: none). Loads it if needed and answers with focus_state, or focus_error; replaces the previous focus and its watches."},
+    "watch": {"type":"object","additionalProperties":false,"required":["type","toolCallId"],"properties":{"type":{"enum":["watch","unwatch"]},"toolCallId":{"type":"string"}},"description":"Start or stop tool_output for a running tool of the focused Agent, e.g. while its card is expanded."},
     "command": {"type":"object","additionalProperties":false,"required":["type","requestId","agentId"],"properties":{"type":{"enum":["prompt","steer","follow-up","abort","clear-queue"]},"requestId":{"type":"string"},"agentId":{"type":"string"},"message":{"type":"string","maxLength":2097152}}},
-    "subscribed": {"type":"object","required":["type","agentId","protocolVersion"],"properties":{"type":{"const":"subscribed"},"agentId":{"type":"string"},"protocolVersion":{"const":1},"currentSequence":{"type":"integer","minimum":0}}},
-    "commandResult": {"type":"object","required":["type","success"],"properties":{"type":{"const":"command_result"},"requestId":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object"},"disposition":{"enum":["handled","queued"],"description":"For steer and follow-up: whether the running turn took the message or it waits in the queue. Omitted by older servers."},"queue":{"$ref":"#/$defs/queue"}}},
+    "commandResult": {"type":"object","required":["type","success"],"properties":{"type":{"const":"command_result"},"requestId":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object"},"disposition":{"enum":["handled","queued"],"description":"For steer and follow-up: whether the running turn took the message or it waits in the queue."},"queue":{"$ref":"#/$defs/queue"}}},
     "queue": {"type":"object","required":["steering","followUp"],"description":"Messages waiting for the running turn.","properties":{"steering":{"type":"array","items":{"type":"string"}},"followUp":{"type":"array","items":{"type":"string"}}}},
-    "agentEvent": {"type":"object","required":["type","agentId","eventId","sequence","event"],"properties":{"type":{"const":"agent_event"},"agentId":{"type":"string"},"eventId":{"type":"string"},"sequence":{"type":"integer","minimum":1},"timestamp":{"type":"integer","minimum":0},"status":{"$ref":"#/$defs/agentStatus","description":"Agent status after this event. Omitted by older servers."},"event":{"type":"object","required":["type"]}}},
+    "agentEvent": {"type":"object","required":["type","agentId","timestamp","status","event"],"properties":{"type":{"const":"agent_event"},"agentId":{"type":"string"},"timestamp":{"type":"integer","minimum":0,"description":"Epoch milliseconds."},"status":{"$ref":"#/$defs/agentStatus","description":"Agent status after this event."},"event":{"type":"object","required":["type"],"description":"Overview events of every Agent: agent_loaded (its backend started on demand), agent_start, agent_end {willRetry, aborted}, agent_settled, activity_changed {activity}, queue_update, session_info_changed, agent_unloaded, auto_retry_*, summarization_retry_*, extension_ui_*. For the focused Agent also bash_execution_start/update/end (output of user shell commands)."}}},
+    "focusState": {"type":"object","required":["type","agentId","sessionId","page","live"],"description":"Snapshot of the focused Agent. Every detail message after it is newer.","properties":{"type":{"const":"focus_state"},"agentId":{"type":"string"},"sessionId":{"type":"string"},"page":{"type":"object","required":["items","total","start","hasMore"],"properties":{"items":{"type":"array","items":{"$ref":"#/$defs/timelineItem"}},"total":{"type":"integer"},"start":{"type":"integer"},"hasMore":{"type":"boolean"}}},"live":{"oneOf":[{"type":"null"},{"type":"object","required":["text","thinking"],"properties":{"text":{"type":"string"},"thinking":{"type":"string"}}}],"description":"Text streamed so far for the message being generated."},"dialogRequests":{"type":"array","description":"Pending dialogs, to rebuild their controls in the transcript."}}},
+    "focusError": {"type":"object","required":["type","agentId","error"],"properties":{"type":{"const":"focus_error"},"agentId":{"type":"string"},"error":{"type":"object"}}},
+    "delta": {"type":"object","required":["type","agentId","kind","delta"],"properties":{"type":{"const":"delta"},"agentId":{"type":"string"},"kind":{"enum":["text","thinking"]},"delta":{"type":"string"}},"description":"More streamed text; adjacent tokens are coalesced."},
+    "items": {"type":"object","required":["type","agentId","sessionId","items"],"properties":{"type":{"const":"items"},"agentId":{"type":"string"},"sessionId":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/$defs/timelineItem"},"description":"Appended to the timeline."},"clearLive":{"const":true,"description":"They record the streamed message: drop its streamed text."}}},
+    "timelineReset": {"type":"object","required":["type","agentId","sessionId"],"properties":{"type":{"const":"timeline_reset"},"agentId":{"type":"string"},"sessionId":{"type":"string"}},"description":"The branch changed other than by appending: focus again for a new snapshot."},
+    "toolOutput": {"type":"object","required":["type","agentId","toolCallId","output"],"description":"Output so far of a watched running tool, at most one per tool per 100 ms.","properties":{"type":{"const":"tool_output"},"agentId":{"type":"string"},"toolCallId":{"type":"string"},"output":{"type":"string"}}},
+    "timelineItem": {
+      "type":"object","required":["id","kind","size"],
+      "description":"One displayable part of one recorded session entry; it never changes. A tool's call and result are separate items paired by toolCallId (a page never splits them); whether a call is running is the Agent's activity. Bodies of user, assistant and error items, and other bodies up to 256 characters, are inline; others load from the item endpoint, cacheable forever.",
+      "properties":{
+        "id":{"type":"string"},
+        "kind":{"enum":["user","assistant","thinking","error","tool_call","tool_result","bash","compaction","branch_summary","custom","system"]},
+        "timestamp":{"type":"integer"},
+        "title":{"type":"string","description":"Tool name, shell command, or what a system item is."},
+        "summary":{"type":"string"},
+        "status":{"enum":["ok","error","cancelled"],"description":"tool_result and bash: how it ended."},
+        "durationMs":{"type":"number"},
+        "toolCallId":{"type":"string"},
+        "size":{"type":"integer","minimum":0},
+        "body":{"type":"string"}
+      }
+    },
     "agentStatus": {"enum":["unloaded","starting","idle","streaming","waiting_for_user","error","stopping","stopped"]},
-    "agentSnapshot": {"type":"object","required":["type","agentId","lastSequence","state","messages"],"properties":{"type":{"const":"agent_snapshot"},"agentId":{"type":"string"},"lastSequence":{"type":"integer","minimum":0},"state":{"$ref":"#/$defs/agentState"},"messages":{"type":"array"}}},
-    "agentStateUpdate": {"type":"object","required":["type","agentId","sequence","state"],"description":"Current state after initial replay/snapshot and before live events, also sent for fromNow or empty replay. Does not replace transcript messages.","properties":{"type":{"const":"agent_state"},"agentId":{"type":"string"},"sequence":{"type":"integer","minimum":0},"state":{"$ref":"#/$defs/agentState"}}},
+    "agentStateUpdate": {"type":"object","required":["type","agentId","state"],"description":"Current state of one Agent, sent for every Agent on subscribe_all.","properties":{"type":{"const":"agent_state"},"agentId":{"type":"string"},"state":{"$ref":"#/$defs/agentState"}}},
+    "activity": {
+      "type":"object","required":["run","phase","bash","dialogs"],
+      "description":"What the Agent is doing now, maintained by the server. Also pushed as agent event {type:'activity_changed', activity} on every change. Times are server epoch milliseconds; correct skew with subscribed_all.serverTime.",
+      "properties":{
+        "run":{"oneOf":[{"type":"null"},{"type":"object","required":["startedAt"],"properties":{"startedAt":{"type":"integer"}}}]},
+        "phase":{
+          "type":"object","required":["kind","since"],
+          "properties":{
+            "kind":{"enum":["idle","waiting_llm","thinking","generating","preparing_tool","running_tools","retrying","compacting","stopping"]},
+            "since":{"type":"integer"},
+            "toolName":{"type":"string","description":"preparing_tool"},
+            "tools":{"type":"array","description":"running_tools: top-level tools in parallel","items":{"type":"object","required":["toolCallId","toolName","since"],"properties":{"toolCallId":{"type":"string"},"toolName":{"type":"string"},"summary":{"type":"string","description":"Command, path or pattern, at most 80 characters"},"since":{"type":"integer"}}}},
+            "attempt":{"type":"integer"},"maxAttempts":{"type":"integer"},"retryAt":{"type":"integer"},"error":{"type":"string"},
+            "reason":{"type":"string","description":"compacting"}
+          }
+        },
+        "bash":{"type":"array","items":{"type":"object","required":["id","since"],"properties":{"id":{"type":"string"},"command":{"type":"string"},"since":{"type":"integer"}}}},
+        "dialogs":{"type":"array","items":{"type":"object","required":["requestId","since"],"properties":{"requestId":{"type":"string"},"title":{"type":"string"},"since":{"type":"integer"}}}}
+      }
+    },
     "agentState": {
       "type":"object","required":["status","agentId","sessionId","cwd"],
       "properties":{
@@ -31,13 +76,11 @@
         "sessionName":{"type":"string"},
         "cwd":{"type":"string"},
         "activity":{
-          "type":"object","required":["bashIds","dialogIds"],
-          "description":"Runtime operations independent of LLM status. Omitted by older servers; never persisted.",
+          "description":"Live activity plus dialog payloads and queue. Never persisted.",
+          "allOf":[{"$ref":"#/$defs/activity"}],
           "properties":{
-            "bashIds":{"type":"array","uniqueItems":true,"items":{"type":"string"}},
-            "dialogIds":{"type":"array","uniqueItems":true,"items":{"type":"string"}},
             "dialogRequests":{
-              "type":"array","description":"Pending request payloads for rebuilding dialog controls, without submitted answers. Omitted by older servers.",
+              "type":"array","description":"Pending request payloads for rebuilding dialog controls, without submitted answers.",
               "items":{
                 "type":"object","required":["type","requestId","kind"],
                 "properties":{

package/web/activity-view.js

@@ -0,0 +1,121 @@
+(() => {
+  'use strict';
+
+  // Presentation of the server-maintained Agent activity (see src/activity.ts).
+  // The server reports what is happening and since when; elapsed times tick locally.
+  const PHASE_TEXT = {
+    waiting_llm: ['⏳', '等待 LLM 响应'],
+    thinking: ['💭', 'LLM 思考中'],
+    generating: ['✍️', 'LLM 输出中'],
+    preparing_tool: ['🛠️', '生成工具参数'],
+    running_tools: ['🔧', '执行工具'],
+    retrying: ['🔁', '重试'],
+    compacting: ['🗜️', '压缩上下文'],
+    stopping: ['⏹️', '正在停止']
+  };
+
+  const isBusy = activity =>
+    !!activity &&
+    (!!activity.run ||
+      (!!activity.phase?.kind && activity.phase.kind !== 'idle') ||
+      !!activity.bash?.length ||
+      !!activity.dialogs?.length);
+
+  function formatElapsed(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000)),
+      h = Math.floor(total / 3600),
+      m = Math.floor((total % 3600) / 60),
+      s = String(total % 60).padStart(2, '0');
+    return h ? `${h}:${String(m).padStart(2, '0')}:${s}` : `${m}:${s}`;
+  }
+
+  /** What an Agent is doing, most important first: open dialogs, the run's phase, then user shell commands. */
+  function activityParts(activity) {
+    if (!activity) return [];
+    const parts = (activity.dialogs || []).map(dialog => ({
+      icon: '❓',
+      text: `等待你回答${dialog.title ? `：${dialog.title}` : ''}`,
+      since: dialog.since
+    }));
+    const phase = activity.phase;
+    if (phase && phase.kind !== 'idle') {
+      const [icon, label] = PHASE_TEXT[phase.kind] || ['•', phase.kind];
+      if (phase.kind === 'running_tools')
+        for (const tool of phase.tools || [])
+          parts.push({
+            icon,
+            text: `${tool.toolName}${tool.summary ? `: ${tool.summary}` : ''}`,
+            since: tool.since
+          });
+      else if (phase.kind === 'preparing_tool')
+        parts.push({
+          icon,
+          text: `${label}${phase.toolName ? `：${phase.toolName}` : ''}`,
+          since: phase.since
+        });
+      else if (phase.kind === 'retrying')
+        parts.push({
+          icon,
+          text: `${label}${phase.attempt ? ` ${phase.attempt}/${phase.maxAttempts || '?'}` : ''}${phase.error ? ` · ${phase.error}` : ''}`,
+          since: phase.since
+        });
+      else parts.push({icon, text: label, since: phase.since});
+    }
+    for (const bash of activity.bash || [])
+      parts.push({icon: '$', text: bash.command || 'bash', since: bash.since});
+    return parts;
+  }
+
+  /**
+   * DOM builders. `serverNow(backendId)` returns that backend's current time, so
+   * client clock skew does not distort elapsed times.
+   */
+  function createActivityView(serverNow) {
+    function elapsed(backendId, since) {
+      const span = document.createElement('span');
+      span.className = 'elapsed';
+      span.dataset.since = String(since);
+      span.dataset.backend = backendId || '';
+      span.textContent = formatElapsed(serverNow(backendId) - since);
+      return span;
+    }
+    function chip(part, backendId) {
+      const node = document.createElement('span'),
+        text = document.createElement('span');
+      node.className = 'activity-chip';
+      text.className = 'activity-text';
+      text.textContent = `${part.icon} ${part.text}`;
+      text.title = part.text;
+      node.append(text, elapsed(backendId, part.since));
+      return node;
+    }
+    /** The full activity of the selected Agent: every part plus the run's total time. */
+    function bar(activity, backendId) {
+      const nodes = activityParts(activity).map(part => chip(part, backendId));
+      if (activity?.run) {
+        const run = document.createElement('span');
+        run.className = 'activity-run';
+        run.append('本次运行 ', elapsed(backendId, activity.run.startedAt));
+        nodes.push(run);
+      }
+      return nodes;
+    }
+    /** One compact line for the Agent list: the most important part and how many more there are. */
+    function line(activity, backendId) {
+      const parts = activityParts(activity);
+      if (!parts.length) return null;
+      const node = document.createElement('div');
+      node.className = 'agent-activity';
+      node.append(chip(parts[0], backendId));
+      if (parts.length > 1) node.append(` +${parts.length - 1}`);
+      return node;
+    }
+    function tick() {
+      for (const el of document.querySelectorAll('.elapsed[data-since]'))
+        el.textContent = formatElapsed(serverNow(el.dataset.backend) - Number(el.dataset.since));
+    }
+    return {bar, line, tick};
+  }
+
+  window.ActivityView = {isBusy, formatElapsed, activityParts, createActivityView};
+})();