opencode-dux 1.0.0

package/src/tools/preset-manager.ts

@@ -0,0 +1,332 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type {
+  AgentOverrideConfig,
+  ModelEntry,
+  PluginConfig,
+  Preset,
+} from '../config';
+import { AGENT_ALIASES } from '../config/constants';
+import {
+  getActiveRuntimePreset,
+  rollbackRuntimePreset,
+  setActiveRuntimePresetWithPrevious,
+} from '../config/runtime-preset';
+
+import { createInternalAgentTextPart } from '../utils';
+
+const COMMAND_NAME = 'preset';
+
+/**
+ * Creates a preset manager for the /preset slash command.
+ *
+ * Uses the OpenCode SDK's client.config.update() to change agent models
+ * and temperatures without restarting. The server invalidates its agent
+ * cache and re-reads config on the next prompt.
+ *
+ * Note: activePreset is tracked in-memory only and resets on plugin reload.
+ * If the user manually edits config or another mechanism changes agents,
+ * this tracker may become stale until the next /preset call.
+ */
+export function createPresetManager(ctx: PluginInput, config: PluginConfig) {
+  // Sync from module-level state in case of plugin re-init - the runtime
+  // preset persists across dispose()/re-init cycles.
+  let activePreset: string | null =
+    getActiveRuntimePreset() ?? config.preset ?? null;
+
+  /**
+   * Handle the /preset command from command.execute.before hook.
+   *
+   * - No arguments: list available presets
+   * - With argument: switch to the named preset
+   */
+  async function handleCommandExecuteBefore(
+    input: {
+      command: string;
+      sessionID: string;
+      arguments: string;
+    },
+    output: { parts: Array<{ type: string; text?: string }> },
+  ): Promise<void> {
+    if (input.command !== COMMAND_NAME) {
+      return;
+    }
+
+    // Clear the template so OpenCode doesn't send it to the LLM
+    output.parts.length = 0;
+
+    const arg = input.arguments.trim();
+    const presets = config.presets ?? {};
+
+    if (!arg) {
+      // List available presets
+      output.parts.push(createInternalAgentTextPart(formatPresetList(presets)));
+      return;
+    }
+
+    // Guard against multi-word arguments
+    if (/\s/.test(arg)) {
+      const suggestion = arg.split(/\s+/)[0];
+      output.parts.push(
+        createInternalAgentTextPart(
+          `Preset names cannot contain spaces. Did you mean: /preset ${suggestion}?`,
+        ),
+      );
+      return;
+    }
+
+    // Switch to named preset
+    await switchPreset(arg, presets, output);
+  }
+
+  /**
+   * Register the /preset command in the OpenCode config.
+   */
+  function registerCommand(opencodeConfig: Record<string, unknown>): void {
+    const configCommand = opencodeConfig.command as
+      | Record<string, unknown>
+      | undefined;
+    if (!configCommand?.[COMMAND_NAME]) {
+      if (!opencodeConfig.command) {
+        opencodeConfig.command = {};
+      }
+      (opencodeConfig.command as Record<string, unknown>)[COMMAND_NAME] = {
+        template: 'List available presets and switch between them',
+        description:
+          'Switch agent presets at runtime (e.g., /preset cheap, /preset powerful)',
+      };
+    }
+  }
+
+  /**
+   * Switch to the given preset name by calling client.config.update().
+   */
+  async function switchPreset(
+    presetName: string,
+    presets: Record<string, Preset>,
+    output: { parts: Array<{ type: string; text?: string }> },
+  ): Promise<void> {
+    const preset = presets[presetName];
+    if (!preset) {
+      const available = Object.keys(presets);
+      const hint =
+        available.length > 0
+          ? `Available presets: ${available.join(', ')}`
+          : 'No presets configured. Define presets in opencode-dux.jsonc.';
+      output.parts.push(
+        createInternalAgentTextPart(
+          `Preset "${presetName}" not found. ${hint}`,
+        ),
+      );
+      return;
+    }
+
+    // Build the agent config overrides from the preset.
+    // Each preset value is { agentName: AgentOverrideConfig }.
+    // We need to convert to SDK AgentConfig format:
+    // { agent: { agentName: { model, temperature, ... } } }
+    const agentUpdates: Record<
+      string,
+      {
+        model?: string;
+        temperature?: number;
+        variant?: string;
+        options?: Record<string, unknown>;
+      }
+    > = {};
+    for (const [agentName, override] of Object.entries(preset)) {
+      const resolvedName = AGENT_ALIASES[agentName] ?? agentName;
+      const agentConfig = mapOverrideToAgentConfig(override);
+      if (Object.keys(agentConfig).length > 0) {
+        agentUpdates[resolvedName] = agentConfig;
+      }
+    }
+
+    // Build reset updates for agents in the old preset but not the new one.
+    // The SDK accumulates client.config.update() calls, so switching from
+    // Preset A to Preset B leaks A's variant/temperature/options on agents
+    // that aren't in B. Reset them to the config-file baseline values.
+    const currentRuntimePreset = getActiveRuntimePreset();
+    const resetUpdates: Record<
+      string,
+      {
+        model?: string;
+        temperature?: number;
+        variant?: string;
+        options?: Record<string, unknown>;
+      }
+    > = {};
+    if (currentRuntimePreset && config.presets?.[currentRuntimePreset]) {
+      const oldPreset = config.presets[currentRuntimePreset];
+      for (const rawName of Object.keys(oldPreset)) {
+        const resolvedOld = AGENT_ALIASES[rawName] ?? rawName;
+        if (resolvedOld in agentUpdates) continue; // new preset handles this agent
+        const baseline = config.agents?.[resolvedOld];
+        if (baseline) {
+          // Note: mapOverrideToAgentConfig(baseline) only emits fields
+          // the baseline defines. Scalar fields (variant/temperature/options)
+          // not in baseline are NOT cleared here. The config() hook in
+          // src/index.ts handles complete cleanup using the previous
+          // preset's override keys to drive deletion.
+          resetUpdates[resolvedOld] = mapOverrideToAgentConfig(baseline);
+        }
+      }
+    }
+
+    const hasAgentUpdates = Object.keys(agentUpdates).length > 0;
+    const allUpdates = { ...resetUpdates, ...agentUpdates };
+    if (!hasAgentUpdates) {
+      output.parts.push(
+        createInternalAgentTextPart(
+          `Preset "${presetName}" is empty (no agent overrides defined).`,
+        ),
+      );
+      return;
+    }
+
+    const previousPreset = activePreset;
+    setActiveRuntimePresetWithPrevious(presetName);
+
+    try {
+      await ctx.client.config.update({
+        body: { agent: allUpdates },
+      });
+
+      activePreset = presetName;
+
+      const summaryParts: string[] = [];
+      for (const [name, cfg] of Object.entries(agentUpdates)) {
+        const parts: string[] = [name];
+        if (cfg.model) parts.push(`model: ${cfg.model}`);
+        if (cfg.variant) parts.push(`variant: ${cfg.variant}`);
+        if (cfg.temperature !== undefined)
+          parts.push(`temp: ${cfg.temperature}`);
+        if (cfg.options) parts.push('options: yes');
+        summaryParts.push(parts.join(' → '));
+      }
+      if (Object.keys(resetUpdates).length > 0) {
+        summaryParts.push(
+          `Reset to baseline: ${Object.keys(resetUpdates).join(', ')}`,
+        );
+      }
+
+      output.parts.push(
+        createInternalAgentTextPart(
+          `Switched to preset "${presetName}":\n${summaryParts.join('\n')}`,
+        ),
+      );
+    } catch (err) {
+      rollbackRuntimePreset(previousPreset);
+      output.parts.push(
+        createInternalAgentTextPart(
+          `Failed to switch preset "${presetName}": ${String(err)}`,
+        ),
+      );
+    }
+  }
+
+  /**
+   * Map an AgentOverrideConfig (from plugin config) to the subset of
+   * SDK AgentConfig fields that client.config.update() can apply at runtime.
+   *
+   * Excluded fields and why:
+   * - prompt: resolved at init by config() hook, not part of SDK AgentConfig
+   * - skills: plugin-level concern, not part of SDK AgentConfig
+   * - displayName: plugin-level concern, not part of SDK AgentConfig
+   */
+  function mapOverrideToAgentConfig(override: AgentOverrideConfig): {
+    model?: string;
+    temperature?: number;
+    variant?: string;
+    options?: Record<string, unknown>;
+  } {
+    const agentConfig: {
+      model?: string;
+      temperature?: number;
+      variant?: string;
+      options?: Record<string, unknown>;
+    } = {};
+
+    if (typeof override.model === 'string') {
+      agentConfig.model = override.model;
+    } else if (Array.isArray(override.model) && override.model.length > 0) {
+      // Array-form model (fallback chain): pick the first entry.
+      // The full chain resolution only happens at init time via config() hook,
+      // so at runtime we use the primary model from the array.
+      const first = override.model[0];
+      agentConfig.model = typeof first === 'string' ? first : first.id;
+      if (typeof first !== 'string' && first.variant) {
+        agentConfig.variant = first.variant;
+      }
+    }
+
+    if (typeof override.temperature === 'number') {
+      agentConfig.temperature = override.temperature;
+    }
+
+    if (typeof override.variant === 'string') {
+      agentConfig.variant = override.variant;
+    }
+
+    if (
+      override.options &&
+      typeof override.options === 'object' &&
+      !Array.isArray(override.options)
+    ) {
+      agentConfig.options = override.options;
+    }
+
+    return agentConfig;
+  }
+
+  /**
+   * Format the list of available presets with the active one highlighted.
+   */
+  function formatPresetList(presets: Record<string, Preset>): string {
+    const names = Object.keys(presets);
+    if (names.length === 0) {
+      return 'No presets configured. Define presets in opencode-dux.jsonc under the "presets" field.';
+    }
+
+    const lines = ['Available presets:'];
+    for (const name of names) {
+      const marker = name === activePreset ? ' ← active' : '';
+      const preset = presets[name];
+      const agentNames = Object.keys(preset);
+      const models = agentNames
+        .map((a) => {
+          const cfg = preset[a];
+          const modelStr =
+            typeof cfg.model === 'string'
+              ? cfg.model
+              : Array.isArray(cfg.model) && cfg.model.length > 0
+                ? resolveFirstModel(cfg.model)
+                : undefined;
+          return modelStr ? `    ${a} → ${modelStr}` : `    ${a}`;
+        })
+        .join('\n');
+      lines.push(`  ${name}${marker}`);
+      lines.push(models);
+    }
+    lines.push('\nUsage: /preset <name> to switch.');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Resolve the first model from an array-form model entry.
+   */
+  function resolveFirstModel(
+    models: Array<string | ModelEntry>,
+  ): string | undefined {
+    if (models.length === 0) return undefined;
+    const first = models[0];
+    return typeof first === 'string' ? first : first.id;
+  }
+
+  return {
+    handleCommandExecuteBefore,
+    registerCommand,
+  };
+}
+
+export type PresetManager = ReturnType<typeof createPresetManager>;

package/src/tools/smartfetch/binary.ts

@@ -0,0 +1,58 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { BinaryFetch } from './types';
+
+function extensionForMime(contentType: string) {
+  const mime = contentType.split(';')[0]?.trim().toLowerCase();
+  const map: Record<string, string> = {
+    'application/pdf': 'pdf',
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'application/zip': 'zip',
+  };
+  return map[mime] || 'bin';
+}
+
+export function buildBinaryResultMessage(
+  fetchResult: BinaryFetch,
+  savedPath?: string,
+) {
+  const subject = fetchResult.binaryKind.toUpperCase();
+  if (savedPath) return `${subject} content saved to ${savedPath}`;
+  return `${subject} content omitted because it exceeds the download limit.`;
+}
+
+export async function saveBinary(
+  binaryDir: string,
+  data: Uint8Array,
+  contentType: string,
+  filename?: string,
+) {
+  await mkdir(binaryDir, { recursive: true });
+  const initialName =
+    filename || `webfetch-${Date.now()}.${extensionForMime(contentType)}`;
+  const parsed = path.parse(initialName);
+  for (let attempt = 0; attempt < 1000; attempt++) {
+    const candidateName =
+      attempt === 0
+        ? initialName
+        : `${parsed.name}-${attempt}${parsed.ext || `.${extensionForMime(contentType)}`}`;
+    const file = path.join(binaryDir, candidateName);
+    try {
+      await writeFile(file, data, { flag: 'wx' });
+      return file;
+    } catch (error: unknown) {
+      if (
+        typeof error === 'object' &&
+        error &&
+        'code' in error &&
+        error.code === 'EEXIST'
+      ) {
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error('Unable to allocate unique filename for binary content');
+}

package/src/tools/smartfetch/cache.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test';
+import { buildCacheKey } from './cache';
+
+describe('smartfetch/cache', () => {
+  test('includes save_binary but not format in the cache key', () => {
+    const markdownKey = buildCacheKey(
+      'https://example.com/docs',
+      true,
+      'auto',
+      false,
+    );
+    const htmlKey = buildCacheKey(
+      'https://example.com/docs',
+      true,
+      'auto',
+      false,
+    );
+    const binaryKey = buildCacheKey(
+      'https://example.com/docs',
+      true,
+      'auto',
+      true,
+    );
+
+    expect(markdownKey).toBe(htmlKey);
+    expect(markdownKey).not.toBe(binaryKey);
+    expect(JSON.parse(markdownKey)).toMatchObject({
+      saveBinary: false,
+    });
+    expect(JSON.parse(binaryKey)).toMatchObject({
+      saveBinary: true,
+    });
+  });
+});

package/src/tools/smartfetch/cache.ts

@@ -0,0 +1,112 @@
+import { LRUCache } from 'lru-cache';
+import { canUseCanonicalCacheAlias, isHtmlLikeContentType } from './network';
+import type { FetchResult } from './types';
+
+export const CACHE = new LRUCache<string, FetchResult>({
+  maxSize: 50 * 1024 * 1024,
+  ttl: 15 * 60 * 1000,
+  sizeCalculation: (value: FetchResult) => {
+    if ('binary' in value) return value.data?.byteLength ?? 1024;
+    const rawContent =
+      value.rawContent ?? value.html ?? value.markdown ?? value.text ?? '';
+    return (
+      Buffer.byteLength(rawContent) +
+      Buffer.byteLength(value.html) +
+      Buffer.byteLength(value.markdown) +
+      Buffer.byteLength(value.text)
+    );
+  },
+});
+
+export function buildCacheKey(
+  url: string,
+  extractMain: boolean,
+  preferLlmsTxt: 'auto' | 'always' | 'never',
+  saveBinary: boolean,
+) {
+  const parsed = new URL(url);
+  return JSON.stringify({
+    url: parsed.toString(),
+    extractMain,
+    preferLlmsTxt,
+    saveBinary,
+  });
+}
+
+function cacheKeysFor(
+  fetchResult: FetchResult,
+  extractMain: boolean,
+  preferLlmsTxt: 'auto' | 'always' | 'never',
+  saveBinary: boolean,
+) {
+  const keys = new Set<string>();
+  keys.add(
+    buildCacheKey(
+      fetchResult.requestedUrl,
+      extractMain,
+      preferLlmsTxt,
+      saveBinary,
+    ),
+  );
+  keys.add(
+    buildCacheKey(fetchResult.finalUrl, extractMain, preferLlmsTxt, saveBinary),
+  );
+  if (
+    fetchResult.canonicalUrl &&
+    canUseCanonicalCacheAlias(fetchResult.finalUrl, fetchResult.canonicalUrl)
+  ) {
+    keys.add(
+      buildCacheKey(
+        fetchResult.canonicalUrl,
+        extractMain,
+        preferLlmsTxt,
+        saveBinary,
+      ),
+    );
+  }
+  return [...keys];
+}
+
+export function cacheFetchResult(
+  fetchResult: FetchResult,
+  extractMain: boolean,
+  preferLlmsTxt: 'auto' | 'always' | 'never',
+  saveBinary: boolean,
+) {
+  for (const key of cacheKeysFor(
+    fetchResult,
+    extractMain,
+    preferLlmsTxt,
+    saveBinary,
+  )) {
+    CACHE.set(key, fetchResult);
+  }
+}
+
+export function isInvalidLlmsResult(fetchResult: FetchResult | undefined) {
+  if (!fetchResult || 'binary' in fetchResult) return false;
+  if (!fetchResult.usedLlmsTxt || fetchResult.sourceKind !== 'llms_txt') {
+    return false;
+  }
+  const finalPath = (() => {
+    try {
+      return new URL(fetchResult.finalUrl).pathname.toLowerCase();
+    } catch {
+      return '';
+    }
+  })();
+  if (
+    !(finalPath.endsWith('/llms.txt') || finalPath.endsWith('/llms-full.txt'))
+  ) {
+    return true;
+  }
+  if (isHtmlLikeContentType(fetchResult.contentType)) return true;
+  if (/^\s*(<!doctype html|<html\b)/i.test(fetchResult.rawContent)) return true;
+  if (
+    /<title>\s*(log in|sign in|login)\b/i.test(fetchResult.rawContent) ||
+    /\blog[ -]?in\b/i.test(fetchResult.finalUrl)
+  ) {
+    return true;
+  }
+  return false;
+}

package/src/tools/smartfetch/constants.ts

@@ -0,0 +1,29 @@
+export const DOCS_HOST_SUFFIXES = [
+  '.readthedocs.io',
+  '.readthedocs.org',
+  '.gitbook.io',
+  '.netlify.app',
+  '.vercel.app',
+  'docs.rs',
+];
+
+export const DOCS_HOST_PREFIXES = ['docs.', 'developer.', 'dev.', 'wiki.'];
+export const MAX_REDIRECTS = 10;
+export const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+export const MAX_BINARY_DOWNLOAD_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_TIMEOUT_SECONDS = 30;
+export const MAX_TIMEOUT_SECONDS = 120;
+export const MAX_LLMS_PROBE_TIMEOUT_MS = 8000;
+export const MAX_MODEL_CONTENT_CHARS = 100_000;
+export const DEFAULT_ACCEPT_LANGUAGE = 'en;q=0.8,*;q=0.5';
+export const BINARY_PREFIXES = [
+  'image/',
+  'audio/',
+  'video/',
+  'application/pdf',
+  'application/zip',
+  'application/octet-stream',
+];
+
+export const WEBFETCH_DESCRIPTION =
+  'Fetch a URL with better extraction for static/docs pages. Supports llms.txt probing, content-focused HTML extraction, metadata, redirects, and an optional prompt processed by a cheap secondary model.';

package/src/tools/smartfetch/index.ts

@@ -0,0 +1,8 @@
+export { WEBFETCH_DESCRIPTION } from './constants';
+export { createWebfetchTool } from './tool';
+export type {
+  BinaryFetch,
+  CachedFetch,
+  FetchResult,
+  SmartfetchOptions,
+} from './types';