52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
# Project Readme Hints
|
|
|
|
## Overview
|
|
`@push.rocks/smartagent` v2.0.0 is an agentic loop built on Vercel AI SDK v6 via `@push.rocks/smartai`. It wraps `streamText` with `stopWhen: stepCountIs(n)` for parallel multi-step tool execution.
|
|
|
|
## Architecture (v2)
|
|
- **`runAgent()`**: Pure async function — the core agentic loop. No class state.
|
|
- **`ToolRegistry`**: Lightweight helper for collecting tools into a `ToolSet`.
|
|
- **`truncateOutput()`**: Utility to prevent tool output from bloating context.
|
|
- **`compactMessages()`**: Context overflow handler (separate subpath export).
|
|
|
|
## Source Layout
|
|
```
|
|
ts/ → core: runAgent, ToolRegistry, truncateOutput, interfaces
|
|
ts_tools/ → built-in tool factories (filesystem, shell, http, json)
|
|
ts_compaction/ → compactMessages helper for onContextOverflow
|
|
```
|
|
|
|
## Built-in Tools (ts_tools/)
|
|
Each exports a factory returning a flat `ToolSet` (Record<string, Tool>):
|
|
1. **filesystemTool()** → `read_file`, `write_file`, `list_directory`, `delete_file`
|
|
2. **shellTool()** → `run_command`
|
|
3. **httpTool()** → `http_get`, `http_post`
|
|
4. **jsonTool()** → `json_validate`, `json_transform`
|
|
|
|
## Key Dependencies
|
|
- `@push.rocks/smartai` ^2.0.0 — provider registry, `getModel()`, re-exports `tool`, `jsonSchema`
|
|
- `ai` ^6.0.0 — Vercel AI SDK v6 (`streamText`, `stepCountIs`, `ModelMessage`, `ToolSet`)
|
|
- `zod` ^3.25.0 — tool input schema definitions
|
|
- `@push.rocks/smartfs`, `smartshell`, `smartrequest` — tool implementations
|
|
|
|
## AI SDK v6 Key APIs
|
|
- `streamText({ model, messages, tools, stopWhen: stepCountIs(20) })` — agentic loop
|
|
- `tool({ description, inputSchema: z.object({...}), execute })` — define tools
|
|
- `ModelMessage` — message type (replaces v4's `CoreMessage`)
|
|
- `LanguageModelV3` — model type from `@ai-sdk/provider`
|
|
- Result is `StreamTextResult` with PromiseLike properties (`await result.text`, etc.)
|
|
|
|
## Package Exports
|
|
- `.` → core (runAgent, ToolRegistry, truncateOutput, re-exports)
|
|
- `./tools` → built-in tool factories
|
|
- `./compaction` → compactMessages
|
|
|
|
## Build
|
|
- `pnpm build` → `tsbuild tsfolders --allowimplicitany`
|
|
- Cross-folder imports via each folder's `plugins.ts` (tsbuild unpack resolves them)
|
|
|
|
## Test Structure
|
|
- Tests use `@git.zone/tstest/tapbundle`
|
|
- Tests must end with `export default tap.start()`
|
|
- `pnpm test` → `tstest test/ --verbose`
|