pi-opencode-go-provider 1.1.21 → 1.1.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,259 @@
1
+ /**
2
+ * Unit tests for sync-policy.ts — the provider-agnostic quiet startup sync
3
+ * policy (TTL, key fingerprint, failure backoff, cross-process lock).
4
+ *
5
+ * Provider-agnostic: copied verbatim into every pi-*-provider repo alongside
6
+ * sync-policy.ts.
7
+ */
8
+
9
+ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
10
+ import { execFile } from "node:child_process";
11
+ import fs from "node:fs";
12
+ import os from "node:os";
13
+ import path from "node:path";
14
+ import { fileURLToPath } from "node:url";
15
+ import {
16
+ DEFAULT_SYNC_TTL_MS,
17
+ SYNC_TTL_ENV,
18
+ acquireModelSync,
19
+ cacheChangedSinceLoad,
20
+ keyFingerprint,
21
+ markCacheLoaded,
22
+ planModelSync,
23
+ resolveSyncTtlMs,
24
+ syncLockPath,
25
+ syncMetaPath,
26
+ writeFileAtomic,
27
+ } from "../sync-policy";
28
+
29
+ const HOUR = 60 * 60 * 1000;
30
+ const KEY = "sk-test-secret-key";
31
+
32
+ let dir: string;
33
+ let cachePath: string;
34
+
35
+ beforeEach(() => {
36
+ vi.stubEnv(SYNC_TTL_ENV, "");
37
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-sync-policy-"));
38
+ cachePath = path.join(dir, "cache", "example-models.json");
39
+ });
40
+
41
+ afterEach(() => {
42
+ vi.unstubAllEnvs();
43
+ fs.rmSync(dir, { recursive: true, force: true });
44
+ });
45
+
46
+ function writeCache(ageMs: number, models: unknown = [{ id: "m" }]): void {
47
+ fs.mkdirSync(path.dirname(cachePath), { recursive: true });
48
+ fs.writeFileSync(cachePath, JSON.stringify(models));
49
+ const t = new Date(Date.now() - ageMs);
50
+ fs.utimesSync(cachePath, t, t);
51
+ }
52
+
53
+ function writeMeta(meta: Record<string, unknown>): void {
54
+ fs.writeFileSync(syncMetaPath(cachePath), JSON.stringify({ version: 1, ...meta }));
55
+ }
56
+
57
+ function writeLock(ageMs: number, token = "someone-else"): void {
58
+ fs.mkdirSync(path.dirname(cachePath), { recursive: true });
59
+ fs.writeFileSync(syncLockPath(cachePath), JSON.stringify({ pid: 999999, token }));
60
+ const t = new Date(Date.now() - ageMs);
61
+ fs.utimesSync(syncLockPath(cachePath), t, t);
62
+ }
63
+
64
+ describe("keyFingerprint", () => {
65
+ it("is a stable 16-hex digest that never contains the key", () => {
66
+ const fp = keyFingerprint(KEY);
67
+ expect(fp).toMatch(/^[0-9a-f]{16}$/);
68
+ expect(keyFingerprint(KEY)).toBe(fp);
69
+ expect(keyFingerprint(`${KEY}x`)).not.toBe(fp);
70
+ expect(fp).not.toContain(KEY);
71
+ });
72
+ });
73
+
74
+ describe("resolveSyncTtlMs", () => {
75
+ it("defaults to 1 hour", () => {
76
+ expect(resolveSyncTtlMs()).toBe(DEFAULT_SYNC_TTL_MS);
77
+ expect(DEFAULT_SYNC_TTL_MS).toBe(HOUR);
78
+ });
79
+
80
+ it(`honors ${SYNC_TTL_ENV} (0 = always revalidate) and ignores garbage`, () => {
81
+ vi.stubEnv(SYNC_TTL_ENV, "0");
82
+ expect(resolveSyncTtlMs()).toBe(0);
83
+ vi.stubEnv(SYNC_TTL_ENV, "120000");
84
+ expect(resolveSyncTtlMs()).toBe(120000);
85
+ vi.stubEnv(SYNC_TTL_ENV, "-5");
86
+ expect(resolveSyncTtlMs()).toBe(DEFAULT_SYNC_TTL_MS);
87
+ vi.stubEnv(SYNC_TTL_ENV, "soon");
88
+ expect(resolveSyncTtlMs()).toBe(DEFAULT_SYNC_TTL_MS);
89
+ });
90
+
91
+ it("prefers an explicit ttlMs over the env", () => {
92
+ vi.stubEnv(SYNC_TTL_ENV, "0");
93
+ expect(resolveSyncTtlMs(5000)).toBe(5000);
94
+ });
95
+ });
96
+
97
+ describe("planModelSync", () => {
98
+ it("never fetches without a key", () => {
99
+ expect(planModelSync({ cachePath, apiKey: undefined })).toEqual({ fetch: false, reason: "no-key" });
100
+ expect(planModelSync({ cachePath, apiKey: "" })).toEqual({ fetch: false, reason: "no-key" });
101
+ });
102
+
103
+ it("fetches when the cache is missing or corrupt", () => {
104
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "missing" });
105
+ fs.mkdirSync(path.dirname(cachePath), { recursive: true });
106
+ fs.writeFileSync(cachePath, "{not json");
107
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "missing" });
108
+ writeCache(0, []);
109
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "missing" });
110
+ });
111
+
112
+ it("skips inside the TTL and fetches once it expires", () => {
113
+ writeCache(10 * 60 * 1000);
114
+ writeMeta({ keyFingerprint: keyFingerprint(KEY) });
115
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: false, reason: "fresh" });
116
+ writeCache(2 * HOUR);
117
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "stale" });
118
+ vi.stubEnv(SYNC_TTL_ENV, "0");
119
+ writeCache(0);
120
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "stale" });
121
+ });
122
+
123
+ it("forces a fetch when the key changed or the cache predates the sidecar", () => {
124
+ writeCache(0);
125
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "key-changed" });
126
+ writeMeta({ keyFingerprint: keyFingerprint("old-key") });
127
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "key-changed" });
128
+ });
129
+
130
+ it("forces a fetch on demand (e.g. after /login) regardless of TTL", () => {
131
+ writeCache(0);
132
+ writeMeta({ keyFingerprint: keyFingerprint(KEY) });
133
+ expect(planModelSync({ cachePath, apiKey: KEY, force: true })).toEqual({ fetch: true, reason: "forced" });
134
+ });
135
+
136
+ it("backs off after a recent failure with the same key, unless forced", () => {
137
+ writeCache(2 * HOUR);
138
+ writeMeta({ keyFingerprint: keyFingerprint(KEY), failedAt: Date.now() - 1000, failedKeyFingerprint: keyFingerprint(KEY) });
139
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: false, reason: "backoff" });
140
+ expect(planModelSync({ cachePath, apiKey: KEY, force: true }).fetch).toBe(true);
141
+ // A different key is not held back by another key's failure.
142
+ expect(planModelSync({ cachePath, apiKey: "new-key" })).toEqual({ fetch: true, reason: "key-changed" });
143
+ // Backoff expires.
144
+ writeMeta({ keyFingerprint: keyFingerprint(KEY), failedAt: Date.now() - HOUR, failedKeyFingerprint: keyFingerprint(KEY) });
145
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: true, reason: "stale" });
146
+ });
147
+ });
148
+
149
+ describe("acquireModelSync", () => {
150
+ it("is single-flight: a second caller skips while the lock is held", () => {
151
+ const skipped: string[] = [];
152
+ const first = acquireModelSync({ cachePath, apiKey: KEY });
153
+ expect(first?.reason).toBe("missing");
154
+ expect(fs.existsSync(syncLockPath(cachePath))).toBe(true);
155
+ expect(acquireModelSync({ cachePath, apiKey: KEY, onSkip: (r) => skipped.push(r) })).toBeNull();
156
+ expect(skipped).toEqual(["locked"]);
157
+ first!.release("aborted");
158
+ expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
159
+ expect(acquireModelSync({ cachePath, apiKey: KEY })).not.toBeNull();
160
+ });
161
+
162
+ it("skips while another process holds a live lock", () => {
163
+ writeLock(1000);
164
+ const skipped: string[] = [];
165
+ expect(acquireModelSync({ cachePath, apiKey: KEY, onSkip: (r) => skipped.push(r) })).toBeNull();
166
+ expect(skipped).toEqual(["locked"]);
167
+ });
168
+
169
+ it("reclaims a stale lock left by a crashed process", () => {
170
+ writeLock(5 * 60 * 1000);
171
+ const lease = acquireModelSync({ cachePath, apiKey: KEY });
172
+ expect(lease).not.toBeNull();
173
+ lease!.release("aborted");
174
+ expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
175
+ });
176
+
177
+ it("never removes a lock it no longer owns", () => {
178
+ const lease = acquireModelSync({ cachePath, apiKey: KEY, lockStaleMs: 0 })!;
179
+ writeLock(0, "reclaimed-by-another-process");
180
+ lease.release("aborted");
181
+ expect(JSON.parse(fs.readFileSync(syncLockPath(cachePath), "utf8")).token).toBe("reclaimed-by-another-process");
182
+ });
183
+
184
+ it("records the key fingerprint on success (never the key) and the failure on error", () => {
185
+ let lease = acquireModelSync({ cachePath, apiKey: KEY })!;
186
+ writeCache(0);
187
+ lease.release("fetched");
188
+ const raw = fs.readFileSync(syncMetaPath(cachePath), "utf8");
189
+ expect(raw).not.toContain(KEY);
190
+ expect(JSON.parse(raw)).toMatchObject({ version: 1, keyFingerprint: keyFingerprint(KEY) });
191
+ expect(planModelSync({ cachePath, apiKey: KEY })).toEqual({ fetch: false, reason: "fresh" });
192
+
193
+ lease = acquireModelSync({ cachePath, apiKey: KEY, force: true })!;
194
+ lease.release("failed");
195
+ expect(JSON.parse(fs.readFileSync(syncMetaPath(cachePath), "utf8"))).toMatchObject({
196
+ keyFingerprint: keyFingerprint(KEY),
197
+ failedKeyFingerprint: keyFingerprint(KEY),
198
+ });
199
+ });
200
+
201
+ it("does not record a failure for an aborted fetch", () => {
202
+ acquireModelSync({ cachePath, apiKey: KEY })!.release("aborted");
203
+ expect(fs.existsSync(syncMetaPath(cachePath))).toBe(false);
204
+ });
205
+
206
+ it("fails open (null, no throw) when the cache dir is unwritable", () => {
207
+ // A regular file where the cache directory should be: mkdir/open fail even as root.
208
+ fs.writeFileSync(path.join(dir, "cache"), "not a directory");
209
+ const skipped: string[] = [];
210
+ expect(() => acquireModelSync({ cachePath, apiKey: KEY, onSkip: (r) => skipped.push(r) })).not.toThrow();
211
+ expect(acquireModelSync({ cachePath, apiKey: KEY })).toBeNull();
212
+ expect(skipped).toEqual(["unwritable"]);
213
+ });
214
+
215
+ // Real processes: children load sync-policy.ts via Node's built-in type stripping (Node >= 22.18).
216
+ it.skipIf(!(process.features as { typescript?: unknown }).typescript)("lets exactly one of many concurrent processes fetch", async () => {
217
+ writeCache(2 * HOUR);
218
+ writeMeta({ keyFingerprint: keyFingerprint(KEY) });
219
+ const modulePath = fileURLToPath(new URL("../sync-policy.ts", import.meta.url));
220
+ // Each child: try to acquire; the winner "fetches" for 300ms, writes the
221
+ // cache and releases. Late starters must then see a fresh cache.
222
+ const child = `
223
+ const { acquireModelSync, writeFileAtomic } = await import(${JSON.stringify(modulePath)});
224
+ const [cachePath, key] = process.argv.slice(-2);
225
+ const lease = acquireModelSync({ cachePath, apiKey: key });
226
+ if (lease) {
227
+ await new Promise((r) => setTimeout(r, 300));
228
+ writeFileAtomic(cachePath, JSON.stringify([{ id: "fresh" }]));
229
+ lease.release("fetched");
230
+ }
231
+ process.stdout.write(lease ? "fetch" : "skip");
232
+ `;
233
+ const run = () => new Promise<string>((resolve, reject) => {
234
+ execFile(process.execPath, ["--input-type=module", "-e", child, cachePath, KEY], (err, stdout) => err ? reject(err) : resolve(stdout));
235
+ });
236
+ const results = await Promise.all(Array.from({ length: 8 }, run));
237
+ expect(results.filter((r) => r === "fetch")).toHaveLength(1);
238
+ expect(results.filter((r) => r === "skip")).toHaveLength(7);
239
+ expect(fs.existsSync(syncLockPath(cachePath))).toBe(false);
240
+ }, 20000);
241
+ });
242
+
243
+ describe("cache helpers", () => {
244
+ it("writeFileAtomic replaces the file without leaving temp files", () => {
245
+ fs.mkdirSync(path.dirname(cachePath), { recursive: true });
246
+ writeFileAtomic(cachePath, "[1]");
247
+ writeFileAtomic(cachePath, "[2]");
248
+ expect(fs.readFileSync(cachePath, "utf8")).toBe("[2]");
249
+ expect(fs.readdirSync(path.dirname(cachePath))).toEqual([path.basename(cachePath)]);
250
+ });
251
+
252
+ it("cacheChangedSinceLoad spots a cache rewritten by another process", () => {
253
+ writeCache(HOUR);
254
+ markCacheLoaded(cachePath);
255
+ expect(cacheChangedSinceLoad(cachePath)).toBe(false);
256
+ writeCache(0);
257
+ expect(cacheChangedSinceLoad(cachePath)).toBe(true);
258
+ });
259
+ });
@@ -0,0 +1,146 @@
1
+ /**
2
+ * Quiet startup sync for the usage widget: /zen/go/v1/usage is polled only with
3
+ * a UI and a key, and background polls are deduped across pi processes through
4
+ * a shared snapshot (`<agentDir>/cache/opencode-go-usage.json`).
5
+ */
6
+
7
+ import { afterEach, describe, expect, it, vi } from "vitest";
8
+ import fs from "node:fs";
9
+ import os from "node:os";
10
+ import path from "node:path";
11
+ import { syncLockPath } from "../sync-policy";
12
+ import embeddedModels from "../models.json" with { type: "json" };
13
+
14
+ const PROVIDER_ID = "opencode-go";
15
+ const KEY = "sk-usage-sync-test";
16
+ const USAGE_URL = "https://opencode.ai/zen/go/v1/usage";
17
+
18
+ let home: string;
19
+ let usagePath: string;
20
+ const shutdowns: Array<() => void> = [];
21
+
22
+ afterEach(() => {
23
+ for (const shutdown of shutdowns.splice(0)) shutdown();
24
+ vi.unstubAllEnvs();
25
+ vi.unstubAllGlobals();
26
+ vi.resetModules();
27
+ if (home) fs.rmSync(home, { recursive: true, force: true });
28
+ });
29
+
30
+ function setupHome(): void {
31
+ home = fs.mkdtempSync(path.join(os.tmpdir(), `pi-${PROVIDER_ID}-usage-sync-`));
32
+ usagePath = path.join(home, "cache", `${PROVIDER_ID}-usage.json`);
33
+ vi.stubEnv("PI_CODING_AGENT_DIR", home);
34
+ vi.stubEnv("PI_PROVIDER_SYNC_TTL_MS", "");
35
+ vi.stubEnv("OPENCODE_API_KEY", "");
36
+ // A fresh model cache keeps /models out of the picture: only usage is polled.
37
+ const modelsCache = path.join(home, "cache", `${PROVIDER_ID}-models.json`);
38
+ fs.mkdirSync(path.dirname(modelsCache), { recursive: true });
39
+ fs.writeFileSync(modelsCache, JSON.stringify(embeddedModels));
40
+ }
41
+
42
+ const usagePayload = () => Response.json({
43
+ usage: {
44
+ rolling: { status: "ok", percent: 10, resetsAt: null },
45
+ weekly: { status: "ok", percent: 20, resetsAt: null },
46
+ monthly: { status: "ok", percent: 30, resetsAt: null },
47
+ },
48
+ });
49
+
50
+ /** Routes usage requests to a counted stub; anything else (e.g. /models) gets a 503. */
51
+ function stubFetch() {
52
+ const usage = vi.fn(async () => usagePayload());
53
+ vi.stubGlobal("fetch", vi.fn(async (input: unknown) => (
54
+ String(input) === USAGE_URL ? usage() : new Response("", { status: 503 })
55
+ )));
56
+ return usage;
57
+ }
58
+
59
+ async function loadExtension(options: { hasUI?: boolean; key?: string | undefined } = {}) {
60
+ vi.resetModules();
61
+ const mod = await import("../index");
62
+ const handlers = new Map<string, (...args: any[]) => any>();
63
+ const commands = new Map<string, { handler: (args: string, ctx: any) => Promise<void> }>();
64
+ mod.default({
65
+ on: (event: string, handler: (...args: any[]) => any) => handlers.set(event, handler),
66
+ registerProvider: () => {},
67
+ registerCommand: (name: string, command: any) => commands.set(name, command),
68
+ } as any);
69
+ const ui = { notify: vi.fn(), setWidget: vi.fn(), setStatus: vi.fn() };
70
+ const key = "key" in options ? options.key : KEY;
71
+ const ctx = {
72
+ hasUI: options.hasUI ?? true,
73
+ mode: "tui",
74
+ model: { provider: PROVIDER_ID, id: "kimi-k2.6" },
75
+ ui,
76
+ modelRegistry: { getApiKeyForProvider: vi.fn(async () => key) },
77
+ sessionManager: { getSessionId: () => "session-1" },
78
+ };
79
+ shutdowns.push(() => handlers.get("session_shutdown")?.({ type: "session_shutdown" }, ctx));
80
+ return {
81
+ ui,
82
+ ctx,
83
+ startSession: () => handlers.get("session_start")!({ type: "session_start" }, ctx),
84
+ turnEnd: () => handlers.get("turn_end")!({ type: "turn_end" }, ctx),
85
+ usageCommand: () => commands.get("opencode-go-usage")!.handler("", ctx),
86
+ };
87
+ }
88
+
89
+ const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
90
+ const widgetInstalled = (ui: { setWidget: ReturnType<typeof vi.fn> }) =>
91
+ ui.setWidget.mock.calls.some(([key, factory]) => key === "opencode-go-usage" && typeof factory === "function");
92
+
93
+ describe("usage polling (quiet startup sync)", () => {
94
+ it("polls once across processes; later processes render the shared snapshot", async () => {
95
+ setupHome();
96
+ const usage = stubFetch();
97
+ const first = await loadExtension();
98
+ await first.startSession();
99
+ await vi.waitFor(() => expect(widgetInstalled(first.ui)).toBe(true));
100
+ expect(usage).toHaveBeenCalledOnce();
101
+ const raw = fs.readFileSync(usagePath, "utf8");
102
+ expect(raw).not.toContain(KEY);
103
+ expect(JSON.parse(raw).snapshot.windows).toHaveLength(3);
104
+ expect(fs.existsSync(syncLockPath(usagePath))).toBe(false);
105
+
106
+ const second = await loadExtension(); // another pi process
107
+ await second.startSession();
108
+ await vi.waitFor(() => expect(widgetInstalled(second.ui)).toBe(true));
109
+ await second.turnEnd();
110
+ await settle();
111
+ expect(usage).toHaveBeenCalledOnce();
112
+ });
113
+
114
+ it("never polls without a UI (print mode, child agents)", async () => {
115
+ setupHome();
116
+ const usage = stubFetch();
117
+ const ext = await loadExtension({ hasUI: false });
118
+ await ext.startSession();
119
+ await ext.turnEnd();
120
+ await settle();
121
+ expect(usage).not.toHaveBeenCalled();
122
+ expect(fs.existsSync(usagePath)).toBe(false);
123
+ });
124
+
125
+ it("never polls without credentials", async () => {
126
+ setupHome();
127
+ const usage = stubFetch();
128
+ const ext = await loadExtension({ key: undefined });
129
+ await ext.startSession();
130
+ await settle();
131
+ expect(usage).not.toHaveBeenCalled();
132
+ expect(fs.existsSync(syncLockPath(usagePath))).toBe(false);
133
+ });
134
+
135
+ it("/opencode-go-usage always re-reads the API, even inside the shared window", async () => {
136
+ setupHome();
137
+ const usage = stubFetch();
138
+ const first = await loadExtension();
139
+ await first.startSession();
140
+ await vi.waitFor(() => expect(usage).toHaveBeenCalledOnce());
141
+ const second = await loadExtension();
142
+ await second.usageCommand();
143
+ expect(usage).toHaveBeenCalledTimes(2);
144
+ expect(second.ui.notify).toHaveBeenCalledWith(expect.stringContaining("OpenCode Go usage"), "info");
145
+ });
146
+ });
package/tsconfig.json CHANGED
@@ -18,5 +18,8 @@
18
18
  "types": ["node"],
