@tokentop/plugin-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Nigel Bazzeghin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @tokentop/plugin-sdk
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+SDK for building [tokentop](https://github.com/tokentopapp/tokentop) plugins. Types, helpers, and a test harness for provider, agent, theme, and notification plugins.
+
+## Install
+
+```bash
+bun add @tokentop/plugin-sdk
+```
+
+## Quick Example
+
+```typescript
+import {
+  createProviderPlugin,
+  apiKeyCredential,
+  credentialFound,
+  credentialMissing,
+} from '@tokentop/plugin-sdk';
+
+export default createProviderPlugin({
+  id: 'my-provider',
+  type: 'provider',
+  name: 'My Provider',
+  version: '1.0.0',
+  meta: { brandColor: '#3b82f6' },
+  permissions: {
+    network: { enabled: true, allowedDomains: ['api.example.com'] },
+    env: { read: true, vars: ['MY_API_KEY'] },
+  },
+  capabilities: {
+    usageLimits: false,
+    apiRateLimits: false,
+    tokenUsage: false,
+    actualCosts: true,
+  },
+  auth: {
+    async discover(ctx) {
+      const key = ctx.authSources.env.get('MY_API_KEY');
+      return key ? credentialFound(apiKeyCredential(key)) : credentialMissing();
+    },
+    isConfigured: (creds) => !!creds.apiKey,
+  },
+  async fetchUsage(ctx) {
+    const resp = await ctx.http.fetch('https://api.example.com/usage', {
+      headers: { Authorization: `Bearer ${ctx.credentials.apiKey}` },
+    });
+    const data = await resp.json();
+    return { fetchedAt: Date.now(), cost: { total: data.total, currency: 'USD', source: 'api' } };
+  },
+});
+```
+
+## Plugin Types
+
+| Type | Interface | Purpose |
+|------|-----------|---------|
+| `provider` | `ProviderPlugin` | Fetch usage data from AI model providers |
+| `agent` | `AgentPlugin` | Parse coding agent sessions for token tracking |
+| `theme` | `ThemePlugin` | Color schemes for the TUI |
+| `notification` | `NotificationPlugin` | Alert delivery (Slack, Discord, terminal bell) |
+
+## Subpath Exports
+
+| Import | Contents |
+|--------|----------|
+| `@tokentop/plugin-sdk` | Everything (types + helpers) |
+| `@tokentop/plugin-sdk/types` | Type definitions only |
+| `@tokentop/plugin-sdk/helpers` | `createPlugin` helpers, auth helpers, version utils |
+| `@tokentop/plugin-sdk/testing` | Test harness and mock factories |
+
+## Testing
+
+Test plugins without running tokentop:
+
+```typescript
+import { createTestContext } from '@tokentop/plugin-sdk/testing';
+import plugin from './src/index.ts';
+
+const ctx = createTestContext({
+  env: { MY_API_KEY: 'test-key' },
+  httpMocks: {
+    'https://api.example.com/usage': {
+      status: 200,
+      body: { total: 4.50 },
+    },
+  },
+});
+
+const creds = await plugin.auth.discover(ctx);
+assert(creds.ok);
+```
+
+## Publishing
+
+| Plugin type | npm package name |
+|-------------|------------------|
+| Provider | `@tokentop/provider-<name>` |
+| Agent | `@tokentop/agent-<name>` |
+| Theme | `@tokentop/theme-<name>` |
+| Notification | `@tokentop/notification-<name>` |
+
+## Versioning
+
+| Version | What it is |
+|---------|------------|
+| SDK semver (`0.1.0`) | Package version on npm. Normal semver rules. |
+| `apiVersion` (`2`) | Plugin contract version. Core checks at load time. Bumped rarely. |
+
+Use `CURRENT_API_VERSION` and `isCompatible()` to check compatibility. The `createProviderPlugin()` / `createAgentPlugin()` / etc. helpers stamp `apiVersion` automatically.
+
+## Documentation
+
+See [docs/plugin-development.md](docs/plugin-development.md) for the full API reference covering all plugin types, credential discovery, lifecycle hooks, configuration schemas, and testing patterns.
+
+## License
+
+MIT

package/dist/helpers/auth.d.ts

@@ -0,0 +1,15 @@
+import type { Credentials, CredentialResult } from '../types/provider.ts';
+export declare function apiKeyCredential(key: string, source?: Credentials['source']): Credentials;
+export declare function oauthCredential(accessToken: string, options?: {
+    refreshToken?: string;
+    expiresAt?: number;
+    accountId?: string;
+    source?: Credentials['source'];
+}): Credentials;
+export declare function credentialFound(credentials: Credentials): CredentialResult;
+export declare function credentialMissing(message?: string): CredentialResult;
+export declare function credentialExpired(message?: string): CredentialResult;
+export declare function credentialInvalid(message?: string): CredentialResult;
+export declare function credentialError(message: string): CredentialResult;
+export declare function isTokenExpired(expiresAt: number | undefined, bufferMs?: number): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/helpers/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/helpers/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAoB,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,WAAW,CAAC,QAAQ,CAAS,GAAG,WAAW,CAEhG;AAED,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;CAChC,GACA,WAAW,CAMb;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,CAE1E;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAEpE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAEpE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAEpE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAEjE;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAG/F"}

package/dist/helpers/create.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderPlugin } from '../types/provider.ts';
+import type { AgentPlugin } from '../types/agent.ts';
+import type { ThemePlugin } from '../types/theme.ts';
+import type { NotificationPlugin } from '../types/notification.ts';
+type WithoutApiVersion<T> = Omit<T, 'apiVersion'>;
+export declare function createProviderPlugin(def: WithoutApiVersion<ProviderPlugin>): ProviderPlugin;
+export declare function createAgentPlugin(def: WithoutApiVersion<AgentPlugin>): AgentPlugin;
+export declare function createThemePlugin(def: WithoutApiVersion<ThemePlugin>): ThemePlugin;
+export declare function createNotificationPlugin(def: WithoutApiVersion<NotificationPlugin>): NotificationPlugin;
+export {};
+//# sourceMappingURL=create.d.ts.map

