tiny-agent-ai 0.1.2

package/README.md

@@ -0,0 +1,155 @@
+# tiny-agent
+
+Minimal, extension-based AI agent. The core is ~200 lines — just the loop and types. Everything else is an extension.
+
+## Usage
+
+```bash
+bun add tiny-agent-ai
+```
+
+```typescript
+import { Agent, OpenAIProvider, toolsExtension, loopDetectionExtension } from 'tiny-agent-ai'
+import type { Tool } from 'tiny-agent-ai'
+
+// Define a custom tool
+const weatherTool: Tool = {
+  definition: {
+    name: 'get_weather',
+    description: 'Get current weather for a city',
+    parameters: {
+      type: 'object',
+      properties: { city: { type: 'string', description: 'City name' } },
+      required: ['city'],
+    },
+  },
+  async execute(input) {
+    const res = await fetch(`https://wttr.in/${input.city}?format=j1`)
+    const data = await res.json()
+    return { output: JSON.stringify(data.current_condition[0]) }
+  },
+}
+
+const provider = new OpenAIProvider(process.env.OPENAI_API_KEY!, 'gpt-4o')
+
+const agent = new Agent({
+  provider,
+  systemPrompt: 'You are a helpful assistant with access to weather data.',
+  extensions: [
+    { name: 'weather', tools: [weatherTool] },
+    toolsExtension(),
+    loopDetectionExtension(),
+  ],
+})
+
+for await (const event of agent.run('What is the weather in Berlin?')) {
+  if (event.type === 'text_delta') process.stdout.write(event.text)
+}
+```
+
+The `Agent` class takes a provider, a system prompt, and an array of extensions. No config files, no env var conventions, no DI — you wire it however you want.
+
+## Architecture
+
+The core (`packages/core/`) has three files:
+
+- **`types.ts`** — `Message`, `Tool`, `Provider`, `Extension`, `MessageStore` interfaces
+- **`agent.ts`** — The loop: stream LLM → parse tool calls → run hooks → execute tools → repeat
+- **`index.ts`** — Barrel exports
+
+The loop:
+
+1. Push user message, call `beforeSend` hooks, stream from provider
+2. Collect text deltas and tool call chunks into a complete assistant message
+3. If no tool calls → `onTurnDone`, yield `turn_done`, return
+4. For each tool call → `beforeToolCall` (can block/inject) → execute → `afterToolCall` (can transform result)
+5. Append tool results, go to step 1
+
+## Extension API
+
+```typescript
+interface Extension {
+  name: string
+  tools?: Tool[]
+  beforeSend?(messages: Message[]): Message[] | Promise<Message[]>
+  beforeToolCall?(toolCall: ToolCall): boolean | { inject: Message } | Promise<...>
+  afterToolCall?(toolCall: ToolCall, result: ToolResult): ToolResult | Promise<ToolResult>
+  onTurnDone?(messages: Message[]): void | Promise<void>
+}
+```
+
+Extensions run in array order. Put safety extensions before tool extensions.
+
+Built-in:
+- **toolsExtension** — read, write, edit, glob, grep, bash
+- **loopDetectionExtension** — breaks infinite tool-call loops
+- **compactionExtension** — summarizes old messages when context fills up
+- **taskExtension** — delegates subtasks to isolated sub-agents
+
+See [`packages/core/README.md`](packages/core/README.md) for detailed extension docs.
+
+## Providers
+
+The core defines a `Provider` interface — anything that implements `stream()` works:
+
+```typescript
+interface Provider {
+  name: string
+  stream(messages, tools, systemPrompt, maxTokens): AsyncIterable<ProviderChunk>
+}
+```
+
+Included: `OpenAIProvider` (works with any OpenAI-compatible API) and `AnthropicProvider`. Write your own for Gemini, Ollama, or anything else.
+
+## Message Persistence
+
+The `Agent` accepts an optional `store: MessageStore` for persistence. The interface is minimal:
+
+```typescript
+interface MessageStore {
+  getMessages(): Message[]
+  append(message: Message): void
+}
+```
+
+The included `Session` class (`packages/session/`) is a JSONL-based implementation. You can swap it for Redis, SQLite, a database — whatever fits your use case.
+
+## Packages
+
+```
+packages/core/                Agent loop + types (zero deps)
+packages/tiny-agent/          Barrel — single import (`tiny-agent-ai` on npm)
+packages/providers/openai/    OpenAI-compatible provider (included)
+packages/providers/anthropic/ Native Anthropic provider (included)
+packages/extensions/tools/    Filesystem + bash tools
+packages/extensions/loop-detection/  Breaks infinite loops
+packages/extensions/compaction/      Context window management
+packages/extensions/task/     Sub-agent delegation
+packages/session/             JSONL MessageStore implementation (example)
+packages/examples/cli/        Interactive REPL with slash commands
+packages/examples/web/        SSE server + chat UI
+```
+
+## Running the Examples
+
+```bash
+bun install
+cd packages/examples/cli   # or web
+cp agent.config.example.json agent.config.json
+# Add your API key and model
+
+bun run dev
+```
+
+See each example's README for details.
+
+## Development
+
+```bash
+bun run typecheck    # Type-check all packages
+bun run format       # Prettier
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "tiny-agent-ai",
+  "version": "0.1.2",
+  "description": "Minimal, extension-based AI agent. ~200 lines core, everything else is an extension.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xy69/tiny-agent"
+  },
+  "keywords": ["ai", "agent", "llm", "coding-agent", "openai", "anthropic", "tools"],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tiny-agent/core": "workspace:*",
+    "@tiny-agent/ext-tools": "workspace:*",
+    "@tiny-agent/ext-compaction": "workspace:*",
+    "@tiny-agent/ext-loop-detection": "workspace:*",
+    "@tiny-agent/ext-task": "workspace:*",
+    "@tiny-agent/provider-openai": "workspace:*",
+    "@tiny-agent/provider-anthropic": "workspace:*",
+    "@tiny-agent/session": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "@types/bun": "catalog:"
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export { Agent } from '@tiny-agent/core'
+export type { AgentOptions } from '@tiny-agent/core'
+export type {
+  Extension,
+  Tool,
+  ToolDefinition,
+  ToolResult,
+  MessageStore,
+  Provider,
+  StreamEvent,
+  Message,
+  ProviderChunk,
+  ToolCall,
+} from '@tiny-agent/core'
+export { Session } from '@tiny-agent/session'
+export { OpenAIProvider } from '@tiny-agent/provider-openai'
+export { AnthropicProvider } from '@tiny-agent/provider-anthropic'
+export { toolsExtension } from '@tiny-agent/ext-tools'
+export { compactionExtension } from '@tiny-agent/ext-compaction'
+export { loopDetectionExtension } from '@tiny-agent/ext-loop-detection'
+export { taskExtension } from '@tiny-agent/ext-task'

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"]
+}