feat: add typed TeaQL tools for Vercel AI SDK

Author: Philip Z

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm test
+      - run: npm run build
+      - run: npm run example

.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+coverage/
+*.log
+.env
+.env.local
+examples/*/*.db

LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 TeaQL
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,164 @@
+# TeaQL Agent Data Tools for Vercel AI SDK
+
+Generated, typed, auditable business tools for AI SDK agents—without exposing raw SQL.
+
+> Don't give your AI agent unrestricted SQL. Give it a typed business language.
+
+`@teaql/ai-sdk` converts an explicit allowlist of TeaQL business capabilities into native [Vercel AI SDK](https://ai-sdk.dev/) tools. The model receives business operations and their schemas. A trusted TeaQL `UserContext`, database resources, authorization state, and internal errors remain on the server.
+
+## Why
+
+| Raw SQL agent | TeaQL agent tools |
+| --- | --- |
+| Model guesses tables and joins | Model selects named business capabilities |
+| Broad database access | Explicit capability allowlist |
+| Untyped rows | Schema-validated input and output |
+| Authorization depends on prompts | Trusted server-side `context` |
+| Mutations are difficult to govern | AI SDK approval plus TeaQL audit semantics |
+| Database errors may leak | Safe public errors and observable internal failures |
+| Database-specific behavior | TeaQL domain semantics can span seven runtimes |
+
+This package does not replace the AI SDK agent loop, model providers, UI, or streaming. It supplies the governed business-data layer beneath those features.
+
+## Install
+
+```bash
+npm install @teaql/ai-sdk @teaql/teaql ai zod
+```
+
+Node.js 22 or newer and AI SDK 7 are required by the initial release.
+
+## Define business capabilities
+
+Capabilities are an explicit allowlist. The adapter intentionally does not expose every entity and CRUD operation automatically.
+
+```ts
+import { defineTeaQLCapability } from '@teaql/ai-sdk';
+import { z } from 'zod';
+
+const searchSchools = defineTeaQLCapability({
+  name: 'searchSchools',
+  description: 'Find schools by governed business criteria.',
+  inputSchema: z.object({
+    schoolType: z.enum(['PRIMARY', 'SECONDARY']),
+    name: z.string().optional(),
+  }),
+  risk: 'read',
+  execute: async ({ context, input }) =>
+    Q.schools()
+      .withSchoolType(input.schoolType)
+      .withNameContaining(input.name)
+      .comment('AI SDK tool: searchSchools')
+      .purpose('Search schools requested by the authenticated user')
+      .executeForList(context),
+});
+```
+
+The exact generated Q API follows the selected TeaQL model and generator version; capability definitions are ordinary typed application code and compile against it.
+
+## Create native AI SDK tools
+
+```ts
+import { UserContext } from '@teaql/teaql';
+import { ToolLoopAgent } from 'ai';
+import { createTeaQLTools } from '@teaql/ai-sdk';
+
+const context = new UserContext()
+  .insertResource('dataService', dataService)
+  .insertResource('authorization', authorization);
+
+const agent = new ToolLoopAgent({
+  model: 'openai/gpt-5.4',
+  instructions: 'Use only the provided business tools. Never invent SQL.',
+  tools: createTeaQLTools({
+    context,
+    capabilities: [searchSchools, updateSchoolContactPhone],
+  }),
+});
+```
+
+Create `context` on the server for each request or session. Never accept it from model output or a browser payload.
+
+## Govern writes
+
+```ts
+const updateSchoolContactPhone = defineTeaQLCapability({
+  name: 'updateSchoolContactPhone',
+  description: 'Update a school phone after explicit user approval.',
+  inputSchema: z.object({
+    schoolId: z.number().int().positive(),
+    contactPhone: z.string(),
+    auditReason: z.string().min(8),
+  }),
+  risk: 'write',
+  needsApproval: true,
+  execute: async ({ context, input }) => {
+    const school = await Q.schools()
+      .withId(input.schoolId)
+      .comment('Load school for approved contact update')
+      .purpose(input.auditReason)
+      .executeForOne(context);
+
+    return school
+      .updateContactPhone(input.contactPhone)
+      .auditAs(input.auditReason)
+      .save(context);
+  },
+});
+```
+
+AI SDK approval controls whether the agent may execute the tool. TeaQL audit and runtime authorization still apply when execution begins. Approval is not a replacement for runtime security.
+
+## Observe execution without leaking internals
+
+```ts
+const tools = createTeaQLTools({
+  context,
+  capabilities,
+  onEvent: event => telemetry.record(event),
+  mapError: (_error, capability) =>
+    `${capability.name} could not be completed. Review the request or contact support.`,
+});
+```
+
+Lifecycle events contain capability name, risk, tool-call ID, timing, and the internal error on the server. Inputs are excluded by default because they may contain sensitive business data. The default model-visible error never includes the original database error.
+
+## Run the local demonstration
+
+The repository includes a deterministic, no-API-key school-management demonstration. It uses an in-memory SQLite resource inside the trusted `UserContext` to show the security boundary, approval metadata, optimistic version change, audit record, and model-visible tools.
+
+```bash
+npm install
+npm run example
+```
+
+The SQLite repository is deliberately small and handwritten so the example is self-contained. A generated TeaQL project replaces that repository implementation with its generated Q, entity, Save, and Runtime Module APIs; the AI SDK adapter remains unchanged.
+
+See [`examples/school-agent`](examples/school-agent).
+
+## Security model
+
+- Capabilities are deny-by-absence: only definitions passed to `createTeaQLTools` exist.
+- `allow` can narrow the registered capabilities for a particular user or agent.
+- `context` is captured by the server-side execute closure and is not part of `inputSchema`.
+- Tool risk is metadata for policy and telemetry; applications must still enforce authorization in the runtime.
+- Writes can request AI SDK approval, but must also use TeaQL audit and validation.
+- Internal failures are available to server telemetry and hidden from the model by default.
+- Capability names and duplicates are validated during startup.
+
+## Current scope
+
+The initial release is a runtime adapter for explicit TypeScript capability definitions. Planned generator work will produce capability definitions, schemas, agent guidance, and conformance fixtures from a TeaQL model. MCP adapters can expose the same capability manifest to Java, Rust, TypeScript, Swift, Python, .NET, and Go runtimes.
+
+## Related projects
+
+- [TeaQL](https://teaql.io)
+- [TeaQL TypeScript Runtime](https://github.com/teaql/teaql-ts)
+- [TeaQL Code Generator](https://github.com/teaql/teaql-code-gen)
+- [TeaQL Agent Kit](https://github.com/teaql/teaql-agent-kit)
+- [TeaQL Conformance](https://github.com/teaql/teaql-conformance)
+- [Vercel AI SDK](https://github.com/vercel/ai)
+
+## License
+
+Apache-2.0

eslint.config.js

@@ -0,0 +1,10 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ['dist', 'coverage', 'node_modules'],
+  },
+);

examples/school-agent/ai-sdk.ts

@@ -0,0 +1,18 @@
+import { UserContext } from '@teaql/teaql';
+import { ToolLoopAgent } from 'ai';
+
+import { createTeaQLTools } from '../../src/index.js';
+import { schoolCapabilities } from './capabilities.js';
+import type { SchoolRepository } from './database.js';
+
+export function createSchoolAgent(repository: SchoolRepository) {
+  // Construct this trusted context on the server for each request or session.
+  const context = new UserContext().insertResource('schoolRepository', repository);
+
+  return new ToolLoopAgent({
+    model: 'openai/gpt-5.4',
+    instructions:
+      'Use only the provided business tools. Never invent SQL or database field names.',
+    tools: createTeaQLTools({ context, capabilities: schoolCapabilities }),
+  });
+}

examples/school-agent/capabilities.ts

@@ -0,0 +1,54 @@
+import { defineTeaQLCapability } from '../../src/index.js';
+import { z } from 'zod';
+
+import type { SchoolRepository } from './database.js';
+
+export const schoolCapabilities = [
+  defineTeaQLCapability({
+    name: 'findSchoolsMissingContact',
+    description:
+      'Find schools of a given type whose contact phone is explicitly null. This is read-only.',
+    inputSchema: z.object({
+      schoolType: z
+        .enum(['PRIMARY', 'SECONDARY'])
+        .describe('The governed TeaQL school type, not a database value.'),
+    }),
+    outputSchema: z.array(
+      z.object({
+        id: z.number(),
+        name: z.string(),
+        schoolType: z.enum(['PRIMARY', 'SECONDARY']),
+        contactPhone: z.string().nullable(),
+        version: z.number(),
+      }),
+    ),
+    risk: 'read',
+    execute: ({ context, input }) =>
+      context
+        .requireResource<SchoolRepository>('schoolRepository')
+        .findMissingContact(input.schoolType),
+  }),
+  defineTeaQLCapability({
+    name: 'updateSchoolContactPhone',
+    description:
+      'Update one school contact phone with an explicit audit reason. Requires user approval.',
+    inputSchema: z.object({
+      schoolId: z.number().int().positive(),
+      contactPhone: z.string().min(5).max(40),
+      auditReason: z.string().min(8).max(200),
+    }),
+    outputSchema: z.object({
+      id: z.number(),
+      name: z.string(),
+      schoolType: z.enum(['PRIMARY', 'SECONDARY']),
+      contactPhone: z.string().nullable(),
+      version: z.number(),
+    }),
+    risk: 'write',
+    needsApproval: true,
+    execute: ({ context, input }) =>
+      context
+        .requireResource<SchoolRepository>('schoolRepository')
+        .updateContactPhone(input.schoolId, input.contactPhone, input.auditReason),
+  }),
+] as const;

examples/school-agent/database.ts

@@ -0,0 +1,82 @@
+import Database from 'better-sqlite3';
+
+export interface School {
+  readonly id: number;
+  readonly name: string;
+  readonly schoolType: 'PRIMARY' | 'SECONDARY';
+  readonly contactPhone: string | null;
+  readonly version: number;
+}
+
+export interface SchoolRepository {
+  findMissingContact(schoolType: School['schoolType']): School[];
+  updateContactPhone(id: number, contactPhone: string, auditReason: string): School;
+  auditLog(): readonly { action: string; entityId: number; reason: string }[];
+}
+
+export function createSchoolRepository(): SchoolRepository {
+  const database = new Database(':memory:');
+  database.exec(`
+    CREATE TABLE school (
+      id INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      school_type TEXT NOT NULL,
+      contact_phone TEXT,
+      version INTEGER NOT NULL
+    );
+    CREATE TABLE audit_log (
+      action TEXT NOT NULL,
+      entity_id INTEGER NOT NULL,
+      reason TEXT NOT NULL
+    );
+    INSERT INTO school VALUES
+      (1, 'Riverside Secondary School', 'SECONDARY', NULL, 1),
+      (2, 'Northwind Primary School', 'PRIMARY', '+1-555-0102', 1),
+      (3, 'Lakeside Secondary School', 'SECONDARY', NULL, 1);
+  `);
+
+  return {
+    findMissingContact(schoolType) {
+      return database
+        .prepare(
+          `SELECT id, name, school_type AS schoolType,
+                  contact_phone AS contactPhone, version
+             FROM school
+            WHERE school_type = ? AND contact_phone IS NULL
+            ORDER BY id`,
+        )
+        .all(schoolType) as School[];
+    },
+    updateContactPhone(id, contactPhone, auditReason) {
+      const transaction = database.transaction(() => {
+        const result = database
+          .prepare(
+            `UPDATE school
+                SET contact_phone = ?, version = version + 1
+              WHERE id = ?`,
+          )
+          .run(contactPhone, id);
+        if (result.changes !== 1) throw new Error(`School row not found: ${id}`);
+        database
+          .prepare('INSERT INTO audit_log VALUES (?, ?, ?)')
+          .run('updateContactPhone', id, auditReason);
+      });
+      transaction();
+      return database
+        .prepare(
+          `SELECT id, name, school_type AS schoolType,
+                  contact_phone AS contactPhone, version
+             FROM school WHERE id = ?`,
+        )
+        .get(id) as School;
+    },
+    auditLog() {
+      return database
+        .prepare(
+          `SELECT action, entity_id AS entityId, reason
+             FROM audit_log ORDER BY rowid`,
+        )
+        .all() as { action: string; entityId: number; reason: string }[];
+    },
+  };
+}