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, grep), wired to execute, 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: VfsReadSession): ToolSet; // ToolSet from 'ai'

Takes a VfsReadSession 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 (including any steering footer) 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

Mint a scoped token, build a session on a second client keyed by that token, and hand the tools to the model:

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

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

const { token } = await client.tokens.mint('handbook', { ttlSeconds: 600 });

// Read AS the token — build a second client keyed by it.
const session = new GrepticonClient({ apiKey: token }).session('handbook');

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

console.log(text);

VfsReadSession

The adapter accepts anything VfsReadSession-shaped — the SDK's HTTP session (client.session(ws)) or core's in-process session — so the same wiring serves both a hosted agent and the eval harness. The interface:

interface VfsReadSession {
  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. In brief:

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.