19
19
  "verbatimModuleSyntax": true
20
20
  },
21
- "include": ["index.ts", "*.ts", "tests/**/*.ts"]
21
+ "include": ["index.ts", "*.ts", "tests/**/*.ts"],
22
+ // Vitest suites (shared verbatim across pi-*-provider repos, extensionless
23
+ // imports) are typechecked by tsconfig.vitest.json with bundler resolution.
24
+ "exclude": ["tests/sync-policy.test.ts", "tests/quiet-startup-sync.test.ts", "tests/usage-sync.test.ts"]
22
25
  }
@@ -0,0 +1,10 @@
1
+ {
2
+ "extends": "./tsconfig.json",
3
+ "exclude": [],
4
+ "compilerOptions": {
5
+ "module": "ESNext",
6
+ "moduleResolution": "Bundler",
7
+ "noUncheckedIndexedAccess": false
8
+ },
9
+ "include": ["tests/sync-policy.test.ts", "tests/quiet-startup-sync.test.ts", "tests/usage-sync.test.ts"]
10
+ }
@@ -4,10 +4,20 @@
4
4
  * Mirrors the pi-better-openai usage controller: one snapshot per session,
5
5
  * polled on a timer plus after each turn, pushed into the extension widget
6
6
  * (favoured) or the footer status line when no terminal UI is available.
