oc-go-usage-display 1.0.2 → 2.0.0

package/dist/index.js

@@ -12,159 +12,66 @@
 // only (one tool). No transcript injection, no TUI
 // footer slot (unstable API).
 //
-// Auth (first match wins, secrets are never logged):
+// Auth (first match wins, secrets are never logged), host-specific stores:
 //   1. OPENCODE_GO_MOCK=1         -> deterministic mock snapshot (for testing)
 //   2. OPENCODE_GO_API_KEY        -> GET https://opencode.ai/zen/go/v1/usage
 //                                    (Authorization: Bearer <key>)
-//   3. Provider auth.json key     -> same Bearer path as (2), no paste needed:
-//                                    $XDG_DATA_HOME/opencode/auth.json (or
-//                                    ~/.local/share/opencode/auth.json), fallback
-//                                    ~/.config/opencode/auth.json (legacy).
-//                                    Uses `opencode-go` key, else `opencode` key.
+//   3. Provider auth.json key     -> same Bearer path as (2), no paste needed.
+//                                    opencode bundle: $XDG_DATA_HOME/opencode/
+//                                    auth.json (~/.local/share/opencode/auth.json),
+//                                    fallback $XDG_CONFIG_HOME/opencode/auth.json
+//                                    (~/.config/opencode/auth.json); uses the
+//                                    `opencode-go` key, else `opencode`.
+//                                    Kilo bundle (oc-go-usage-display.kilo.ts):
+//                                    the same files under the `kilo` roots, so
+//                                    a Kilo-only login works.
 //   4. OPENCODE_GO_WORKSPACE_ID + OPENCODE_GO_AUTH_COOKIE (env), or
-//      ~/.config/opencode/oc-go-usage-display.json
+//      <host config dir>/oc-go-usage-display.json
 //      ({ "workspaceId": "...", "authCookie": "..." })
 //                                   -> GET https://opencode.ai/workspace/{id}/go
 //                                    (scraped rolling/weekly/monthly)
 //   5. none                       -> unavailable snapshot (literal-only error)
-// Snapshots are cached 60s in memory + on disk.
+// Snapshots are cached 60s in memory + on disk (host config dir).
 import { tool } from "@opencode-ai/plugin";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
+import { formatServerLine, hasMalformedAuthCookie, isMalformedAuthCookie, readFileConfig, resolveAllowedRedirect, } from "./helpers.js";
+import { errorMessage, extractSnapshotFromApiPayload, extractWindow, hostEnv, hostEnvName, isLimitedStatus, isRecord, mockSnapshot, readAuthJsonApiKey, resolveHostRoots, resolveUsageHost, safeJoinPath, toFiniteNumber, toNonEmptyString, unavailableSnapshot, } from "./shared.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const API_USAGE_URL = "https://opencode.ai/zen/go/v1/usage";
 const CACHE_TTL_MS = 60_000;
 const FETCH_TIMEOUT_MS = 10_000;
