@shuyhere/takotako 0.0.1

package/docs/architecture.md

@@ -0,0 +1,128 @@
+# Architecture
+
+Tako follows an **Agent-as-CPU** design: the LLM is the processor, the core runtime is the OS kernel, and skills are pluggable arms.
+
+## Design Principles
+
+1. **Minimal kernel** — only what every agent needs, nothing more
+2. **Trait-based** — every subsystem is an interface; swap implementations freely
+3. **Clear boundaries** — each subsystem has one job, one interface, zero leakage
+4. **Convention over config** — sane defaults, override when needed
+5. **Markdown-first memory** — plain files are the source of truth
+6. **Single binary mindset** — one process, fast start
+
+## System Diagram
+
+```
+┌─────────────────────────────────────────────┐
+│                  Tako Gateway                │
+│            (WebSocket control plane)         │
+├──────┬──────┬──────┬──────┬────────────────┤
+│ Prov │ Chan │ Tool │ Mem  │    Session      │
+│ ider │ nel  │      │ ory  │    Manager      │
+├──────┴──────┴──────┴──────┴────────────────┤
+│              Agent Loop                      │
+│   intake → context → infer → tools → reply  │
+├─────────────────────────────────────────────┤
+│           Skill Arms (pluggable)             │
+│  find-skills │ skill-creator │ your-skill  │
+└─────────────────────────────────────────────┘
+```
+
+## Core Subsystems
+
+### 1. Provider (inference engine)
+
+Adapts LLM APIs into a unified streaming interface. Each provider handles:
+- API authentication and key rotation
+- Message format conversion
+- Streaming response parsing
+- Model capability detection
+
+Interface: `src/providers/provider.ts`
+
+### 2. Channel (messaging I/O)
+
+Adapts messaging platforms into a unified message handler. Multiple channels run simultaneously. Each handles:
+- Platform connection and authentication
+- Message format conversion
+- Rate limiting and message splitting
+- Reconnection and error recovery
+
+Interface: `src/channels/channel.ts`
+
+### 3. Tool (agent syscalls)
+
+Named functions the model can invoke during generation. Organized into groups, activated by profiles:
+- **Kernel tools**: organized into 10 groups across 3 profiles
+- **Skill tools**: registered at runtime by skill arms
+- **Policy**: deny/allow lists override profile defaults
+
+Interface: `src/tools/tool.ts`
+
+### 4. MemoryStore (persistence + recall)
+
+Hybrid search over the agent's markdown memory:
+- **BM25**: keyword matching with TF-IDF scoring and temporal decay
+- **Vector**: semantic similarity via embeddings (OpenAI or Voyage)
+- **Fusion**: Reciprocal Rank Fusion combines both result sets
+
+Interface: `src/memory/store.ts`
+
+### 5. HookSystem (lifecycle events)
+
+Simple event emitter for intercepting agent lifecycle moments:
+- Agent start/end, prompt build
+- Tool call before/after
+- Session start/end
+- Message received/sending
+- Gateway start/stop
+
+Interface: `src/hooks/types.ts`
+
+## Agent Loop
+
+The CPU cycle runs for each user message:
+
+1. **Message arrives** from any channel
+2. **Session resolved** (or created) based on channel + author
+3. **System prompt assembled** from workspace files + matching skill instructions
+4. **Provider.chat()** called with streaming
+5. **Tool calls executed** (up to 50 per turn, configurable `maxTurns` default 20)
+6. **Response streamed** back through the originating channel
+7. **Session persisted** to disk
+
+Dynamic skill injection happens at step 3: the loader checks each skill's trigger conditions against the user message and injects matching skill instructions into the prompt.
+
+## Gateway
+
+The WebSocket server manages:
+- Client authentication
+- Session create/resume/list
+- Streaming agent responses as chunks
+- Tool call notifications
+
+Protocol: `src/gateway/protocol.ts`
+
+## Skill Extensions (Pluggable Subsystems)
+
+Skills can provide entire subsystem implementations via extension subdirectories:
+
+| Type | Subdirectory | Interface | Factory |
+|------|-------------|-----------|---------|
+| Channel | `channel/` | `Channel` | `createChannel(config)` |
+| Provider | `provider/` | `Provider` | `createProvider(config)` |
+| Memory | `memory/` | `MemoryStore` | `createMemory(config)` |
+| Network | `network/` | `NetworkAdapter` | `createNetwork(config)` |
+| Sandbox | `sandbox/` | `SandboxProvider` | `createSandbox(config)` |
+| Auth | `auth/` | `AuthProvider` | `createAuth(config)` |
+
+Extensions are auto-detected during skill loading, configured via `skillExtensions` in tako.json, and tracked at runtime in the `ExtensionRegistry`.
+
+See `src/skills/extensions.ts` for interfaces and `src/skills/extension-loader.ts` for the loader.
+
+## Memory Hierarchy
+
+- **MEMORY.md** — curated long-term memory, always in system prompt
+- **Daily logs** (memory/YYYY-MM-DD.md) — append-only, accessed via search
+- **Bootstrap files** — SOUL.md, IDENTITY.md, AGENTS.md, USER.md, TOOLS.md, HEARTBEAT.md

