opencode-usage-report 0.4.1 → 0.5.0

package/README.md

@@ -71,6 +71,12 @@ Or add the plugin manually to each file and restart opencode:
 > `opencode plugin opencode-usage-report` prints `Detected server + tui targets`
 > when the resolution works.
 
+> **OpenCode 2.x (0.5.0).** The server entrypoint default-exports the V2
+> `{ id, setup }` definition and still carries the V1 `server` hook, so
+> OpenCode 1.18.29+ and 2.x both load it. Before 0.5.0 the module exported a
+> bare V1 function, which OpenCode 2 rejects. The TUI entrypoint is unchanged
+> in this release.
+
 Options can be passed in the tuple form, independently per entrypoint:
 
 ```jsonc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-report",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "opencode plugin: /usage command showing subscription quota windows for configured providers",
   "keywords": [
     "kimi",

package/src/index.ts

@@ -1,4 +1,4 @@
-import type { Plugin } from "@opencode-ai/plugin";
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
 import { DEFAULT_OPTIONS, collectReports } from "./report";
 import { renderJson, renderText } from "./render";
@@ -39,12 +39,16 @@ export function coerceOptions(raw: Record<string, unknown> | undefined): PluginO
   return opts;
 }
 
-const plugin: Plugin = async ({ client }, options) => {
-  const opts = coerceOptions(options);
+/**
+ * Throttled warning pass shared by the V1 and V2 plugin APIs (spec §3.6/§3.7).
+ * Every failure is swallowed (spec §4): it must never throw into the event bus.
+ */
+function makeWarnRunner(
+  opts: PluginOptions,
+  notify: (message: string) => Promise<unknown> | unknown,
+): () => Promise<void> {
   let lastWarnCheck = 0;
-
-  /** Throttled warning pass (spec §3.7). Every failure is swallowed (spec §4). */
-  const runWarnCheck = async (): Promise<void> => {
+  return async (): Promise<void> => {
     try {
       if (Date.now() - lastWarnCheck < WARN_THROTTLE_MS) return;
       lastWarnCheck = Date.now();
@@ -53,9 +57,7 @@ const plugin: Plugin = async ({ client }, options) => {
       const hits = await checkWarnings(reports, opts.thresholdPercent);
       for (const hit of hits) {
         try {
-          await client.tui.showToast({
-            body: { title: "Usage warning", message: hit.message, variant: "warning" },
-          });
+          await notify(hit.message);
         } catch {
           // Toast delivery is best-effort; it is unavailable in headless/server mode.
         }
@@ -64,6 +66,159 @@ const plugin: Plugin = async ({ client }, options) => {
       // Never throw into the event bus.
     }
   };
+}
+
+async function runUsageReport(
+  args: Record<string, unknown> | undefined,
+  opts: PluginOptions,
+): Promise<{ content: string }> {
+  const reports = await collectReports({
+    providers: args?.provider ? [String(args.provider)] : undefined,
+    refresh: args?.refresh === true,
+    options: opts,
+  });
+  return { content: args?.json === true ? renderJson(reports) : renderText(reports) };
+}
+
+const TOOL_INPUT_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    provider: { type: "string" },
+    json: { type: "boolean" },
+    refresh: { type: "boolean" },
+  },
+  additionalProperties: false,
+};
+
+// ---------------------------------------------------------------------------
+// OpenCode 2.x (V2) plugin API.
+//
+// The harness decodes the module's default export against `{ id, setup }` or
+// `{ id, effect }` and otherwise fails with "Plugin must export a default
+// definition with an id and an effect or setup function" (err_b890e30e). The
+// context types are declared locally so the package needs no runtime dependency
+// on the V2 SDK; opencode erases `import type` anyway.
+// ---------------------------------------------------------------------------
+
+interface V2ToolDefinition {
+  name: string;
+  description: string;
+  input: Record<string, unknown>;
+  execute: (args: Record<string, unknown> | undefined) => Promise<{ content: string }>;
+}
+
+interface V2ToolEditor {
+  add(definition: V2ToolDefinition): void;
+}
+
+interface V2ContextEvent {
+  sessionID?: string;
+  model?: { providerID?: string; id?: string };
+  system?: Array<{ type?: string; text?: string } | string>;
+}
+
+interface V2PluginContext {
+  options?: Record<string, unknown>;
+  tool: { transform: (callback: (editor: V2ToolEditor) => void) => Promise<unknown> };
+  session: {
+    hook: (name: "context", handler: (event: V2ContextEvent) => unknown) => Promise<unknown>;
+  };
+  event: { subscribe: (options: { signal: AbortSignal }) => AsyncIterable<{ type?: string }> };
+  /** Not part of the V2 server context; present only if the runtime exposes it. */
+  tui?: { showToast?: (input: unknown) => Promise<unknown> };
+}
+
+/** Joins V2 system parts (text parts plus plain strings) into one prompt string. */
+function joinSystem(event: V2ContextEvent | undefined): string {
+  if (!Array.isArray(event?.system)) return "";
+  return event.system
+    .map((part) => (typeof part === "string" ? part : (part?.text ?? "")))
+    .join("\n");
+}
+
+/** Best-effort capture of the assembled system prompt size (spec §9.1). */
+async function captureSystemFromContext(event: V2ContextEvent | undefined): Promise<void> {
+  try {
+    const sessionID = event?.sessionID;
+    const model = event?.model;
+    if (typeof sessionID !== "string" || sessionID === "") return;
+    if (
+      model === undefined ||
+      typeof model.providerID !== "string" ||
+      typeof model.id !== "string"
+    ) {
+      return;
+    }
+
+    const system = joinSystem(event);
+    if (system === "") return;
+
+    await writeCapture({
+      version: 1,
+      sessionID,
+      providerID: model.providerID,
+      modelID: model.id,
+      systemChars: system.length,
+      systemTokens: estimateTokens(system),
+      capturedAt: Date.now(),
+    });
+  } catch {
+    // Best-effort: an experimental hook must never be able to break a request.
+  }
+}
+
+async function setup(ctx: V2PluginContext): Promise<() => void> {
+  const opts = coerceOptions(ctx?.options);
+
+  await ctx.tool.transform((editor) => {
+    editor.add({
+      name: "usage_report",
+      description: TOOL_DESCRIPTION,
+      input: TOOL_INPUT_SCHEMA,
+      execute: (args) => runUsageReport(args, opts),
+    });
+  });
+
+  await ctx.session.hook("context", (event) => captureSystemFromContext(event));
+
+  const runWarnCheck = makeWarnRunner(opts, (message) => {
+    const showToast = ctx.tui?.showToast;
+    if (typeof showToast !== "function") return;
+    return showToast({ body: { title: "Usage warning", message, variant: "warning" } });
+  });
+
+  // Spec §3.6: one throttled warning check at startup, fire-and-forget.
+  setTimeout(() => {
+    void runWarnCheck();
+  }, 0);
+
+  const controller = new AbortController();
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        if (event?.type === "session.idle") await runWarnCheck();
+      }
+    } catch {
+      // Subscription aborted on unload, or the event transport failed.
+    }
+  })();
+
+  return () => controller.abort();
+}
+
+// ---------------------------------------------------------------------------
+// OpenCode 1.x (V1) plugin API. Kept from the previous release so packages can
+// serve both APIs during the V2 migration; V2 calls `setup`, V1 calls `server`.
+// ---------------------------------------------------------------------------
+
+async function server({ client }: PluginInput, options?: Record<string, unknown>): Promise<Hooks> {
+  const opts = coerceOptions(options);
+
+  const runWarnCheck = makeWarnRunner(opts, (message) =>
+    client.tui.showToast({
+      body: { title: "Usage warning", message, variant: "warning" },
+    }),
+  );
 
   // Spec §3.6: one throttled warning check at startup, fire-and-forget.
   setTimeout(() => {
@@ -80,12 +235,7 @@ const plugin: Plugin = async ({ client }, options) => {
           refresh: tool.schema.boolean().optional(),
         },
         async execute(args) {
-          const reports = await collectReports({
-            providers: args.provider ? [args.provider] : undefined,
-            refresh: args.refresh === true,
-            options: opts,
-          });
-          return args.json ? renderJson(reports) : renderText(reports);
+          return (await runUsageReport(args, opts)).content;
         },
       }),
     },
@@ -126,6 +276,12 @@ const plugin: Plugin = async ({ client }, options) => {
       }
     },
   };
+}
+
+const definition = {
+  id: "opencode-usage-report",
+  setup,
+  server,
 };
 
-export default plugin;
+export default definition;