-const CONFIG_DIR = path.join(os.homedir(), ".config", "opencode");
-const FILE_CONFIG_PATH = path.join(CONFIG_DIR, "oc-go-usage-display.json");
-const DISK_CACHE_PATH = path.join(CONFIG_DIR, "oc-go-usage-display-cache.json");
-function dataShareAuthPath() {
-    const xdgDataHome = toNonEmptyString(process.env.XDG_DATA_HOME);
-    if (xdgDataHome)
-        return path.join(xdgDataHome, "opencode", "auth.json");
-    return path.join(os.homedir(), ".local", "share", "opencode", "auth.json");
-}
-function authJsonPaths() {
-    return [dataShareAuthPath(), path.join(CONFIG_DIR, "auth.json")];
-}
-// ---------------------------------------------------------------------------
-// Small pure helpers
-// ---------------------------------------------------------------------------
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function toFiniteNumber(value) {
-    if (typeof value !== "number" || !Number.isFinite(value))
-        return null;
-    return value;
-}
-function toNonEmptyString(value) {
-    if (typeof value !== "string")
-        return null;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}
-function formatResetDuration(totalSec) {
-    if (totalSec === null || !Number.isFinite(totalSec) || totalSec < 0)
-        return null;
-    const sec = Math.floor(totalSec);
-    const hours = Math.floor(sec / 3600);
-    const minutes = Math.floor((sec % 3600) / 60);
-    if (hours > 0)
-        return `${hours}h${minutes}m`;
-    if (minutes > 0)
-        return `${minutes}m`;
-    return `${sec}s`;
-}
-function formatWindow(window) {
-    if (!window)
-        return "n/a";
-    return `${window.percent}%`;
-}
-function formatCompactLine(snapshot) {
-    if (snapshot.apiUnavailable || (!snapshot.rolling && !snapshot.weekly && !snapshot.monthly)) {
-        const reason = snapshot.apiError ?? "unknown error";
-        return `Go n/a (${reason})`;
-    }
-    const rollingReset = formatResetDuration(snapshot.rolling?.resetInSec ?? null) ??
-        snapshot.rolling?.resetText ??
-        null;
-    const rollingText = snapshot.rolling === null
-        ? "5h n/a"
-        : `5h ${snapshot.rolling.percent}%${rollingReset ? ` (reset ${rollingReset})` : ""}`;
-    return `Go ${rollingText} | 7d ${formatWindow(snapshot.weekly)} | 30d ${formatWindow(snapshot.monthly)}`;
-}
+const WINDOW_KEYS = ["rolling", "weekly", "monthly"];
+// Fetch redirect statuses (the cookie path handles them manually).
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+// Host this bundle serves: "kilo" only when baked in by the build (see
+// scripts/build-plugins.mjs); every other case is opencode. Credentials, file
+// config and the disk cache always resolve from this host's own roots.
+const HOST = resolveUsageHost();
+const DISK_CACHE_PATH = safeJoinPath(resolveHostRoots(HOST).configDir, "oc-go-usage-display-cache.json");
 // ---------------------------------------------------------------------------
 // Credentials (boundary: env + optional JSON file; never logged)
 // ---------------------------------------------------------------------------
