@link-assistant/agent 0.5.2 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",
@@ -82,6 +82,7 @@
     "hono-openapi": "^1.1.1",
     "ignore": "^7.0.5",
     "jsonc-parser": "^3.3.1",
+    "lino-objects-codec": "^0.1.1",
     "minimatch": "^10.1.1",
     "open": "^11.0.0",
     "partial-json": "^0.1.7",

package/src/provider/cache.ts

@@ -0,0 +1,259 @@
+/**
+ * Cache Provider - A synthetic provider for caching API responses
+ *
+ * This provider caches API responses to enable deterministic testing.
+ * When a response is not cached, it falls back to the echo provider behavior.
+ * Cached responses are stored using Links Notation format (.lino files).
+ *
+ * Usage:
+ *   agent --model link-assistant/cache/opencode -p "hello"  # Uses cached responses
+ *
+ * Cache location: ./data/api-cache/{provider}/{model}/
+ * Format: Links Notation files with .lino extension
+ *
+ * @see https://github.com/link-assistant/agent/issues/89
+ * @see https://github.com/link-foundation/lino-objects-codec
+ */
+
+import type { LanguageModelV2, LanguageModelV2CallOptions } from 'ai';
+import { Log } from '../util/log';
+import { createEchoModel } from './echo';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+// @ts-ignore - lino-objects-codec is a JavaScript library
+import { encode, decode } from 'lino-objects-codec';
+
+const log = Log.create({ service: 'provider.cache' });
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CACHE_ROOT = join(__dirname, '../../data/api-cache');
+
+/**
+ * Generate a cache key from the prompt
+ */
+function generateCacheKey(
+  prompt: LanguageModelV2CallOptions['prompt']
+): string {
+  // Simple hash of the prompt content
+  const content = JSON.stringify(prompt);
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+  return Math.abs(hash).toString(36);
+}
+
+/**
+ * Get cache file path for a provider/model combination
+ * Uses .lino extension for Links Notation format
+ */
+function getCachePath(provider: string, model: string, key: string): string {
+  return join(CACHE_ROOT, provider, model, `${key}.lino`);
+}
+
+/**
+ * Generate a unique ID for streaming parts
+ */
+function generatePartId(): string {
+  return `cache_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+}
+
+/**
+ * Load cached response from file using Links Notation format
+ */
+function loadCachedResponse(filePath: string): any | null {
+  try {
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    const content = readFileSync(filePath, 'utf8');
+    // Decode from Links Notation format
+    return decode({ notation: content });
+  } catch (error: any) {
+    log.warn('Failed to load cached response', {
+      filePath,
+      error: error.message,
+    });
+    return null;
+  }
+}
+
+/**
+ * Save response to cache file using Links Notation format
+ */
+function saveCachedResponse(filePath: string, response: any): void {
+  try {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    // Encode to Links Notation format
+    const encoded = encode({ obj: response });
+    writeFileSync(filePath, encoded, 'utf8');
+    log.info('Saved cached response', { filePath });
+  } catch (error: any) {
+    log.warn('Failed to save cached response', {
+      filePath,
+      error: error.message,
+    });
+  }
+}
+
+/**
+ * Creates a cache language model that stores/retrieves responses
+ * Implements LanguageModelV2 interface for AI SDK 6.x compatibility
+ */
+export function createCacheModel(
+  providerId: string,
+  modelId: string
+): LanguageModelV2 {
+  const model: LanguageModelV2 = {
+    specificationVersion: 'v2',
+    provider: 'link-assistant',
+    modelId: `${providerId}/${modelId}`,
+
+    // No external URLs are supported by this synthetic provider
+    supportedUrls: {},
+
+    async doGenerate(options: LanguageModelV2CallOptions) {
+      const cacheKey = generateCacheKey(options.prompt);
+      const cachePath = getCachePath(providerId, modelId, cacheKey);
+
+      // Try to load from cache first
+      const cached = loadCachedResponse(cachePath);
+      if (cached) {
+        log.info('Using cached response', { providerId, modelId, cacheKey });
+        return cached;
+      }
+
+      // Fall back to echo behavior
+      log.info('No cached response, using echo fallback', {
+        providerId,
+        modelId,
+        cacheKey,
+      });
+      const echoModel = createEchoModel(`${providerId}/${modelId}`);
+      const response = await echoModel.doGenerate(options);
+
+      // Save to cache for future use
+      saveCachedResponse(cachePath, response);
+
+      return response;
+    },
+
+    async doStream(options: LanguageModelV2CallOptions) {
+      const cacheKey = generateCacheKey(options.prompt);
+      const cachePath = getCachePath(providerId, modelId, cacheKey);
+
+      // Try to load from cache first
+      const cached = loadCachedResponse(cachePath);
+      if (cached) {
+        log.info('Using cached streaming response', {
+          providerId,
+          modelId,
+          cacheKey,
+        });
+
+        // For cached responses, we need to simulate streaming
+        // Extract the text from the cached response
+        const echoText =
+          cached.content?.[0]?.text || cached.text || 'Cached response';
+        const textPartId = generatePartId();
+
+        // Create a ReadableStream with LanguageModelV2StreamPart format
+        const stream = new ReadableStream({
+          async start(controller) {
+            // Emit text-start
+            controller.enqueue({
+              type: 'text-start',
+              id: textPartId,
+              providerMetadata: undefined,
+            });
+
+            // Emit the text in chunks for realistic streaming behavior
+            const chunkSize = 10;
+            for (let i = 0; i < echoText.length; i += chunkSize) {
+              const chunk = echoText.slice(i, i + chunkSize);
+              controller.enqueue({
+                type: 'text-delta',
+                id: textPartId,
+                delta: chunk,
+                providerMetadata: undefined,
+              });
+            }
+
+            // Emit text-end
+            controller.enqueue({
+              type: 'text-end',
+              id: textPartId,
+              providerMetadata: undefined,
+            });
+
+            // Emit finish event
+            controller.enqueue({
+              type: 'finish',
+              finishReason: 'stop',
+              usage: cached.usage || {
+                promptTokens: Math.ceil(echoText.length / 4),
+                completionTokens: Math.ceil(echoText.length / 4),
+              },
+              providerMetadata: undefined,
+            });
+
+            controller.close();
+          },
+        });
+
+        return {
+          stream,
+          request: undefined,
+          response: undefined,
+          warnings: [],
+        };
+      }
+
+      // Fall back to echo streaming behavior
+      log.info('No cached streaming response, using echo fallback', {
+        providerId,
+        modelId,
+        cacheKey,
+      });
+      const echoModel = createEchoModel(`${providerId}/${modelId}`);
+      const response = await echoModel.doStream(options);
+
+      // Note: We don't cache streaming responses as they're consumed immediately
+      return response;
+    },
+  };
+
+  return model;
+}
+
+/**
+ * Cache provider factory function
+ */
+export function createCacheProvider(options?: { name?: string }) {
+  return {
+    languageModel(modelId: string): LanguageModelV2 {
+      // Parse provider/model from modelId like "opencode/grok-code"
+      const parts = modelId.split('/');
+      if (parts.length < 2) {
+        throw new Error(
+          `Invalid cache model ID: ${modelId}. Expected format: provider/model`
+        );
+      }
+      const [providerId, ...modelParts] = parts;
+      const actualModelId = modelParts.join('/');
+
+      return createCacheModel(providerId, actualModelId);
+    },
+    textEmbeddingModel() {
+      throw new Error('Cache provider does not support text embeddings');
+    },
+  };
+}
+
+export const cacheProvider = createCacheProvider();

package/src/provider/echo.ts

@@ -0,0 +1,174 @@
+/**
+ * Echo Provider - A synthetic provider for testing dry-run mode
+ *
+ * This provider echoes back the user's input message without making actual API calls.
+ * It's designed to enable robust testing of round-trips and multi-turn conversations
+ * without incurring API costs.
+ *
+ * Usage:
+ *   agent --dry-run -p "hello"  # Uses echo provider automatically
+ *   agent --model link-assistant/echo -p "hello"  # Explicit usage
+ *
+ * The echo behavior follows the issue #89 specification:
+ *   Input: "hi" -> Output: "hi"
+ *   Input: "How are you?" -> Output: "How are you?"
+ */
+
+import type { LanguageModelV2, LanguageModelV2CallOptions } from 'ai';
+import { Log } from '../util/log';
+
+const log = Log.create({ service: 'provider.echo' });
+
+/**
+ * Extract text content from the prompt messages
+ */
+function extractTextFromPrompt(
+  prompt: LanguageModelV2CallOptions['prompt']
+): string {
+  const textParts: string[] = [];
+
+  for (const message of prompt) {
+    if (message.role === 'user') {
+      for (const part of message.content) {
+        if (part.type === 'text') {
+          textParts.push(part.text);
+        }
+      }
+    }
+  }
+
+  // Return the last user message or a default response
+  return textParts.length > 0
+    ? textParts[textParts.length - 1]
+    : 'Echo: No user message found';
+}
+
+/**
+ * Generate a unique ID for streaming parts
+ */
+function generatePartId(): string {
+  return `echo_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+}
+
+/**
+ * Creates an echo language model that echoes back the user's input
+ * Implements LanguageModelV2 interface for AI SDK 6.x compatibility
+ */
+export function createEchoModel(modelId: string = 'echo'): LanguageModelV2 {
+  const model: LanguageModelV2 = {
+    specificationVersion: 'v2',
+    provider: 'link-assistant',
+    modelId,
+
+    // No external URLs are supported by this synthetic provider
+    supportedUrls: {},
+
+    async doGenerate(options: LanguageModelV2CallOptions) {
+      const echoText = extractTextFromPrompt(options.prompt);
+      log.info('echo generate', { modelId, echoText });
+
+      // Simulate token usage
+      const promptTokens = Math.ceil(echoText.length / 4);
+      const completionTokens = Math.ceil(echoText.length / 4);
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: echoText,
+          },
+        ],
+        finishReason: 'stop' as const,
+        usage: {
+          promptTokens,
+          completionTokens,
+        },
+        warnings: [],
+        providerMetadata: undefined,
+        request: undefined,
+        response: undefined,
+      };
+    },
+
+    async doStream(options: LanguageModelV2CallOptions) {
+      const echoText = extractTextFromPrompt(options.prompt);
+      log.info('echo stream', { modelId, echoText });
+
+      // Simulate token usage
+      const promptTokens = Math.ceil(echoText.length / 4);
+      const completionTokens = Math.ceil(echoText.length / 4);
+
+      const textPartId = generatePartId();
+
+      // Create a ReadableStream with LanguageModelV2StreamPart format
+      // V2 format uses: text-start -> text-delta (with delta) -> text-end -> finish
+      const stream = new ReadableStream({
+        async start(controller) {
+          // Emit text-start
+          controller.enqueue({
+            type: 'text-start',
+            id: textPartId,
+            providerMetadata: undefined,
+          });
+
+          // Emit the text in chunks for realistic streaming behavior
+          const chunkSize = 10;
+          for (let i = 0; i < echoText.length; i += chunkSize) {
+            const chunk = echoText.slice(i, i + chunkSize);
+            controller.enqueue({
+              type: 'text-delta',
+              id: textPartId,
+              delta: chunk,
+              providerMetadata: undefined,
+            });
+          }
+
+          // Emit text-end
+          controller.enqueue({
+            type: 'text-end',
+            id: textPartId,
+            providerMetadata: undefined,
+          });
+
+          // Emit finish event with usage information
+          controller.enqueue({
+            type: 'finish',
+            finishReason: 'stop',
+            usage: {
+              promptTokens,
+              completionTokens,
+            },
+            providerMetadata: undefined,
+          });
+
+          controller.close();
+        },
+      });
+
+      return {
+        stream,
+        request: undefined,
+        response: undefined,
+        warnings: [],
+      };
+    },
+  };
+
+  return model;
+}
+
+/**
+ * Echo provider factory function - follows AI SDK provider pattern
+ */
+export function createEchoProvider(options?: { name?: string }) {
+  return {
+    languageModel(modelId: string): LanguageModelV2 {
+      return createEchoModel(modelId);
+    },
+    textEmbeddingModel() {
+      throw new Error('Echo provider does not support text embeddings');
+    },
+  };
+}
+
+export const echoProvider = createEchoProvider();