7
+ *
8
+ * Quiet startup sync: polling is skipped entirely without a UI (print/JSON mode,
9
+ * fan-out child agents) and without credentials. Background polls (session
10
+ * start, timer, turn/model events) are deduped across pi processes through
11
+ * sync-policy.ts: one process polls per USAGE_SYNC_TTL_MS and writes the
12
+ * snapshot to `<agentDir>/cache/opencode-go-usage.json`; the others render that
13
+ * file. `/opencode-go-usage` (notify) always polls.
7
14
  */
8
15
 
16
+ import fs from "node:fs";
17
+ import path from "node:path";
9
18
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
10
- import { PROVIDER_ID, configPath, type UsageConfig } from "./config.ts";
19
+ import { PROVIDER_ID, configPath, usageCachePath, type UsageConfig } from "./config.ts";
20
+ import { acquireModelSync, keyFingerprint, writeFileAtomic, type SkipReason } from "./sync-policy.ts";
11
21
  import { getActiveMultiproviderService } from "./multiprovider.ts";
12
22
  import {
13
23
  USAGE_LIMITS_NOTE,
@@ -20,6 +30,43 @@ import {
20
30
  } from "./usage.ts";
21
31
 
22
32
  const REQUEST_TIMEOUT_MS = 10_000;
33
+ /**
34
+ * Cross-process freshness window for the shared usage snapshot: half the
35
+ * default 60s poll interval. Each process's widget is at most ~30s behind a
36
+ * direct poll, while any number of pi processes collapse to about one usage
37
+ * request per 30s. Fixed (PI_PROVIDER_SYNC_TTL_MS tunes the model catalog only).
38
+ */
39
+ export const USAGE_SYNC_TTL_MS = 30_000;
40
+
41
+ /** On-disk shape of the shared usage snapshot (never contains the key). */
42
+ interface SharedUsage {
43
+ version: 1;
44
+ keyFingerprint: string;
45
+ fetchedAt: number;
46
+ snapshot: UsageSnapshot;
47
+ }
48
+
49
+ /** The shared snapshot, only when it was polled with this same key. */
50
+ function readSharedUsage(cachePath: string, apiKey: string): SharedUsage | undefined {
51
+ try {
52
+ const data = JSON.parse(fs.readFileSync(cachePath, "utf8")) as Partial<SharedUsage> | null;
53
+ if (!data || data.keyFingerprint !== keyFingerprint(apiKey)) return undefined;
54
+ if (typeof data.fetchedAt !== "number" || !Array.isArray(data.snapshot?.windows)) return undefined;
55
+ return data as SharedUsage;
56
+ } catch {
57
+ return undefined;
58
+ }
59
+ }
60
+
61
+ function writeSharedUsage(cachePath: string, apiKey: string, snapshot: UsageSnapshot, fetchedAt: number): void {
62
+ try {
63
+ fs.mkdirSync(path.dirname(cachePath), { recursive: true });
64
+ const shared: SharedUsage = { version: 1, keyFingerprint: keyFingerprint(apiKey), fetchedAt, snapshot };
65
+ writeFileAtomic(cachePath, JSON.stringify(shared) + "\n");
66
+ } catch {
67
+ // Non-fatal: other processes just poll themselves.
68
+ }
69
+ }
23
70
  const STALE_CONTEXT_MESSAGE = "This extension ctx is stale";
24
71
  const MISSING_KEY_MESSAGE =
25
72
  "no opencode-go API key. Set OPENCODE_API_KEY or add \"opencode-go\" to ~/.pi/agent/auth.json.";
@@ -42,6 +89,7 @@ export class UsageController {
42
89
  private usageUpdatedAt: number | undefined;
43
90
  private usageError: string | undefined;
44
91
  private usageLastFetchAt: number | undefined;
92
+ private usageSource: "network" | "shared cache" | undefined;
45
93
  private usageTimer: ReturnType<typeof setInterval> | undefined;
46
94
  private usageRefreshInFlight = false;
47
95
  private queuedRefresh: QueuedRefresh | undefined;
@@ -125,6 +173,8 @@ export class UsageController {
125
173
  `Last fetch: ${this.usageLastFetchAt ? new Date(this.usageLastFetchAt).toLocaleTimeString() : "never"}`,
126
174
  `Last success: ${this.usageUpdatedAt ? new Date(this.usageUpdatedAt).toLocaleTimeString() : "never"}`,
127
175
  `Last error: ${this.usageError ?? "none"}`,
176
+ `Last source: ${this.usageSource ?? "none"}`,
177
+ `Shared snapshot: ${usageCachePath()} (fresh for ${USAGE_SYNC_TTL_MS / 1000}s)`,
128
178
  `Windows: ${this.usageSnapshot?.windows.map((window) => `${window.label}=${window.remainingPercent}% left`).join(" ") ?? "none"}`,
129
179
  `Endpoint: ${USAGE_URL}`,
130
180
  `Config file: ${configPath()}`,
@@ -189,6 +239,15 @@ export class UsageController {
189
239
  return envKey ? envKey : undefined;
190
240
  }
191
241
 
242
+ /**
243
+ * Whether this context can render usage at all. Print/JSON mode and child
244
+ * agents run without a UI, so polling there would only spend requests.
245
+ * Throws the stale-context error like any other ctx access.
246
+ */
247
+ private hasUI(ctx: ExtensionContext): boolean {
248
+ return ctx.hasUI !== false;
249
+ }
250
+
192
251
  private fail(ctx: ExtensionContext, message: string, options?: UsageRefreshOptions): void {
193
252
  this.usageError = message;
194
253
  this.onUpdate(ctx);
@@ -202,6 +261,16 @@ export class UsageController {
202
261
  ): Promise<void> {
203
262
  if (!this.isCurrent(generation)) return;
204
263
 
264
+ // Background polls never run without a UI; an explicit command (notify) still does.
265
+ if (!options?.notify) {
266
+ try {
267
+ if (!this.hasUI(ctx)) return;
268
+ } catch (error) {
269
+ if (isStaleContextError(error)) this.deactivate(generation);
270
+ return;
271
+ }
272
+ }
273
+
205
274
  const config = this.getConfig();
206
275
  if (!config.enabled) {
207
276
  this.usageSnapshot = undefined;
@@ -248,6 +317,8 @@ export class UsageController {
248
317
  }
249
318
 
250
319
  this.usageRefreshInFlight = true;
320
+ let lease: ReturnType<typeof acquireModelSync> = null;
321
+ let outcome: "fetched" | "failed" | "aborted" = "failed";
251
322
  try {
252
323
  const apiKey = await this.resolveApiKey(ctx);
253
324
  if (!this.isCurrent(generation)) return;
@@ -259,6 +330,33 @@ export class UsageController {
259
330
  }
260
331
 
261
332
  this.usageLastFetchAt = Date.now();
333
+
334
+ // Cross-process dedupe: one process polls per USAGE_SYNC_TTL_MS, the rest
335
+ // render its snapshot. An explicit refresh (notify) bypasses the window and
336
+ // polls even while another process holds the lock. If the cache dir is
337
+ // unusable we fail open to polling (still throttled per process).
338
+ const cachePath = usageCachePath();
339
+ let skipReason: SkipReason | undefined;
340
+ lease = acquireModelSync({
341
+ cachePath,
342
+ apiKey,
343
+ force: options?.notify === true,
344
+ ttlMs: USAGE_SYNC_TTL_MS,
345
+ isValidCache: (d) => d != null,
346
+ onSkip: (reason) => { skipReason = reason; },
347
+ });
348
+ if (!lease && !options?.notify && skipReason !== "unwritable") {
349
+ const shared = readSharedUsage(cachePath, apiKey);
350
+ if (shared) {
351
+ this.usageSnapshot = shared.snapshot;
352
+ this.usageUpdatedAt = shared.fetchedAt;
353
+ this.usageError = undefined;
354
+ this.usageSource = "shared cache";
355
+ }
356
+ this.onUpdate(ctx);
357
+ return;
358
+ }
359
+
262
360
  this.usageAbortController = new AbortController();
263
361
  const response = await fetch(USAGE_URL, {
264
362
  headers: { accept: "application/json", authorization: `Bearer ${apiKey}` },
@@ -286,6 +384,9 @@ export class UsageController {
286
384
  this.usageSnapshot = snapshot;
287
385
  this.usageUpdatedAt = Date.now();
288
386
  this.usageError = undefined;
387
+ this.usageSource = "network";
388
+ if (lease) writeSharedUsage(cachePath, apiKey, snapshot, this.usageUpdatedAt);
389
+ outcome = "fetched";
289
390
  this.onUpdate(ctx);
290
391
  if (options?.notify) this.notify(ctx, this.formatStatus(ctx), "info");
291
392
  } catch (error) {
@@ -297,6 +398,8 @@ export class UsageController {
297
398
  const message = error instanceof Error ? error.message : String(error);
298
399
  this.fail(ctx, message, options);
299
400
  } finally {
401
+ if (outcome !== "fetched" && !this.isCurrent(generation)) outcome = "aborted";
402
+ lease?.release(outcome);
300
403
  this.usageAbortController = undefined;
301
404
  this.usageRefreshInFlight = false;
302
405
  const next = this.queuedRefresh;
@@ -320,6 +423,11 @@ export class UsageController {
320
423
  this.shuttingDown = false;
321
424
 
322
425
  if (!this.getConfig().enabled) return;
426
+ try {
427
+ if (!this.hasUI(ctx)) return; // nothing to render: no startup poll, no timer
428
+ } catch {
429
+ return;
430
+ }
323
431
  void this.refresh(ctx, { force: true }, generation);
324
432
  this.usageTimer = setInterval(() => {
325
433
  if (!this.isCurrent(generation)) return;
@@ -0,0 +1,11 @@
1
+ import { defineConfig } from "vitest/config";
2
+
3
+ export default defineConfig({
4
+ test: {
5
+ environment: "node",
6
+ // The other tests/*.test.ts files are node:test suites run by `node --test`.
7
+ include: ["tests/sync-policy.test.ts", "tests/quiet-startup-sync.test.ts", "tests/usage-sync.test.ts"],
8
+ clearMocks: true,
9
+ restoreMocks: true,
10
+ },
11
+ });