@goodandready/dsh-opencode-provider 0.0.0-stage → 0.5.0

package/lib/index.d.ts

@@ -0,0 +1,380 @@
+import { GenerateOptions, LlmAdapter, LlmError, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from "@deepseek-ai/dsh-llm";
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
+import { WebServer } from "@deepseek-ai/dsh-host-webserver";
+//#region src/config.d.ts
+type TransportId = 'openai-chat' | 'openai-responses' | 'anthropic' | 'google';
+interface AccountConfig {
+  label?: string;
+  apiKeyEnv?: string;
+  apiKey?: string;
+}
+interface ModelAccountRule {
+  pattern: string;
+  account: string;
+}
+/**
+ * Plugin configuration. Every field except the literal `apiKey` is volatile:
+ * the harness projects settings forms from schema fields carrying that marker.
+ */
+interface Config {
+  /** Credential reference resolved per request; defaults to `OPENCODE_API_KEY`. */
+  apiKeyEnv?: string;
+  /** Literal key for composition config only; stripped from settings reads by `role('secret')`. */
+  apiKey?: string;
+  /** Console/Zen inference root; defaults to `https://opencode.ai/inference`. */
+  apiBase?: string;
+  /** Go inference root; defaults to `https://opencode.ai/inference/go`. */
+  goApiBase?: string;
+  /** Go unified gateway root; defaults to `https://opencode.ai/zen/go/v1`. */
+  goZenBase?: string;
+  /** Go usage endpoint; defaults to `https://opencode.ai/zen/go/v1/usage`. */
+  usageUrl?: string;
+  /** Entry in OpenCode's `auth.json` to import; defaults to `opencode-go`. */
+  openCodeAuthEntry?: string;
+  /** Milliseconds to wait for response headers; defaults to 300s. */
+  requestTimeoutMs?: number;
+  /** Milliseconds a stream may stall; defaults to 300s. */
+  streamIdleTimeoutMs?: number;
+  /** Visible-model allowlist; an empty list means "show everything". */
+  visibleModels?: string[];
+  /** Per-model visibility overrides; wins over `visibleModels`. */
+  modelVisibility?: Record<string, boolean>;
+  /** Hide models outside the Go allowance on the Go route; defaults to true. */
+  filterModelsByPlan?: boolean;
+  /** Per-model transport overrides; wins over the generated metadata. */
+  modelTransports?: Record<string, TransportId>;
+  /** Global context-window override. */
+  contextWindow?: number;
+  /** Per-model context-window overrides. */
+  contextWindowOverrides?: Record<string, number>;
+  /** Per-turn output cap; `0` omits `max_tokens`. */
+  maxOutputTokens?: number;
+  /** Extra accounts for rotation (parsed now, used by the account pool later). */
+  accounts?: AccountConfig[];
+  /** Preferred account per model glob; other accounts remain fallbacks. */
+  modelAccountRules?: ModelAccountRule[];
+  /** Pinned account id; empty means automatic. */
+  activeAccount?: string;
+  /** Show the quota card in the sidebar. */
+  showSidebarQuota?: boolean;
+  /** Product user agent sent to OpenCode. */
+  userAgent?: string;
+}
+declare const Config: z<Config>;
+interface ResolvedConfig {
+  apiKeyEnv: string;
+  apiKey?: string;
+  apiBase: string;
+  goApiBase: string;
+  goZenBase: string;
+  usageUrl: string;
+  openCodeAuthEntry: string;
+  requestTimeoutMs: number;
+  streamIdleTimeoutMs: number;
+  visibleModels: readonly string[];
+  modelVisibility: Readonly<Record<string, boolean>>;
+  filterModelsByPlan: boolean;
+  modelTransports: Readonly<Record<string, TransportId>>;
+  contextWindow?: number;
+  contextWindowOverrides: Readonly<Record<string, number>>;
+  maxOutputTokens?: number;
+  accounts: readonly AccountConfig[];
+  modelAccountRules: readonly ModelAccountRule[];
+  activeAccount: string;
+  showSidebarQuota: boolean;
+  userAgent: string;
+}
+//#endregion
+//#region src/credentials.d.ts
+interface ResolvedKey {
+  readonly key: string;
+  readonly source: string;
+  /** Slot label (`default` or the configured account name). */
+  readonly label?: string;
+}
+type KeyResolver = (provider: string) => Promise<ResolvedKey>;
+interface KeyPool {
+  resolve(provider: string): Promise<ResolvedKey>;
+  resolveAll(provider: string): Promise<readonly ResolvedKey[]>;
+}
+/** OpenCode stores its own sign-in at this XDG data path. */
+declare function openCodeAuthPath(): string;
+/**
+ * Resolve every configured account for one request. The default account comes
+ * first unless `activeAccount` pins another slot by label or credential name.
+ * Keys are deduplicated; a slot without a resolvable value is skipped.
+ */
+declare function createKeyPool(ctx: Context, config: () => ResolvedConfig): KeyPool;
+/** Backwards-compatible single-key facade over the pool. */
+declare function createKeyResolver(ctx: Context, config: () => ResolvedConfig): KeyResolver;
+//#endregion
+//#region src/adapter.d.ts
+interface OpenCodeAdapterDeps {
+  readonly config: () => ResolvedConfig;
+  readonly resolveKey: KeyResolver;
+  readonly resolveKeys?: (provider: string) => Promise<readonly ResolvedKey[]>;
+  readonly resolveAttachments?: () => AttachmentStore | undefined;
+  readonly fetchImpl?: typeof fetch;
+  /** Test seam; defaults to the local append-only request log. */
+  readonly recordRequest?: (provider: string, model: string, purpose?: string) => void;
+  /** Test seam; defaults to ~/.dsh/storages/dsh-opencode/cooldowns.json. */
+  readonly cooldownPath?: string;
+  /** Receives a one-time warning when the provider tool limit drops tools. */
+  readonly warn?: (message: string) => void;
+}
+declare class OpenCodeAdapter extends LlmAdapter {
+  private readonly deps;
+  private readonly fetchImpl;
+  private readonly cooldownPath;
+  private cooldownWrites;
+  /** key fingerprint → cooldown deadline and the rejection that caused it. */
+  private readonly cooldowns;
+  private warnedTools;
+  constructor(deps: OpenCodeAdapterDeps);
+  providerInfo(provider: string): LlmProviderInfo;
+  providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
+  listModels(provider: string, opts?: {
+    unfiltered?: boolean;
+  }): Promise<readonly LlmModelInfo[]>;
+  resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+  stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+  private run;
+  private parse;
+  private send;
+  private keyId;
+  private coolingDown;
+  /** Current cooldown for one resolved key, if any. */
+  accountHealth(key: string): {
+    coolingUntil: number;
+    reason: string;
+  } | undefined;
+  /** Await pending cooldown persistence writes (tests and shutdown). */
+  flushCooldowns(): Promise<void>;
+  private loadCooldowns;
+  private pruneCooldowns;
+  private persistCooldowns;
+  private markCooldown;
+  private isTransient;
+}
+//#endregion
+//#region src/usage.d.ts
+interface UsageWindow {
+  readonly percentUsed: number;
+  readonly resetsAt?: string;
+  readonly status?: string;
+}
+interface UsageReport {
+  readonly windows: {
+    readonly fiveHour?: UsageWindow;
+    readonly weekly?: UsageWindow;
+    readonly monthly?: UsageWindow;
+  };
+}
+interface UsageResult {
+  readonly report?: UsageReport;
+  readonly error?: string;
+  readonly checkedAt: number;
+}
+interface UsageWindowPayload {
+  status?: string;
+  percent?: number;
+  resetsAt?: string;
+}
+interface UsagePayload {
+  usage?: {
+    rolling?: UsageWindowPayload;
+    weekly?: UsageWindowPayload;
+    monthly?: UsageWindowPayload;
+  };
+}
+declare function normalizeUsage(payload: UsagePayload): UsageReport;
+interface UsageReader {
+  (provider: string, key?: string): Promise<UsageResult | undefined>;
+  /** Drop the cache so the next read hits the endpoint. */
+  clear(): void;
+}
+/** Cached reader for the (undocumented) Go usage endpoint. Fail-open by design. */
+declare function createUsageReader(config: () => ResolvedConfig, resolveKey: KeyResolver, fetchImpl?: typeof fetch): UsageReader;
+//#endregion
+//#region src/commands.d.ts
+interface CommandDeps {
+  readonly config: () => ResolvedConfig;
+  readonly pool: KeyPool;
+  readonly usage: (provider: string, key?: string) => Promise<UsageResult | undefined>;
+  readonly adapter: OpenCodeAdapter;
+}
+declare function applyCommands(ctx: Context, deps: CommandDeps): void;
+//#endregion
+//#region src/analytics.d.ts
+interface ModelUsageRow {
+  provider: string;
+  model: string;
+  sessions: number;
+  turns: number;
+  steps: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  cost: number;
+  priced: boolean;
+  partial: boolean;
+  free: boolean;
+  llmMs: number;
+  ttftMs: number;
+  ttftSteps: number;
+  decodeMs: number;
+}
+interface AnalyticsSummary {
+  sessions: number;
+  requests: number;
+  tokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens: number | null;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  cost: number;
+  priced: boolean;
+  partial: boolean;
+  free: boolean;
+  avgTtftMs: number | null;
+  avgLatencyMs: number | null;
+  errors: number | null;
+  successRate: number | null;
+}
+interface DayUsageRow {
+  date: string;
+  sessions: number;
+  requests: number;
+  tokens: number;
+  cost: number;
+  priced: boolean;
+  partial: boolean;
+  free: boolean;
+  avgTtftMs: number | null;
+}
+interface SessionUsageRow {
+  id: string;
+  provider: string;
+  model: string;
+  at: number;
+  requests: number;
+  tokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  cost: number;
+  priced: boolean;
+  partial: boolean;
+  free: boolean;
+  avgTtftMs: number | null;
+  avgLatencyMs: number | null;
+}
+interface AnalyticsReport {
+  since: number;
+  scannedSessions: number;
+  matchedSessions: number;
+  models: ModelUsageRow[];
+  summary: AnalyticsSummary;
+  days: DayUsageRow[];
+  sessions: SessionUsageRow[];
+}
+//#endregion
+//#region src/request-log.d.ts
+interface ModelRequestHeatmap {
+  provider: string;
+  model: string;
+  total: number;
+  hours: number[];
+  grid: number[][];
+}
+interface RequestHeatmap {
+  since: number;
+  total: number;
+  /** Requests per hour of day, local time. */
+  hours: number[];
+  /** Monday-first weekday × hour grid, local time. */
+  grid: number[][];
+  firstAt: number | null;
+  lastAt: number | null;
+  models: ModelRequestHeatmap[];
+}
+//#endregion
+//#region src/routes.d.ts
+interface RouteDeps {
+  readonly config: () => ResolvedConfig;
+  readonly adapter: OpenCodeAdapter;
+  readonly pool: KeyPool;
+  readonly usage: UsageReader;
+  readonly analytics?: (days: number) => Promise<AnalyticsReport>;
+  readonly heatmap?: (days: number) => Promise<RequestHeatmap>;
+  readonly refreshTui?: () => void;
+}
+/** Register the Host HTTP surface consumed by the browser settings page. */
+declare function applyRoutes(ctx: Context, web: WebServer, deps: RouteDeps): void;
+//#endregion
+//#region src/session-id.d.ts
+/**
+ * A stable, opaque session id for `x-opencode-session`. The header must stay
+ * identical across every turn and retry of one conversation; deriving it from
+ * the durable session id (or, for hand-built calls, the first user turn) gives
+ * that stability without storing state. OpenCode only treats it as an opaque
+ * routing key, so the `dsh_` prefix is safe.
+ */
+declare function openCodeSessionId(options: GenerateOptions): string;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Translate an OpenCode HTTP failure into the harness failure taxonomy.
+ * OpenCode reports several distinct conditions as 400/401, so the body type
+ * and message decide the code — never the status alone.
+ */
+declare function classifyResponseError(status: number, text: string, headers: Headers): LlmError;
+//#endregion
+//#region src/models.generated.d.ts
+type OpenCodeTransport = 'openai-chat' | 'openai-responses' | 'anthropic' | 'google';
+interface OpenCodeModelMeta {
+  readonly id: string;
+  readonly name: string;
+  readonly transport: OpenCodeTransport;
+  readonly contextWindow: number;
+  readonly maxTokens: number;
+  readonly input: readonly ('text' | 'image')[];
+  readonly reasoning: readonly string[];
+  readonly free: boolean;
+  readonly cost: {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+  };
+}
+//#endregion
+//#region src/catalog.d.ts
+interface EffectiveModel extends OpenCodeModelMeta {
+  readonly transport: OpenCodeTransport;
+  readonly contextWindow: number;
+}
+declare function effectiveModel(id: string, config: ResolvedConfig): EffectiveModel;
+declare function describeModel(meta: EffectiveModel, provider?: string): string;
+declare function clearCatalogCache(): void;
+//#endregion
+//#region src/index.d.ts
+declare const name = "llm-opencode";
+declare const inject: string[];
+/**
+ * Register both provider routes against the dsh `llm` service:
+ *
+ * - `opencode`    — Console / Zen pay-as-you-go.
+ * - `opencode-go` — Go / Go Plus subscription (same API, Go base path, quotas).
+ *
+ * Requests resolve their key per call, so a changed credential reaches the
+ * next request without a restart.
+ */
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { type CommandDeps, Config, type Config as OpenCodeConfig, OpenCodeAdapter, type OpenCodeAdapterDeps, type ResolvedConfig, type ResolvedKey, type RouteDeps, type TransportId, type UsageReport, type UsageResult, type UsageWindow, apply, applyCommands, applyRoutes, classifyResponseError, clearCatalogCache, createKeyPool, createKeyResolver, createUsageReader, describeModel, effectiveModel, inject, name, normalizeUsage, openCodeAuthPath, openCodeSessionId };
+//# sourceMappingURL=index.d.ts.map