KV

kv() adds model-facing tools for a configured ViteHub KV primitive. It exposes read tools by default and edit tools only in write mode.

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 kv_read for exact-key reads or prefix key listing. When configured with write mode, it also contributes kv_edit for putting or deleting one key.

Configuration

Attach KV in read mode until the product needs model-facing writes. The KV primitive must already be configured by the app.

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

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

Runtime behavior

ViteHub selects the configured KV store and exposes a small Storage Capability Tool Surface. Read mode supports one exact key or one prefix per tool call. Write mode adds a put/delete tool with approval required by default.

Requirements

kv() requires a configured kv primitive. Named store selection requires the KV primitive to expose store selection.

Writes require write mode and should keep approval enabled unless the product explicitly accepts autonomous storage writes.

Driver support

Inspect and verify

Inspect the Agent tool list in DevTools. Read mode should show only kv_read; write mode should also show kv_edit with the configured policy.

Run one invocation against a missing KV primitive during development. The Capability should fail before exposing tools.

Options

Reference

• KV primitive
• Official capabilities
• Source: packages/agent/src/capabilities/storage/kv.ts