@link-assistant/agent 0.24.2 → 0.25.0

package/README.md

@@ -24,7 +24,7 @@ This is an MVP implementation of an OpenCode-compatible CLI agent, focused on ma
 
 - ✅ **JSON Input/Output**: Compatible with `opencode run --format json --model opencode/minimax-m2.5-free`
 - ✅ **Plain Text Input**: Also accepts plain text messages (auto-converted to JSON format)
-- ✅ **Flexible Model Selection**: Defaults to free OpenCode Zen MiniMax M2.5 Free, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Claude OAuth](../docs/claude-oauth.md), [Groq](../docs/groq.md), and [OpenRouter](../docs/openrouter.md) providers
+- ✅ **Flexible Model Selection**: Defaults to free OpenCode Zen MiniMax M2.5 Free, supports [OpenCode Zen](https://opencode.ai/docs/zen/), [Formal AI](../docs/formal-ai.md), [Claude OAuth](../docs/claude-oauth.md), [Groq](../docs/groq.md), and [OpenRouter](../docs/openrouter.md) providers
 - ✅ **No Restrictions**: Fully unrestricted file system and command execution access (no sandbox)
 - ✅ **Minimal Footprint**: Built with Bun.sh for maximum efficiency
 - ✅ **Full Tool Support**: 13 tools including websearch, codesearch, batch - all enabled by default
@@ -201,6 +201,10 @@ echo "hi" | agent --model opencode/nemotron-3-super-free
 echo "hi" | agent --model opencode/gpt-5-nano
 echo "hi" | agent --model opencode/big-pickle
 
+# Formal AI local server
+echo "hi" | agent --model formal-ai
+echo "hi" | agent --model @link-assistant/formal-ai
+
 # Premium models (OpenCode Zen subscription)
 echo "hi" | agent --model opencode/sonnet        # Claude Sonnet 4.5
 echo "hi" | agent --model opencode/haiku         # Claude Haiku 4.5
@@ -237,6 +241,7 @@ echo "hi" | agent --model github-copilot/gpt-4o        # Uses Copilot
 ```
 
 See [MODELS.md](../MODELS.md) for complete list of available models and pricing.
+See [docs/formal-ai.md](../docs/formal-ai.md) for Formal AI local server setup.
 See [docs/groq.md](../docs/groq.md) for Groq provider documentation.
 See [docs/openrouter.md](../docs/openrouter.md) for OpenRouter provider documentation.
 See [docs/claude-oauth.md](../docs/claude-oauth.md) for Claude OAuth provider documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",

package/src/provider/provider.ts

@@ -75,7 +75,79 @@ export namespace Provider {
 
   type Source = 'env' | 'config' | 'custom' | 'api';
 
+  const FORMAL_AI_DEFAULT_BASE_URL = 'http://127.0.0.1:8080/api/openai/v1';
+  const FORMAL_AI_API_KEY_ENV = 'FORMAL_AI_API_KEY';
+  const FORMAL_AI_BASE_URL_ENV = 'FORMAL_AI_BASE_URL';
+  const FORMAL_AI_DEFAULT_API_KEY = 'formal-ai';
+
+  function getFormalAiBaseURL(provider?: ModelsDev.Provider) {
+    return (
+      process.env[FORMAL_AI_BASE_URL_ENV] ??
+      provider?.api ??
+      FORMAL_AI_DEFAULT_BASE_URL
+    );
+  }
+
+  function createFormalAiLoader(input?: ModelsDev.Provider) {
+    return {
+      autoload: true,
+      options: {
+        apiKey: process.env[FORMAL_AI_API_KEY_ENV] ?? FORMAL_AI_DEFAULT_API_KEY,
+        baseURL: getFormalAiBaseURL(input),
+      },
+    };
+  }
+
+  function createFormalAiModel(name = 'Formal AI'): ModelsDev.Model {
+    return {
+      id: 'formal-ai',
+      name,
+      release_date: '2026-07-03',
+      attachment: false,
+      reasoning: true,
+      temperature: true,
+      tool_call: true,
+      cost: {
+        input: 0,
+        output: 0,
+        cache_read: 0,
+        cache_write: 0,
+      },
+      limit: {
+        context: 60000,
+        output: 8192,
+      },
+      modalities: {
+        input: ['text'],
+        output: ['text'],
+      },
+      options: {},
+      provider: {
+        npm: '@ai-sdk/openai-compatible',
+      },
+    };
+  }
+
+  function createFormalAiProvider(
+    id: string,
+    name: string
+  ): ModelsDev.Provider {
+    return {
+      id,
+      name,
+      npm: '@ai-sdk/openai-compatible',
+      api: getFormalAiBaseURL(),
+      env: [FORMAL_AI_API_KEY_ENV],
+      models: {
+        'formal-ai': createFormalAiModel('formal-ai'),
+      },
+    };
+  }
+
   const CUSTOM_LOADERS: Record<string, CustomLoader> = {
+    'formal-ai': async (input) => createFormalAiLoader(input),
+    formalai: async (input) => createFormalAiLoader(input),
+    '@link-assistant': async (input) => createFormalAiLoader(input),
     async anthropic(input) {
       // Check if OAuth credentials are available via the auth plugin
       const auth = await Auth.get('anthropic');
@@ -791,6 +863,22 @@ export namespace Provider {
       realIdByKey.set('google/gemini-3-pro', 'gemini-3-pro-preview');
     }
 
+    // Add Formal AI local OpenAI-compatible provider and selectors.
+    // Formal AI serves the canonical model ID "formal-ai"; Agent also accepts
+    // the scoped selector "@link-assistant/formal-ai" as a provider alias.
+    database['formal-ai'] = createFormalAiProvider(
+      'formal-ai',
+      'Formal AI Local Server'
+    );
+    database['formalai'] = createFormalAiProvider(
+      'formalai',
+      'Formal AI Local Server'
+    );
+    database['@link-assistant'] = createFormalAiProvider(
+      '@link-assistant',
+      'Formal AI Local Server (@link-assistant alias)'
+    );
+
     // 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
@@ -1994,6 +2082,17 @@ export namespace Provider {
       }
     }
 
+    if (modelID === 'formal-ai') {
+      const formalAiProvider = s.providers['formal-ai'];
+      if (formalAiProvider && formalAiProvider.info.models[modelID]) {
+        log.info(() => ({
+          message: 'resolved short model name to formal-ai (canonical)',
+          modelID,
+        }));
+        return { providerID: 'formal-ai', modelID };
+      }
+    }
+
     // Check if model exists in any provider
     const matchingProviders: string[] = [];
     for (const [providerID, provider] of Object.entries(s.providers)) {

package/src/tool/grep.ts

@@ -4,6 +4,12 @@ import { Ripgrep } from '../file/ripgrep';
 
 import DESCRIPTION from './grep.txt';
 import { Instance } from '../project/instance';
+import {
+  byteOffsetToColumnIndex,
+  formatFocusedLineWindow,
+} from './text-window';
+
+const MAX_MATCHING_LINE_LENGTH = 2000;
 
 export const GrepTool = Tool.define('grep', {
   description: DESCRIPTION,
@@ -32,12 +38,7 @@ export const GrepTool = Tool.define('grep', {
     const searchPath = params.path || Instance.directory;
 
     const rgPath = await Ripgrep.filepath();
-    const args = [
-      '-nH',
-      '--field-match-separator=|',
-      '--regexp',
-      params.pattern,
-    ];
+    const args = ['--json', '--regexp', params.pattern];
     if (params.include) {
       args.push('--glob', params.include);
     }
@@ -64,17 +65,29 @@ export const GrepTool = Tool.define('grep', {
       throw new Error(`ripgrep failed: ${errorOutput}`);
     }
 
-    const lines = output.trim().split('\n');
     const matches = [];
 
-    for (const line of lines) {
+    for (const line of output.trim().split('\n')) {
       if (!line) continue;
 
-      const [filePath, lineNumStr, ...lineTextParts] = line.split('|');
-      if (!filePath || !lineNumStr || lineTextParts.length === 0) continue;
+      const event = JSON.parse(line);
+      if (event.type !== 'match') continue;
 
-      const lineNum = parseInt(lineNumStr, 10);
-      const lineText = lineTextParts.join('|');
+      const filePath = event.data?.path?.text;
+      const lineNum = event.data?.line_number;
+      const rawLineText = event.data?.lines?.text;
+      const submatch = event.data?.submatches?.[0];
+      if (!filePath || !lineNum || typeof rawLineText !== 'string') continue;
+
+      const lineText = stripTrailingLineEnding(rawLineText);
+      const matchStart = byteOffsetToColumnIndex(
+        lineText,
+        submatch?.start ?? 0
+      );
+      const matchEnd = byteOffsetToColumnIndex(
+        lineText,
+        submatch?.end ?? submatch?.start ?? 0
+      );
 
       const file = Bun.file(filePath);
       const stats = await file.stat().catch(() => null);
@@ -85,6 +98,8 @@ export const GrepTool = Tool.define('grep', {
         modTime: stats.mtime.getTime(),
         lineNum,
         lineText,
+        matchStart,
+        matchEnd,
       });
     }
 
@@ -113,7 +128,15 @@ export const GrepTool = Tool.define('grep', {
         currentFile = match.path;
         outputLines.push(`${match.path}:`);
       }
-      outputLines.push(`  Line ${match.lineNum}: ${match.lineText}`);
+      outputLines.push(
+        `  Line ${match.lineNum}: ${formatFocusedLineWindow({
+          line: match.lineText,
+          lineNumber: match.lineNum,
+          focusStart: match.matchStart,
+          focusEnd: match.matchEnd,
+          limit: MAX_MATCHING_LINE_LENGTH,
+        })}`
+      );
     }
 
     if (truncated) {
@@ -133,3 +156,7 @@ export const GrepTool = Tool.define('grep', {
     };
   },
 });
+
+function stripTrailingLineEnding(line: string) {
+  return line.replace(/\r?\n$/, '');
+}

package/src/tool/grep.txt

@@ -3,6 +3,7 @@
 - Supports full regex syntax (eg. "log.*Error", "function\s+\w+", etc.)
 - Filter files by pattern with the include parameter (eg. "*.js", "*.{ts,tsx}")
 - Returns file paths with at least one match sorted by modification time
+- Long matching lines are summarized around the match with omitted-column ranges, so the matching text remains visible without dumping the whole line.
 - Use this tool when you need to find files containing specific patterns
 - If you need to identify/count the number of matches within files, use the Bash tool with `rg` (ripgrep) directly. Do NOT use `grep`.
 - When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Task tool instead

package/src/tool/read.ts

@@ -5,11 +5,10 @@ import { Tool } from './tool';
 import { FileTime } from '../file/time';
 import DESCRIPTION from './read.txt';
 import { config } from '../config/config';
-import { Filesystem } from '../util/filesystem';
 import { Instance } from '../project/instance';
 import { Provider } from '../provider/provider';
 import { Identifier } from '../id/id';
-import { iife } from '../util/iife';
+import { formatBalancedLineWindow, formatColumnWindow } from './text-window';
 
 const DEFAULT_READ_LIMIT = 2000;
 const MAX_LINE_LENGTH = 2000;
@@ -26,6 +25,14 @@ export const ReadTool = Tool.define('read', {
       .number()
       .describe('The number of lines to read (defaults to 2000)')
       .optional(),
+    columnOffset: z.coerce
+      .number()
+      .describe('The column number to start reading from (0-based)')
+      .optional(),
+    columnLimit: z.coerce
+      .number()
+      .describe('The number of columns to read from each selected line')
+      .optional(),
   }),
   async execute(params, ctx) {
     let filepath = params.filePath;
@@ -120,25 +127,53 @@ export const ReadTool = Tool.define('read', {
     const isBinary = await isBinaryFile(filepath, file);
     if (isBinary) throw new Error(`Cannot read binary file: ${filepath}`);
 
-    const limit = params.limit ?? DEFAULT_READ_LIMIT;
-    const offset = params.offset || 0;
+    const limit = normalizeNonNegativeInteger(params.limit, DEFAULT_READ_LIMIT);
+    const offset = normalizeNonNegativeInteger(params.offset, 0);
+    const hasExplicitLineRange =
+      params.offset !== undefined || params.limit !== undefined;
+    const hasExplicitColumnRange =
+      params.columnOffset !== undefined || params.columnLimit !== undefined;
+    const columnOffset = normalizeNonNegativeInteger(params.columnOffset, 0);
+    const columnLimit = normalizeNonNegativeInteger(
+      params.columnLimit,
+      MAX_LINE_LENGTH
+    );
     const lines = await file.text().then((text) => text.split('\n'));
-    const raw = lines.slice(offset, offset + limit).map((line) => {
-      return line.length > MAX_LINE_LENGTH
-        ? line.substring(0, MAX_LINE_LENGTH) + '...'
-        : line;
+    const selected = selectLines({
+      lines,
+      offset,
+      limit,
+      summarizeMiddle: !hasExplicitLineRange,
     });
-    const content = raw.map((line, index) => {
-      return `${(index + offset + 1).toString().padStart(5, '0')}| ${line}`;
+    const content = selected.parts.flatMap((part) => {
+      if (part.type === 'omitted') {
+        return [`... [omitted lines ${part.start}..${part.end}] ...`];
+      }
+
+      return part.lines.map(({ line, lineNumber }) => {
+        const formattedLine = hasExplicitColumnRange
+          ? formatColumnWindow({
+              line,
+              lineNumber,
+              offset: columnOffset,
+              limit: columnLimit,
+            })
+          : formatBalancedLineWindow({
+              line,
+              lineNumber,
+              limit: MAX_LINE_LENGTH,
+            });
+        return `${lineNumber.toString().padStart(5, '0')}| ${formattedLine}`;
+      });
     });
-    const preview = raw.slice(0, 20).join('\n');
+    const preview = content.slice(0, 20).join('\n');
 
     let output = '<file>\n';
     output += content.join('\n');
 
     const totalLines = lines.length;
-    const lastReadLine = offset + content.length;
-    const hasMoreLines = totalLines > lastReadLine;
+    const lastReadLine = selected.lastLine;
+    const hasMoreLines = hasExplicitLineRange && totalLines > lastReadLine;
 
     if (hasMoreLines) {
       output += `\n\n(File has more lines. Use 'offset' parameter to read beyond line ${lastReadLine})`;
@@ -160,6 +195,79 @@ export const ReadTool = Tool.define('read', {
   },
 });
 
+function normalizeNonNegativeInteger(
+  value: number | undefined,
+  fallback: number
+) {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.floor(value));
+}
+
+type SelectedLinePart =
+  | {
+      type: 'lines';
+      lines: Array<{ line: string; lineNumber: number }>;
+    }
+  | {
+      type: 'omitted';
+      start: number;
+      end: number;
+    };
+
+function selectLines(input: {
+  lines: string[];
+  offset: number;
+  limit: number;
+  summarizeMiddle: boolean;
+}): { parts: SelectedLinePart[]; lastLine: number } {
+  const totalLines = input.lines.length;
+
+  if (!input.summarizeMiddle || totalLines <= input.limit) {
+    const end = Math.min(input.offset + input.limit, totalLines);
+    return {
+      parts: [
+        {
+          type: 'lines',
+          lines: lineRange(input.lines, input.offset, end),
+        },
+      ],
+      lastLine: end,
+    };
+  }
+
+  const headCount = Math.ceil(input.limit / 2);
+  const tailCount = input.limit - headCount;
+  const tailStart = totalLines - tailCount;
+  const omittedStart = headCount + 1;
+  const omittedEnd = tailStart;
+
+  return {
+    parts: [
+      {
+        type: 'lines',
+        lines: lineRange(input.lines, 0, headCount),
+      },
+      {
+        type: 'omitted',
+        start: omittedStart,
+        end: omittedEnd,
+      },
+      {
+        type: 'lines',
+        lines: lineRange(input.lines, tailStart, totalLines),
+      },
+    ],
+    lastLine: totalLines,
+  };
+}
+
+function lineRange(lines: string[], start: number, end: number) {
+  return lines.slice(start, end).map((line, index) => ({
+    line,
+    lineNumber: start + index + 1,
+  }));
+}
+
 function isImageFile(filePath: string): string | false {
   const ext = path.extname(filePath).toLowerCase();
   switch (ext) {

package/src/tool/read.txt

@@ -3,9 +3,10 @@ Assume this tool is able to read all files on the machine. If the User provides
 
 Usage:
 - The filePath parameter must be an absolute path, not a relative path
-- By default, it reads up to 2000 lines starting from the beginning of the file
-- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
-- Any lines longer than 2000 characters will be truncated
+- By default, it reads the whole file when it fits the read limit. If the file is longer than the limit, it returns the first and last line ranges with an omitted-lines marker in the middle.
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the default first/last summary first and then request omitted ranges if needed.
+- You can optionally specify columnOffset and columnLimit to read a window from each selected line, especially for long single-line files.
+- Long lines are summarized with first and last columns plus omitted-column ranges instead of being silently truncated.
 - Results are returned using cat -n format, with line numbers starting at 1
 - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
 - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.

package/src/tool/text-window.ts

@@ -0,0 +1,121 @@
+const OMITTED_COLUMNS_LABEL = 'omitted columns';
+
+function columnsOf(text: string) {
+  return Array.from(text);
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function normalizeIndex(value: number | undefined, fallback: number) {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.floor(value));
+}
+
+function joinColumnWindow(
+  columns: string[],
+  lineNumber: number,
+  start: number,
+  end: number
+) {
+  const before =
+    start > 0
+      ? `[${OMITTED_COLUMNS_LABEL} 1..${start} of line ${lineNumber}] ... `
+      : '';
+  const body = columns.slice(start, end).join('');
+  const after =
+    end < columns.length
+      ? ` ... [${OMITTED_COLUMNS_LABEL} ${end + 1}..${columns.length} of line ${lineNumber}]`
+      : '';
+
+  return `${before}${body}${after}`;
+}
+
+export function formatColumnWindow(input: {
+  line: string;
+  lineNumber: number;
+  offset?: number;
+  limit: number;
+}) {
+  const columns = columnsOf(input.line);
+  const offset = clamp(normalizeIndex(input.offset, 0), 0, columns.length);
+  const limit = normalizeIndex(input.limit, columns.length);
+  const end = Math.min(offset + limit, columns.length);
+
+  return joinColumnWindow(columns, input.lineNumber, offset, end);
+}
+
+export function formatBalancedLineWindow(input: {
+  line: string;
+  lineNumber: number;
+  limit: number;
+}) {
+  const columns = columnsOf(input.line);
+  const limit = normalizeIndex(input.limit, columns.length);
+
+  if (columns.length <= limit) return input.line;
+  if (limit === 0) {
+    return `[${OMITTED_COLUMNS_LABEL} 1..${columns.length} of line ${input.lineNumber}]`;
+  }
+
+  const headLength = Math.ceil(limit / 2);
+  const tailLength = limit - headLength;
+  const omittedStart = headLength;
+  const omittedEnd = columns.length - tailLength;
+  const head = columns.slice(0, headLength).join('');
+  const tail = tailLength > 0 ? columns.slice(omittedEnd).join('') : '';
+  const omitted = `[${OMITTED_COLUMNS_LABEL} ${omittedStart + 1}..${omittedEnd} of line ${input.lineNumber}]`;
+
+  return tail ? `${head} ... ${omitted} ... ${tail}` : `${head} ... ${omitted}`;
+}
+
+export function formatFocusedLineWindow(input: {
+  line: string;
+  lineNumber: number;
+  focusStart: number;
+  focusEnd: number;
+  limit: number;
+}) {
+  const columns = columnsOf(input.line);
+  const limit = normalizeIndex(input.limit, columns.length);
+
+  if (columns.length <= limit) return input.line;
+  if (limit === 0) {
+    return `[${OMITTED_COLUMNS_LABEL} 1..${columns.length} of line ${input.lineNumber}]`;
+  }
+
+  const focusStart = clamp(
+    normalizeIndex(input.focusStart, 0),
+    0,
+    columns.length
+  );
+  const focusEnd = clamp(
+    Math.max(normalizeIndex(input.focusEnd, focusStart + 1), focusStart + 1),
+    focusStart + 1,
+    columns.length
+  );
+  const focusLength = focusEnd - focusStart;
+  const maxStart = Math.max(0, columns.length - limit);
+  const start =
+    focusLength >= limit
+      ? clamp(focusStart, 0, maxStart)
+      : clamp(focusStart - Math.floor((limit - focusLength) / 2), 0, maxStart);
+  const end = Math.min(start + limit, columns.length);
+
+  return joinColumnWindow(columns, input.lineNumber, start, end);
+}
+
+export function byteOffsetToColumnIndex(text: string, byteOffset: number) {
+  let bytes = 0;
+  let column = 0;
+
+  for (const char of text) {
+    const nextBytes = bytes + Buffer.byteLength(char);
+    if (nextBytes > byteOffset) break;
+    bytes = nextBytes;
+    column++;
+  }
+
+  return column;
+}