@linkshell/wire 0.2.30 → 0.2.32

package/src/relay-client.ts

@@ -52,6 +52,8 @@ export interface RelayClientOptions {
 /** Errors no retry soon will fix (wrong key, no account support, no subscription). */
 const LASTING_ERRORS = new Set(["bad_identity", "accounts_disabled", "not_admitted"]);
 const LASTING_RETRY_MS = 2 * 60_000;
+const HANDSHAKE_TIMEOUT_MS = 15_000;
+const STABLE_ONLINE_MS = 15_000;
 
 export class RelayRequestError extends Error {
   constructor(
@@ -68,7 +70,11 @@ export class RelayClient {
   private socket?: RelaySocket;
   private statusValue: RelayStatus = "offline";
   private attempt = 0;
+  private replacedCount = 0;
+  private onlineAt = 0;
   private timer?: ReturnType<typeof setTimeout>;
+  private handshakeTimer?: ReturnType<typeof setTimeout>;
+  private stableTimer?: ReturnType<typeof setTimeout>;
   private pinger?: ReturnType<typeof setInterval>;
   private probeTimer?: ReturnType<typeof setTimeout>;
   /** When the current socket last received anything. */
@@ -77,7 +83,7 @@ export class RelayClient {
   private readonly pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }>();
   private readonly statusListeners = new Set<(status: RelayStatus, error?: { code: string; message: string }) => void>();
   private readonly frameListeners = new Set<(from: PublicIdentity, via: "paired" | "account", frame: TunnelFrame) => void>();
-  private readonly undeliverableListeners = new Set<(to: string, reason: string) => void>();
+  private readonly undeliverableListeners = new Set<(to: string, reason: string, channel?: string) => void>();
   private readonly eventListeners = new Map<string, Set<(data: unknown) => void>>();
   private readonly waiters = new Set<() => void>();
   /** Account the gateway recognised on the last connection. */
@@ -104,7 +110,7 @@ export class RelayClient {
     return () => this.frameListeners.delete(listener);
   }
 
-  onUndeliverable(listener: (to: string, reason: string) => void): () => void {
+  onUndeliverable(listener: (to: string, reason: string, channel?: string) => void): () => void {
     this.undeliverableListeners.add(listener);
     return () => this.undeliverableListeners.delete(listener);
   }
@@ -119,12 +125,17 @@ export class RelayClient {
 
   start(): void {
     if (this.statusValue === "connecting" || this.statusValue === "online") return;
+    clearTimeout(this.timer);
+    this.replacedCount = 0;
     this.open();
   }
 
   stop(): void {
     this.setStatus("stopped");
     clearTimeout(this.timer);
+    this.clearHandshakeTimer();
+    this.clearStableTimer();
+    this.onlineAt = 0;
     this.stopPinging();
     this.socket?.close(1000, "stopped");
     this.socket = undefined;
@@ -137,6 +148,7 @@ export class RelayClient {
     if (this.statusValue === "stopped" || this.statusValue === "online" || this.statusValue === "connecting") return;
     clearTimeout(this.timer);
     this.attempt = 0;
+    this.replacedCount = 0;
     this.open();
   }
 
@@ -159,8 +171,12 @@ export class RelayClient {
   reauthenticate(): void {
     if (this.statusValue === "stopped") return;
     clearTimeout(this.timer);
+    this.clearHandshakeTimer();
+    this.clearStableTimer();
+    this.onlineAt = 0;
     this.stopPinging();
     this.attempt = 0;
+    this.replacedCount = 0;
     const socket = this.socket;
     this.socket = undefined;
     socket?.close(1000, "signing in again");
@@ -239,6 +255,24 @@ export class RelayClient {
     }
     this.socket = socket;
     this.heardAt = Date.now();
+    this.clearHandshakeTimer();
+    this.handshakeTimer = setTimeout(() => {
+      this.handshakeTimer = undefined;
+      if (this.socket !== socket || this.statusValue === "stopped") return;
+      this.socket = undefined;
+      this.clearStableTimer();
+      this.onlineAt = 0;
+      this.stopPinging();
+      socket.onclose = null;
+      socket.onmessage = null;
+      try {
+        socket.close(4002, "handshake timeout");
+      } catch {
+        // Already closed.
+      }
+      this.failPending("连接网关超时");
+      this.scheduleReconnect({ code: "handshake_timeout", message: "连接网关超时" });
+    }, HANDSHAKE_TIMEOUT_MS);
     let fatal: { code: string; message: string } | undefined;
     socket.onmessage = (event) => {
       if (this.socket !== socket) return;
@@ -256,10 +290,19 @@ export class RelayClient {
           void this.authenticate(frame.nonce, socket);
           return;
         case "ready":
+          this.clearHandshakeTimer();
           this.attempt = 0;
+          this.onlineAt = Date.now();
           this.account = frame.userId ? { userId: frame.userId, email: frame.email } : undefined;
           this.setStatus("online");
           this.startPinging(socket);
+          this.clearStableTimer();
+          if (this.replacedCount > 0) {
+            this.stableTimer = setTimeout(() => {
+              this.stableTimer = undefined;
+              if (this.socket === socket && this.statusValue === "online") this.replacedCount = 0;
+            }, STABLE_ONLINE_MS);
+          }
           return;
         case "res": {
           const entry = this.pending.get(frame.id);
@@ -286,7 +329,7 @@ export class RelayClient {
           return;
         }
         case "undeliverable":
-          for (const listener of this.undeliverableListeners) listener(frame.to, frame.reason);
+          for (const listener of this.undeliverableListeners) listener(frame.to, frame.reason, frame.channel);
           return;
         case "error":
           fatal = { code: frame.code, message: frame.message };
@@ -299,18 +342,40 @@ export class RelayClient {
     socket.onclose = (event) => {
       if (this.socket !== socket) return;
       this.socket = undefined;
+      this.clearHandshakeTimer();
+      const wasOnline = this.statusValue === "online";
+      if (wasOnline && this.onlineAt > 0 && Date.now() - this.onlineAt >= STABLE_ONLINE_MS) {
+        this.replacedCount = 0;
+      }
+      this.onlineAt = 0;
+      this.clearStableTimer();
       this.stopPinging();
       this.failPending("与网关的连接断开了");
       if (this.statusValue === "stopped") return;
-      // Another connection with our identity took over: don't fight it.
+      // Transient dual-socket handoffs can trigger 4000; retry a few times with wide jitter,
+      // and only stop permanently when another peer persistently reclaims the identity.
       if (event.code === 4000) {
+        this.replacedCount += 1;
         this.setStatus("offline", { code: "replaced", message: "这台设备已在别处连上网关" });
+        if (this.replacedCount > 3) return;
+        const delay = 5_000 + Math.random() * 10_000;
+        this.timer = setTimeout(() => this.open(), delay);
         return;
       }
-      this.scheduleReconnect(fatal ?? { code: "disconnected", message: event.reason || "与网关的连接断开了" });
+      this.scheduleReconnect(fatal ?? { code: "disconnected", message: event.reason || "与网关的连接断开了" }, wasOnline);
     };
   }
 
+  private clearHandshakeTimer(): void {
+    clearTimeout(this.handshakeTimer);
+    this.handshakeTimer = undefined;
+  }
+
+  private clearStableTimer(): void {
+    clearTimeout(this.stableTimer);
+    this.stableTimer = undefined;
+  }
+
   private startPinging(socket: RelaySocket): void {
     this.stopPinging();
     const every = this.options.pingMs ?? 15_000;
@@ -348,6 +413,13 @@ export class RelayClient {
   private drop(socket: RelaySocket, message: string): void {
     if (this.socket !== socket) return;
     this.socket = undefined;
+    this.clearHandshakeTimer();
+    const wasOnline = this.statusValue === "online";
+    if (wasOnline && this.onlineAt > 0 && Date.now() - this.onlineAt >= STABLE_ONLINE_MS) {
+      this.replacedCount = 0;
+    }
+    this.onlineAt = 0;
+    this.clearStableTimer();
     this.stopPinging();
     socket.onclose = null;
     socket.onmessage = null;
@@ -361,7 +433,7 @@ export class RelayClient {
     this.failPending("与网关的连接断开了");
     if (this.statusValue === "stopped") return;
     this.attempt = 0;
-    this.scheduleReconnect({ code: "disconnected", message });
+    this.scheduleReconnect({ code: "disconnected", message }, wasOnline);
   }
 
   private async authenticate(nonce: string, socket: RelaySocket): Promise<void> {
@@ -386,14 +458,18 @@ export class RelayClient {
     });
   }
 
-  private scheduleReconnect(error: { code: string; message: string }): void {
+  private scheduleReconnect(error: { code: string; message: string }, wasOnline = this.statusValue === "online"): void {
     this.setStatus("offline", error);
     const min = this.options.minBackoffMs ?? 500;
     const max = this.options.maxBackoffMs ?? 30_000;
     // Still tried now and then (a subscription can be bought, a key re-registered), and at once
     // on reconnectNow, but not every 30 s for as long as the program runs.
     const floor = LASTING_ERRORS.has(error.code) ? LASTING_RETRY_MS : 0;
-    const delay = Math.max(floor, Math.min(max, min * 2 ** this.attempt)) * (0.75 + Math.random() * 0.5);
+    // Spread out peers dropping together when a gateway restarts.
+    const delay =
+      wasOnline && this.attempt === 0 && !floor
+        ? Math.min(max, min + Math.random() * (min * 5))
+        : Math.max(floor, Math.min(max, min * 2 ** this.attempt)) * (0.75 + Math.random() * 0.5);
     this.attempt += 1;
     this.timer = setTimeout(() => this.open(), delay);
   }

package/src/relay.ts

@@ -81,7 +81,7 @@ export const serverFrameSchema = z.discriminatedUnion("t", [
   /** An encrypted frame from a peer, with the keys the gateway verified it holds. */
   z.object({ t: z.literal("from"), from: publicIdentitySchema, via: z.enum(["paired", "account"]), d: z.string() }),
   /** A frame couldn't be delivered: the peer is offline or not reachable. */
-  z.object({ t: z.literal("undeliverable"), to: z.string(), reason: z.string() }),
+  z.object({ t: z.literal("undeliverable"), to: z.string(), reason: z.string(), channel: z.string().optional() }),
   z.object({ t: z.literal("pong") }),
   z.object({ t: z.literal("error"), code: z.string(), message: z.string() }),
 ]);

package/src/rpc.ts

@@ -3,12 +3,14 @@ import { usageQuerySchema, usageReportSchema } from "./usage.js";
 import { goalChangeSchema, sessionGoalSchema } from "./goal.js";
 import { acpAgentSettingsSchema, acpFeaturesSchema, acpRemoteAgentSchema, acpProviderSchema } from "./acp.js";
 import { editorRequestSchema, editorResultSchema } from "./editor.js";
-import { liveActivityIdSchema, liveActivitySubscriptionSchema } from "./live-activity.js";
+import { liveActivityIdSchema, liveActivityPushToStartSchema, liveActivitySubscriptionSchema, wakeupNoticeSchema } from "./live-activity.js";
 import {
   backgroundTaskSchema,
   agentInfoSchema,
   gatewayStatusSchema,
+  keepAwakeModeSchema,
   machineInfoSchema,
+  machineKeepAwakeSchema,
   machineMetricsSnapshotSchema,
   portInfoSchema,
   projectSummarySchema,
@@ -24,6 +26,7 @@ import {
 import { contentBlockSchema, sessionConfigOptionSchema, sessionEventSchema, sessionNoticeSchema } from "./updates.js";
 import { sideChatSchema } from "./side.js";
 import { mcpMethods } from "./rpc-mcp.js";
+import { lsaMethods } from "./lsa.js";
 
 // ── JSON-RPC 2.0 framing ─────────────────────────────────────────────
 
@@ -77,11 +80,51 @@ export const RPC_APP_ERROR = -32000;
  * 1: side conversations (`sessions.side`), `machine.info.protocol` itself.
  * 2: session terminals (`terminals.create` `sessionId`, `TerminalInfo.sessionId`).
  * 3: whole-computer CPU and physical memory sampling (`machine.metrics`).
+ * 4: smart keep-awake & battery telemetry (`machine.keepAwake`), real git working-tree
+ *    diff/revert (`git.diff`, `git.revertFile`), fast `@file` search (`fs.projectFiles`),
+ *    clipboard & screen privacy (`clipboard.*`, `screen.privacy`), push-to-start wakeup
+ *    (`liveActivities.registerPushToStart`), and LSA Phase 1 steward RPCs (`lsa.*`).
  */
-export const HOST_PROTOCOL = 3;
+export const HOST_PROTOCOL = 4;
 
 const empty = z.looseObject({});
 
+export const gitDiffFileStatusSchema = z.enum(["modified", "added", "deleted", "renamed", "untracked"]);
+export type GitDiffFileStatus = z.infer<typeof gitDiffFileStatusSchema>;
+
+export const gitDiffFileSchema = z.object({
+  path: z.string(),
+  oldPath: z.string().optional(),
+  status: gitDiffFileStatusSchema,
+  oldText: z.string(),
+  newText: z.string(),
+  additions: z.number().int().nonnegative(),
+  deletions: z.number().int().nonnegative(),
+  binary: z.boolean().optional(),
+});
+export type GitDiffFile = z.infer<typeof gitDiffFileSchema>;
+
+export const gitDiffResultSchema = z.object({
+  files: z.array(gitDiffFileSchema),
+  truncated: z.boolean(),
+  branch: z.string().optional(),
+});
+export type GitDiffResult = z.infer<typeof gitDiffResultSchema>;
+
+export const projectFileEntrySchema = z.object({
+  path: z.string(),
+  relativePath: z.string(),
+  isDir: z.boolean().optional(),
+});
+export type ProjectFileEntry = z.infer<typeof projectFileEntrySchema>;
+
+export const screenPrivacyStateSchema = z.object({
+  curtain: z.boolean(),
+  lockOnDisconnect: z.boolean(),
+  supported: z.boolean(),
+});
+export type ScreenPrivacyState = z.infer<typeof screenPrivacyStateSchema>;
+
 export const directoryEntrySchema = z.object({
   name: z.string(),
   path: z.string(),
@@ -124,6 +167,14 @@ const acpMethods = {
 
 const coreMethods = {
   "desktop.shutdown": { params: z.object({ pid: z.number().int().positive() }), result: empty },
+  /** Opens a local path in the chosen desktop editor, file manager, or terminal (local only). */
+  "desktop.openPath": {
+    params: z.object({
+      path: z.string().min(1),
+      app: z.enum(["default", "reveal", "cursor", "vscode", "zed", "terminal"]).optional(),
+    }),
+    result: z.object({ ok: z.boolean() }),
+  },
   "usage.summary": { params: usageQuerySchema, result: usageReportSchema },
   "liveActivities.subscribe": {
     params: liveActivitySubscriptionSchema,
@@ -133,11 +184,19 @@ const coreMethods = {
     params: z.object({ activityId: liveActivityIdSchema }),
     result: z.object({}),
   },
+  "liveActivities.registerPushToStart": {
+    params: liveActivityPushToStartSchema,
+    result: z.looseObject({ ok: z.boolean().optional() }),
+  },
   "machine.info": {
     params: empty,
     result: machineInfoSchema,
   },
   "machine.metrics": { params: empty, result: machineMetricsSnapshotSchema },
+  "machine.keepAwake": {
+    params: z.object({ mode: keepAwakeModeSchema.optional() }),
+    result: machineKeepAwakeSchema,
+  },
   "machine.rename": {
     /** Empty restores the configured default; names never change peer identities. */
     params: z.object({ name: z.string().trim().max(40) }),
@@ -152,13 +211,20 @@ const coreMethods = {
       limit: z.number().int().positive().max(200).optional(),
       /** Only sessions updated strictly before this timestamp (pagination). */
       before: z.number().optional(),
+      /** Tie-breaker session id when multiple sessions share the `before` timestamp. */
+      beforeId: z.string().optional(),
       includeArchived: z.boolean().optional(),
     }),
     result: z.object({
       sessions: z.array(sessionSummarySchema),
       nextBefore: z.number().optional(),
+      nextBeforeId: z.string().optional(),
     }),
   },
+  "sessions.get": {
+    params: z.object({ sessionId: z.string().min(1) }),
+    result: z.object({ session: sessionSummarySchema.optional() }),
+  },
   /**
    * The models a new session of `agent` can start on, for choosing one before
    * there is a session (whose own list comes later, in its `ls_config`).
@@ -192,6 +258,8 @@ const coreMethods = {
       cwd: z.string().min(1),
       prompt: z.array(contentBlockSchema).optional(),
       clientMessageId: z.string().optional(),
+      /** Client-generated idempotency key so a retried create does not spawn a duplicate session. */
+      requestId: z.string().max(128).optional(),
       /** One of `agents.models`' values; absent: the agent's own default. */
       model: z.string().optional(),
       /** Explicit choices from agents.models.config, applied before the first prompt. */
@@ -508,9 +576,38 @@ const coreMethods = {
     params: z.object({ password: z.string().min(4).max(128).optional() }),
     result: z.object({ password: z.boolean() }),
   },
-  // ── Git: sessions in worktrees ──
+  // ── Git: sessions in worktrees & working-tree diffs ──
   /** What git says about `path`; no `git` when it isn't in a repository. */
   "git.info": { params: z.object({ path: z.string().min(1) }), result: z.object({ git: gitInfoSchema.optional() }) },
+  /** Real git working-tree diff (or against `base`), bounded by `maxBytes` and including untracked text files by default. */
+  "git.diff": {
+    params: z.object({
+      cwd: z.string().min(1),
+      base: z.string().optional(),
+      includeUntracked: z.boolean().optional(),
+      maxBytes: z.number().int().positive().max(10_000_000).optional(),
+    }),
+    result: gitDiffResultSchema,
+  },
+  /** Restores a tracked file or removes an untracked file strictly inside the repository root. */
+  "git.revertFile": {
+    params: z.object({ cwd: z.string().min(1), path: z.string().min(1) }),
+    result: z.object({ ok: z.boolean() }),
+  },
+  /** Commits staged or specified paths inside `cwd`'s repository. */
+  "git.commit": {
+    params: z.object({
+      cwd: z.string().min(1),
+      message: z.string().min(1).max(4000),
+      stageAll: z.boolean().optional(),
+      paths: z.array(z.string().min(1)).max(500).optional(),
+    }),
+    result: z.object({
+      sha: z.string(),
+      branch: z.string().optional(),
+      summary: z.string(),
+    }),
+  },
   /** The worktrees LinkShell made, newest first. */
   "worktrees.list": { params: empty, result: z.object({ worktrees: z.array(worktreeEntrySchema) }) },
   /** Removes a worktree and its branch. Refused (`busy`) while a session uses it, or (`dirty`) when work in it would be lost, unless `force`. */
@@ -579,14 +676,17 @@ const coreMethods = {
   },
   /**
    * Saves a file from the device into `dir`. A name that's taken gets a
-   * numbered suffix ("photo 2.jpg") rather than overwriting.
+   * numbered suffix ("photo 2.jpg") rather than overwriting; subsequent chunks
+   * pass `appendPath` and `offset` so each chunk stays below the relay frame cap.
    */
   "fs.upload": {
     params: z.object({
       dir: z.string().min(1),
       name: z.string().min(1).max(255),
-      /** base64; up to ~30 MB of file. */
-      data: z.string().max(40_000_000),
+      /** base64; up to ~20 MB single-shot upload (smaller when chunked via `offset`/`appendPath`). */
+      data: z.string().max(30_000_000),
+      offset: z.number().int().nonnegative().optional(),
+      appendPath: z.string().optional(),
     }),
     result: z.object({ path: z.string(), size: z.number().int() }),
   },
@@ -600,6 +700,27 @@ const coreMethods = {
     params: z.object({ query: z.string().min(1).max(200), limit: z.number().int().min(1).max(200).default(60) }),
     result: z.object({ entries: z.array(directoryEntrySchema), truncated: z.boolean() }),
   },
+  /** Fast project file listing under `cwd` (`git ls-files` with directory walk fallback) for `@file` autocomplete. */
+  "fs.projectFiles": {
+    params: z.object({
+      cwd: z.string().min(1),
+      query: z.string().max(200).optional(),
+      limit: z.number().int().min(1).max(2000).optional(),
+    }),
+    result: z.object({
+      files: z.array(projectFileEntrySchema),
+      truncated: z.boolean(),
+    }),
+  },
+  // ── Clipboard: encrypted host clipboard access ──
+  "clipboard.read": {
+    params: empty,
+    result: z.object({ text: z.string() }),
+  },
+  "clipboard.write": {
+    params: z.object({ text: z.string().max(2_000_000) }),
+    result: z.object({ ok: z.boolean() }),
+  },
   // ── Terminals: plain shells on the host, any command, like SSH ──
   "terminals.list": {
     params: empty,
@@ -733,6 +854,14 @@ const coreMethods = {
       problem: z.string().optional(),
     }),
   },
+  /** Privacy curtain (dim/blank physical screen while viewing remotely) and auto-lock on disconnect. */
+  "screen.privacy": {
+    params: z.object({
+      curtain: z.boolean().optional(),
+      lockOnDisconnect: z.boolean().optional(),
+    }),
+    result: screenPrivacyStateSchema,
+  },
   /** Bytes to the host's end of a stream (base64). */
   "proxy.write": {
     params: z.object({ streamId: z.string().min(1), data: z.string().max(2_000_000) }),
@@ -744,7 +873,12 @@ const coreMethods = {
   },
 } as const;
 
-export const methods: typeof coreMethods & typeof acpMethods & typeof mcpMethods = { ...coreMethods, ...acpMethods, ...mcpMethods };
+export const methods: typeof coreMethods & typeof acpMethods & typeof mcpMethods & typeof lsaMethods = {
+  ...coreMethods,
+  ...acpMethods,
+  ...mcpMethods,
+  ...lsaMethods,
+};
 
 export type MethodName = keyof typeof methods;
 export type MethodParams<M extends MethodName> = z.input<(typeof methods)[M]["params"]>;
@@ -789,6 +923,8 @@ export const notifications = {
   "proxy.data": z.object({ streamId: z.string(), data: z.string() }),
   /** The host's end of a stream closed (the server hung up, or refused). */
   "proxy.closed": z.object({ streamId: z.string(), error: z.string().optional() }),
+  /** Zero-plaintext transition wakeup metadata. */
+  "liveActivities.wakeup": wakeupNoticeSchema,
 } as const;
 
 export type NotificationName = keyof typeof notifications;

package/src/updates.ts

@@ -105,12 +105,16 @@ export const sessionUpdateSchema = z.discriminatedUnion("sessionUpdate", [
     parentToolCallId: z.string().optional(),
     messageId: z.string(),
     content: contentBlockSchema,
+    /** Replaces any buffered partial text for `messageId` (e.g. compacted turn chunks). */
+    replace: z.boolean().optional(),
   }),
   z.object({
     sessionUpdate: z.literal("agent_thought_chunk"),
     parentToolCallId: z.string().optional(),
     messageId: z.string(),
     content: contentBlockSchema,
+    /** Replaces any buffered partial thought for `messageId` (e.g. compacted turn chunks). */
+    replace: z.boolean().optional(),
   }),
   z.object({
     sessionUpdate: z.literal("tool_call"),

package/src/usage.ts

@@ -4,21 +4,133 @@ export const usageQuerySchema = z.object({
   days: z.union([z.literal(1), z.literal(7), z.literal(30)]).default(7),
   agent: z.string().min(1).max(128).default("all"),
 });
+
 export const usageTotalsSchema = z.object({
-  records: z.number(), sessions: z.number(), inputTokens: z.number(), outputTokens: z.number(),
-  cacheReadTokens: z.number(), cacheWriteTokens: z.number(), totalTokens: z.number(),
+  records: z.number(),
+  sessions: z.number(),
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  cacheReadTokens: z.number(),
+  cacheWriteTokens: z.number(),
+  totalTokens: z.number(),
+  estimatedCostUsd: z.number().nonnegative().optional(),
+});
+
+export const usageRemoteStatsSchema = z.object({
+  remoteTurns: z.number().int().nonnegative(),
+  remoteApprovals: z.number().int().nonnegative(),
 });
+
 export const usageReportSchema = z.object({
-  generatedAt: z.number(), days: z.number(), agent: z.string(), timezone: z.string(),
+  generatedAt: z.number(),
+  days: z.number(),
+  agent: z.string(),
+  timezone: z.string(),
   totals: usageTotalsSchema,
   daily: z.array(usageTotalsSchema.extend({ date: z.string() })),
   models: z.array(usageTotalsSchema.extend({ agent: z.string(), model: z.string() })),
   agents: z.array(z.object({
-    id: z.string(), label: z.string(), source: z.enum(["native", "acp"]),
-    status: z.enum(["available", "no_data"]), records: z.number(), totalTokens: z.number(), note: z.string(),
+    id: z.string(),
+    label: z.string(),
+    source: z.enum(["native", "acp"]),
+    status: z.enum(["available", "no_data"]),
+    records: z.number(),
+    totalTokens: z.number(),
+    note: z.string(),
+    estimatedCostUsd: z.number().nonnegative().optional(),
   })).optional(),
+  estimatedCostUsd: z.number().nonnegative().optional(),
+  remoteStats: usageRemoteStatsSchema.optional(),
   warnings: z.array(z.string()),
 });
+
 export type UsageQuery = z.infer<typeof usageQuerySchema>;
 export type UsageTotals = z.infer<typeof usageTotalsSchema>;
+export type UsageRemoteStats = z.infer<typeof usageRemoteStatsSchema>;
 export type UsageReport = z.infer<typeof usageReportSchema>;
+
+export interface ModelPricingPerMillion {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+export interface TokenCostInput {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+/**
+ * Reference public API pricing (USD per 1M tokens), ordered most-specific first.
+ * Subscription users (ChatGPT Plus/Pro, Claude Pro/Max) pay flat fees; this
+ * estimates the equivalent API value of work orchestrated through LinkShell.
+ */
+const MODEL_PRICING_RULES: ReadonlyArray<{ match: RegExp; pricing: ModelPricingPerMillion }> = [
+  // Anthropic Claude
+  { match: /claude[-_.]?opus[-_.]?(?:4[._][56]|5)/i, pricing: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 } },
+  { match: /opus/i, pricing: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 } },
+  { match: /sonnet/i, pricing: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 } },
+  { match: /claude[-_.]?haiku[-_.]?4[._]5/i, pricing: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 } },
+  { match: /haiku/i, pricing: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 } },
+  // OpenAI / Codex
+  { match: /(?:gpt-5|o1|o3)[-_]pro/i, pricing: { input: 15, output: 60, cacheRead: 3.75, cacheWrite: 15 } },
+  { match: /gpt-5[-_.]?mini/i, pricing: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0.25 } },
+  { match: /gpt-5[-_.]?nano/i, pricing: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0.05 } },
+  { match: /codex[-_.]?mini/i, pricing: { input: 1.5, output: 6, cacheRead: 0.375, cacheWrite: 1.5 } },
+  { match: /gpt-5|codex/i, pricing: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 1.25 } },
+  { match: /gpt-4\.1[-_.]?mini/i, pricing: { input: 0.4, output: 1.6, cacheRead: 0.1, cacheWrite: 0.4 } },
+  { match: /gpt-4\.1[-_.]?nano/i, pricing: { input: 0.1, output: 0.4, cacheRead: 0.025, cacheWrite: 0.1 } },
+  { match: /gpt-4\.1/i, pricing: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 2 } },
+  { match: /gpt-4o[-_.]?mini/i, pricing: { input: 0.15, output: 0.6, cacheRead: 0.075, cacheWrite: 0.15 } },
+  { match: /gpt-4o/i, pricing: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 2.5 } },
+  { match: /o[34][-_.]?mini/i, pricing: { input: 1.1, output: 4.4, cacheRead: 0.275, cacheWrite: 1.1 } },
+  { match: /\bo3\b|\bo1\b/i, pricing: { input: 2, output: 8, cacheRead: 0.5, cacheWrite: 2 } },
+  // Google Gemini
+  { match: /gemini.*flash/i, pricing: { input: 0.3, output: 2.5, cacheRead: 0.075, cacheWrite: 0.3 } },
+  { match: /gemini/i, pricing: { input: 1.25, output: 10, cacheRead: 0.3125, cacheWrite: 1.25 } },
+  // xAI Grok & DeepSeek
+  { match: /grok/i, pricing: { input: 3, output: 15, cacheRead: 0.75, cacheWrite: 3 } },
+  { match: /deepseek/i, pricing: { input: 0.27, output: 1.1, cacheRead: 0.07, cacheWrite: 0.27 } },
+];
+
+const DEFAULT_PRICING_PER_MILLION: ModelPricingPerMillion = {
+  input: 2,
+  output: 8,
+  cacheRead: 0.2,
+  cacheWrite: 2,
+};
+
+export function modelPricingPerMillionUsd(model: string): ModelPricingPerMillion {
+  const normalized = model.trim();
+  for (const rule of MODEL_PRICING_RULES) {
+    if (rule.match.test(normalized)) return rule.pricing;
+  }
+  return DEFAULT_PRICING_PER_MILLION;
+}
+
+function safeTokenCount(value: number | undefined): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Pure reference cost estimator (in USD) for a model and non-overlapping token bucket totals.
+ */
+export function estimateModelCostUsd(model: string, totals: TokenCostInput): number {
+  const input = safeTokenCount(totals.inputTokens);
+  const output = safeTokenCount(totals.outputTokens);
+  const cacheRead = safeTokenCount(totals.cacheReadTokens);
+  const cacheWrite = safeTokenCount(totals.cacheWriteTokens);
+  if (input === 0 && output === 0 && cacheRead === 0 && cacheWrite === 0) return 0;
+
+  const rate = modelPricingPerMillionUsd(model);
+  const rawUsd =
+    (input * rate.input +
+      output * rate.output +
+      cacheRead * rate.cacheRead +
+      cacheWrite * rate.cacheWrite) /
+    1_000_000;
+  return Math.round(rawUsd * 1_000_000) / 1_000_000;
+}