package/docs/channels.md

@@ -0,0 +1,140 @@
+# Channels
+
+Channels are messaging I/O adapters that connect Tako to different platforms. Multiple channels run simultaneously.
+
+## CLI (Built-in)
+
+Terminal readline interface. Always active.
+
+**Configuration:**
+```json
+{
+  "channels": {
+    "cli": {
+      "prompt": "tako> "
+    }
+  }
+}
+```
+
+**Features:**
+- Streaming output (chunks written to stdout in real-time)
+- `/quit` and `/exit` commands to stop
+- Serialized message handling (no overlapping executions)
+
+## TUI (Built-in)
+
+Terminal UI built with Ink/React. Attach to a running daemon or run standalone.
+
+**Launch:**
+```bash
+tako tui          # Attach to running daemon
+```
+
+**Features:**
+- Real-time streaming output
+- Image attachment support
+- Tab-completion for commands
+- Active agent display in header
+- Bot name masking for privacy
+
+## Discord (Built-in)
+
+Discord bot via discord.js.
+
+**Configuration:**
+```json
+{
+  "channels": {
+    "discord": {
+      "token": "your-bot-token",
+      "guilds": ["guild-id-1", "guild-id-2"]
+    }
+  }
+}
+```
+
+**Features:**
+- Auto-create threads for replies (reference runtime-style)
+- DM support (via Partials.Channel + Partials.Message)
+- Typing indicators (configurable via `agent.typingMode`)
+- Automatic message splitting (Discord's 2000 char limit)
+- Auto-reconnect with exponential backoff (up to 5 attempts)
+- Guild filtering (optional — respond only in specific servers)
+- Attachment extraction (images, files)
+- Sender name shown in messages: `[From: name]`
+
+**Setup:**
+1. Create a bot at [Discord Developer Portal](https://discord.com/developers/applications)
+2. Enable Message Content Intent
+3. Invite bot to your server with message permissions
+4. Set the token via `tako onboard` or `tako channels`
+
+## Telegram (Built-in)
+
+Telegram bot via grammY.
+
+**Configuration:**
+```json
+{
+  "channels": {
+    "telegram": {
+      "token": "your-bot-token",
+      "allowedUsers": ["username1", "username2"]
+    }
+  }
+}
+```
+
+**Features:**
+- Long polling (non-blocking)
+- Typing indicators (configurable via `agent.typingMode`)
+- Reactions support
+- Markdown formatting with fallback to plain text
+- Max 4096 chars per message (Telegram limit)
+- User filtering (optional — respond only to specific users)
+- Supports photos, documents, audio, video attachments
+- Sender name shown in messages: `[From: name]`
+
+**Setup:**
+1. Create a bot via [@BotFather](https://t.me/BotFather)
+2. Get the token
+3. Set via `tako onboard` or `tako channels`
+
+## Custom Channels
+
+Implement the `Channel` interface in `src/channels/channel.ts`:
+
+```typescript
+import type { Channel, OutboundMessage, MessageHandler, InboundMessage } from './channel.js';
+
+export class MyChannel implements Channel {
+  id = 'my-channel';
+  private handler?: MessageHandler;
+
+  async connect(): Promise<void> {
+    // Connect to your platform
+  }
+
+  async disconnect(): Promise<void> {
+    // Clean up
+  }
+
+  async send(msg: OutboundMessage): Promise<void> {
+    // Send message to your platform
+  }
+
+  onMessage(handler: MessageHandler): void {
+    this.handler = handler;
+  }
+}
+```
+
+## Multi-Channel Routing
+
+When multiple channels are active, Tako routes messages independently:
+
+- Each channel + author pair gets its own session
+- Sessions are keyed by `channelId:authorId`
+- The agent loop runs per-message, streaming output back through the originating channel
+- CLI streams to stdout; other channels send the complete response

package/docs/configuration.md

@@ -0,0 +1,209 @@
+# Configuration
+
+Tako is configured via `~/.tako/tako.json`, managed through `tako onboard` or CLI commands. Environment variables can also be used.
+
+**Important:** Never commit `tako.json` to git — it contains tokens and API keys.
+
+## Config File
+
+```json
+{
+  "providers": {
+    "primary": "anthropic/claude-sonnet-4-6",
+    "fallback": ["anthropic/claude-haiku-4-5"]
+  },
+  "channels": {
+    "discord": {
+      "token": "your-discord-bot-token",
+      "guilds": ["guild-id-1"]
+    },
+    "telegram": {
+      "token": "your-telegram-bot-token",
+      "allowedUsers": ["username1"]
+    },
+    "cli": {
+      "prompt": "tako> "
+    }
+  },
+  "tools": {
+    "profile": "full",
+    "deny": ["web_search"],
+    "allow": ["exec"]
+  },
+  "memory": {
+    "workspace": "~/.tako/workspace",
+    "embeddings": {
+      "provider": "openai",
+      "model": "text-embedding-3-small"
+    }
+  },
+  "gateway": {
+    "bind": "127.0.0.1",
+    "port": 18790,
+    "authToken": "optional-auth-token"
+  },
+  "agent": {
+    "timeout": 600,
+    "thinking": "adaptive",
+    "maxToolCalls": 50,
+    "maxTurns": 20,
+    "maxOutputChars": 50000,
+    "maxTokens": 16384,
+    "typingMode": "instant"
+  },
+  "sandbox": {
+    "mode": "off",
+    "scope": "session",
+    "workspaceAccess": "ro"
+  },
+  "heartbeat": {
+    "every": "30m",
+    "target": "none",
+    "ackMaxChars": 300
+  },
+  "session": {
+    "compaction": { "auto": true, "thresholdPercent": 80 },
+    "pruneAfterDays": 7,
+    "maxEntries": 100
+  }
+}
+```
+
+## Reference
+
+### providers
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `primary` | string | `"anthropic/claude-sonnet-4-6"` | Primary model (format: `provider/model`) |
+| `fallback` | string[] | — | Ordered fallback model chain (up to 3) |
+| `overrides` | object | — | Per-provider configuration overrides |
+| `litellm` | object | — | LiteLLM proxy config (`baseUrl`, `apiKey`, `model`, `models`) |
+
+### channels
+
+#### discord
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `token` | string | — | Discord bot token |
+| `guilds` | string[] | — | Restrict to specific guild IDs |
+
+#### telegram
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `token` | string | — | Telegram bot token |
+| `allowedUsers` | string[] | — | Restrict to specific usernames |
+
+#### cli
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `prompt` | string | `"tako> "` | CLI prompt string |
+
+### tools
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `profile` | string | `"full"` | Tool profile: `minimal`, `coding`, or `full` |
+| `deny` | string[] | `[]` | Tools to always block |
+| `allow` | string[] | — | Tools to always allow (overrides profile) |
+| `exec.security` | string | — | Exec safety: `deny`, `allowlist`, or `full` |
+| `exec.allowlist` | string[] | — | Regex patterns for pre-approved commands |
+| `exec.timeout` | number | — | Max exec timeout in ms |
+
+**Profiles:**
+- `minimal`: fs + runtime only
+- `coding`: + search, git, memory
+- `full`: all 10 groups (fs, runtime, search, git, memory, web, sessions, image, agents, messaging)
+
+### memory
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `workspace` | string | `"~/.tako/workspace"` | Workspace directory path (~ expanded) |
+| `embeddings.provider` | string | — | Embedding provider: `"openai"` or `"voyage"` |
+| `embeddings.model` | string | — | Embedding model name |
+
+### gateway
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `bind` | string | `"127.0.0.1"` | Bind address for WebSocket server |
+| `port` | number | `18790` | Port number |
+| `authToken` | string | — | Auth token (auto-generated if missing) |
+
+### agent
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `timeout` | number | `600` | Max agent loop duration in seconds |
+| `thinking` | string | `"adaptive"` | Thinking mode: `none`, `adaptive`, `always` |
+| `maxToolCalls` | number | `50` | Max tool calls per loop iteration |
+| `maxTurns` | number | `20` | Max tool-call turns per agent loop run |
+| `maxOutputChars` | number | `50000` | Max output characters before truncation |
+| `maxTokens` | number | `16384` | Max output tokens per API call |
+| `typingMode` | string | — | Typing indicator: `never`, `instant`, `thinking`, `message` |
+| `typingIntervalSeconds` | number | `6` | How often to refresh typing indicator |
+
+### sandbox
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `mode` | string | `"off"` | When to sandbox: `off`, `non-main`, `all` |
+| `scope` | string | `"session"` | Container lifecycle: `session`, `agent`, `shared` |
+| `workspaceAccess` | string | `"ro"` | Workspace mount: `none`, `ro`, `rw` |
+| `docker.image` | string | — | Custom Docker image |
+| `docker.network` | string | — | Docker network binding |
+
+### heartbeat
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `every` | string | `"30m"` | Interval: `"30m"`, `"1h"`, `"0m"` (disabled) |
+| `target` | string | `"none"` | Delivery: `none`, `last`, or channel ID |
+| `prompt` | string | *(built-in)* | Prompt sent to agent loop |
+| `ackMaxChars` | number | `300` | Max chars before delivery is dropped |
+| `activeHours` | object | — | Window: `{ start, end, timezone }` |
+
+### session
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `compaction.auto` | boolean | `true` | Enable auto-compaction |
+| `compaction.thresholdPercent` | number | `80` | Trigger at this % of context window |
+| `pruneAfterDays` | number | `7` | Prune completed sub-agent sessions after N days |
+| `maxEntries` | number | `100` | Max sessions to keep in memory |
+
+### agents
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `defaults.workspace` | string | `"~/.tako/workspace"` | Default workspace for agents |
+| `defaults.model` | object | — | Default model override |
+| `list` | AgentEntry[] | `[]` | Configured agents with bindings and roles |
+
+### skills
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `dirs` | string[] | `["./skills", "~/.tako/skills"]` | Directories to scan for skills |
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `ANTHROPIC_API_KEY` | Anthropic provider auth |
+| `ANTHROPIC_API_KEYS` | Comma-separated keys for rotation |
+| `OPENAI_API_KEY` | OpenAI provider / embeddings |
+| `VOYAGE_API_KEY` | Voyage embeddings (alternative) |
+| `DISCORD_TOKEN` | Discord bot token |
+| `TELEGRAM_TOKEN` | Telegram bot token |
+
+**Recommended:** Use `tako onboard` or `tako models auth login` instead of manual env vars.
+
+## Resolution Order
+
+1. Hardcoded defaults
+2. `~/.tako/tako.json` file (shallow merge per section)
+3. Environment variables
+
+Path expansion: `~` is expanded to the home directory in path fields.