Database

db() adds model-facing tools for a configured ViteHub Database primitive. It exposes read-only query and schema inspection by default, then adds SQL mutation only when write modes allow it.

Installation

Import the Capability factory from -hub/agent/capabilities and add it to defineAgent({ capabilities }). Use the configuration example below as the starting point, then tighten modes, policies, stores, and providers for the Agent boundary.

What it adds

The Capability contributes db_query for one read-only SQL statement and db_schema for schema inspection. When data or schema write modes allow it, it also contributes db_exec for one mutation statement with a rationale.

Configuration

Attach DB in read mode until the Agent needs guarded mutations. The Database primitive must already be configured by the app.

import { defineAgent } from '@vite-hub/agent'
import { db } from '@vite-hub/agent/capabilities'

export default defineAgent({
  driver: { model },
  capabilities: [
    db({ mode: 'read' }),
  ],
})

Runtime behavior

ViteHub selects the configured database handle and enforces the single-statement SQL guardrail. db_query accepts one read-only query. db_exec rejects read-only SQL, requires a rationale, and separates data mutations from schema changes through mode and schemaMode.

Requirements

db() requires a configured db primitive. The primitive must expose raw string query() for reads and exec() for mutations.

Mutation tools require write mode. DDL requires schema write mode. Writes require approval by default.

Driver support

Inspect and verify

Inspect the Agent tool list in DevTools. Read mode should show db_query and db_schema; write-capable configurations should also show db_exec with the configured policy.

Run a multi-statement SQL input during development. The Capability should reject it before it reaches the database primitive.

Options

Reference

• Database primitive
• Official capabilities
• Source: packages/agent/src/capabilities/storage/db.ts