@yunazgr/pi-companion 0.2.5 → 0.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 Lightweight, local-first remote control for Pi sessions.
 
+**New in 0.3.0:** [automations](docs/automations.md) with manual/UTC-cron runs, read-only agent sessions, run history, native agent tools and a standalone MCP surface. Disconnected sessions auto-archive after seven days; mobile Settings is now in the header.
+
 Pi Companion is deliberately not another agent runtime. Pi owns execution and conversation state. A single Rust daemon owns session discovery, pairing, temporary file exchange, browser fan-out, and the embedded web UI.
 
 The UI is a static SvelteKit application. There is no Node runtime in production and no Tauri shell. Rust embeds the generated frontend into the daemon binary.
@@ -153,7 +155,7 @@ Dialogs from other extensions (`ctx.ui.select`, `ctx.ui.confirm`, `ctx.ui.input`
 
 Settings → **Notifications and camera** (on every device, not just the console) asks the browser for both permissions from a tap, as browsers require, and shows whether each is allowed, blocked or unavailable. Overview also offers a one-time "Turn on notifications" banner.
 
-With notifications on, the device gets a system notification (through the service worker, so it works for installed apps and Android) when Pi asks a question, finishes a turn or a session ends. Tapping it opens that session. Nothing is sent while you are already looking at that session. iPhone and iPad only allow web notifications from an app added to the Home Screen. The camera is used only for the pairing QR scanner.
+With notifications on, the device gets a system notification (through the service worker, so it works for installed apps and Android) when Pi asks a question, finishes a turn or a session ends. Tapping it opens that session. Nothing is sent while you are already looking at that session. iPhone and iPad only allow web notifications from an app added to the Home Screen. The camera is used only for the pairing QR scanner. Camera access requires HTTPS or localhost; plain HTTP LAN/phone links cannot prompt. After upgrading, restart the daemon and reload the app to refresh cached camera policies. Settings distinguishes browser denial, page/proxy policy blocks and transient camera errors, with retry or manual-code pairing guidance.
 
 Activity no longer lives only in the open tab. The daemon keeps a bounded, in-memory log of each session's recent feed (streamed text is merged, up to 800 entries) at `GET /api/sessions/{id}/activity` on both surfaces (paired devices: shared sessions only). The UI rebuilds the feed from it when a session opens and after every reconnect or resync, so a phone that slept, dropped its connection or was closed catches up without sending a new message. Prompts, steers and answers from any device are added to that log too. The log is cleared when the daemon restarts or the session is archived.
 
@@ -178,11 +180,37 @@ Paired devices (name, browser user agent, pairing and last-seen times, credentia
 
 A phone pairs once with the daemon. Individual Pi sessions still opt in using /companion.
 
-Network loss and daemon restarts reconnect automatically with bounded backoff. Heartbeats detect silent connections, and returning to the foreground or restoring network access retries immediately. Pairing credentials and unsent drafts survive outages; session snapshots, pending questions, and previously loaded upload lists refresh on reconnect. Missed activity is not replayed, and prompts/answers are never automatically resent. A deliberate **Disconnect** waits for the device’s explicit retry; **Revoke** removes access and requires pairing again.
+Network loss and daemon restarts reconnect automatically with bounded backoff. Heartbeats detect silent connections, and returning to the foreground or restoring network access retries immediately. Pairing credentials and unsent drafts survive outages; session snapshots, pending questions, and previously loaded upload lists refresh on reconnect. Recent activity is replayed from the daemon’s bounded log, but prompts/answers are never automatically resent. A deliberate **Disconnect** waits for the device’s explicit retry; **Revoke** removes access and requires pairing again.
+
+## Session metadata and usage
+
+Shared session title, model, effort and working directory refresh on Pi events and once per second while sharing, including while idle. Session detail shows context-window usage and estimated session cost. Native Pi context and recorded usage costs take precedence; independent extension reports fill unavailable fields. Missing usage is shown as unavailable, not zero.
+
+**Settings → Usage** is available on the console and paired devices. It displays the latest snapshot per provider: weekly usage, 5-hour usage when reported, reset times, source and snapshot age. Quota snapshots are not added across sessions or accounts. These are extension-reported limits, not billing totals or locally inferred quotas; providers without a quota report remain unavailable.
+
+Extensions can publish a provider-neutral event without importing Companion:
+
+```ts
+pi.events.emit("companion:telemetry", {
+  source: "my-usage-extension", // distinguish independent producers
+  // sessionId: ctx.sessionManager.getSessionId(), // optional session guard
+  context: { tokens: 24000, window: 200000, percent: 12 },
+  cost: { amount: 0.25, currency: "USD" },
+  providers: [{
+    provider: "openai-codex", updatedAt: new Date().toISOString(),
+    weekly: { usedPercent: 35, resetsAt: "2026-10-12T00:00:00Z" },
+    fiveHour: { usedPercent: 20 } // omit windows the provider doesn't supply
+  }]
+});
+```
+
+Publish complete snapshots per provider; session context and cost may be supplied independently by different extensions. Companion also accepts `usage:update`, `session:usage` and `provider:usage` with this shape. On opt-in and every 30 seconds it emits `companion:telemetry:request` with the Pi `sessionId` and `companionSessionId`, allowing adapters to respond with their cached snapshots. It never reads provider credentials or calls quota APIs itself. Extensions with private, non-exported quota data need an adapter to publish this contract.
+
+As a legacy fallback, `ctx.ui.setStatus` reports with explicit `ctx 12%` / `context 12%` and `cost: $0.25` (or cost/usage/footer keys containing `$0.25`) are recognized. Quota status lines must identify `provider=…` and label `7d`/`weekly` and `5h`/`5-hour` percentages (`used`, `left`, or `remaining`). Unlabelled percentages mean used. Status rendering is preserved. Invalid reports are ignored; extension context/cost expires after five minutes without a fresh reading. Context estimates are also invalidated on model changes, compaction and tree navigation; quota snapshots retain their original timestamps and visibly age.
 
 ## Settings
 
-The **Settings** page (local console only) covers:
+The **Settings → General** page provides appearance and device permissions on every device; daemon configuration is local-console-only:
 
 | Setting | Default | Notes |
 |---|---|---|
@@ -326,7 +354,7 @@ Clone the repository, then:
 
 `npm run serve` builds the embedded Svelte UI and starts the Rust daemon in the foreground. It prints:
 
-      Pi Companion v0.2.5
+      Pi Companion v0.3.0
 
       Console          http://127.0.0.1:43721
       Paired devices   http://127.0.0.1:43722

package/SECURITY.md

@@ -24,7 +24,7 @@ Strict Origin checks: WebSocket upgrades and POST/DELETE requests must carry an
 
 Pairing invitations are single-use and expire (5 minutes by default). The short typed code is rate limited: ten wrong codes within ten minutes withdraw every open invitation and further code claims get HTTP 429 until the window passes.
 
-Paired devices can see only sessions that explicitly enabled remote control.
+Paired devices can see only sessions that explicitly enabled remote control, including daemon-owned automation sessions created by an authorized automation run. Paired devices may read automation definitions/history and start/stop existing automations, but cannot create, edit, delete, or enable/disable them.
 
 Revoking a device deletes its credential hash and closes its open connections immediately (WebSocket close 4003). Disconnecting closes them without deleting the credential (close 4001).
 
@@ -32,6 +32,14 @@ Revoking a device deletes its credential hash and closes its open connections im
 
 Paired devices (name, browser user agent, pairing and last-seen times, and the SHA-256 hash of the credential; never the credential) and settings are written atomically to `~/.pi/agent/pi-companion/state.json`. On Unix the directory is 0700 and the file is created 0600 before any byte is written; a looser mode found at startup is tightened.
 
+Automation definitions, prompts, and bounded run output are stored separately in `automations.json`, using atomic replacement and private Unix permissions. Output can contain sensitive command/agent data; it is readable by paired devices. Failed or stopped runs are retained; interrupted runs are marked failed on daemon restart.
+
+### Automations
+
+Only the local admin surface can author automation scripts. Native extension and standalone MCP tools use that surface and do not start the daemon implicitly. Commands use argv without an implicit shell, but both commands and spawned Pi agents run with the OS user's permissions; this is not a sandbox. A paired device can start a previously authorized script with side effects. Disabling a definition prevents scheduling, not explicit manual runs.
+
+Automation sessions accept only question answers/cancellation from browsers. Prompts, steering, abort/plan/diff commands, uploads, and file deletion are denied server-side. Stop a run through its automation endpoint instead. Five-field UTC schedules run only while the daemon is alive, without overlapping runs or catch-up. Automatic session archiving after seven disconnected days removes registry/feed records only, never local Pi/project files.
+
 ### Web UI hardening
 
 HTML responses send a same-origin Content-Security-Policy (no third-party scripts, styles, fonts or connections), `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` and `X-Content-Type-Options: nosniff`. The UI loads nothing from the network beyond the daemon itself.
@@ -54,7 +62,7 @@ Agent deletion uses the opaque id rather than a path. Before unlinking, the daem
 
 Pi Companion does not provide:
 
-- remote shell access
+- arbitrary remote shell access (paired devices can start admin-authored automation commands)
 - arbitrary filesystem browsing
 - arbitrary tool invocation
 - direct git push/commit endpoints

package/docs/automations.md

@@ -0,0 +1,63 @@
+# Automations (0.3.0)
+
+Automations are persisted, named JSON scripts run by the Companion daemon. Open **Automations** in the navigation to view definitions, start/stop runs, and inspect timestamped run history. Click a run to view its captured output and Pi summary. Desktop console users can create, edit, delete, and enable/disable definitions; mobile and paired-device users can only inspect and start/stop them.
+
+## JSON DSL
+
+```json
+{
+  "name": "Daily repository check",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "preconditions": [
+    { "type": "command", "command": "git", "args": ["rev-parse", "--is-inside-work-tree"], "cwd": "/absolute/project" }
+  ],
+  "actions": [
+    { "type": "command", "command": "npm", "args": ["test"], "cwd": "/absolute/project", "timeoutSeconds": 600 },
+    { "type": "pi", "prompt": "Summarize the repository's current health. Do not edit files.", "cwd": "/absolute/project", "timeoutSeconds": 900 }
+  ],
+  "postActions": []
+}
+```
+
+Commands run as executable + argv, not through an implicit shell. A nonzero precondition skips the main actions. Actions execute in order. Post-actions provide a finalization stage. `schedule: null` is manual-only; otherwise use five cron fields (minute, hour, day of month, month, day of week), evaluated in **UTC**. Scheduled execution requires the daemon to remain running; it does not catch up missed executions. A definition cannot have overlapping runs. Disabling scheduling and stopping a run are separate operations.
+
+A Pi action starts `pi --mode rpc --no-session` in the specified directory. Pi must be on PATH and already configured with credentials/model settings. It exposes a read-only Companion session: the feed and questions are visible, but steering, prompts, plan changes, file uploads, and diffs are unavailable. This restriction applies to browser control, **not** the agent's own tools or filesystem access. Pi's final assistant output is stored in the run result. Supported RPC `select`, `confirm`, `input`, and `editor` questions are forwarded; terminal-only custom dialogs cannot be displayed. The native `companion_ask_user` tool falls back to these RPC dialogs for daemon-owned runs.
+
+**Security:** automations run with the daemon user's operating-system privileges. They are not sandboxed. Paired devices can start an existing automation, including commands with side effects. Pair only devices you trust, and review commands, prompts, working directories, and schedules before saving/enabling a definition. Native agent tools and MCP management use the local admin surface; do not expose that surface publicly.
+
+## Agent surface
+
+The extension registers `companion_automation` and ships the `companion-automations` skill. Operations: `list`, `get`, `create`, `update`, `delete`, `enable`, `disable`, `start`, `stop`, `runs`, and `run`. Supply `id` except for list/create, a full `automation` definition for create/update, and `runId` for run detail.
+
+```json
+{"action":"create","automation":{"name":"Check","enabled":true,"schedule":null,"preconditions":[],"actions":[{"type":"command","command":"git","args":["status","--short"],"cwd":"/absolute/project"}],"postActions":[]}}
+```
+
+Tools only contact an already-running daemon. They never download/start one or activate sharing for a normal Pi session. Start Companion explicitly via `/companion` or `npm run serve` first. Inspect the final run status rather than assuming an accepted start means success.
+
+## Standalone MCP
+
+Node >=22.17 can run the shipped stdio MCP server, without an MCP SDK dependency:
+
+```bash
+pi mcp add companion-automations -- node --experimental-strip-types --no-warnings /absolute/path/to/pi-companion/src/automation-mcp.ts
+```
+
+Other MCP clients can configure the same executable and arguments. The server exposes `companion_automation` with the same schema as the native extension tool. Configure only one surface if you want to avoid duplicate tools. It uses the default local admin address, overridable with `PI_COMPANION_URL=ws://127.0.0.1:PORT`; non-loopback management targets are rejected.
+
+## HTTP API
+
+Admin console:
+
+- `GET /api/automations` → `{automations}`; `POST` creates a definition.
+- `GET /api/automations/{id}` → definition; `PUT` replaces it; `DELETE` removes it.
+- `POST /api/automations/{id}/start` and `/stop`.
+- `GET /api/automations/{id}/runs` → `{runs}`.
+- `GET /api/automations/{id}/runs/{runId}` → run details including result.
+
+The paired-device surface requires valid device authentication and allowed Origin, and exposes only GET/start/stop. Mobile layout is a UI restriction, not a separate authentication role; local console API callers remain administrators.
+
+## Automatic archiving
+
+Disconnected/stopped session records older than seven days are archived automatically. Live command channels, active/idle sessions, and recent disconnections are retained. Archiving removes only the daemon registry/feed entries, never the project, local Pi history, or files. Automation definitions and run history are independent of session archiving.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunazgr/pi-companion",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Local-first remote control for Pi sessions: live activity feed, steering, git diff, file drop and phone pairing from a single Rust daemon.",
   "keywords": [
     "pi-package",
@@ -28,6 +28,8 @@
   "main": "src/index.ts",
   "files": [
     "src",
+    "skills",
+    "docs/automations.md",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -37,6 +39,7 @@
   },
   "scripts": {
     "serve": "npm run --silent ui:build -- --logLevel warn && cargo run -q --manifest-path server/Cargo.toml",
+    "automation:mcp": "node --experimental-strip-types --no-warnings src/automation-mcp.ts",
     "server:dev": "npm run serve",
     "server:check": "npm run ui:build && cargo check --manifest-path server/Cargo.toml",
     "ui:dev": "cd ui && vite dev",
@@ -44,13 +47,17 @@
     "check": "tsc --noEmit && npm run ui:check",
     "ui:check": "cd ui && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings",
     "test": "npm run test:extension && npm run test:server",
-    "test:extension": "node --test --experimental-transform-types --no-warnings test/*.test.ts",
-    "test:server": "cargo test --manifest-path server/Cargo.toml"
+    "test:extension": "node --test --experimental-transform-types --no-warnings test/*.test.ts ui/automation.test.ts",
+    "test:server": "cargo test --manifest-path server/Cargo.toml",
+    "test:smoke": "npm run ui:build && cargo build --manifest-path server/Cargo.toml --locked && node tools/smoke-automations.mjs"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "image": "https://raw.githubusercontent.com/ygrip/pi-companion/main/docs/dashboard.png"
   },
   "dependencies": {

package/skills/companion-automations/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: companion-automations
+description: Create, update, delete, enable, disable, run, stop, and inspect Pi Companion automations with the companion_automation tool. Use for recurring repository tasks, scheduled agent work, and automation run history.
+---
+
+# Companion automations
+
+Use `companion_automation` (native extension or standalone MCP surface). It talks only to the local admin daemon; it does not launch the daemon or enable session sharing. If unavailable, ask the user to start Companion with `/companion` or `npm run serve`.
+
+## Safety
+
+Before saving or starting an automation, confirm the user's intended command, working directory, schedule, and side effects. Do not silently schedule destructive commands, spend model quota, or turn an untrusted prompt into a recurring task. Commands and Pi runs execute with the user's OS permissions, not in a sandbox. Remote/mobile clients can inspect, start, and stop existing definitions, but cannot author them.
+
+Read the current definition with `get` before `update`, `enable`, or `disable`. Updating replaces the full definition. Preserve fields not intentionally changed. `disable` prevents scheduled runs; use `stop` separately to cancel a running automation. Definitions and run history are daemon-owned; archiving sessions never deletes local Pi data.
+
+## Definition DSL
+
+```json
+{
+  "name": "Repository check",
+  "enabled": true,
+  "schedule": "0 9 * * 1-5",
+  "preconditions": [],
+  "actions": [
+    { "type": "command", "command": "npm", "args": ["test"], "cwd": "/absolute/repo", "timeoutSeconds": 600 },
+    { "type": "pi", "prompt": "Summarize repository health. Do not edit files.", "cwd": "/absolute/repo", "timeoutSeconds": 900 }
+  ],
+  "postActions": []
+}
+```
+
+- `schedule` is a five-field **UTC** cron expression; `null` means manual only. The daemon must be running for scheduling. There is no catch-up while it is stopped.
+- Commands use executable plus argument array, **no implicit shell**. Shell syntax must never be passed as an executable. Avoid explicit shells unless the user requested and authorized them.
+- Preconditions gate execution. Actions run sequentially. Post-actions are the cleanup/finalization stage; inspect the run result to determine failures.
+- A Pi action starts a daemon-owned, read-only Companion session: users can answer asks, but cannot steer, prompt, upload, request changes, or edit its plan. The agent itself still has ordinary Pi tool permissions.
+- Pi must be installed on PATH and configured with model credentials. Its final assistant output is saved in run history.
+
+## Tool operations
+
+- `list`, `get` (`id`)
+- `create` (`automation`), `update` (`id`, full `automation`)
+- `delete`, `enable`, `disable`, `start`, `stop` (`id`)
+- `runs` (`id`), `run` (`id`, `runId`)
+
+After `start`, inspect `runs`/`run`; an accepted start is not completion. Report the actual final status and stored result. Do not retry a side-effecting run automatically after an ambiguous network error.

package/src/automation-mcp.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/** Standalone stdio MCP surface. Run with Node >=22.17 (native TypeScript stripping). */
+import { automationTool, executeAutomation, type AutomationParams } from "./automation.ts";
+
+const inFlight = new Map<string | number, AbortController>();
+let output = Promise.resolve();
+function send(record: unknown) {
+  const line = JSON.stringify(record) + "\n";
+  output = output.then(() => new Promise<void>((resolve, reject) => {
+    process.stdout.write(line, error => error ? reject(error) : resolve());
+  }));
+  void output.catch(() => { process.exitCode = 1; process.stdin.destroy(); });
+}
+const error = (id: unknown, code: number, message: string) => send({ jsonrpc: "2.0", id, error: { code, message } });
+async function receive(line: string) {
+  let message: { jsonrpc?: string; id?: string | number; method?: string; params?: Record<string, unknown> };
+  try { message = JSON.parse(line); }
+  catch { error(null, -32700, "Invalid JSON"); return; }
+  if (!message || message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    error(message?.id ?? null, -32600, "Invalid JSON-RPC request"); return;
+  }
+  if (message.method === "notifications/cancelled") {
+    const id = message.params?.requestId;
+    if (typeof id === "string" || typeof id === "number") inFlight.get(id)?.abort();
+    return;
+  }
+  if (message.id === undefined) return;
+  const id = message.id;
+  const reply = (result: unknown) => send({ jsonrpc: "2.0", id, result });
+  switch (message.method) {
+    case "initialize": {
+      const versions = ["2025-06-18", "2025-03-26", "2024-11-05"];
+      const requested = message.params?.protocolVersion;
+      reply({ protocolVersion: versions.includes(String(requested)) ? requested : versions[0], capabilities: { tools: {} }, serverInfo: { name: "pi-companion-automations", version: "0.3.0" } });
+      return;
+    }
+    case "ping": reply({}); return;
+    case "tools/list": reply({ tools: [automationTool] }); return;
+    case "tools/call": {
+      if (message.params?.name !== automationTool.name) { error(id, -32602, "Unknown tool"); return; }
+      const args = message.params?.arguments;
+      if (!args || typeof args !== "object" || Array.isArray(args)) { error(id, -32602, "Expected tool arguments"); return; }
+      const controller = new AbortController();
+      inFlight.set(id, controller);
+      try {
+        const result = await executeAutomation(args as AutomationParams, controller.signal);
+        reply({ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
+      } catch (failure) {
+        reply({ isError: true, content: [{ type: "text", text: String(failure instanceof Error ? failure.message : failure) }] });
+      } finally { inFlight.delete(id); }
+      return;
+    }
+    default: error(id, -32601, "Method not found");
+  }
+}
+
+// Split only LF: Unicode line separators are legal inside JSON string values.
+let buffer = Buffer.alloc(0);
+for await (const chunk of process.stdin) {
+  buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+  let newline: number;
+  while ((newline = buffer.indexOf(10)) !== -1) {
+    const line = buffer.subarray(0, newline).toString("utf8").replace(/\r$/, "");
+    buffer = buffer.subarray(newline + 1);
+    if (Buffer.byteLength(line) > 1024 * 1024) { error(null, -32600, "Request too large"); continue; }
+    if (line.trim()) void receive(line);
+  }
+  if (buffer.length > 1024 * 1024) { error(null, -32600, "Request too large"); process.stdin.destroy(); break; }
+}
+for (const controller of inFlight.values()) controller.abort();
+await output;

package/src/automation.ts

@@ -0,0 +1,105 @@
+import { adminHttpUrl } from "./daemon.ts";
+
+export type AutomationAction =
+  | { type: "command"; command: string; args: string[]; cwd?: string; timeoutSeconds?: number }
+  | { type: "pi"; prompt: string; cwd: string; timeoutSeconds?: number };
+export type AutomationDefinition = {
+  name: string;
+  enabled: boolean;
+  schedule: string | null;
+  preconditions: AutomationAction[];
+  actions: AutomationAction[];
+  postActions: AutomationAction[];
+};
+export type AutomationParams = {
+  action: "list" | "get" | "create" | "update" | "delete" | "enable" | "disable" | "start" | "stop" | "runs" | "run";
+  id?: string;
+  runId?: string;
+  automation?: AutomationDefinition;
+};
+
+const actionSchema = {
+  oneOf: [
+    { type: "object", additionalProperties: false, required: ["type", "command", "args"], properties: {
+      type: { const: "command" }, command: { type: "string", minLength: 1 },
+      args: { type: "array", items: { type: "string" } }, cwd: { type: "string" },
+      timeoutSeconds: { type: "integer", minimum: 1, maximum: 86400 }
+    } },
+    { type: "object", additionalProperties: false, required: ["type", "prompt", "cwd"], properties: {
+      type: { const: "pi" }, prompt: { type: "string", minLength: 1 }, cwd: { type: "string", minLength: 1 },
+      timeoutSeconds: { type: "integer", minimum: 1, maximum: 86400 }
+    } }
+  ]
+};
+
+export const automationTool = {
+  name: "companion_automation",
+  description: "Manage Pi Companion automations: list, get, create, update, delete, enable, disable, start, stop, runs, or run detail. Definitions use preconditions, actions, postActions and optional five-field UTC cron schedule. Commands execute argv without a shell. Mutations require the user's authorization; running actions has the computer user's permissions. Does not start the daemon or enable session sharing.",
+  inputSchema: {
+    type: "object", additionalProperties: false, required: ["action"],
+    properties: {
+      action: { type: "string", enum: ["list", "get", "create", "update", "delete", "enable", "disable", "start", "stop", "runs", "run"] },
+      id: { type: "string", minLength: 1 }, runId: { type: "string", minLength: 1 },
+      automation: {
+        type: "object", additionalProperties: false,
+        required: ["name", "enabled", "schedule", "preconditions", "actions", "postActions"],
+        properties: {
+          name: { type: "string", minLength: 1 }, enabled: { type: "boolean" },
+          schedule: { type: ["string", "null"], description: "Five-field UTC cron; null for manual only." },
+          preconditions: { type: "array", items: actionSchema },
+          actions: { type: "array", minItems: 1, items: actionSchema },
+          postActions: { type: "array", items: actionSchema }
+        }
+      }
+    }
+  }
+};
+
+/** Explicit tool calls only: never probe, download, or launch a daemon here. */
+export async function executeAutomation(params: AutomationParams, signal?: AbortSignal) {
+  const actions = ['list', 'get', 'create', 'update', 'delete', 'enable', 'disable', 'start', 'stop', 'runs', 'run'];
+  if (!params || typeof params !== 'object' || !actions.includes(params.action)) throw new Error("Unknown automation action.");
+  if (params.id !== undefined && (typeof params.id !== 'string' || !params.id.trim())) throw new Error("id must be a nonempty string.");
+  if (params.runId !== undefined && (typeof params.runId !== 'string' || !params.runId.trim())) throw new Error("runId must be a nonempty string.");
+  const base = adminHttpUrl();
+  const target = new URL(base);
+  if (!['127.0.0.1', 'localhost', '[::1]', '::1'].includes(target.hostname) || !['http:', 'https:'].includes(target.protocol)) {
+    throw new Error("Automation management requires the local Companion admin address.");
+  }
+  const request = async (path: string, method = "GET", body?: unknown) => {
+    const response = await fetch(base + path, {
+      method,
+      headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000)
+    });
+    if (!response.ok) throw new Error(`Companion ${response.status}: ${await response.text()}`);
+    return response.status === 204 ? { ok: true } : await response.json();
+  };
+  if (params.action === "list") return request("/api/automations");
+  if (params.action === "create") {
+    if (!params.automation) throw new Error("create requires automation.");
+    return request("/api/automations", "POST", params.automation);
+  }
+  if (!params.id) throw new Error(`${params.action} requires id.`);
+  const path = "/api/automations/" + encodeURIComponent(params.id);
+  switch (params.action) {
+    case "get": return request(path);
+    case "update":
+      if (!params.automation) throw new Error("update requires a complete automation definition.");
+      return request(path, "PUT", params.automation);
+    case "delete": return request(path, "DELETE");
+    case "enable": case "disable": {
+      const current = await request(path) as AutomationDefinition;
+      // PUT only definition fields, never server-generated metadata.
+      const { name, schedule, preconditions, actions, postActions } = current;
+      return request(path, "PUT", { name, schedule, preconditions, actions, postActions, enabled: params.action === "enable" });
+    }
+    case "start": case "stop": return request(path + "/" + params.action, "POST");
+    case "runs": return request(path + "/runs");
+    case "run":
+      if (!params.runId) throw new Error("run requires runId.");
+      return request(path + "/runs/" + encodeURIComponent(params.runId));
+    default: throw new Error("Unknown automation action.");
+  }
+}

package/src/bridge.ts

@@ -5,6 +5,7 @@ import WebSocket from "ws";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { relayDialogs, ToolDialogRelay, type AskChannel, type AskInput } from "./ask.js";
 import { ensureDaemon } from "./daemon.js";
+import { TelemetryRelay } from "./telemetry.js";
 import type { AskAnswers, AskRequest, BridgeMessage, ServerMessage, SessionSnapshot, TempFile } from "./protocol.js";
 
 const execFileAsync = promisify(execFile);
@@ -17,6 +18,10 @@ export class CompanionBridge implements AskChannel {
   private ctx?: ExtensionContext;
   private reconnect?: NodeJS.Timeout;
   private heartbeat?: NodeJS.Timeout;
+  private metadataTimer?: NodeJS.Timeout;
+  private telemetryRequestedAt = 0;
+  private restoreStatus?: () => void;
+  private telemetry = new TelemetryRelay();
   private closed = false;
   private activated = false;
   private restoreDialogs?: () => void;
@@ -44,22 +49,55 @@ export class CompanionBridge implements AskChannel {
   setContext(ctx: ExtensionContext) {
     this.ctx = ctx;
     if (this.activated && this.snapshot.remoteEnabled && ctx.hasUI && !this.restoreDialogs) this.restoreDialogs = relayDialogs(ctx.ui, this, this.toolDialogs);
-    const name = this.pi.getSessionName() ?? this.snapshot.name;
-    this.snapshot = {
-      ...this.snapshot,
-      name,
-      cwd: ctx.cwd,
-      shortTitle: name?.trim() || ctx.cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi",
-      mainModel: ctx.model?.id,
-      effort: ctx.thinkingLevel,
-      status: ctx.isIdle() ? "idle" : "active"
-    };
+    this.refreshMetadata();
   }
 
   setName(name?: string) {
-    this.snapshot.name = name;
+    this.snapshot.name = name ?? null;
     this.snapshot.shortTitle = name?.trim() || this.snapshot.cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi";
-    this.send({ type: "session.update", session: { name, shortTitle: this.snapshot.shortTitle } });
+    this.send({ type: "session.update", session: { name: name ?? null, shortTitle: this.snapshot.shortTitle } });
+  }
+
+  /** Context getters remain live while idle; send only changed metadata, including explicit clears. */
+  refreshMetadata() {
+    const ctx = this.ctx;
+    if (!ctx || this.closed) return;
+    const cwd = ctx.cwd || ctx.sessionManager?.getCwd?.() || process.cwd();
+    const name = this.pi.getSessionName() ?? null;
+    if ((this.snapshot.mainModel ?? null) !== (ctx.model?.id ?? null)) this.telemetry.invalidateContext();
+    const next = {
+      name, cwd,
+      shortTitle: name?.trim() || cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi",
+      mainModel: ctx.model?.id ?? null,
+      effort: ctx.thinkingLevel ?? this.pi.getThinkingLevel?.() ?? null,
+      telemetry: this.telemetry.snapshot(ctx)
+    };
+    const patch: Partial<SessionSnapshot> = {};
+    for (const key of Object.keys(next) as Array<keyof typeof next>) {
+      if (JSON.stringify(this.snapshot[key]) !== JSON.stringify(next[key])) Object.assign(patch, { [key]: next[key] });
+    }
+    Object.assign(this.snapshot, patch);
+    if (Object.keys(patch).length) this.send({ type: "session.update", session: patch });
+    if (this.activated && this.snapshot.remoteEnabled && Date.now() - this.telemetryRequestedAt >= 30_000) this.requestTelemetry();
+  }
+
+  invalidateContext() {
+    this.telemetry.invalidateContext();
+  }
+
+  ingestTelemetry(value: unknown, source: string) {
+    if (!this.isActivated() || !this.snapshot.remoteEnabled) return;
+    const id = value && typeof value === "object" ? (value as { sessionId?: unknown }).sessionId : undefined;
+    if (id !== undefined && id !== this.sessionId && id !== this.ctx?.sessionManager?.getSessionId?.()) return;
+    this.telemetry.ingest(value, source);
+    this.refreshMetadata();
+  }
+
+  private requestTelemetry() {
+    this.telemetryRequestedAt = Date.now();
+    try {
+      this.pi.events?.emit("companion:telemetry:request", { sessionId: this.ctx?.sessionManager?.getSessionId?.(), companionSessionId: this.sessionId });
+    } catch { /* A failing third-party responder must never interrupt sharing. */ }
   }
 
   setRemoteEnabled(remoteEnabled: boolean) {
@@ -73,6 +111,10 @@ export class CompanionBridge implements AskChannel {
     // End only Companion sharing: Pi itself and its local history keep running.
     this.restoreDialogs?.();
     this.restoreDialogs = undefined;
+    this.restoreStatus?.();
+    this.restoreStatus = undefined;
+    if (this.metadataTimer) clearInterval(this.metadataTimer);
+    this.metadataTimer = undefined;
     for (const entry of [...this.asks.values()]) entry.settle(null);
     for (const pending of this.pendingDeletes.values()) {
       clearTimeout(pending.timer);
@@ -99,6 +141,23 @@ export class CompanionBridge implements AskChannel {
   activate() {
     this.activated = true;
     if (this.snapshot.remoteEnabled && this.ctx?.hasUI && !this.restoreDialogs) this.restoreDialogs = relayDialogs(this.ctx.ui, this, this.toolDialogs);
+    if (!this.snapshot.remoteEnabled) return;
+    const ui = this.ctx?.ui;
+    if (ui && typeof ui.setStatus === "function" && !this.restoreStatus) {
+      const original = ui.setStatus;
+      const relay = this.telemetry;
+      const wrapped: typeof original = function(key, value) {
+        original.call(ui, key, value);
+        relay.status(key, value);
+      };
+      ui.setStatus = wrapped;
+      this.restoreStatus = () => { if (ui.setStatus === wrapped) ui.setStatus = original; };
+    }
+    if (!this.metadataTimer) {
+      this.metadataTimer = setInterval(() => this.refreshMetadata(), 1000);
+      this.metadataTimer.unref();
+    }
+    this.refreshMetadata();
   }
 
   isActivated() {
@@ -170,6 +229,10 @@ export class CompanionBridge implements AskChannel {
     this.closed = true;
     this.restoreDialogs?.();
     this.restoreDialogs = undefined;
+    this.restoreStatus?.();
+    this.restoreStatus = undefined;
+    if (this.metadataTimer) clearInterval(this.metadataTimer);
+    this.metadataTimer = undefined;
     for (const entry of [...this.asks.values()]) entry.settle(null);
     if (this.reconnect) clearTimeout(this.reconnect);
     if (this.heartbeat) clearTimeout(this.heartbeat);

package/src/index.ts

@@ -3,6 +3,7 @@ import { Type } from "typebox";
 import { formatAnswers, toQuestions } from "./ask.js";
 import { CompanionBridge } from "./bridge.js";
 import { adminHttpUrl, ensureDaemon } from "./daemon.js";
+import { automationTool, executeAutomation, type AutomationParams } from "./automation.ts";
 
 const AskOptionParam = Type.Union([
   Type.String(),
@@ -71,6 +72,11 @@ export default function companionExtension(pi: ExtensionAPI) {
   let bridge = new CompanionBridge(pi);
   let sharingGeneration = 0;
 
+  // Any extension can publish the neutral contract. No dependency on a particular footer/provider.
+  for (const channel of ["companion:telemetry", "usage:update", "session:usage", "provider:usage"]) {
+    pi.events?.on(channel, value => bridge.ingestTelemetry(value, channel));
+  }
+
   pi.on("session_start", (_event, ctx) => {
     // Switching or starting a Pi session must not inherit the previous opt-in.
     sharingGeneration += 1;
@@ -84,6 +90,7 @@ export default function companionExtension(pi: ExtensionAPI) {
     bridge.setName(event.name);
   });
   pi.on("model_select", (_event, ctx) => {
+    bridge.invalidateContext();
     bridge.setContext(ctx);
   });
   pi.on("thinking_level_select", (_event, ctx) => {
@@ -99,6 +106,15 @@ export default function companionExtension(pi: ExtensionAPI) {
     bridge.updateStatus("idle");
     bridge.emit("agent.end", { messages: Array.isArray((event as { messages?: unknown[] }).messages) ? (event as { messages: unknown[] }).messages.length : 0 });
   });
+  pi.on("message_end", (_event, ctx) => bridge.setContext(ctx));
+  pi.on("session_compact", (_event, ctx) => {
+    bridge.invalidateContext();
+    bridge.setContext(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    bridge.invalidateContext();
+    bridge.setContext(ctx);
+  });
   // Forward compact deltas instead of the full partial message on every token.
   pi.on("message_update", event => {
     const update = event.assistantMessageEvent;
@@ -128,6 +144,22 @@ export default function companionExtension(pi: ExtensionAPI) {
     bridge.close();
   });
 
+  pi.registerTool({
+    name: automationTool.name,
+    label: "Companion automation",
+    description: automationTool.description,
+    parameters: Type.Unsafe<AutomationParams>(automationTool.inputSchema),
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal) {
+      try {
+        const result = await executeAutomation(params, signal);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: { result, error: null as string | null } };
+      } catch (error) {
+        return { isError: true, content: [{ type: "text", text: String(error instanceof Error ? error.message : error) }], details: { result: null, error: String(error) } };
+      }
+    }
+  });
+
   pi.registerTool({
     name: "companion_ask_user",
     label: "Ask via Companion",
@@ -135,7 +167,46 @@ export default function companionExtension(pi: ExtensionAPI) {
       "Ask the user one to four questions through the Pi Companion web/phone UI. Each question can offer options (single or multi-select) and an optional free-text answer.",
     parameters: AskParams,
     executionMode: "sequential",
-    async execute(_toolCallId, params, signal) {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      // Daemon-owned RPC runs relay supported extension UI dialogs, not a second bridge.
+      // Normal sessions still require explicit /companion activation.
+      if (ctx?.mode === "rpc" && process.env.PI_COMPANION_AUTOMATION_RUN_ID) {
+        const items = params.questions?.length ? params.questions : params.question ? [{ question: params.question, options: params.options }] : [];
+        if (!items.length) return { content: [{ type: "text", text: "Provide `question` or `questions`." }], details: { questions: [], answers: null } };
+        const questions = toQuestions(items);
+        const answers: Record<string, string[]> = {};
+        for (const question of questions) {
+          if (signal?.aborted) break;
+          const choices = question.options.map(option => option.label);
+          const title = question.question + (question.options.some(option => option.description) ? "\n" + question.options.map(option => option.label + (option.description ? ": " + option.description : "")).join("\n") : "");
+          if (choices.length && !question.multiSelect) {
+            const custom = "Other (enter a response)";
+            const selected = await ctx.ui.select(title, question.allowCustom ? [...choices, custom] : choices, { signal, timeout: ASK_TIMEOUT_MS });
+            if (selected === undefined) break;
+            if (question.allowCustom && selected === custom) {
+              const value = await ctx.ui.input(question.question, "Your response", { signal, timeout: ASK_TIMEOUT_MS });
+              if (value === undefined) break;
+              answers[question.id] = [value];
+            } else answers[question.id] = [selected];
+          } else if (question.multiSelect && choices.length) {
+            answers[question.id] = [];
+            for (const choice of choices) {
+              if (signal?.aborted) break;
+              if (await ctx.ui.confirm(question.question, "Select: " + choice, { signal, timeout: ASK_TIMEOUT_MS })) answers[question.id].push(choice);
+            }
+            if (question.allowCustom) {
+              const value = await ctx.ui.input(question.question, "Optional additional response", { signal, timeout: ASK_TIMEOUT_MS });
+              if (value?.trim()) answers[question.id].push(value);
+            }
+          } else {
+            const value = await ctx.ui.input(title, question.placeholder, { signal, timeout: ASK_TIMEOUT_MS });
+            if (value === undefined) break;
+            answers[question.id] = [value];
+          }
+        }
+        const complete = !signal?.aborted && questions.every(question => question.id in answers);
+        return { content: [{ type: "text", text: complete ? formatAnswers(questions, answers) : "The user dismissed the question in Pi Companion." }], details: { questions, answers: complete ? answers : null } };
+      }
       if (!bridge.isActivated()) {
         return {
           content: [{ type: "text", text: "Pi Companion is not enabled for this session. Run /companion before asking through the dashboard." }],

package/src/protocol.ts

@@ -36,15 +36,30 @@ export type AskRequest = {
 /** Answers keyed by question id; each value lists chosen option labels and/or custom text. */
 export type AskAnswers = Record<string, string[]>;
 
+export type UsageWindow = { usedPercent: number; resetsAt?: string };
+export type ProviderUsage = {
+  provider: string;
+  source?: string;
+  updatedAt: string;
+  weekly?: UsageWindow;
+  fiveHour?: UsageWindow;
+};
+export type SessionTelemetry = {
+  context?: { tokens?: number; window?: number; percent?: number; source?: string };
+  cost?: { amount: number; currency?: string; source?: string };
+  providers?: ProviderUsage[];
+};
+
 export type SessionSnapshot = {
   id: string;
-  name?: string;
+  name?: string | null;
   cwd: string;
   pid: number;
   shortTitle: string;
   status: "active" | "idle" | "stopped";
-  mainModel?: string;
-  effort?: string;
+  mainModel?: string | null;
+  effort?: string | null;
+  telemetry?: SessionTelemetry;
   remoteEnabled: boolean;
   connectedAt: string;
   /** Questions waiting for an answer. Kept in the snapshot so late-joining browsers see them. */

package/src/telemetry.ts

@@ -0,0 +1,145 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ProviderUsage, SessionTelemetry, UsageWindow } from "./protocol.js";
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const number = (value: unknown): number | undefined => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+const text = (value: unknown): string | undefined => typeof value === "string" && value.trim() ? value.slice(0, 160) : undefined;
+function timestamp(value: unknown): string | undefined {
+  const millis = typeof value === "number" ? (value < 1e12 ? value * 1000 : value) : typeof value === "string" ? Date.parse(value) : NaN;
+  return Number.isFinite(millis) && Math.abs(millis) <= 8.64e15 ? new Date(millis).toISOString() : undefined;
+}
+function usageWindow(value: unknown): UsageWindow | undefined {
+  const raw = record(value);
+  if (!raw) return;
+  const remaining = number(raw.remainingPercent);
+  const usedPercent = number(raw.usedPercent ?? raw.used_percent) ?? (remaining !== undefined && remaining <= 100 ? 100 - remaining : undefined);
+  if (usedPercent === undefined || usedPercent > 100) return;
+  return { usedPercent, resetsAt: timestamp(raw.resetsAt ?? raw.resetAt ?? raw.reset_at) };
+}
+
+/** Allowlisted, provider-neutral input; never relay arbitrary extension data or credentials. */
+export function normalizeTelemetry(value: unknown, source = "extension", now = Date.now()): SessionTelemetry {
+  const raw = record(value);
+  if (!raw) return {};
+  const result: SessionTelemetry = {};
+  const context = record(raw.context ?? raw.contextUsage);
+  if (context) {
+    const tokens = number(context.tokens);
+    const window = number(context.window ?? context.contextWindow);
+    const percent = number(context.percent) ?? (tokens !== undefined && window ? tokens / window * 100 : undefined);
+    if (tokens !== undefined || percent !== undefined) result.context = { tokens, window, percent, source };
+  }
+  const cost = record(raw.cost);
+  const amount = number(cost?.amount ?? cost?.total ?? raw.cost);
+  if (amount !== undefined) result.cost = { amount, currency: text(cost?.currency) ?? "USD", source };
+  const providers = Array.isArray(raw.providers) ? raw.providers.slice(0, 100) : raw.provider ? [raw] : [];
+  const normalized: ProviderUsage[] = [];
+  for (const item of providers) {
+    const provider = record(item);
+    const name = text(provider?.provider);
+    if (!provider || !name) continue;
+    const weekly = usageWindow(provider.weekly ?? provider.sevenDay ?? provider.seven_day);
+    const fiveHour = usageWindow(provider.fiveHour ?? provider.five_hour);
+    if (!weekly && !fiveHour) continue;
+    normalized.push({ provider: name, source, updatedAt: timestamp(provider.updatedAt) ?? new Date(now).toISOString(), weekly, fiveHour });
+  }
+  if (normalized.length) result.providers = normalized;
+  return result;
+}
+
+/** Independent sources may supply different fields; one broken/missing adapter cannot erase another. */
+export class TelemetryRelay {
+  private sources = new Map<string, { telemetry: SessionTelemetry; contextAt?: number; costAt?: number }>();
+
+  ingest(value: unknown, fallbackSource = "extension", now = Date.now()) {
+    const raw = record(value);
+    const source = text(raw?.source) ?? fallbackSource;
+    const telemetry = normalizeTelemetry(raw?.telemetry ?? value, source, now);
+    if (!Object.keys(telemetry).length) return;
+    const previousEntry = this.sources.get(source);
+    const previous = previousEntry?.telemetry;
+    const providers = new Map(previous?.providers?.map(provider => [provider.provider, provider]));
+    for (const provider of telemetry.providers ?? []) {
+      const old = providers.get(provider.provider);
+      // A delayed adapter response must not roll a newer provider snapshot backward.
+      if (!old || Date.parse(provider.updatedAt) >= Date.parse(old.updatedAt)) providers.set(provider.provider, provider);
+    }
+    this.sources.delete(source);
+    this.sources.set(source, {
+      telemetry: { ...previous, ...telemetry, providers: [...providers.values()] },
+      contextAt: telemetry.context ? now : previousEntry?.contextAt,
+      costAt: telemetry.cost ? now : previousEntry?.costAt
+    });
+    if (this.sources.size > 100) this.sources.delete(this.sources.keys().next().value!);
+  }
+
+  /** Token estimates from the old projection/model are not valid after compaction or a switch. */
+  invalidateContext() {
+    for (const entry of this.sources.values()) {
+      delete entry.telemetry.context;
+      delete entry.contextAt;
+    }
+  }
+
+  /** Legacy status producers need no Companion dependency. Explicit labels avoid ambiguous numbers. */
+  status(key: string, value: string | undefined) {
+    if (!value) { this.sources.delete("status:" + key); return; }
+    const plain = value.replace(/\x1b\[[0-9;]*m/g, "");
+    const telemetry: Record<string, unknown> = { source: "status:" + key };
+    const context = plain.match(/(?:context|ctx)\s*[:=]?\s*([\d.]+)%/i);
+    const labelledCost = plain.match(/cost\s*[:=]?\s*\$([\d.]+)/i);
+    const cost = labelledCost ?? (/cost|usage|token|footer|context/i.test(key) ? plain.match(/\$([\d.]+)/) : null);
+    if (context) telemetry.context = { percent: Number(context[1]) };
+    if (cost) telemetry.cost = { amount: Number(cost[1]) };
+    const weekly = plain.match(/(?:weekly|7d|7-day)\s*[:=]?\s*([\d.]+)%\s*(left|remaining|used)?/i);
+    const fiveHour = plain.match(/(?:5h|5-hour)\s*[:=]?\s*([\d.]+)%\s*(left|remaining|used)?/i);
+    const window = (match: RegExpMatchArray | null) => match ? { usedPercent: /left|remaining/i.test(match[2] ?? "") ? 100 - Number(match[1]) : Number(match[1]) } : undefined;
+    const provider = plain.match(/provider\s*[:=]\s*([\w.-]+)/i)?.[1];
+    if (provider && (weekly || fiveHour)) telemetry.providers = [{ provider, weekly: window(weekly), fiveHour: window(fiveHour) }];
+    this.ingest(telemetry);
+  }
+
+  snapshot(ctx: ExtensionContext | undefined, now = Date.now()): SessionTelemetry {
+    const result: SessionTelemetry = {};
+    const providers = new Map<string, ProviderUsage>();
+    let latestContext = -Infinity;
+    let latestCost = -Infinity;
+    for (const { telemetry, contextAt, costAt } of this.sources.values()) {
+      if (telemetry.context && contextAt !== undefined && now - contextAt <= 300_000 && contextAt >= latestContext) {
+        result.context = telemetry.context;
+        latestContext = contextAt;
+      }
+      if (telemetry.cost && costAt !== undefined && now - costAt <= 300_000 && costAt >= latestCost) {
+        result.cost = telemetry.cost;
+        latestCost = costAt;
+      }
+      for (const provider of telemetry.providers ?? []) {
+        const old = providers.get(provider.provider);
+        if (!old || Date.parse(provider.updatedAt) >= Date.parse(old.updatedAt)) providers.set(provider.provider, provider);
+      }
+    }
+    if (providers.size) result.providers = [...providers.values()];
+    try {
+      const native = ctx?.getContextUsage?.();
+      if (native) {
+        // Native unknown after compaction is authoritative: do not resurrect stale extension tokens.
+        result.context = { tokens: number(native.tokens), window: number(native.contextWindow), percent: number(native.percent), source: "native" };
+      }
+    } catch { /* Older runtimes/other extensions may not implement this getter. */ }
+    try {
+      const entries = ctx?.sessionManager?.getEntries?.() ?? [];
+      let total = 0;
+      let known = false;
+      for (const entry of entries) {
+        const raw = record(entry);
+        const message = record(raw?.message);
+        const usage = record(raw?.type === "message" ? message?.usage : ["usage", "compaction", "branch_summary"].includes(String(raw?.type)) ? raw?.usage : undefined);
+        const cost = number(record(usage?.cost)?.total);
+        if (cost !== undefined) { known = true; total += cost; }
+      }
+      if (known && Number.isFinite(total)) result.cost = { amount: total, currency: "USD", source: "native" };
+    } catch { /* Preserve extension estimate when native usage is unavailable. */ }
+    return result;
+  }
+}