package/dist/helpers/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/helpers/create.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,KAAK,iBAAiB,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;AAiBlD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,GAAG,cAAc,CAM3F;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,CAAC,WAAW,CAAC,GAAG,WAAW,CAMlF;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,CAAC,WAAW,CAAC,GAAG,WAAW,CAMlF;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAMvG"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export { createProviderPlugin, createAgentPlugin, createThemePlugin, createNotificationPlugin, } from './create.ts';
+export { apiKeyCredential, oauthCredential, credentialFound, credentialMissing, credentialExpired, credentialInvalid, credentialError, isTokenExpired, } from './auth.ts';
+export { SDK_VERSION, CURRENT_API_VERSION, isCompatible, assertCompatible, } from './version.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,MAAM,cAAc,CAAC"}

package/dist/helpers/index.js

@@ -0,0 +1,182 @@
+import {
+  CURRENT_API_VERSION
+} from "../index-y0tp0jk5.js";
+
+// src/helpers/create.ts
+function validateBase(plugin) {
+  if (!plugin.id || typeof plugin.id !== "string") {
+    throw new Error('Plugin must have a non-empty string "id"');
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(plugin.id)) {
+    throw new Error(`Plugin id "${plugin.id}" must be kebab-case (lowercase letters, numbers, hyphens)`);
+  }
+  if (!plugin.name || typeof plugin.name !== "string") {
+    throw new Error('Plugin must have a non-empty string "name"');
+  }
+  if (!plugin.version || !/^\d+\.\d+\.\d+/.test(plugin.version)) {
+    throw new Error('Plugin must have a valid semver version (e.g. "1.0.0")');
+  }
+}
+function createProviderPlugin(def) {
+  validateBase(def);
+  if (def.type !== "provider") {
+    throw new Error('createProviderPlugin requires type: "provider"');
+  }
+  return { ...def, apiVersion: CURRENT_API_VERSION };
+}
+function createAgentPlugin(def) {
+  validateBase(def);
+  if (def.type !== "agent") {
+    throw new Error('createAgentPlugin requires type: "agent"');
+  }
+  return { ...def, apiVersion: CURRENT_API_VERSION };
+}
+function createThemePlugin(def) {
+  validateBase(def);
+  if (def.type !== "theme") {
+    throw new Error('createThemePlugin requires type: "theme"');
+  }
+  return { ...def, apiVersion: CURRENT_API_VERSION };
+}
+function createNotificationPlugin(def) {
+  validateBase(def);
+  if (def.type !== "notification") {
+    throw new Error('createNotificationPlugin requires type: "notification"');
+  }
+  return { ...def, apiVersion: CURRENT_API_VERSION };
+}
+// src/helpers/auth.ts
+function apiKeyCredential(key, source = "env") {
+  return { apiKey: key, source };
+}
+function oauthCredential(accessToken, options) {
+  const oauth = { accessToken };
+  if (options?.refreshToken !== undefined)
+    oauth.refreshToken = options.refreshToken;
+  if (options?.expiresAt !== undefined)
+    oauth.expiresAt = options.expiresAt;
+  if (options?.accountId !== undefined)
+    oauth.accountId = options.accountId;
+  return { oauth, source: options?.source ?? "external" };
+}
+function credentialFound(credentials) {
+  return { ok: true, credentials };
+}
+function credentialMissing(message) {
+  return { ok: false, reason: "missing", message };
+}
+function credentialExpired(message) {
+  return { ok: false, reason: "expired", message };
+}
+function credentialInvalid(message) {
+  return { ok: false, reason: "invalid", message };
+}
+function credentialError(message) {
+  return { ok: false, reason: "error", message };
+}
+function isTokenExpired(expiresAt, bufferMs = 5 * 60 * 1000) {
+  if (expiresAt === undefined)
+    return false;
+  return expiresAt <= Date.now() + bufferMs;
+}
+// package.json
+var package_default = {
+  name: "@tokentop/plugin-sdk",
+  version: "1.0.0",
+  description: "SDK for building tokentop plugins — providers, agents, themes, and notifications",
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./types": {
+      types: "./dist/types/index.d.ts",
+      import: "./dist/types/index.js"
+    },
+    "./helpers": {
+      types: "./dist/helpers/index.d.ts",
+      import: "./dist/helpers/index.js"
+    },
+    "./testing": {
+      types: "./dist/testing/index.d.ts",
+      import: "./dist/testing/index.js"
+    }
+  },
+  files: [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  scripts: {
+    build: "bun run build:types && bun run build:js",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build:js": "bun build src/index.ts src/types/index.ts src/helpers/index.ts src/testing/index.ts --outdir dist --target node --format esm --splitting",
+    typecheck: "tsc --noEmit",
+    test: "bun test",
+    clean: "rm -rf dist",
+    prepublishOnly: "bun run clean && bun run build"
+  },
+  keywords: [
+    "tokentop",
+    "plugin",
+    "sdk",
+    "ai",
+    "llm",
+    "token-usage",
+    "cost-monitoring"
+  ],
+  author: "Nigel Bazzeghin <nbazzeghin@gmail.com>",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "https://github.com/tokentopapp/plugin-sdk.git"
+  },
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org/"
+  },
+  homepage: "https://github.com/tokentopapp/tokentop",
+  engines: {
+    bun: ">=1.0.0"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    "semantic-release": "^25.0.3",
+    typescript: "^5.7.0"
+  },
+  peerDependencies: {},
+  dependencies: {}
+};
+
+// src/helpers/version.ts
+var SDK_VERSION = package_default.version;
+function isCompatible(pluginApiVersion) {
+  return pluginApiVersion === CURRENT_API_VERSION;
+}
+function assertCompatible(pluginId, pluginApiVersion) {
+  if (!isCompatible(pluginApiVersion)) {
+    throw new Error(`Plugin "${pluginId}" requires API version ${pluginApiVersion}, ` + `but this SDK supports version ${CURRENT_API_VERSION}. ` + (pluginApiVersion > CURRENT_API_VERSION ? "Update tokentop to use this plugin." : "Update the plugin to the latest SDK."));
+  }
+}
+export {
+  oauthCredential,
+  isTokenExpired,
+  isCompatible,
+  credentialMissing,
+  credentialInvalid,
+  credentialFound,
+  credentialExpired,
+  credentialError,
+  createThemePlugin,
+  createProviderPlugin,
+  createNotificationPlugin,
+  createAgentPlugin,
+  assertCompatible,
+  apiKeyCredential,
+  SDK_VERSION,
+  CURRENT_API_VERSION
+};
+export { createProviderPlugin, createAgentPlugin, createThemePlugin, createNotificationPlugin, apiKeyCredential, oauthCredential, credentialFound, credentialMissing, credentialExpired, credentialInvalid, credentialError, isTokenExpired, SDK_VERSION, isCompatible, assertCompatible };

