@pellux/goodvibes-agent 0.1.0

package/src/input/commands/local-provider-runtime.ts

@@ -0,0 +1,170 @@
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { writeFile, unlink } from 'node:fs/promises';
+import type { CommandRegistry } from '../command-registry.ts';
+import { fetchModelContextWindows } from '@pellux/goodvibes-sdk/platform/discovery';
+import type { CustomProviderConfig } from '@pellux/goodvibes-sdk/platform/providers';
+import { requireProviderApi, requireShellPaths } from './runtime-services.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../../config/surface.ts';
+
+function isValidProviderName(name: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+
+export function registerLocalProviderRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'provider',
+    aliases: ['p'],
+    description: 'Switch provider or manage custom providers (add/remove)',
+    usage: '[add <name> <baseURL> [apiKey] | remove <name> | <provider-name>]',
+    argsHint: '[add|remove|name]',
+    async handler(args, ctx) {
+      const shellPaths = requireShellPaths(ctx);
+      if (args[0] === 'add') {
+        const addArgs = args.slice(1);
+        if (addArgs.length < 2) {
+          ctx.print('Usage: /provider add <name> <baseURL> [apiKey]\nExample: /provider add my-server http://192.168.0.85:8001/v1');
+          return;
+        }
+        const [name, baseURL, apiKey] = addArgs;
+        if (!isValidProviderName(name)) {
+          ctx.print('Error: Provider name must contain only letters, numbers, hyphens, and underscores.');
+          return;
+        }
+        let parsedUrl: URL;
+        try {
+          parsedUrl = new URL(baseURL);
+        } catch {
+          ctx.print(`Error: '${baseURL}' is not a valid URL. Example: http://192.168.0.85:8001/v1`);
+          return;
+        }
+        const providersDir = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'providers');
+        const providerFile = join(providersDir, `${name}.json`);
+        if (existsSync(providerFile)) {
+          ctx.print(`Error: Provider '${name}' already exists at ${providerFile}\nRemove it first with: /provider remove ${name}`);
+          return;
+        }
+
+        ctx.print(`Probing ${baseURL}/models ...`);
+        let discoveredModelIds: string[] = [];
+        try {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), 5000);
+          const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+          if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+          const res = await fetch(`${baseURL}/models`, { signal: controller.signal, headers });
+          clearTimeout(timeoutId);
+          if (res.ok) {
+            const body = await res.json() as unknown;
+            if (body && typeof body === 'object' && 'data' in body && Array.isArray((body as Record<string, unknown>).data)) {
+              discoveredModelIds = ((body as { data: unknown[] }).data)
+                .filter((m): m is Record<string, unknown> => typeof m === 'object' && m !== null && 'id' in m)
+                .map((m) => String(m.id))
+                .filter(Boolean);
+            }
+          }
+        } catch {
+          ctx.print(`Could not reach ${baseURL}/models — creating provider with a minimal starter config.`);
+        }
+
+        let contextWindows: Record<string, number> = {};
+        if (discoveredModelIds.length > 0) {
+          if (parsedUrl.protocol === 'http:') {
+            try {
+              contextWindows = await fetchModelContextWindows(parsedUrl.hostname, parseInt(parsedUrl.port) || 80, 'unknown', discoveredModelIds);
+            } catch {}
+          } else {
+            ctx.print('Note: Context window detection is only supported for http:// URLs. Using defaults.');
+          }
+        }
+        const defaultModel = `${name}-model`;
+        const models: CustomProviderConfig['models'] = discoveredModelIds.length === 0
+          ? [{
+              id: defaultModel,
+              displayName: defaultModel,
+              contextWindow: 8192,
+              capabilities: { toolCalling: true, codeEditing: true, reasoning: false, multimodal: false },
+            }]
+          : discoveredModelIds.map((id) => ({
+              id,
+              displayName: id,
+              contextWindow: contextWindows[id] ?? 8192,
+              capabilities: { toolCalling: true, codeEditing: true, reasoning: false, multimodal: false },
+            }));
+        const config: CustomProviderConfig = {
+          name,
+          displayName: name,
+          type: 'openai-compat',
+          baseURL,
+          ...(apiKey ? { apiKey } : {}),
+          models,
+        };
+        try {
+          mkdirSync(providersDir, { recursive: true });
+          await writeFile(providerFile, JSON.stringify(config, null, 2), 'utf-8');
+        } catch (e) {
+          ctx.print(`Error writing provider file: ${summarizeError(e)}`);
+          return;
+        }
+        ctx.print(`Provider '${name}' added with ${models.length} model(s):\n${discoveredModelIds.length > 0 ? discoveredModelIds.map((id) => `  • ${id} (${(contextWindows[id] ?? 8192).toLocaleString()} ctx)`).join('\n') : `  • ${defaultModel} (starter entry)`}\nThe file watcher will auto-register it shortly.`);
+        return;
+      }
+
+      if (args[0] === 'remove' || args[0] === 'rm') {
+        const name = args[1];
+        if (!name) {
+          ctx.print('Usage: /provider remove <name>');
+          return;
+        }
+        if (!isValidProviderName(name)) {
+          ctx.print('Error: Provider name must contain only letters, numbers, hyphens, and underscores.');
+          return;
+        }
+        const providerFile = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'providers', `${name}.json`);
+        if (!existsSync(providerFile)) {
+          ctx.print(`Error: No custom provider '${name}' found at ${providerFile}`);
+          return;
+        }
+        try {
+          await unlink(providerFile);
+          ctx.print(`Provider '${name}' removed. The file watcher will deregister it shortly.`);
+        } catch (e) {
+          ctx.print(`Error removing provider file: ${summarizeError(e)}`);
+        }
+        return;
+      }
+
+      if (args.length === 0) {
+        if (ctx.openProviderPicker) {
+          ctx.openProviderPicker();
+          return;
+        }
+        const providers = requireProviderApi(ctx).listProviderIds();
+        ctx.print(['Available providers:', ...providers.map((provider) => `  ${provider === ctx.session.runtime.provider ? '▶' : ' '} ${provider}`)].join('\n'));
+        return;
+      }
+
+      const providerName = args[0];
+      const providerApi = requireProviderApi(ctx);
+      const selectable = await providerApi.listModels({
+        providerId: providerName,
+        selectableOnly: true,
+      });
+      const match = selectable[0];
+      if (!match) {
+        ctx.print(`Unknown provider: ${providerName}. Available: ${providerApi.listProviderIds().join(', ')}`);
+        return;
+      }
+      try {
+        const selected = await providerApi.selectModel(match.registryKey);
+        ctx.session.runtime.model = selected.registryKey;
+        ctx.session.runtime.provider = selected.providerId;
+        ctx.platform.configManager.set('provider.model', selected.registryKey);
+        ctx.print(`Switched to provider: ${selected.providerId} (model: ${selected.modelId})`);
+      } catch (e) {
+        ctx.print(`Error: ${summarizeError(e)}`);
+      }
+    },
+  });
+}