package/src/provider/provider.ts

@@ -14,6 +14,8 @@ import { Instance } from '../project/instance';
 import { Global } from '../global';
 import { Flag } from '../flag/flag';
 import { iife } from '../util/iife';
+import { createEchoModel } from './echo';
+import { createCacheModel } from './cache';
 
 export namespace Provider {
   const log = Log.create({ service: 'provider' });
@@ -452,6 +454,56 @@ export namespace Provider {
         },
       };
     },
+    /**
+     * Echo provider - synthetic provider for dry-run testing
+     * Echoes back the user's input without making actual API calls.
+     *
+     * This provider is automatically enabled when --dry-run mode is active.
+     * It can also be used explicitly with: --model link-assistant/echo
+     *
+     * @see https://github.com/link-assistant/agent/issues/89
+     */
+    'link-assistant': async () => {
+      // Echo provider is always available - no external dependencies needed
+      return {
+        autoload: Flag.OPENCODE_DRY_RUN, // Auto-load only in dry-run mode
+        async getModel(_sdk: any, modelID: string) {
+          // Return our custom echo model that implements LanguageModelV1
+          return createEchoModel(modelID);
+        },
+        options: {},
+      };
+    },
+    /**
+     * Cache provider - synthetic provider for caching API responses
+     * Caches responses using links notation for deterministic testing.
+     *
+     * This provider caches API responses and falls back to echo behavior.
+     * It can be used explicitly with: --model link-assistant/cache/opencode/grok-code
+     *
+     * @see https://github.com/link-assistant/agent/issues/89
+     */
+    'link-assistant/cache': async () => {
+      // Cache provider is always available - no external dependencies needed
+      return {
+        autoload: false, // Not auto-loaded
+        async getModel(_sdk: any, modelID: string) {
+          // modelID should be in format "provider/model" like "opencode/grok-code"
+          const parts = modelID.split('/');
+          if (parts.length < 2) {
+            throw new Error(
+              `Invalid cache model ID: ${modelID}. Expected format: provider/model`
+            );
+          }
+          const [providerId, ...modelParts] = parts;
+          const actualModelId = modelParts.join('/');
+
+          // Return our custom cache model that implements LanguageModelV1
+          return createCacheModel(providerId, actualModelId);
+        },
+        options: {},
+      };
+    },
   };
 
   const state = Instance.state(async () => {
@@ -555,6 +607,51 @@ export namespace Provider {
       realIdByKey.set('google/gemini-3-pro', 'gemini-3-pro-preview');
     }
 
+    // Add link-assistant echo provider for dry-run testing
+    // This synthetic provider echoes back user input without API calls
+    // @see https://github.com/link-assistant/agent/issues/89
+    database['link-assistant'] = {
+      id: 'link-assistant',
+      name: 'Link Assistant (Echo)',
+      env: [], // No environment variables needed - synthetic provider
+      models: {
+        echo: {
+          id: 'echo',
+          name: 'Echo Model',
+          release_date: '2024-01-01',
+          attachment: false,
+          reasoning: false,
+          temperature: false,
+          tool_call: true,
+          cost: {
+            input: 0,
+            output: 0,
+            cache_read: 0,
+            cache_write: 0,
+          },
+          limit: {
+            context: 1000000, // Virtually unlimited
+            output: 100000,
+          },
+          modalities: {
+            input: ['text'],
+            output: ['text'],
+          },
+          options: {},
+        },
+      },
+    };
+
+    // Add link-assistant/cache provider for caching API responses
+    // This synthetic provider caches responses and falls back to echo
+    // @see https://github.com/link-assistant/agent/issues/89
+    database['link-assistant/cache'] = {
+      id: 'link-assistant/cache',
+      name: 'Link Assistant (Cache)',
+      env: [], // No environment variables needed - synthetic provider
+      models: {}, // Models are dynamically created based on the provider/model syntax
+    };
+
     for (const [providerID, provider] of configProviders) {
       const existing = database[providerID];
       const parsed: ModelsDev.Provider = {
@@ -806,23 +903,41 @@ export namespace Provider {
 
     const provider = s.providers[providerID];
     if (!provider) throw new ModelNotFoundError({ providerID, modelID });
-    const info = provider.info.models[modelID];
-    if (!info) throw new ModelNotFoundError({ providerID, modelID });
-    const sdk = await getSDK(provider.info, info);
+
+    // For synthetic providers (like link-assistant/echo and link-assistant/cache), skip SDK loading
+    // These providers have a custom getModel function that creates the model directly
+    const isSyntheticProvider =
+      providerID === 'link-assistant' || providerID === 'link-assistant/cache';
+
+    // For synthetic providers, we don't need model info from the database
+    const info = isSyntheticProvider ? null : provider.info.models[modelID];
+    if (!isSyntheticProvider && !info)
+      throw new ModelNotFoundError({ providerID, modelID });
 
     try {
       const keyReal = `${providerID}/${modelID}`;
-      const realID = s.realIdByKey.get(keyReal) ?? info.id;
-      const language = provider.getModel
-        ? await provider.getModel(sdk, realID, provider.options)
-        : sdk.languageModel(realID);
+      const realID = s.realIdByKey.get(keyReal) ?? (info ? info.id : modelID);
+
+      let language: LanguageModel;
+      if (isSyntheticProvider && provider.getModel) {
+        // For synthetic providers, call getModel directly without SDK
+        language = await provider.getModel(null, realID, provider.options);
+      } else {
+        // For regular providers, load the SDK first
+        const sdk = await getSDK(provider.info, info!);
+        language = provider.getModel
+          ? await provider.getModel(sdk, realID, provider.options)
+          : sdk.languageModel(realID);
+      }
       log.info('found', { providerID, modelID });
       s.models.set(key, {
         providerID,
         modelID,
         info,
         language,
-        npm: info.provider?.npm ?? provider.info.npm,
+        npm: isSyntheticProvider
+          ? provider.info.npm
+          : (info.provider?.npm ?? provider.info.npm),
       });
       return {
         modelID,
@@ -897,6 +1012,18 @@ export namespace Provider {
 
   export async function defaultModel() {
     const cfg = await Config.get();
+
+    // In dry-run mode, use the echo provider by default
+    // This allows testing round-trips and multi-turn conversations without API costs
+    // @see https://github.com/link-assistant/agent/issues/89
+    if (Flag.OPENCODE_DRY_RUN) {
+      log.info('dry-run mode enabled, using echo provider as default');
+      return {
+        providerID: 'link-assistant',
+        modelID: 'echo',
+      };
+    }
+
     if (cfg.model) return parseModel(cfg.model);
 
     // Prefer opencode provider if available

package/src/session/prompt.ts

@@ -447,7 +447,7 @@ export namespace SessionPrompt {
         lastFinished.summary !== true &&
         SessionCompaction.isOverflow({
           tokens: lastFinished.tokens,
-          model: model.info,
+          model: model.info ?? { id: model.modelID },
         })
       ) {
         await SessionCompaction.create({
@@ -488,13 +488,13 @@ export namespace SessionPrompt {
           sessionID,
         })) as MessageV2.Assistant,
         sessionID: sessionID,
-        model: model.info,
+        model: model.info ?? { id: model.modelID },
         providerID: model.providerID,
         abort,
       });
       const system = await resolveSystemPrompt({
         providerID: model.providerID,
-        modelID: model.info.id,
+        modelID: model.info?.id ?? model.modelID,
         agent,
         system: lastUser.system,
         appendSystem: lastUser.appendSystem,
@@ -507,10 +507,11 @@ export namespace SessionPrompt {
         processor,
       });
       const params = {
-        temperature: model.info.temperature
-          ? (agent.temperature ??
-            ProviderTransform.temperature(model.providerID, model.modelID))
-          : undefined,
+        temperature:
+          (model.info?.temperature ?? false)
+            ? (agent.temperature ??
+              ProviderTransform.temperature(model.providerID, model.modelID))
+            : undefined,
         topP:
           agent.topP ?? ProviderTransform.topP(model.providerID, model.modelID),
         options: {
@@ -520,7 +521,7 @@ export namespace SessionPrompt {
             model.npm ?? '',
             sessionID
           ),
-          ...model.info.options,
+          ...(model.info?.options ?? {}),
           ...agent.options,
         },
       };
@@ -575,9 +576,11 @@ export namespace SessionPrompt {
         log.info(`User message tokens (estimated): ${userTokens}`);
         log.info(`Total estimated tokens: ${totalEstimatedTokens}`);
         log.info(
-          `Model context limit: ${model.info.limit.context || 'unknown'}`
+          `Model context limit: ${model.info?.limit?.context || 'unknown'}`
+        );
+        log.info(
+          `Model output limit: ${model.info?.limit?.output || 'unknown'}`
         );
-        log.info(`Model output limit: ${model.info.limit.output || 'unknown'}`);
         log.info('=== END VERBOSE ===');
       }
 
@@ -616,7 +619,7 @@ export namespace SessionPrompt {
                   'x-opencode-request': lastUser.id,
                 }
               : undefined),
-            ...model.info.headers,
+            ...(model.info?.headers ?? {}),
           },
           // set to 0, we handle loop
           maxRetries: 0,
@@ -624,7 +627,7 @@ export namespace SessionPrompt {
           maxOutputTokens: ProviderTransform.maxOutputTokens(
             model.providerID,
             params.options,
-            model.info.limit.output,
+            model.info?.limit?.output ?? 100000,
             OUTPUT_TOKEN_MAX
           ),
           abortSignal: abort,
@@ -662,7 +665,7 @@ export namespace SessionPrompt {
               })
             ),
           ],
-          tools: model.info.tool_call === false ? undefined : tools,
+          tools: model.info?.tool_call === false ? undefined : tools,
           model: wrapLanguageModel({
             model: model.language,
             middleware: [
@@ -1494,7 +1497,7 @@ export namespace SessionPrompt {
         small.npm ?? '',
         input.session.id
       ),
-      ...small.info.options,
+      ...(small.info?.options ?? {}),
     };
     if (small.providerID === 'openai' || small.modelID.includes('gpt-5')) {
       if (small.modelID.includes('5.1')) {
@@ -1509,7 +1512,7 @@ export namespace SessionPrompt {
       };
     }
     await generateText({
-      maxOutputTokens: small.info.reasoning ? 1500 : 20,
+      maxOutputTokens: small.info?.reasoning ? 1500 : 20,
       providerOptions: ProviderTransform.providerOptions(
         small.npm,
         small.providerID,
@@ -1550,7 +1553,7 @@ export namespace SessionPrompt {
           },
         ]),
       ],
-      headers: small.info.headers,
+      headers: small.info?.headers ?? {},
       model: small.language,
     })
       .then((result) => {
@@ -1569,7 +1572,10 @@ export namespace SessionPrompt {
           });
       })
       .catch((error) => {
-        log.error('failed to generate title', { error, model: small.info.id });
+        log.error('failed to generate title', {
+          error,
+          model: small.info?.id ?? small.modelID,
+        });
       });
   }
 }