package/dist/helpers/version.d.ts

@@ -0,0 +1,6 @@
+import { CURRENT_API_VERSION } from '../types/plugin.ts';
+export declare const SDK_VERSION: string;
+export { CURRENT_API_VERSION };
+export declare function isCompatible(pluginApiVersion: number): boolean;
+export declare function assertCompatible(pluginId: string, pluginApiVersion: number): void;
+//# sourceMappingURL=version.d.ts.map

package/dist/helpers/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/helpers/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD,eAAO,MAAM,WAAW,EAAE,MAAoB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAE/B,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAUjF"}

package/dist/index-y0tp0jk5.js

@@ -0,0 +1,15 @@
+// src/types/plugin.ts
+var CURRENT_API_VERSION = 2;
+
+class PluginPermissionError extends Error {
+  pluginId;
+  permission;
+  constructor(pluginId, permission, message) {
+    super(`Plugin "${pluginId}" permission denied: ${message}`);
+    this.pluginId = pluginId;
+    this.permission = permission;
+    this.name = "PluginPermissionError";
+  }
+}
+
+export { CURRENT_API_VERSION, PluginPermissionError };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { PluginId, PluginType, PluginPermissions, PluginMeta, ConfigField, BasePlugin, PluginLifecycleContext, PluginLogger, PluginHttpClient, AuthSources, OpenCodeAuthEntry, PluginStorage, PluginContext, CredentialSource, Credentials, OAuthCredentials, RefreshedCredentials, CredentialResult, ProviderAuth, ProviderCapabilities, ModelPricing, ProviderPricing, UsageLimit, CostBreakdown, ProviderUsageData, ProviderFetchContext, ProviderPlugin, AgentConfig, AgentCapabilities, AgentCredentials, AgentProviderConfig, SessionParseOptions, SessionUsageData, ActivityUpdate, ActivityCallback, AgentFetchContext, AgentPlugin, ThemeColors, GaugeColors, ThemeComponents, ThemePlugin, NotificationSeverity, NotificationEventType, NotificationEvent, NotificationContext, NotificationPlugin, AnyPlugin, PluginByType, PluginOfType, } from './types/index.ts';
+export { CURRENT_API_VERSION, PluginPermissionError } from './types/index.ts';
+export { createProviderPlugin, createAgentPlugin, createThemePlugin, createNotificationPlugin, apiKeyCredential, oauthCredential, credentialFound, credentialMissing, credentialExpired, credentialInvalid, credentialError, isTokenExpired, SDK_VERSION, isCompatible, assertCompatible, } from './helpers/index.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,UAAU,EACV,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,WAAW,EACX,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG9E,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,41 @@
+import {
+  CURRENT_API_VERSION,
+  PluginPermissionError
+} from "./index-y0tp0jk5.js";
+import"./types/index.js";
+import {
+  SDK_VERSION,
+  apiKeyCredential,
+  assertCompatible,
+  createAgentPlugin,
+  createNotificationPlugin,
+  createProviderPlugin,
+  createThemePlugin,
+  credentialError,
+  credentialExpired,
+  credentialFound,
+  credentialInvalid,
+  credentialMissing,
+  isCompatible,
+  isTokenExpired,
+  oauthCredential
+} from "./helpers/index.js";
+export {
+  oauthCredential,
+  isTokenExpired,
+  isCompatible,
+  credentialMissing,
+  credentialInvalid,
+  credentialFound,
+  credentialExpired,
+  credentialError,
+  createThemePlugin,
+  createProviderPlugin,
+  createNotificationPlugin,
+  createAgentPlugin,
+  assertCompatible,
+  apiKeyCredential,
+  SDK_VERSION,
+  PluginPermissionError,
+  CURRENT_API_VERSION
+};

