AI-SDK adapter

The @grepticon/sdk/ai-sdk subpath turns a read session into a ready-to-use Vercel AI SDK ToolSet: the four Grepticon tools ls, find, cat, and grep, wired to execute and ready to hand straight to generateText / streamText. It's a thin, opinionated binding; if you drive the tools yourself, call the session methods directly instead.

npm install @grepticon/sdk ai

ai, the Vercel AI SDK, is a peer dependency of this subpath; install it alongside the SDK. The base @grepticon/sdk client does not need it; only this adapter does.

createVfsTools(session)

// from '@grepticon/sdk/ai-sdk'
declare function createVfsTools(session: GrepticonSession): ToolSet; // ToolSet from 'ai'

Takes a GrepticonSession and returns a ToolSet with four tools keyed ls, find, cat, and grep. Each tool's inputSchema is the tool's real contract and its execute calls the session, returning the envelope's text to the model: the plain-text output the model reads and acts on. Tool descriptions come from the shared contracts, so the model sees the same guidance across the SDK, MCP, and the eval harness.

Full example

Open a read session on your workspace and hand the tools to the model. On a trusted backend, read straight through your client:

import { anthropic } from '@ai-sdk/anthropic';
import { GrepticonClient } from '@grepticon/sdk';
import { createVfsTools } from '@grepticon/sdk/ai-sdk';
import { generateText, stepCountIs } from 'ai';

const client = new GrepticonClient({
  apiKey: process.env.GREPTICON_API_KEY,
});

const { text } = await generateText({
  model: anthropic('claude-sonnet-5'),
  tools: createVfsTools(client.session('handbook')),
  stopWhen: stepCountIs(10),
  prompt: 'When do new hires finish account setup?',
});

console.log(text);

Give the loop room to run

Reading is multi-step: the model calls grep or ls, sees the result, and only then writes an answer. The AI SDK stops after one step by default, so a run without stopWhen ends the moment the first tool call comes back, and text resolves to an empty string. Pass a stop condition to let the loop continue:

import { generateText, stepCountIs } from 'ai';

const { text, steps } = await generateText({
  model: anthropic('claude-sonnet-5'),
  tools: createVfsTools(client.session('handbook')),
  stopWhen: stepCountIs(10), // read, then answer
  prompt: 'When do new hires finish account setup?',
});

Ten steps is a comfortable default for a question answered from a file or two. Raise it for agents that browse widely; steps on the result tells you how many were actually used. The same applies to streamText. See the AI SDK's agent loop docs for the other stop conditions, such as hasToolCall.

GrepticonSession

The adapter accepts any GrepticonSession: a client session (client.session(ws)), a standalone new GrepticonSession(...), or core's in-process session, so the same wiring serves a hosted agent and the eval harness alike. The shape:

interface GrepticonSession {
  ls(input: LsInput): Promise<ToolEnvelope>;
  find(input: FindInput): Promise<ToolEnvelope>;
  cat(input: CatInput): Promise<ToolEnvelope>;
  grep(input: GrepInput): Promise<ToolEnvelope>;
}

interface ToolEnvelope {
  text: string;
  status: 'ok' | 'not_found' | 'bad_request';
}

Each method resolves with a { text, status } envelope and does not throw on not_found / bad_request; only auth and server failures throw. The adapter forwards text to the model and ignores status; if you call the session directly you can branch on status yourself. See the error model for the full contract.

The four tools

For each tool's exact parameters, defaults, and behavior, see the Tools guide and the generated Read API reference.

Where to go next

• SDK reference: the full GrepticonClient surface.
• Error handling: throw-vs-envelope and retries.
• Tools: how an agent navigates with ls / find / cat / grep.