smartagent/readme.hints.md

# 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`