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