package/dist/testing/harness.d.ts

@@ -0,0 +1,49 @@
+import type { PluginContext } from '../types/context.ts';
+import type { PluginLogger } from '../types/plugin.ts';
+import type { ProviderFetchContext } from '../types/provider.ts';
+import type { AgentFetchContext } from '../types/agent.ts';
+import type { Credentials } from '../types/provider.ts';
+export interface MockLogEntry {
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    data?: Record<string, unknown>;
+}
+export interface MockLogger extends PluginLogger {
+    entries: MockLogEntry[];
+    clear(): void;
+}
+export declare function createMockLogger(): MockLogger;
+export interface HttpMock {
+    status: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+export interface MockHttpClientOptions {
+    mocks?: Record<string, HttpMock>;
+    defaultStatus?: number;
+}
+export declare function createMockHttpClient(options?: MockHttpClientOptions): {
+    calls: {
+        url: string;
+        init?: RequestInit;
+    }[];
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+};
+export declare function createMockStorage(initial?: Record<string, string>): {
+    store: Map<string, string>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+};
+export interface TestContextOptions {
+    env?: Record<string, string>;
+    files?: Record<string, string>;
+    httpMocks?: Record<string, HttpMock>;
+    config?: Record<string, unknown>;
+    storage?: Record<string, string>;
+}
+export declare function createTestContext(options?: TestContextOptions): PluginContext;
+export declare function createTestProviderFetchContext(credentials: Credentials, options?: TestContextOptions): ProviderFetchContext;
+export declare function createTestAgentFetchContext(options?: TestContextOptions): AgentFetchContext;
+//# sourceMappingURL=harness.d.ts.map

package/dist/testing/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/testing/harness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAMxD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,gBAAgB,IAAI,UAAU,CAU7C;AAMD,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B;;aAC5C,MAAM;eAAS,WAAW;;eAIjC,MAAM,SAAS,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;EAelE;AAMD,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;aAI/C,MAAM;aACN,MAAM,SAAS,MAAM;gBAClB,MAAM;aACT,MAAM;EAExB;AAMD,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,aAAa,CAuCjF;AAED,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,WAAW,EACxB,OAAO,GAAE,kBAAuB,GAC/B,oBAAoB,CAStB;AAED,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAQnB"}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { createMockLogger, createMockHttpClient, createMockStorage, createTestContext, createTestProviderFetchContext, createTestAgentFetchContext, } from './harness.ts';
+export type { MockLogEntry, MockLogger, HttpMock, MockHttpClientOptions, TestContextOptions, } from './harness.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,134 @@
+// src/testing/harness.ts
+function createMockLogger() {
+  const entries = [];
+  return {
+    entries,
+    debug(message, data) {
+      entries.push({ level: "debug", message, data });
+    },
+    info(message, data) {
+      entries.push({ level: "info", message, data });
+    },
+    warn(message, data) {
+      entries.push({ level: "warn", message, data });
+    },
+    error(message, data) {
+      entries.push({ level: "error", message, data });
+    },
+    clear() {
+      entries.length = 0;
+    }
+  };
+}
+function createMockHttpClient(options = {}) {
+  const calls = [];
+  return {
+    calls,
+    async fetch(url, init) {
+      calls.push({ url, init });
+      const mock = options.mocks?.[url];
+      if (mock) {
+        return new Response(mock.body !== undefined ? JSON.stringify(mock.body) : null, {
+          status: mock.status,
+          headers: { "Content-Type": "application/json", ...mock.headers }
+        });
+      }
+      return new Response(null, { status: options.defaultStatus ?? 404 });
+    }
+  };
+}
+function createMockStorage(initial) {
+  const store = new Map(Object.entries(initial ?? {}));
+  return {
+    store,
+    async get(key) {
+      return store.get(key) ?? null;
+    },
+    async set(key, value) {
+      store.set(key, value);
+    },
+    async delete(key) {
+      store.delete(key);
+    },
+    async has(key) {
+      return store.has(key);
+    }
+  };
+}
+function createTestContext(options = {}) {
+  const logger = createMockLogger();
+  const http = createMockHttpClient({ mocks: options.httpMocks });
+  const storage = createMockStorage(options.storage);
+  const controller = new AbortController;
+  const envMap = options.env ?? {};
+  const fileMap = options.files ?? {};
+  return {
+    config: options.config ?? {},
+    logger,
+    http,
+    storage,
+    signal: controller.signal,
+    authSources: {
+      env: {
+        get(name) {
+          return envMap[name];
+        }
+      },
+      files: {
+        async readText(path) {
+          return fileMap[path] ?? null;
+        },
+        async readJson(path) {
+          const text = fileMap[path];
+          if (!text)
+            return null;
+          try {
+            return JSON.parse(text);
+          } catch {
+            return null;
+          }
+        },
+        async exists(path) {
+          return path in fileMap;
+        }
+      },
+      opencode: {
+        async getProviderEntry(_key) {
+          return null;
+        }
+      },
+      platform: {
+        os: process.platform,
+        homedir: process.env.HOME ?? "/home/test",
+        arch: process.arch
+      }
+    }
+  };
+}
+function createTestProviderFetchContext(credentials, options = {}) {
+  const ctx = createTestContext(options);
+  return {
+    credentials,
+    http: ctx.http,
+    logger: ctx.logger,
+    config: ctx.config,
+    signal: ctx.signal
+  };
+}
+function createTestAgentFetchContext(options = {}) {
+  const ctx = createTestContext(options);
+  return {
+    http: ctx.http,
+    logger: ctx.logger,
+    config: ctx.config,
+    signal: ctx.signal
+  };
+}
+export {
+  createTestProviderFetchContext,
+  createTestContext,
+  createTestAgentFetchContext,
+  createMockStorage,
+  createMockLogger,
+  createMockHttpClient
+};