package/src/input/commands/local-runtime.ts

@@ -0,0 +1,392 @@
+import { dirname, resolve } from 'path';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import type { CommandRegistry, CommandContext } from '../command-registry.ts';
+import type { SelectionItem } from '../selection-modal.ts';
+import type { ContentPart } from '@pellux/goodvibes-sdk/platform/providers';
+import { resolveAndValidatePath } from '@pellux/goodvibes-sdk/platform/utils';
+import { BUILTIN_SECRET_PROVIDER_SOURCES, describeSecretRef, isSecretRefInput, resolveSecretRef } from '@pellux/goodvibes-sdk/platform/config';
+import { openCommandPanel, requireBookmarkManager, requireProviderApi, requireSecretsManager } from './runtime-services.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+function isGoodVibesSecretRefInput(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://secrets/') && isSecretRefInput(normalized);
+}
+
+function isMalformedGoodVibesSecretRefInput(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://') && !isGoodVibesSecretRefInput(normalized);
+}
+
+function toggleBlocks(typeFilter: string, collapsed: boolean, ctx: CommandContext): void {
+  const VALID_TYPES = ['all', 'thinking', 'tool', 'code'] as const;
+  if (!VALID_TYPES.includes(typeFilter as typeof VALID_TYPES[number])) {
+    ctx.print(`Unknown type: ${typeFilter}\nValid types: ${VALID_TYPES.join(', ')}`);
+    return;
+  }
+  const blockRegistry = ctx.session.conversationManager.getBlockRegistry();
+  if (!blockRegistry || blockRegistry.length === 0) {
+    ctx.print('No blocks found.');
+    return;
+  }
+  let count = 0;
+  for (let i = 0; i < blockRegistry.length; i++) {
+    const block = blockRegistry[i];
+    const matchesType = typeFilter === 'all'
+      || (typeFilter === 'tool' && block.type === 'tool')
+      || (typeFilter === 'code' && block.type === 'code')
+      || (typeFilter === 'thinking' && block.type === 'thinking');
+    if (!matchesType) continue;
+    const isCurrentlyCollapsed = ctx.session.conversationManager.isCollapsed(i);
+    if (collapsed ? !isCurrentlyCollapsed : isCurrentlyCollapsed) {
+      ctx.session.conversationManager.toggleCollapseAtLine(block.startLine);
+      count++;
+    }
+  }
+  ctx.print(`${collapsed ? 'Collapsed' : 'Expanded'} ${count} block${count !== 1 ? 's' : ''}${typeFilter !== 'all' ? ` (${typeFilter})` : ''}.`);
+  ctx.renderRequest();
+}
+
+export function registerLocalRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'incident-review',
+    aliases: [],
+    description: 'Alias for /incident open',
+    usage: '',
+    handler(_args, ctx) {
+      if (ctx.openIncidentPanel) {
+        ctx.openIncidentPanel();
+        return;
+      }
+      ctx.print('Incident panel is not available in this runtime.');
+    },
+  });
+
+  registry.register({
+    name: 'tools',
+    aliases: ['t'],
+    description: 'List available tools and review compact native tool capability surfaces',
+    usage: '[review|panel]',
+    handler(args, ctx) {
+      const sub = (args[0] ?? '').toLowerCase();
+      if (sub === 'panel' || sub === 'review') {
+        try {
+          openCommandPanel(ctx, 'tools');
+        } catch {
+          // Panel registry may be unavailable in lightweight command-only contexts.
+        }
+        if (sub === 'review') {
+          ctx.print([
+            'Tool Surface Review',
+            '  Native file tools stay compact by default.',
+            '  Read/write/edit/notebook capabilities are available through the native tool stack, with detail routed to the tools panel and approval surfaces instead of transcript bloat.',
+            '  Shell and native tool approvals classify work into read, mutation, destructive, dependency, config, notebook, network, remote, and lifecycle risk families.',
+            '  Use /tools panel to inspect risk class, output-policy actions, spill posture, compact summaries, and approval posture for recent calls.',
+            '  Use /approval review shell or /approval review file when you need the action-specific why-prompted posture.',
+          ].join('\n'));
+        }
+        return;
+      }
+      const tools = ctx.extensions.toolRegistry.list();
+      if (ctx.openSelection) {
+        const items: SelectionItem[] = tools.map(t => ({
+          id: t.definition.name,
+          label: t.definition.name,
+          detail: typeof t.definition.description === 'string' ? t.definition.description.slice(0, 50) : '',
+        }));
+        ctx.openSelection('Available Tools', items, { allowSearch: true }, (result) => {
+          if (!result) return;
+          const tool = tools.find(t2 => t2.definition.name === result.item.id);
+          if (tool) ctx.print(`Tool: ${tool.definition.name}\n  ${tool.definition.description ?? ''}`);
+        });
+        return;
+      }
+      ctx.print(['Available tools:', ...tools.map(t => `  • ${t.definition.name}`)].join('\n'));
+    },
+  });
+
+  registry.register({ name: 'expand', description: 'Expand blocks by type', usage: '[all|thinking|tool|code]', argsHint: '[all|thinking|tool|code]', handler(args, ctx) { toggleBlocks(args[0] || 'all', false, ctx); } });
+  registry.register({ name: 'collapse', description: 'Collapse blocks by type', usage: '[all|thinking|tool|code]', argsHint: '[all|thinking|tool|code]', handler(args, ctx) { toggleBlocks(args[0] || 'all', true, ctx); } });
+
+  registry.register({
+    name: 'bookmarks',
+    aliases: ['bm'],
+    description: 'List bookmarked blocks',
+    handler(_args, ctx) {
+      if (ctx.openBookmarkModal) {
+        ctx.openBookmarkModal();
+        return;
+      }
+      const bm = requireBookmarkManager(ctx);
+      const entries = bm.list();
+      if (ctx.openSelection) {
+        const deleteAction = new Map([['d', 'delete' as const]]);
+        const items: SelectionItem[] = entries.length === 0
+          ? [{ id: '_empty', label: 'No bookmarks', detail: 'Use Ctrl+B to bookmark' }]
+          : entries.map(entry => ({ id: entry.key, label: entry.label, detail: new Date(entry.timestamp).toLocaleTimeString(), actions: '[d] delete' }));
+        ctx.openSelection('Bookmarks', items, { allowSearch: true, customActions: deleteAction }, (result) => {
+          if (!result) return;
+          if (result.action === 'delete') {
+            bm.toggle(result.item.id);
+            ctx.print(`Bookmark removed: ${result.item.id}`);
+          } else {
+            ctx.jumpToBookmark?.(result.item.id);
+          }
+        });
+        return;
+      }
+      ctx.print(['Bookmarks:', '', ...entries.map(entry => `  ${entry.key.padEnd(32)} ${entry.label}  (${new Date(entry.timestamp).toLocaleTimeString()})`)].join('\n'));
+    },
+  });
+
+  registry.register({
+    name: 'secrets',
+    description: 'Manage hierarchy-aware secrets, external secret refs, and secure/plaintext storage policy controls',
+    usage: 'set <KEY> <value> [--user|--project] [--secure|--plaintext] | link <KEY> <secret-ref> [--user|--project] [--secure|--plaintext] | get <KEY> | test <secret-ref> | providers | list | delete <KEY> [--user|--project] [--secure|--plaintext]',
+    argsHint: '<set|link|get|test|providers|list|delete> [KEY]',
+    async handler(args, ctx) {
+      const mgr = requireSecretsManager(ctx);
+      const [sub, ...rest] = args;
+      if (!sub || sub === 'list') {
+        const records = await mgr.listDetailed();
+        const storedRecords = records.filter((record) => record.source !== 'env');
+        ctx.print(storedRecords.length === 0
+          ? '[secrets] No secrets stored. Use: /secrets set <KEY> <value>'
+          : [
+            '[secrets] Stored keys:',
+            ...storedRecords.map((record) => `  ${record.key} (${record.source}${record.refSource ? `, ref:${record.refSource}` : ''}${record.overriddenByEnv ? ', env override' : ''})`),
+          ].join('\n'));
+        return;
+      }
+      if (sub === 'providers') {
+        ctx.print([
+          '[secrets] Built-in secret providers:',
+          ...BUILTIN_SECRET_PROVIDER_SOURCES.map((source) => `  ${source}`),
+          '',
+          'Examples:',
+          '  /secrets link OPENAI_API_KEY goodvibes://secrets/env/OPENAI_API_KEY',
+          '  /secrets link SLACK_BOT_TOKEN goodvibes://secrets/bitwarden?item=GoodVibes%20Slack&field=password&sessionEnv=BW_SESSION',
+          '  /secrets link SLACK_BOT_TOKEN goodvibes://secrets/vaultwarden?item=GoodVibes%20Slack&field=password&server=https%3A%2F%2Fvault.example.test',
+          '  /secrets link STRIPE_TOKEN goodvibes://secrets/bws/00000000-0000-0000-0000-000000000000?field=value&accessTokenEnv=BWS_ACCESS_TOKEN',
+          '  /secrets link OPENAI_API_KEY goodvibes://secrets/1password?vault=Private&item=GoodVibes%20OpenAI&field=API%20Key',
+        ].join('\n'));
+        return;
+      }
+      if (sub === 'test') {
+        const refText = rest.join(' ').trim();
+        if (!refText) {
+          ctx.print('[secrets] Usage: /secrets test <secret-ref>');
+          return;
+        }
+        if (!isGoodVibesSecretRefInput(refText)) {
+          ctx.print('[secrets] Invalid secret reference. Use /secrets providers for examples.');
+          return;
+        }
+        try {
+          const resolved = await resolveSecretRef(refText, { resolveLocalSecret: (key) => mgr.get(key) });
+          ctx.print(`[secrets] ${describeSecretRef(refText)}: ${resolved.value ? 'resolved <redacted>' : 'missing'}`);
+        } catch (error) {
+          ctx.print(`[secrets] ${describeSecretRef(refText)} failed: ${summarizeError(error)}`);
+        }
+        return;
+      }
+      if (sub === 'set' || sub === 'link') {
+        const flags = new Set(rest.filter((value) => value.startsWith('--')));
+        const valueParts = rest.filter((value) => !value.startsWith('--'));
+        const [key, ...rawValueParts] = valueParts;
+        if (!key || valueParts.length === 0) {
+          ctx.print(`[secrets] Usage: /secrets ${sub} <KEY> <${sub === 'link' ? 'secret-ref' : 'value'}> [--user|--project] [--secure|--plaintext]`);
+          return;
+        }
+        const value = rawValueParts.join(' ');
+        if (sub === 'link' && !isGoodVibesSecretRefInput(value)) {
+          ctx.print('[secrets] Invalid secret reference. Use /secrets providers for examples.');
+          return;
+        }
+        if (sub === 'set' && isMalformedGoodVibesSecretRefInput(value)) {
+          ctx.print('[secrets] Invalid secret reference. Use /secrets providers for examples.');
+          return;
+        }
+        const scope = flags.has('--user') ? 'user' : 'project';
+        const medium = flags.has('--plaintext') ? 'plaintext' : 'secure';
+        await mgr.set(key, value, { scope, medium });
+        ctx.print(sub === 'link'
+          ? `[secrets] Linked: ${key} -> ${describeSecretRef(value)} (${scope}, ${medium})`
+          : `[secrets] Stored: ${key} (${scope}, ${medium})`);
+        return;
+      }
+      if (sub === 'get') {
+        const [key] = rest;
+        if (!key) {
+          ctx.print('[secrets] Usage: /secrets get <KEY>');
+          return;
+        }
+        const value = await mgr.get(key);
+        ctx.print(value === null ? `[secrets] Not found: ${key}` : `[secrets] ${key} = <stored> (use /secrets list to see all keys)`);
+        return;
+      }
+      if (sub === 'delete') {
+        const flags = new Set(rest.filter((value) => value.startsWith('--')));
+        const [key] = rest.filter((value) => !value.startsWith('--'));
+        if (!key) {
+          ctx.print('[secrets] Usage: /secrets delete <KEY> [--user|--project] [--secure|--plaintext]');
+          return;
+        }
+        await mgr.delete(key, {
+          scope: flags.has('--user') ? 'user' : flags.has('--project') ? 'project' : undefined,
+          medium: flags.has('--plaintext') ? 'plaintext' : flags.has('--secure') ? 'secure' : undefined,
+        });
+        ctx.print(`[secrets] Deleted: ${key}`);
+        return;
+      }
+      ctx.print('[secrets] Usage: /secrets set <KEY> <value> [--user|--project] [--secure|--plaintext] | link <KEY> <secret-ref> [--user|--project] [--secure|--plaintext] | get <KEY> | test <secret-ref> | providers | list | delete <KEY> [--user|--project] [--secure|--plaintext]');
+    },
+  });
+
+  registry.register({
+    name: 'image',
+    aliases: ['img'],
+    description: 'Attach an image file to the next message',
+    usage: '<path> [prompt text]',
+    argsHint: '<path> [prompt]',
+    async handler(args, ctx) {
+      if (args.length === 0) {
+        ctx.print('Usage: /image <path> [prompt text]\nSupported formats: PNG, JPEG, WebP, GIF');
+        return;
+      }
+      const rawPath = args[0];
+      const promptText = args.slice(1).join(' ') || `Attached image: ${rawPath.split('/').pop() ?? rawPath}`;
+      const projectRoot = ctx.workspace.shellPaths?.workingDirectory ?? ctx.platform.configManager.getWorkingDirectory();
+      if (!projectRoot) {
+        ctx.print('Error: working directory is unavailable.');
+        return;
+      }
+      let resolvedPath: string;
+      try {
+        resolvedPath = resolveAndValidatePath(rawPath, projectRoot);
+      } catch (err) {
+        ctx.print(`Error: ${summarizeError(err)}`);
+        return;
+      }
+      if (!existsSync(resolvedPath)) {
+        ctx.print(`File not found: ${rawPath}`);
+        return;
+      }
+      const ext = resolvedPath.slice(resolvedPath.lastIndexOf('.')).toLowerCase();
+      const mediaType = ({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' } as Record<string, string>)[ext];
+      if (!mediaType) {
+        ctx.print(`Unsupported image format: ${ext}\nSupported: .png, .jpg, .jpeg, .webp, .gif`);
+        return;
+      }
+      const stat = statSync(resolvedPath);
+      if (stat.size > 20 * 1024 * 1024) {
+        ctx.print(`Image too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Maximum: 20MB`);
+        return;
+      }
+      let data: string;
+      try {
+        data = (await readFile(resolvedPath)).toString('base64');
+      } catch (err) {
+        ctx.print(`Failed to read image: ${summarizeError(err)}`);
+        return;
+      }
+      const currentModel = await requireProviderApi(ctx).getCurrentModel();
+      if (!currentModel.capabilities.multimodal) {
+        ctx.print(`Warning: ${currentModel.displayName} does not support image input. The image will be stripped when sending.`);
+      }
+      const content: ContentPart[] = [{ type: 'text', text: promptText }, { type: 'image', data, mediaType }];
+      ctx.submitInput?.(promptText, content);
+    },
+  });
+
+  registry.register({
+    name: 'refresh-models',
+    description: 'Refresh model catalog, benchmarks, and token limits',
+    async handler(_args, ctx) {
+      const providerApi = requireProviderApi(ctx);
+      let catalogOk = false;
+      let benchmarksOk = false;
+      let limitsOk = false;
+      ctx.print('Refreshing model catalog...');
+      try {
+        const catalog = await providerApi.refreshCatalog();
+        catalogOk = true;
+        ctx.print(`Model catalog refreshed: ${catalog.modelCount} models from ${catalog.providerCount} providers`);
+      } catch (e) {
+        ctx.print(`Catalog refresh failed: ${summarizeError(e)}`);
+      }
+      ctx.print('Refreshing benchmarks...');
+      try {
+        const benchmarkCount = await providerApi.refreshBenchmarks();
+        benchmarksOk = true;
+        ctx.print(`Benchmarks refreshed${benchmarkCount > 0 ? `: ${benchmarkCount} model records available.` : '.'}`);
+      } catch (e) {
+        ctx.print(`Benchmarks refresh failed: ${summarizeError(e)}`);
+      }
+      ctx.print('Refreshing token limits...');
+      try {
+        const count = await providerApi.refreshModelLimits();
+        limitsOk = true;
+        ctx.print(`Token limits refreshed: ${count} models updated.`);
+      } catch (e) {
+        ctx.print(`Token limits refresh failed: ${summarizeError(e)}`);
+      }
+      if (!catalogOk || !benchmarksOk || !limitsOk) ctx.print('Some refreshes failed — see messages above.');
+    },
+  });
+
+  registry.register({
+    name: 'pin',
+    description: 'Pin a model to the favorites list',
+    usage: '<model-id>',
+    argsHint: '<model-id>',
+    async handler(args, ctx) {
+      const providerApi = requireProviderApi(ctx);
+      const modelId = args[0];
+      if (!modelId) {
+        const favorites = await providerApi.getFavorites();
+        ctx.print(
+          favorites.pinned.length === 0
+            ? 'No pinned models. Use /pin <model-id> to pin one.'
+            : `Pinned models:\n${favorites.pinned.map((entry) => `  ★ ${entry.registryKey ?? entry.modelId}`).join('\n')}`,
+        );
+        return;
+      }
+      const favorites = await providerApi.getFavorites();
+      if (favorites.pinned.some((entry) => entry.modelId === modelId || entry.registryKey === modelId)) {
+        ctx.print(`Model already pinned: ${modelId}`);
+        return;
+      }
+      try {
+        await providerApi.pinModel(modelId);
+        ctx.print(`Pinned: ${modelId}`);
+      } catch (e) {
+        ctx.print(`Error: ${summarizeError(e)}`);
+      }
+    },
+  });
+
+  registry.register({
+    name: 'unpin',
+    description: 'Unpin a model from the favorites list',
+    usage: '<model-id>',
+    argsHint: '<model-id>',
+    async handler(args, ctx) {
+      const providerApi = requireProviderApi(ctx);
+      const modelId = args[0];
+      if (!modelId) {
+        ctx.print('Usage: /unpin <model-id>');
+        return;
+      }
+      const favorites = await providerApi.getFavorites();
+      const pinned = favorites.pinned.find((entry) => entry.registryKey === modelId);
+      if (!pinned) {
+        ctx.print(`Model is not pinned: ${modelId}`);
+        return;
+      }
+      await providerApi.unpinModel(pinned.registryKey);
+      ctx.print(`Unpinned: ${modelId}`);
+    },
+  });
+}