-function readFileConfig() {
-    let raw;
-    try {
-        raw = fs.readFileSync(FILE_CONFIG_PATH, "utf8");
-    }
-    catch {
-        return { workspaceId: null, authCookie: null };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return { workspaceId: null, authCookie: null };
-    }
-    if (!isRecord(parsed))
-        return { workspaceId: null, authCookie: null };
-    return {
-        workspaceId: toNonEmptyString(parsed.workspaceId),
-        authCookie: toNonEmptyString(parsed.authCookie),
-    };
-}
-function readAuthJsonApiKey() {
-    for (const authPath of authJsonPaths()) {
-        let raw;
-        try {
-            raw = fs.readFileSync(authPath, "utf8");
-        }
-        catch {
-            continue;
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            continue;
-        }
-        if (!isRecord(parsed))
-            continue;
-        const goEntry = parsed["opencode-go"];
-        const fallbackEntry = parsed["opencode"];
-        const goKey = isRecord(goEntry) ? toNonEmptyString(goEntry.key) : null;
-        if (goKey)
-            return goKey;
-        const fallbackKey = isRecord(fallbackEntry) ? toNonEmptyString(fallbackEntry.key) : null;
-        if (fallbackKey)
-            return fallbackKey;
-    }
-    return null;
-}
-function resolveCredentials() {
-    if (process.env.OPENCODE_GO_MOCK === "1")
+function resolveCredentials(fileConfig = readFileConfig(HOST)) {
+    if (hostEnv(HOST, "MOCK") === "1")
         return { kind: "mock" };
-    const apiKey = toNonEmptyString(process.env.OPENCODE_GO_API_KEY);
+    const apiKey = toNonEmptyString(hostEnv(HOST, "API_KEY"));
     if (apiKey)
         return { kind: "apiKey", apiKey };
-    const authJsonKey = readAuthJsonApiKey();
+    const authJsonKey = readAuthJsonApiKey(HOST);
     if (authJsonKey)
         return { kind: "apiKey", apiKey: authJsonKey };
-    const fileConfig = readFileConfig();
-    const workspaceId = toNonEmptyString(process.env.OPENCODE_GO_WORKSPACE_ID) ?? fileConfig.workspaceId;
-    const authCookie = toNonEmptyString(process.env.OPENCODE_GO_AUTH_COOKIE) ?? fileConfig.authCookie;
-    if (workspaceId && authCookie)
+    const workspaceId = toNonEmptyString(hostEnv(HOST, "WORKSPACE_ID")) ?? fileConfig.workspaceId;
+    const authCookie = toNonEmptyString(hostEnv(HOST, "AUTH_COOKIE")) ?? fileConfig.authCookie;
+    if (workspaceId && authCookie) {
+        // Reject header-injection / cookie-jar confusion payloads. The cookie
+        // value is never logged; malformed values fall through to "none".
+        if (isMalformedAuthCookie(authCookie))
+            return { kind: "none" };
         return { kind: "cookie", workspaceId, authCookie };
+    }
     return { kind: "none" };
 }
 // ---------------------------------------------------------------------------
@@ -172,7 +79,7 @@ function resolveCredentials() {
 // ---------------------------------------------------------------------------
 let memoryCache = null;
 function isFresh(at, now) {
-    return now - at < CACHE_TTL_MS;
+    return at <= now && now - at < CACHE_TTL_MS;
 }
 function readDiskCache(now) {
     let raw;
@@ -199,7 +106,25 @@ function readDiskCache(now) {
     const snapshot = parsed.snapshot;
     if (!("rolling" in snapshot && "weekly" in snapshot && "monthly" in snapshot))
         return null;
-    return snapshot;
+    // Re-parse the stored windows instead of casting the raw entry: a cache file
+    // written by an older build predates newer `UsageWindow` fields, so the entry
+    // can be missing them. A window that no longer parses drops the whole entry
+    // so the next fetch repopulates the cache.
+    const windows = {
+        rolling: null,
+        weekly: null,
+        monthly: null,
+    };
+    for (const key of WINDOW_KEYS) {
+        const cachedWindow = snapshot[key];
+        if (cachedWindow === null)
+            continue;
+        const window = extractWindow(cachedWindow);
+        if (window === null)
+            return null;
+        windows[key] = window;
+    }
+    return { ...snapshot, ...windows };
 }
 function writeDiskCache(snapshot) {
     try {
@@ -213,96 +138,54 @@ function writeDiskCache(snapshot) {
 // ---------------------------------------------------------------------------
 // Fetch helpers
 // ---------------------------------------------------------------------------
-function unavailableSnapshot(error, source = "unavailable") {
-    return {
-        rolling: null,
-        weekly: null,
-        monthly: null,
-        source,
-        fetchedAt: Date.now(),
-        apiUnavailable: true,
-        apiError: error,
-    };
-}
-async function fetchWithTimeout(url, init) {
+// Run the whole exchange (headers and body) under one abort timer: clearing
+// it as soon as the response headers arrive would leave a server that stalls
+// mid-body hanging past FETCH_TIMEOUT_MS. `read` consumes the body while the
+// timer is armed; the signal lets callers tell an aborted read from a payload
+// problem. The timer is cleared on every path (body read, redirect handling,
+// fetch failure, abort).
+async function fetchWithTimeout(url, init, read) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
-        return await fetch(url, { ...init, signal: controller.signal });
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        return await read(response, controller.signal);
     }
     finally {
         clearTimeout(timer);
     }
 }
-// --- API-key path: tolerant JSON parsing (shape may evolve) ---
-function extractWindow(candidate) {
-    if (!isRecord(candidate))
-        return null;
-    const percent = toFiniteNumber(candidate.percent ??
-        candidate.usagePercent ??
-        candidate.usedPercent ??
-        candidate.value ??
-        candidate.usage);
-    if (percent === null)
-        return null;
-    const resetInSec = toFiniteNumber(candidate.resetInSec ?? candidate.resetInSeconds ?? null);
-    const status = toNonEmptyString(candidate.status);
-    const resetText = toNonEmptyString(candidate.resetText ?? candidate.reset ?? null);
-    return { percent: Math.round(percent), resetInSec, status, resetText };
-}
-function extractSnapshotFromApiPayload(payload) {
-    if (!isRecord(payload))
-        return null;
-    const containers = [payload];
-    for (const key of ["usage", "data", "go"]) {
-        if (isRecord(payload[key]))
-            containers.push(payload[key]);
-    }
-    for (const container of containers) {
-        if (!isRecord(container))
-            continue;
-        const rolling = extractWindow(container.rolling ?? container.rollingUsage ?? container["5h"]);
-        const weekly = extractWindow(container.weekly ?? container.weeklyUsage ?? container["7d"]);
-        const monthly = extractWindow(container.monthly ?? container.monthlyUsage ?? container["30d"]);
-        if (rolling || weekly || monthly) {
-            return {
-                rolling,
-                weekly,
-                monthly,
-                source: "api",
-                fetchedAt: Date.now(),
-            };
-        }
-    }
-    return null;
-}
+// --- API-key path: tolerant JSON parsing lives in `./shared.js` (shape may
+// evolve); scrape helpers below stay server-local. ---
 async function fetchViaApiKey(apiKey) {
-    let response;
     try {
-        response = await fetchWithTimeout(API_USAGE_URL, {
+        return await fetchWithTimeout(API_USAGE_URL, {
             headers: {
                 Authorization: `Bearer ${apiKey}`,
                 Accept: "application/json",
             },
+        }, async (response, signal) => {
+            if (response.status === 401 || response.status === 403) {
+                return unavailableSnapshot("API key rejected (401/403)");
+            }
+            if (!response.ok) {
+                return unavailableSnapshot(`upstream returned HTTP ${response.status}`);
+            }
+            let payload;
+            try {
+                payload = await response.json();
+            }
+            catch {
+                // A body read cut off by the timeout is a request failure; anything
+                // else is a payload the API-shape parser cannot use.
+                return unavailableSnapshot(signal.aborted ? "request failed" : "unexpected API response shape");
+            }
+            return extractSnapshotFromApiPayload(payload) ?? unavailableSnapshot("unexpected API response shape");
         });
     }
     catch {
         return unavailableSnapshot("request failed");
     }
-    if (response.status === 401 || response.status === 403) {
-        return unavailableSnapshot("API key rejected (401/403)");
-    }
-    if (!response.ok) {
-        return unavailableSnapshot(`upstream returned HTTP ${response.status}`);
-    }
-    let payload;
-    try {
-        payload = await response.json();
-    }
-    catch {
-        return unavailableSnapshot("unexpected API response shape");
-    }
-    return extractSnapshotFromApiPayload(payload) ?? unavailableSnapshot("unexpected API response shape");
 }
 // --- Cookie path: workspace page scrape (ported from opencode-go-hud) ---
 const USAGE_KEYS = {
@@ -310,6 +193,9 @@ const USAGE_KEYS = {
     weekly: "weeklyUsage",
     monthly: "monthlyUsage",
 };
+// Markup order of the `usage-item` slots. Spelled out rather than derived from
+// `WINDOW_KEYS`: it is a property of the scraped page, not of the display, and
+// must not follow a display-order change.
 const DOM_ORDER = ["rolling", "weekly", "monthly"];
 const LOGIN_TITLE_MARKER = "<title>OpenAuth</title>";
 function isLoginPage(finalUrl, html) {
@@ -357,11 +243,12 @@ function extractUsageBlock(html, key) {
 }
 function parseIntField(block, field) {
     const match = new RegExp(`${escapeRegex(field)}\\s*:\\s*(-?\\d+)`).exec(block);
-    return match ? Number.parseInt(match[1], 10) : null;
+    const digits = match?.[1];
+    return digits === undefined ? null : Number.parseInt(digits, 10);
 }
 function parseStrField(block, field) {
     const match = new RegExp(`${escapeRegex(field)}\\s*:\\s*"([^"]*)"`).exec(block);
-    return match ? match[1] : null;
+    return match?.[1] ?? null;
 }
 function parseInlineUsage(html) {
     const result = {};
@@ -373,10 +260,12 @@ function parseInlineUsage(html) {
         const percent = parseIntField(block, "usagePercent");
         if (percent === null)
             continue;
+        const status = parseStrField(block, "status");
         result[window] = {
             percent,
+            status,
+            limited: isLimitedStatus(status),
             resetInSec: parseIntField(block, "resetInSec"),
-            status: parseStrField(block, "status"),
             resetText: null,
         };
     }
@@ -397,19 +286,25 @@ function parseDomUsage(html) {
             itemStarts.push(match.index);
     }
     for (let idx = 0; idx < DOM_ORDER.length; idx++) {
-        if (idx >= itemStarts.length)
+        const window = DOM_ORDER[idx];
+        const start = itemStarts[idx];
+        if (window === undefined || start === undefined)
             break;
-        const segment = html.slice(itemStarts[idx], idx + 1 < itemStarts.length ? itemStarts[idx + 1] : itemStarts[idx] + 800);
+        const nextStart = itemStarts[idx + 1];
+        const segment = html.slice(start, nextStart !== undefined ? nextStart : start + 800);
         const valueMatch = /data-slot="usage-value">\s*(?:<!--[\s\S]*?-->)?\s*(\d+)/s.exec(segment) ??
             /width:\s*(\d+)%/.exec(segment);
-        if (!valueMatch)
+        const percent = valueMatch?.[1];
+        if (percent === undefined)
             continue;
         const resetMatch = /data-slot="reset-time">\s*([\s\S]*?)<\/span>/.exec(segment);
-        result[DOM_ORDER[idx]] = {
-            percent: Number.parseInt(valueMatch[1], 10),
-            resetInSec: null,
+        const resetText = resetMatch?.[1];
+        result[window] = {
+            percent: Number.parseInt(percent, 10),
             status: null,
-            resetText: resetMatch ? cleanResetText(resetMatch[1]) : null,
+            limited: false,
+            resetInSec: null,
+            resetText: resetText !== undefined ? cleanResetText(resetText) : null,
         };
     }
     return result;
@@ -422,61 +317,76 @@ function parseScrapedUsage(html) {
 }
 async function fetchViaCookie(workspaceId, authCookie) {
     const workspaceUrl = `https://opencode.ai/workspace/${encodeURIComponent(workspaceId)}/go`;
-    let response;
-    try {
-        response = await fetchWithTimeout(workspaceUrl, {
-            redirect: "follow",
-            headers: {
-                Cookie: `auth=${authCookie}`,
-                "User-Agent": "oc-go-usage-display-plugin/1.0",
-                Accept: "text/html,application/xhtml+xml",
-            },
-        });
-    }
-    catch {
-        return unavailableSnapshot("request failed");
-    }
-    let html = "";
-    try {
-        html = await response.text();
-    }
-    catch {
-        return unavailableSnapshot("request failed");
-    }
-    if (isLoginPage(response.url, html)) {
-        return unavailableSnapshot("login expired (refresh auth cookie)");
-    }
-    if (response.status !== 200) {
-        return unavailableSnapshot(`upstream returned HTTP ${response.status}`);
-    }
-    const usages = parseScrapedUsage(html);
-    if (Object.keys(usages).length === 0) {
-        if (isNoSubscription(html))
-            return unavailableSnapshot("no OpenCode Go subscription");
-        return unavailableSnapshot("usage markup not recognized");
+    let currentUrl = workspaceUrl;
+    let hopsFollowed = 0;
+    // `redirect: "manual"`: automatic redirect following may re-send caller
+    // headers (including the auth cookie) to a cross-origin Location, and runtime
+    // header stripping cannot be relied on. Each hop is re-requested only after
+    // `resolveAllowedRedirect` approves the Location (allowlisted canonical HTTPS
+    // hosts, at most MAX_REDIRECT_HOPS hops).
+    for (;;) {
+        let hop;
+        try {
+            hop = await fetchWithTimeout(currentUrl, {
+                redirect: "manual",
+                headers: {
+                    Cookie: `auth=${authCookie}`,
+                    "User-Agent": "oc-go-usage-display-plugin",
+                    Accept: "text/html,application/xhtml+xml",
+                },
+            }, async (response) => {
+                if (REDIRECT_STATUSES.has(response.status)) {
+                    // The redirect body is never read: Location alone decides the next
+                    // hop, so this resolves (and clears the abort timer) immediately.
+                    return { kind: "redirect", location: response.headers.get("location") };
+                }
+                return { kind: "body", status: response.status, html: await response.text() };
+            });
+        }
+        catch {
+            return unavailableSnapshot("request failed");
+        }
+        if (hop.kind === "redirect") {
+            const decision = resolveAllowedRedirect(currentUrl, hop.location, hopsFollowed);
+            if (!decision.follow)
+                return unavailableSnapshot(decision.reason);
+            currentUrl = decision.url;
+            hopsFollowed += 1;
+            continue;
+        }
+        const { status, html } = hop;
+        if (isLoginPage(currentUrl, html)) {
+            return unavailableSnapshot("login expired (refresh auth cookie)");
+        }
+        if (status !== 200) {
+            return unavailableSnapshot(`upstream returned HTTP ${status}`);
+        }
+        const usages = parseScrapedUsage(html);
+        if (Object.keys(usages).length === 0) {
+            if (isNoSubscription(html))
+                return unavailableSnapshot("no OpenCode Go subscription");
+            return unavailableSnapshot("usage markup not recognized");
+        }
+        return {
+            rolling: usages.rolling ?? null,
+            weekly: usages.weekly ?? null,
+            monthly: usages.monthly ?? null,
+            source: "scrape",
+            fetchedAt: Date.now(),
+        };
     }
-    return {
-        rolling: usages.rolling ?? null,
-        weekly: usages.weekly ?? null,
-        monthly: usages.monthly ?? null,
-        source: "scrape",
-        fetchedAt: Date.now(),
-    };
-}
-function mockSnapshot() {
-    return {
-        rolling: { percent: 42, resetInSec: 7543, status: "active", resetText: null },
-        weekly: { percent: 15, resetInSec: null, status: "active", resetText: null },
-        monthly: { percent: 61, resetInSec: null, status: "active", resetText: null },
-        source: "mock",
-        fetchedAt: Date.now(),
-    };
 }
 // ---------------------------------------------------------------------------
 // Snapshot entry point (cached, never throws, never logs secrets)
 // ---------------------------------------------------------------------------
 async function getUsageSnapshot() {
     const now = Date.now();
+    // Mock bypasses cache for determinism: a stale disk/memory entry must
+    // never shadow the deterministic mock snapshot during tests. The mock
+    // never reads or writes the cache.
+    if (hostEnv(HOST, "MOCK") === "1") {
+        return mockSnapshot();
+    }
     if (memoryCache && isFresh(memoryCache.at, now))
         return memoryCache.snapshot;
     const diskCached = readDiskCache(now);
@@ -484,14 +394,20 @@ async function getUsageSnapshot() {
         memoryCache = { at: now, snapshot: diskCached };
         return diskCached;
     }
-    const credentials = resolveCredentials();
+    const fileConfig = readFileConfig(HOST);
+    const credentials = resolveCredentials(fileConfig);
     if (credentials.kind === "mock") {
-        const snapshot = mockSnapshot();
-        memoryCache = { at: now, snapshot };
-        return snapshot;
+        return mockSnapshot();
     }
     if (credentials.kind === "none") {
-        return unavailableSnapshot("not configured (set OPENCODE_GO_API_KEY)");
+        // A malformed-cookie reason is only meaningful when a workspaceId is
+        // present (the user actually attempted cookie auth); a fully
+        // unconfigured setup reports the generic reason.
+        const workspaceId = toNonEmptyString(hostEnv(HOST, "WORKSPACE_ID")) ?? fileConfig.workspaceId;
+        if (workspaceId && hasMalformedAuthCookie(fileConfig)) {
+            return unavailableSnapshot("not configured (malformed auth cookie)");
+        }
+        return unavailableSnapshot(`not configured (set ${hostEnvName(HOST, "API_KEY")})`);
     }
     const snapshot = credentials.kind === "apiKey"
         ? await fetchViaApiKey(credentials.apiKey)
@@ -505,19 +421,83 @@ async function getUsageSnapshot() {
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
-export default (async () => {
-    return {
-        tool: {
-            go_usage: tool({
-                description: "Show OpenCode Go subscription usage: rolling 5h, weekly, and monthly windows. Takes no arguments.",
-                args: {},
-                execute: async () => {
-                    const snapshot = await getUsageSnapshot().catch(() => unavailableSnapshot("request failed"));
-                    const line = formatCompactLine(snapshot);
-                    return `${line}\n${JSON.stringify(snapshot, null, 2)}`;
-                },
-            }),
-        },
-    };
-});
+// The ONLY export must be the default module: OpenCode's loader enumerates
+// every export and invokes each as a plugin factory when the default is not a
+// `{ id, server }` module. Helpers live in `./helpers.js` for exactly that
+// reason. `server` returns the existing `{ tool: { go_usage } }` hook surface.
+// A Hooks value is always a plain object. Drop nullish hook entries (and
+// nullish tool definitions) so the loader can never dereference
+// `hook.config` / `hook.provider` on a null value.
+function sanitizeHooks(hooks) {
+    if (!isRecord(hooks))
+        return {};
+    const clean = {};
+    for (const [key, value] of Object.entries(hooks)) {
+        if (value === null || value === undefined)
+            continue;
+        if (key === "tool" && isRecord(value)) {
+            const tools = {};
+            for (const [name, definition] of Object.entries(value)) {
+                if (definition === null || definition === undefined)
+                    continue;
+                tools[name] = definition;
+            }
+            clean[key] = tools;
+            continue;
+        }
+        clean[key] = value;
+    }
+    return clean;
+}
+// Best-effort error log. The client (or its `log` method) may be absent or
+// throw on a malformed input, and logging must never rethrow into a caller or
+// delay plugin resolution: callers use `void logServerError(...)`.
+async function logServerError(input, message) {
+    try {
+        const client = input?.client;
+        await client?.app?.log?.({
+            service: "oc-go-usage-display",
+            level: "error",
+            message,
+        });
+    }
+    catch {
+        // Logging is best-effort; callers must never fail because of it.
+    }
+}
+// Fail-safe contract: OpenCode always starts, even if this plugin cannot. The
+// factory resolves to a valid Hooks object (never undefined/null) for any
+// input; on initialization failure it logs best-effort and resolves to `{}`.
+const server = async (input, _options) => {
+    try {
+        return sanitizeHooks({
+            tool: {
+                go_usage: tool({
+                    description: "Show OpenCode Go subscription usage: rolling 5h, weekly, and monthly windows. Takes no arguments.",
+                    args: {},
+                    execute: async () => {
+                        try {
+                            const snapshot = await getUsageSnapshot().catch(() => unavailableSnapshot("request failed"));
+                            const line = formatServerLine(snapshot);
+                            return `${line}\n${JSON.stringify(snapshot, null, 2)}`;
+                        }
+                        catch (error) {
+                            // Same output shape as the success path (line + JSON tail); the
+                            // failure is logged best-effort and the invocation still
+                            // resolves so it can never reject into the host.
+                            const snapshot = unavailableSnapshot("request failed");
+                            void logServerError(input, `go_usage tool execution failed: ${errorMessage(error)}`);
+                            return `${formatServerLine(snapshot)}\n${JSON.stringify(snapshot, null, 2)}`;
+                        }
+                    },
+                }),
+            },
+        });
+    }
+    catch (error) {
+        void logServerError(input, `Go usage plugin failed to initialize: ${errorMessage(error)}; continuing without hooks`);
+        return {};
+    }
+};
+export default { id: "oc-go-usage-display", server };
 //# sourceMappingURL=index.js.map