Workspace shell

workspaceShell() adds model-facing Workspace tools to an Agent. It exposes shell-shaped inspection by default and write tools only when the Agent's Workspace grants 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 Workspace inspection tools in read mode and structured Workspace mutation tools in write mode. When Workspace Sources expose request descriptors, it also contributes instructions that tell the Agent how to inspect controlled curl access.

Configuration

Attach workspaceShell() only when the Agent should inspect the Workspace. Use read mode first, then switch to write mode when product behavior requires mutation.

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

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

Runtime behavior

ViteHub validates Workspace requirements before the Capability resolves tools. In read mode, the Agent receives inspection tools from the active Workspace facade. In write mode, the Agent receives writable Workspace tools when the Workspace exposes them.

Requirements

workspaceShell() requires an explicit Workspace. Write mode requires workspace.mode: 'write'.

Workspace Shell is not Sandbox. It exposes Workspace file operations, while sandbox() runs allowlisted executables in an isolated runtime.

Driver support

Inspect and verify

Open DevTools and inspect the Agent's tool list. Read mode should expose inspection tools, and write mode should expose mutation tools only when the Workspace is writable.

Try reading outside an access() Workspace Scope when both Capabilities are attached. The scoped Workspace should hide or reject paths outside the selected grants.

Options

Reference

• Workspace context
• Workspace primitive
• sandbox()
• Source: packages/agent/src/capabilities/workspace-shell.ts