Parent PRD

#2

What to build

Create @agentskit/tools — a marketplace of reusable executable tools. Each tool follows the evolved ToolDefinition contract from core (JSONSchema7 schema, optional init/dispose lifecycle, streaming execute support).

Ship a first batch of tools: web search, filesystem (read/write/list), and a shell/command executor. Each tool is independently importable.

Include auto-discovery: tools export their metadata (name, description, tags, category) so runtime and chat can enumerate available tools. Support parallel tool calling and human confirmation via requiresConfirmation.

Acceptance criteria

• packages/tools/ package created with tsup, vitest
• Each tool satisfies the evolved ToolDefinition contract (JSONSchema7 schema, typed args)
• Web search tool: accepts query, returns results (uses fetch, no heavy deps)
• Filesystem tool: read, write, list files with path restrictions
• Shell tool: execute commands with timeout, returns stdout/stderr
• Stateful tool lifecycle: init() called before first use, dispose() called on cleanup
• At least one tool demonstrates AsyncIterable streaming output
• Auto-discovery: listTools() function returns all available tools with metadata
• Contract compliance tests for every tool
• Unit tests per tool with mocked externals
• Works with both ChatController (useChat) and AgentRunner (runtime.run)

Blocked by

• Blocked by Evolve core contracts & extract shared primitives #3 (core contracts — evolved ToolDefinition)

User stories addressed

• User story 5 (pre-built tools)
• User story 6 (custom tools with simple contract)
• User story 7 (JSON Schema for tool params)
• User story 8 (init/dispose lifecycle)
• User story 9 (streaming tool output)