dsh-plugin-subscription-usage 0.1.0 → 0.2.0

package/README.md

@@ -2,8 +2,6 @@
 
 A DeepSeek Harness plugin that uses your ChatGPT (Codex), Claude, Grok, GitHub Copilot and Google Antigravity subscriptions as LLM providers, and shows how fast you are using each limit.
 
-It replaces `dsh-plugin-subscriptions`. Both register the `codex` adapter, so enabling both fails with `DUPLICATE_ADAPTER`. Disable the other one first.
-
 ## What you get
 
 - **Models page.** Each subscription is a provider row where you sign in, manage accounts, choose models and enable tools.
@@ -11,6 +9,24 @@ It replaces `dsh-plugin-subscriptions`. Both register the `codex` adapter, so en
 - **Composer gauge.** The current model's provider, plus any you pinned, shows under the composer.
 - **API key usage.** Z.ai, Ollama Cloud and Kimi Code usage is read with an API key you paste on the Usage page. These providers are usage-only. The plugin does not route requests to them.
 
+## Screenshots
+
+Usage page in Settings, with pace forecasts and pins:
+
+![Settings, Usage page](https://raw.githubusercontent.com/P4rthPat3l/dsh-plugin-subscription-usage/main/docs/screenshots/settings-usage.png)
+
+Models page, where each subscription is a provider row:
+
+![Settings, Models page](https://raw.githubusercontent.com/P4rthPat3l/dsh-plugin-subscription-usage/main/docs/screenshots/settings-models.png)
+
+Usage pop-up in the composer on a new session:
+
+![Composer usage pop-up on a new session](https://raw.githubusercontent.com/P4rthPat3l/dsh-plugin-subscription-usage/main/docs/screenshots/composer-popup.png)
+
+The same pop-up inside a chat:
+
+![Composer usage pop-up in a chat](https://raw.githubusercontent.com/P4rthPat3l/dsh-plugin-subscription-usage/main/docs/screenshots/usage-in-chat.png)
+
 ## Install
 
 ```bash
@@ -30,10 +46,6 @@ Restart DSH, then open Settings, Models.
 - Copilot, Z.ai, Ollama Cloud and Kimi Code usage comes from endpoints the vendors do not document. They can change without notice, and the card then shows "Usage unavailable".
 - A plain Moonshot key does not work for Kimi Code usage.
 
-## Credits
-
-Built on [V1ki/dsh-plugin-subscriptions](https://github.com/V1ki/dsh-plugin-subscriptions) (MIT). The sign-in, provider, pool and translation code under `src/auth`, `src/providers`, `src/translate` and `src/tools` comes from it. The Usage page, key providers and the Models UI are new.
-
 ## License
 
 MIT

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  * RPC channel the web Settings page uses to run the logins. The token store
  * lives at `~/.dsh/plugins/subscriptions/auth.json`; the channel registers only when
  * a host `connection` service exists, so headless compositions load fine.
- * @module dsh-plugin-subscriptions
+ * @module dsh-plugin-subscription-usage
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';

package/lib/index.js

@@ -8856,7 +8856,8 @@ var ImageAccountPool = class {
 const TOOL_ALIASES = {
 	x_search: "dsh_subscriptions_x_search",
 	video_generate: "dsh_subscriptions_video_generate",
-	image_generate: "dsh_subscriptions_image_generate"
+	image_generate: "dsh_subscriptions_image_generate",
+	subscription_usage: "dsh_subscriptions_subscription_usage"
 };
 /** Register a tool under its canonical name, then a plugin-scoped alias. */
 function registerWithAlias(registry, definition, warn = (message) => console.warn(message)) {
@@ -8883,6 +8884,162 @@ function registerWithAlias(registry, definition, warn = (message) => console.war
 	}
 }
 
+//#endregion
+//#region src/usage/pace.ts
+/** Below this share of elapsed window a burst says little about the whole window. */
+const MIN_FORECAST_ELAPSED = .2;
+/** Below this usage the projection is noise. */
+const MIN_FORECAST_USED_PERCENT = 3;
+/** Projected use above this percent turns a window `tight`. */
+const TIGHT_PROJECTED_PERCENT = 85;
+/**
+* Compute the pace of one window at `now`.
+* @param window - the provider-reported window.
+* @param now - epoch milliseconds.
+* @returns the pace; `elapsed` is the share of the window passed, 0 to 1.
+*/
+function pace(window, now) {
+	const used = window.usedPercent;
+	if (!Number.isFinite(used)) return { state: "unknown" };
+	const usedPercent = Math.max(0, Math.min(100, used));
+	if (usedPercent >= 100) return {
+		state: "out",
+		usedPercent
+	};
+	const { durationMs: durationMs$1, resetsAt } = window;
+	if (durationMs$1 === void 0 || resetsAt === void 0 || !(durationMs$1 > 0) || !Number.isFinite(resetsAt)) return {
+		state: "calm",
+		usedPercent
+	};
+	const elapsed = Math.min(1, Math.max(0, 1 - (resetsAt - now) / durationMs$1));
+	if (elapsed < MIN_FORECAST_ELAPSED || usedPercent < MIN_FORECAST_USED_PERCENT) return {
+		state: "calm",
+		usedPercent,
+		elapsed
+	};
+	const projectedPercent = usedPercent / elapsed;
+	if (projectedPercent > 100) {
+		const ratePerMs = usedPercent / (elapsed * durationMs$1);
+		return {
+			state: "over",
+			usedPercent,
+			elapsed,
+			projectedPercent,
+			emptyAt: now + (100 - usedPercent) / ratePerMs
+		};
+	}
+	if (projectedPercent > TIGHT_PROJECTED_PERCENT) return {
+		state: "tight",
+		usedPercent,
+		elapsed,
+		projectedPercent
+	};
+	return {
+		state: "calm",
+		usedPercent,
+		elapsed,
+		projectedPercent
+	};
+}
+
+//#endregion
+//#region src/tools/usage.ts
+function iso(ms) {
+	return ms !== void 0 && Number.isFinite(ms) ? new Date(ms).toISOString() : void 0;
+}
+function reportWindows(usage, now) {
+	return (usage.windows ?? []).map((window) => {
+		const state = pace(window, now);
+		const used = Number.isFinite(window.usedPercent) ? Math.max(0, Math.min(100, window.usedPercent)) : 0;
+		const resetsAt = iso(window.resetsAt);
+		const emptyAt = state.state === "over" ? iso(state.emptyAt) : void 0;
+		return {
+			kind: window.kind,
+			...window.scope === void 0 ? {} : { scope: window.scope },
+			usedPercent: Math.round(used),
+			leftPercent: 100 - Math.round(used),
+			...resetsAt === void 0 ? {} : { resetsAt },
+			pace: state.state,
+			...emptyAt === void 0 ? {} : { emptyAt }
+		};
+	});
+}
+/**
+* Collect usage for the requested provider, or for every signed-in provider.
+* One provider's failure becomes an `error` on its own entry.
+*/
+async function buildUsageReport(options, args, signal) {
+	const now = (options.now ?? Date.now)();
+	const all = await options.source.targets();
+	const known = [...new Set(all.map((target) => target.provider))];
+	if (args.provider !== void 0 && !known.includes(args.provider)) throw new Error(`subscription_usage: no signed-in provider "${args.provider}". Available: ${known.length > 0 ? known.join(", ") : "none"}`);
+	const targets = args.provider === void 0 ? all : all.filter((target) => target.provider === args.provider);
+	if (targets.length === 0) return {
+		providers: [],
+		note: "No subscription or usage key is set up."
+	};
+	return { providers: await Promise.all(targets.map(async (target) => {
+		const base = {
+			provider: target.provider,
+			account: target.label
+		};
+		try {
+			const usage = await options.source.read(target, args.refresh === true, signal);
+			if (!usage.supported) return {
+				...base,
+				note: "This provider reports no usage."
+			};
+			const fetchedAt = iso(usage.fetchedAt);
+			return {
+				...base,
+				...usage.plan === void 0 ? {} : { plan: usage.plan },
+				windows: reportWindows(usage, now),
+				...usage.stale === true || usage.refreshFailed === true ? { stale: true } : {},
+				...fetchedAt === void 0 ? {} : { fetchedAt }
+			};
+		} catch (error) {
+			return {
+				...base,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	})) };
+}
+/** Build the `subscription_usage` tool definition. */
+function createUsageTool(options) {
+	return defineTool({
+		name: "subscription_usage",
+		description: "Read how much of each AI subscription limit is used (ChatGPT Codex, Claude, Grok, Copilot, Antigravity, Z.ai, Ollama Cloud, Kimi Code). Returns per provider the plan, each window's percent used and left, the reset time, and a pace state: calm, tight, over (will run out before reset, with emptyAt) or out. Call it before long, critical or heavy work, and prefer a provider whose pace is calm. Read-only. It returns cached data unless refresh is true.",
+		parameters: {
+			provider: {
+				type: "string",
+				description: "Limit the answer to one provider id, such as codex or claude. Omit for all."
+			},
+			refresh: {
+				type: "boolean",
+				description: "Fetch fresh numbers instead of the cached snapshot."
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: args.provider === void 0 ? "subscription_usage" : `subscription_usage: ${args.provider}`,
+			kind: "search"
+		}),
+		async execute(args, exec) {
+			return JSON.stringify(await buildUsageReport(options, args, exec.signal));
+		}
+	});
+}
+/** The system prompt reminder, kept short so it costs little on every step. */
+const USAGE_PROMPT_REMINDER = "Before long, critical or heavy work on a subscription model, call subscription_usage to check how much of the limit is left, and prefer a provider whose pace is calm.";
+
 //#endregion
 //#region src/providers/pool-usage.ts
 /** Near-full members are tried only after members below this fill level. */
@@ -9244,7 +9401,7 @@ async function grokFlow() {
 				state,
 				nonce,
 				plan: "generic",
-				referrer: "dsh-plugin-subscriptions"
+				referrer: "dsh-plugin-subscription-usage"
 			});
 			return `${discovery.authorizationEndpoint}?${params.toString()}`;
 		}
@@ -10464,7 +10621,7 @@ const ANTIGRAVITY_TOKEN_URL = "https://oauth2.googleapis.com/token";
 const ANTIGRAVITY_USERINFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo";
 const ANTIGRAVITY_DEFAULT_BASE_URL = "https://daily-cloudcode-pa.googleapis.com";
 const ANTIGRAVITY_PROD_BASE_URL = "https://cloudcode-pa.googleapis.com";
-const ANTIGRAVITY_DEFAULT_USER_AGENT = "antigravity/1.104.0 dsh-plugin-subscriptions";
+const ANTIGRAVITY_DEFAULT_USER_AGENT = "antigravity/1.104.0 dsh-plugin-subscription-usage";
 const ANTIGRAVITY_PREEMPT_MS = 5 * 6e4;
 const ANTIGRAVITY_CALLBACK_PATH = "/oauth-callback";
 const ANTIGRAVITY_CONTEXT_WINDOW = 1024e3;
@@ -13049,13 +13206,14 @@ function apply(ctx, config) {
 		if (!codexTokens) throw new BadRequest("Codex unavailable");
 		await consumeCodexResetCredit(await codexTokens.session(account), creditId, requestId, proxiedFetch, signal);
 	}, (account) => usageTracker.invalidate("codex", account));
-	registerAuthRpc(ctx, new SubscriptionsAuthController(flows, deviceFlows, authChanged, resolveAttachments, usageFetchers, void 0, usageTracker, config.antigravity, {
+	const authController = new SubscriptionsAuthController(flows, deviceFlows, authChanged, resolveAttachments, usageFetchers, void 0, usageTracker, config.antigravity, {
 		...providers.includes("codex") ? { codex: config.codexClientVersion === void 0 ? presentedVersion(codexVersion) : async () => ({
 			version: config.codexClientVersion,
 			source: "config"
 		}) } : {},
 		...providers.includes("claude") ? { claude: presentedVersion(claudeVersion) } : {}
-	}, resetRedemption, (provider, account) => poolHealth?.clear(provider, account), usage, keyUsage), speed, {
+	}, resetRedemption, (provider, account) => poolHealth?.clear(provider, account), usage, keyUsage);
+	registerAuthRpc(ctx, authController, speed, {
 		get: () => proxyGetConfig(),
 		set: (input) => proxySetConfig(input),
 		test: (payload) => proxyTestConnection(payload.url, payload.proxy)
@@ -13173,12 +13331,43 @@ function apply(ctx, config) {
 			}));
 		});
 	}
+	const usageTargets = async () => {
+		const targets = [];
+		for (const provider of PROVIDER_IDS) {
+			if (!authController.hasUsage(provider)) continue;
+			const status = await authController.status(provider).catch(() => void 0);
+			const account = status?.accounts.find((entry) => entry.key === status.servingAccount) ?? status?.accounts.find((entry) => entry.isDefault) ?? status?.accounts[0];
+			if (account !== void 0) targets.push({
+				provider,
+				key: account.key,
+				label: account.account ?? account.key
+			});
+		}
+		for (const view of await authController.keyProviders()) if (view.configured) targets.push({
+			provider: view.id,
+			key: KEY_ACCOUNT,
+			label: view.name
+		});
+		return targets;
+	};
+	ctx.inject(["systemPrompt"], (promptCtx) => {
+		promptCtx.systemPrompt.section({
+			name: "subscription-usage:reminder",
+			order: 5e3,
+			text: USAGE_PROMPT_REMINDER
+		});
+	});
 	ctx.inject(["tools"], (toolsCtx) => {
 		const registeredNames = /* @__PURE__ */ new Map();
 		if (grokTokens !== void 0) for (const definition of [createXSearchTool({ tokens: grokTokens }), createVideoGenerateTool({ tokens: grokTokens })]) {
 			const result = registerWithAlias(toolsCtx.tools, definition);
 			if (result !== void 0) registeredNames.set(definition.name, result.name);
 		}
+		const usageResult = registerWithAlias(toolsCtx.tools, createUsageTool({ source: {
+			targets: usageTargets,
+			read: (target, refresh, signal) => authController.usage(target.provider, target.key, signal, refresh, refresh ? "manual" : "poll")
+		} }));
+		if (usageResult !== void 0) registeredNames.set("subscription_usage", usageResult.name);
 		if (codexTokens !== void 0 || grokTokens !== void 0) {
 			const result = registerWithAlias(toolsCtx.tools, createImageGenerateTool({
 				imagePool,

package/lib/providers/antigravity.d.ts

@@ -18,7 +18,7 @@ export declare const ANTIGRAVITY_TOKEN_URL = "https://oauth2.googleapis.com/toke
 export declare const ANTIGRAVITY_USERINFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo";
 export declare const ANTIGRAVITY_DEFAULT_BASE_URL = "https://daily-cloudcode-pa.googleapis.com";
 export declare const ANTIGRAVITY_PROD_BASE_URL = "https://cloudcode-pa.googleapis.com";
-export declare const ANTIGRAVITY_DEFAULT_USER_AGENT = "antigravity/1.104.0 dsh-plugin-subscriptions";
+export declare const ANTIGRAVITY_DEFAULT_USER_AGENT = "antigravity/1.104.0 dsh-plugin-subscription-usage";
 export declare const ANTIGRAVITY_PREEMPT_MS: number;
 /** Antigravity, not Gemini CLI, OAuth scopes from the local reference clients. */
 export declare const ANTIGRAVITY_SCOPES: readonly ["openid", "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/cclog", "https://www.googleapis.com/auth/experimentsandconfigs"];

package/lib/providers/antigravity.js

@@ -17,7 +17,7 @@ export const ANTIGRAVITY_TOKEN_URL = 'https://oauth2.googleapis.com/token';
 export const ANTIGRAVITY_USERINFO_URL = 'https://www.googleapis.com/oauth2/v2/userinfo';
 export const ANTIGRAVITY_DEFAULT_BASE_URL = 'https://daily-cloudcode-pa.googleapis.com';
 export const ANTIGRAVITY_PROD_BASE_URL = 'https://cloudcode-pa.googleapis.com';
-export const ANTIGRAVITY_DEFAULT_USER_AGENT = 'antigravity/1.104.0 dsh-plugin-subscriptions';
+export const ANTIGRAVITY_DEFAULT_USER_AGENT = 'antigravity/1.104.0 dsh-plugin-subscription-usage';
 export const ANTIGRAVITY_PREEMPT_MS = 5 * 60_000;
 const ANTIGRAVITY_CALLBACK_PATH = '/oauth-callback';
 const ANTIGRAVITY_CONTEXT_WINDOW = 1_024_000;

package/lib/providers/grok.js

@@ -90,7 +90,7 @@ export async function grokFlow() {
                 state,
                 nonce,
                 plan: 'generic',
-                referrer: 'dsh-plugin-subscriptions',
+                referrer: 'dsh-plugin-subscription-usage',
             });
             return `${discovery.authorizationEndpoint}?${params.toString()}`;
         },

package/lib/providers/rate-limit.d.ts

@@ -13,7 +13,7 @@
  * adapter contributes one {@link RateLimitResetReader} built from the parsing
  * primitives here.
  *
- * @module dsh-plugin-subscriptions/providers/rate-limit
+ * @module dsh-plugin-subscription-usage/providers/rate-limit
  */
 import type { ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm';
 /**

package/lib/providers/rate-limit.js

@@ -13,7 +13,7 @@
  * adapter contributes one {@link RateLimitResetReader} built from the parsing
  * primitives here.
  *
- * @module dsh-plugin-subscriptions/providers/rate-limit
+ * @module dsh-plugin-subscription-usage/providers/rate-limit
  */
 import { resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
 /**

package/lib/tools/registration.d.ts

@@ -4,6 +4,7 @@ export declare const TOOL_ALIASES: {
     readonly x_search: "dsh_subscriptions_x_search";
     readonly video_generate: "dsh_subscriptions_video_generate";
     readonly image_generate: "dsh_subscriptions_image_generate";
+    readonly subscription_usage: "dsh_subscriptions_subscription_usage";
 };
 export interface ToolRegistry {
     register(definition: ToolDefinition): () => void;

package/lib/tools/registration.js

@@ -3,6 +3,7 @@ export const TOOL_ALIASES = {
     x_search: 'dsh_subscriptions_x_search',
     video_generate: 'dsh_subscriptions_video_generate',
     image_generate: 'dsh_subscriptions_image_generate',
+    subscription_usage: 'dsh_subscriptions_subscription_usage',
 };
 /** Register a tool under its canonical name, then a plugin-scoped alias. */
 export function registerWithAlias(registry, definition, warn = message => console.warn(message)) {

package/lib/tools/usage.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `subscription_usage` tool: lets the agent read how much of each
+ * subscription limit is used before it starts long or heavy work. Read-only;
+ * it reuses the usage snapshots the Settings page shows.
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { ProviderUsage } from '../providers/common.js';
+/** One signed-in account the tool may report on. */
+export interface UsageTarget {
+    provider: string;
+    /** Account key passed to `read`. */
+    key: string;
+    /** Label safe to show the model: an email or login, never a secret. */
+    label: string;
+}
+/** Where the tool gets accounts and snapshots from. */
+export interface UsageToolSource {
+    /** One account per provider that has a usage endpoint. */
+    targets(): Promise<UsageTarget[]>;
+    read(target: UsageTarget, refresh: boolean, signal: AbortSignal): Promise<ProviderUsage>;
+}
+export interface UsageToolOptions {
+    source: UsageToolSource;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+}
+interface WindowReport {
+    kind: string;
+    scope?: string;
+    usedPercent: number;
+    leftPercent: number;
+    resetsAt?: string;
+    pace: string;
+    emptyAt?: string;
+}
+interface ProviderReport {
+    provider: string;
+    account: string;
+    plan?: string;
+    windows?: WindowReport[];
+    stale?: boolean;
+    fetchedAt?: string;
+    note?: string;
+    error?: string;
+}
+export interface UsageReport {
+    providers: ProviderReport[];
+    note?: string;
+}
+/**
+ * Collect usage for the requested provider, or for every signed-in provider.
+ * One provider's failure becomes an `error` on its own entry.
+ */
+export declare function buildUsageReport(options: UsageToolOptions, args: {
+    provider?: string;
+    refresh?: boolean;
+}, signal: AbortSignal): Promise<UsageReport>;
+/** Build the `subscription_usage` tool definition. */
+export declare function createUsageTool(options: UsageToolOptions): ToolDefinition;
+/** The system prompt reminder, kept short so it costs little on every step. */
+export declare const USAGE_PROMPT_REMINDER = "Before long, critical or heavy work on a subscription model, call subscription_usage to check how much of the limit is left, and prefer a provider whose pace is calm.";
+export {};

package/lib/tools/usage.js

@@ -0,0 +1,89 @@
+/**
+ * `subscription_usage` tool: lets the agent read how much of each
+ * subscription limit is used before it starts long or heavy work. Read-only;
+ * it reuses the usage snapshots the Settings page shows.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { pace } from '../usage/pace.js';
+function iso(ms) {
+    return ms !== undefined && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+}
+function reportWindows(usage, now) {
+    return (usage.windows ?? []).map(window => {
+        const state = pace(window, now);
+        const used = Number.isFinite(window.usedPercent) ? Math.max(0, Math.min(100, window.usedPercent)) : 0;
+        const resetsAt = iso(window.resetsAt);
+        const emptyAt = state.state === 'over' ? iso(state.emptyAt) : undefined;
+        return {
+            kind: window.kind,
+            ...window.scope === undefined ? {} : { scope: window.scope },
+            usedPercent: Math.round(used),
+            leftPercent: 100 - Math.round(used),
+            ...resetsAt === undefined ? {} : { resetsAt },
+            pace: state.state,
+            ...emptyAt === undefined ? {} : { emptyAt },
+        };
+    });
+}
+/**
+ * Collect usage for the requested provider, or for every signed-in provider.
+ * One provider's failure becomes an `error` on its own entry.
+ */
+export async function buildUsageReport(options, args, signal) {
+    const now = (options.now ?? Date.now)();
+    const all = await options.source.targets();
+    const known = [...new Set(all.map(target => target.provider))];
+    if (args.provider !== undefined && !known.includes(args.provider)) {
+        throw new Error(`subscription_usage: no signed-in provider "${args.provider}". Available: ${known.length > 0 ? known.join(', ') : 'none'}`);
+    }
+    const targets = args.provider === undefined ? all : all.filter(target => target.provider === args.provider);
+    if (targets.length === 0)
+        return { providers: [], note: 'No subscription or usage key is set up.' };
+    const providers = await Promise.all(targets.map(async (target) => {
+        const base = { provider: target.provider, account: target.label };
+        try {
+            const usage = await options.source.read(target, args.refresh === true, signal);
+            if (!usage.supported)
+                return { ...base, note: 'This provider reports no usage.' };
+            const fetchedAt = iso(usage.fetchedAt);
+            return {
+                ...base,
+                ...usage.plan === undefined ? {} : { plan: usage.plan },
+                windows: reportWindows(usage, now),
+                ...usage.stale === true || usage.refreshFailed === true ? { stale: true } : {},
+                ...fetchedAt === undefined ? {} : { fetchedAt },
+            };
+        }
+        catch (error) {
+            return { ...base, error: error instanceof Error ? error.message : String(error) };
+        }
+    }));
+    return { providers };
+}
+/** Build the `subscription_usage` tool definition. */
+export function createUsageTool(options) {
+    return defineTool({
+        name: 'subscription_usage',
+        description: 'Read how much of each AI subscription limit is used (ChatGPT Codex, Claude, Grok, Copilot, Antigravity, Z.ai, Ollama Cloud, Kimi Code). '
+            + 'Returns per provider the plan, each window\'s percent used and left, the reset time, and a pace state: calm, tight, over (will run out before reset, with emptyAt) or out. '
+            + 'Call it before long, critical or heavy work, and prefer a provider whose pace is calm. Read-only. It returns cached data unless refresh is true.',
+        parameters: {
+            provider: { type: 'string', description: 'Limit the answer to one provider id, such as codex or claude. Omit for all.' },
+            refresh: { type: 'boolean', description: 'Fetch fresh numbers instead of the cached snapshot.' },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        presentCall: args => ({
+            card: 'generic',
+            title: args.provider === undefined ? 'subscription_usage' : `subscription_usage: ${args.provider}`,
+            kind: 'search',
+        }),
+        async execute(args, exec) {
+            return JSON.stringify(await buildUsageReport(options, args, exec.signal));
+        },
+    });
+}
+/** The system prompt reminder, kept short so it costs little on every step. */
+export const USAGE_PROMPT_REMINDER = 'Before long, critical or heavy work on a subscription model, call subscription_usage to check how much of the limit is left, and prefer a provider whose pace is calm.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-subscription-usage",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ChatGPT (Codex), Claude, Grok, GitHub Copilot and Google Antigravity subscriptions as rows on the DSH Models page, with pace-aware usage meters",
   "license": "MIT",
   "author": "Parth Patel <pp542004@gmail.com>",