khabotcli 1.0.0

package/.OLD/STEP-1/RESEARCH-TODO/deep-research-testing-ai-agents.md

@@ -0,0 +1,74 @@
+# Deep Research: Testing Strategies for AI Agent Runtimes
+
+## Research Goal
+Define a comprehensive testing strategy for an AI agent runtime (KhaBotCLI) that handles non-deterministic LLM outputs, multi-agent workflows, and tool execution.
+
+## Key Questions
+
+### 1. Testing Non-Deterministic Outputs
+AI agents produce different outputs each time. How do you test them?
+- **Scoring rubrics** — define criteria, score output (e.g., "contains key info: 3/5")
+- **LLM-as-judge** — use another LLM to evaluate output quality
+- **Property-based testing** — test properties (output is valid JSON, file was created, test passes)
+- **Snapshot testing** — record "golden" outputs, compare semantically (not exact match)
+- **Regression detection** — detect when quality drops across versions
+
+For each approach:
+- How is it implemented?
+- What are the tradeoffs?
+- What tools/frameworks exist?
+
+### 2. Testing Agent Tools
+- How to test individual tool implementations (bash, read_file, edit_file)?
+- How to test tool permission evaluation?
+- How to test tool error handling?
+- How to mock LLM responses for deterministic tool testing?
+
+### 3. Testing Multi-Agent Workflows
+- How to test agent-to-agent communication?
+- How to test task delegation chains?
+- How to test concurrent agent execution?
+- How to test compaction preserves critical context?
+- How to integration-test a full agent lifecycle?
+
+### 4. CI/CD for AI Agent Projects
+- How do leading projects (Claude Code, OpenCode, Cursor) run their CI?
+- What does a CI pipeline look like for an agent runtime?
+- How to handle flaky tests due to LLM non-determinism?
+- How to benchmark performance across versions?
+- How to gate releases on quality metrics?
+
+### 5. Mock LLM Strategies
+- Record/replay LLM responses for deterministic tests
+- Fake LLM that returns scripted responses based on input patterns
+- Lightweight local model for testing (e.g., small Ollama model)
+- When to use real LLM calls in tests vs mocks?
+
+### 6. MCP Server Testing
+- How to test MCP server discovery and handshake?
+- How to create mock MCP servers for testing?
+- How to test tool registration from MCP?
+- How to test MCP error handling?
+
+### 7. Performance & Load Testing
+- How to benchmark agent startup time?
+- How to test with 1000+ sessions in storage?
+- How to test concurrent task execution limits?
+- Memory usage profiling strategies?
+
+## Sources to Investigate
+- Microsoft's "Observability and testing" guide for AI agents
+- datagrid.com "AI Agent CI/CD Pipeline Guide"
+- SWE-bench and Terminal-Bench methodologies
+- OpenCode's test suite (Go tests)
+- Anthropic's eval framework
+- LangSmith, Braintrust, Promptfoo for LLM evaluation
+- Vitest/Jest for JS, Go test for Go
+
+## Expected Output
+1. Testing pyramid for KhaBotCLI (unit → integration → e2e → eval)
+2. Recommended test frameworks and tools
+3. Mock LLM implementation specification
+4. CI pipeline specification (step-by-step)
+5. Quality gates and metrics
+6. Example test cases for each layer

package/.OLD/STEP-1/SCOPED-QUESTIONS/scoped-agent-types.md

@@ -0,0 +1,44 @@
+# Question: Should Chat, Task, and Daemon Be Separate Agent Types or Invocation Modes?
+
+## Context
+You are designing an AI agent runtime — a locally-running server that manages autonomous AI agents. The runtime exposes a REST API and supports multiple agents running simultaneously.
+
+Currently, agents are categorized into three rigid types:
+- **Chat Agent** — stateful conversation, user sends messages, agent responds
+- **Task Agent** — asynchronous job, agent runs to completion, produces output
+- **Daemon Agent** — runs on a schedule (cron), checks conditions, alerts if needed
+
+Each type has separate code paths, separate API endpoints, and separate lifecycle logic.
+
+## The Question
+**Should these be three separate agent types defined at the agent level, or should they be three invocation modes that any agent can be triggered with?**
+
+### Option A: Separate Types (current design)
+- Agent definition includes `type: chat | task | daemon`
+- A "researcher" agent is either a Chat agent OR a Task agent, not both
+- Different API endpoints: `/agents/:name/spawn` (chat) vs `/tasks` (task) vs `/daemons/:name/trigger` (daemon)
+- Different lifecycles and storage
+
+### Option B: Unified Agent with Invocation Modes
+- Agent definition has no `type` field — any agent can be invoked in any mode
+- A "researcher" agent can be chatted with, given a task, or set up as a daemon
+- Unified API: `POST /agents/:name/invoke { mode: "chat" | "task" | "daemon" }`
+- Shared lifecycle logic, mode just determines: how it starts, how it ends, whether it persists
+
+### Option C: Hybrid
+- Agent definition has a `defaultMode` but can be overridden
+- Some agents are "optimized" for a mode but can run in others
+- Daemon-specific fields (cron, heartbeat) only apply when running as daemon
+
+## Considerations
+- A chat agent's system prompt might say "engage in dialogue" while a task agent's might say "complete the job and return results." Would running a chat-optimized agent as a task produce weird results?
+- Daemons need cron config and heartbeat logic. This is fundamentally different from chat/task. Should it really be a "mode" or is it a wrapper?
+- From an API consumer's perspective, is it simpler to have one concept ("agent") or three?
+- How do Claude Code, OpenCode, and Cursor handle this? (They mostly have "primary" vs "subagent" modes, not chat/task/daemon)
+
+## Please Provide
+1. Your recommendation (A, B, or C) with reasoning
+2. If B or C: How to handle daemon-specific concerns (cron, heartbeat)?
+3. If A: How to handle the case where someone wants to both chat with and assign tasks to the same agent?
+4. API design implications of your choice
+5. Any alternative approaches you'd suggest

package/.OLD/STEP-1/SCOPED-QUESTIONS/scoped-mcp-vs-custom-tools.md

@@ -0,0 +1,61 @@
+# Question: MCP-Only vs Custom Tool Scripts for an AI Agent Runtime
+
+## Context
+You are designing the tool extension system for an AI agent runtime. Agents need to interact with external services and perform actions beyond their built-in capabilities.
+
+There are two approaches to extending tool capabilities:
+
+### Approach A: Custom Tool Scripts
+Users define tools as scripts (JavaScript/Python/etc.) with a manifest:
+```
+.khabot/tools/send_slack/
+├── tool.json    ← manifest (name, description, input schema)
+└── index.js     ← implementation (Node.js script)
+```
+The runtime executes `index.js` when the agent calls the tool, passing input as JSON, reading output from stdout.
+
+### Approach B: MCP Servers Only
+Users run MCP (Model Context Protocol) servers that expose tools:
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "mcp-slack-server"],
+      "env": { "SLACK_TOKEN": "..." }
+    }
+  }
+}
+```
+MCP servers run as separate processes, communicate via JSON-RPC over stdio or HTTP. They can expose multiple tools, resources, and prompts.
+
+### Approach C: Both (support both custom scripts and MCP)
+Users can define simple tools as scripts and complex integrations as MCP servers.
+
+## Tradeoffs to Consider
+
+| Aspect | Custom Scripts | MCP Servers |
+|--------|---------------|-------------|
+| **Simplicity** | Very simple: write a function, done | Need to understand MCP protocol |
+| **Security** | Arbitrary code execution risk | Sandboxed process, controlled interface |
+| **Ecosystem** | Custom to this runtime only | Industry standard, shared ecosystem |
+| **Multi-tool** | One script = one tool | One server = many tools |
+| **Lifecycle** | Spawned per-call or long-running? | Long-running process, managed lifecycle |
+| **Discovery** | Read manifest files | JSON-RPC handshake, dynamic |
+| **Resources** | Tools only | Tools + Resources + Prompts |
+| **Community** | None (proprietary) | Growing MCP server ecosystem |
+
+## Key Questions
+1. Is the simplicity of custom scripts worth the security and ecosystem tradeoffs?
+2. MCP is becoming an industry standard — should we bet entirely on it?
+3. For simple tools (e.g., "send a Slack message"), is MCP overkill?
+4. Could custom scripts be wrapped as lightweight MCP servers automatically?
+5. If we support both, how do we handle naming conflicts?
+6. What's the maintenance burden of supporting two extension systems?
+
+## Please Provide
+1. Your recommendation (A, B, or C) with reasoning
+2. If B (MCP-only): How to make simple tool creation easy for users who don't know MCP?
+3. If C (both): How to manage the two systems and avoid confusion?
+4. Security considerations for each approach
+5. What does the community/ecosystem momentum suggest?

package/.OLD/STEP-1/SCOPED-QUESTIONS/scoped-session-storage.md

@@ -0,0 +1,63 @@
+# Question: Best Storage Strategy for 50k+ AI Agent Sessions
+
+## Context
+You are designing storage for an AI agent runtime. The system needs to store:
+- **Sessions** — conversation histories (each with metadata + message array)
+- **Tasks** — async jobs with status, input, output, logs
+- **Messages** — individual messages within sessions (could be 10-500+ per session)
+
+Scale expectations:
+- Up to 50,000 sessions over time
+- Up to 40,000 tasks over time
+- Average session: 20 messages, each message 500-5000 tokens
+- Some sessions have 500+ messages
+- Need to query by: agent name, status, date range, session ID
+- Need fast: create, read latest, list with filters
+- Need periodic: cleanup old sessions, archive completed tasks
+
+The runtime is a **local application** (not cloud), running on a user's machine. It should be lightweight and not require external database setup.
+
+## Options
+
+### Option A: Individual JSON Files (current design)
+```
+~/.khabot/sessions/<sessionId>/meta.json
+~/.khabot/sessions/<sessionId>/messages.json
+~/.khabot/tasks/<taskId>/task.json
+~/.khabot/tasks/<taskId>/log.md
+```
+- **Pro:** Human-readable, easy to inspect/debug, no dependencies
+- **Con:** 100k+ files at scale, slow directory listing, no indexing, no querying, no atomic writes
+
+### Option B: SQLite
+```
+~/.khabot/data.db
+Tables: sessions, messages, tasks, task_logs
+```
+- **Pro:** Fast queries, indexing, atomic writes, single file backup, pagination built-in
+- **Con:** Not human-readable, requires SQLite dependency, migration complexity
+
+### Option C: Hybrid
+```
+~/.khabot/data.db          ← index + metadata
+~/.khabot/sessions/<id>/   ← full message history as files (lazy loaded)
+```
+- **Pro:** Fast queries via SQLite, human-readable messages, best of both
+- **Con:** Two storage systems to maintain, consistency challenges
+
+### Option D: Single JSONL Files
+```
+~/.khabot/sessions.jsonl     ← one JSON per line, append-only
+~/.khabot/messages.jsonl     ← messages with session ID reference
+~/.khabot/tasks.jsonl
+```
+- **Pro:** Append-only is fast, human-readable, simple
+- **Con:** No indexing (full scan for queries), large file over time, no atomic updates
+
+## Please Provide
+1. Your recommendation with reasoning
+2. How to handle lazy loading (only load what's needed into memory)
+3. How to handle cleanup/archival of old sessions
+4. How to handle the transition from initial development (few sessions) to production scale (50k+)
+5. Backup and migration strategy
+6. How does OpenCode use SQLite for this? Any lessons learned?

package/.OLD/STEP-1/SCOPED-QUESTIONS/scoped-skill-auto-loading.md

@@ -0,0 +1,56 @@
+# Question: How Should Skills/Tools Be Loaded Into an AI Agent's Context?
+
+## Context
+You are designing an AI agent runtime where agents have access to:
+- **Built-in tools** (bash, read_file, edit_file, grep, etc.) — always available
+- **Skills** (reusable prompt templates, like "review-code", "generate-tests") — project or global level
+- **MCP tools** (external tools from MCP servers) — could be 50+ tools across multiple servers
+- **Custom tools** (user-defined)
+
+The agent's context window is limited (e.g., 200k tokens). Every tool/skill description added to the system prompt consumes tokens and reduces the agent's "attention budget" for actual work.
+
+## The Problem
+If you have 15 built-in tools + 20 skills + 30 MCP tools = **65 tool/skill descriptions** in the system prompt. At ~200 tokens each = **13,000 tokens** just for tool descriptions. This is a significant chunk of the context window and causes "context pollution" — the agent has so much to read that it becomes less focused.
+
+## Options
+
+### Option A: Load Everything at Startup
+- All tool descriptions in system prompt from the start
+- **Pro:** Agent always knows what's available
+- **Con:** Context pollution, wasted tokens, agent confusion with too many options
+
+### Option B: ToolSearch Pattern (Claude Code's approach)
+- System prompt includes: built-in tools (always) + list of available skill/MCP tool NAMES only
+- Agent uses `ToolSearch` tool to find and load full descriptions when needed
+- After using a tool, its description can be kept or removed from context
+- **Pro:** Minimal context pollution, on-demand loading
+- **Con:** Extra LLM call to search for tools, agent might not know to search
+
+### Option C: Category-Based Loading
+- Tools grouped by category (file, network, memory, orchestration)
+- Agent starts with core category only
+- Other categories loaded when agent's task involves them (detected from prompt)
+- **Pro:** Smart pre-loading, no extra search step
+- **Con:** Needs reliable task classification
+
+### Option D: Progressive Loading
+- Start with top 10 most-used tools
+- After each agent response, analyze which tools might be needed next
+- Pre-load those tool descriptions for the next turn
+- Remove unused tool descriptions after N turns
+- **Pro:** Dynamic optimization
+- **Con:** Complex, may pre-load wrong tools
+
+## Additional Questions
+1. Should skills be treated differently from tools? (Skills are prompt templates, tools are executable functions)
+2. How should MCP tool descriptions be managed? They can change when MCP servers restart.
+3. Should the agent be told "there are more tools available, use tool_search to find them" or should it not know about tools it hasn't discovered?
+4. How do you handle the case where an agent needs a tool it doesn't know about?
+5. Should auto-removal of tool descriptions happen? (e.g., remove `web_search` description from context if the agent hasn't used it in 10 turns)
+
+## Please Provide
+1. Your recommended approach with reasoning
+2. What should always be in context vs discoverable?
+3. How to handle the "agent doesn't know what it doesn't know" problem
+4. Implementation sketch of the recommended approach
+5. How does this interact with context compaction? (When context is compacted, are tool descriptions re-added?)

package/.OLD/STEP-1/SCOPED-QUESTIONS/scoped-system-prompt-architecture.md

@@ -0,0 +1,62 @@
+# Question: How to Structure a Modular System Prompt for an AI Agent Runtime?
+
+## Context
+You are designing the system prompt architecture for an AI agent runtime. The system prompt is what gets sent to the LLM at the beginning of every conversation to set up the agent's identity, rules, capabilities, and context.
+
+The challenge: A modern AI agent's system prompt can be 10,000-25,000+ tokens. It's assembled from many sources:
+- Core identity and rules
+- Safety guidelines
+- Available tools and their descriptions
+- Available skills/commands
+- Project-specific instructions (from user's config files)
+- Environment information (OS, shell, git status)
+- Agent-specific personality/instructions
+- Memory from previous sessions
+- Permission rules
+- Conditional sections based on context
+
+## The Question
+**How should the system prompt be structured? Monolithic (one big string) vs Modular (assembled from fragments)?**
+
+### Option A: Monolithic
+- One large system prompt template with placeholders
+- `${AGENT_INSTRUCTIONS}`, `${TOOLS}`, `${MEMORY}`, etc. filled in at runtime
+- **Pro:** Simple, predictable, easy to debug
+- **Con:** Hard to maintain, can't conditionally include/exclude sections, all-or-nothing
+
+### Option B: Fragment-Based (Claude Code's approach)
+- 100+ small fragments, each ~30-500 tokens
+- Each fragment has: category, condition for inclusion, priority
+- Assembly engine combines fragments in defined order
+- **Pro:** Fine-grained control, conditional inclusion, easy to update individual pieces
+- **Con:** Complex assembly logic, hard to see the "full picture", ordering matters
+
+### Option C: Layered
+- 5-7 layers, each is a complete section:
+  1. Base identity
+  2. Environment context
+  3. Agent instructions (AGENT.md)
+  4. Tools and capabilities
+  5. Rules and permissions
+  6. Memory and history
+  7. Task-specific context
+- Each layer is a complete markdown section
+- **Pro:** Organized, understandable, manageable number of pieces
+- **Con:** Less granular than fragments, might include unnecessary content within layers
+
+## Additional Questions
+1. Should the system prompt be visible/editable by the user?
+2. Should users be able to override/patch specific fragments?
+3. How to handle conflicting instructions (user says "always use TypeScript" but system says "use whatever the project uses")?
+4. Where should safety instructions go? (Start? End? Scattered throughout?)
+5. Should there be "system reminders" injected mid-conversation? (Claude Code does this ~40 times)
+6. How to handle different system prompts for different agent modes (primary vs sub-agent)?
+7. What's the optimal token budget for a system prompt? (5k? 10k? 20k?)
+
+## Please Provide
+1. Your recommended architecture with reasoning
+2. Fragment/layer structure with categories
+3. Assembly order specification
+4. How to handle conditional inclusion
+5. Token budget recommendations per section
+6. How to handle user customization without breaking the system prompt

package/.OLD/STEP-1/SCOPED-QUESTIONS-ANSWERS/scoped-agent-types.md

@@ -0,0 +1,290 @@
+# Answer: Should Chat, Task, and Daemon Be Separate Agent Types or Invocation Modes?
+
+## Recommendation: Option D — Chat/Task Are Invocation Modes, Daemon Is a Schedule (Not a Type or Mode)
+
+Neither A, B, nor C as stated. The correct decomposition is:
+
+- **Chat and Task are invocation modes** — they share the same agent loop, same tools, same session storage, and the same prompt compilation pipeline. The only difference is lifecycle: chat is synchronous request/response, task is asynchronous run-to-completion.
+- **Daemon is not an agent type or an invocation mode — it is an infrastructure schedule** that triggers a task invocation of any agent on a cron interval. It's a wrapper, not a peer of chat/task.
+
+This is not just theoretical. **Your spec already implies this.** Section 9.3 states that Daemon agents "ALSO respond to all API calls like a Chat Agent." Section 11 states that tasks "Spawn session for this task." Chat and Task already share sessions. The three "types" are already bleeding into each other — the architecture just hasn't acknowledged it yet.
+
+---
+
+## Why Not the Other Options
+
+### Why Not Option A (Separate Types)
+
+The current spec creates three parallel code paths that share 90% of their logic:
+
+| Concern | Chat | Task | Daemon |
+|---|---|---|---|
+| Load AGENT.md + SOUL.md + MEMORY.md | ✅ | ✅ | ✅ |
+| Compile system prompt | ✅ | ✅ | ✅ |
+| Call LLM in agentic loop | ✅ | ✅ | ✅ |
+| Execute tools with permissions | ✅ | ✅ | ✅ |
+| Persist session to disk | ✅ | ✅ | ✅ |
+| Track iterations/duration limits | ✅ | ✅ | ✅ |
+
+The **only** differences are:
+- **Chat**: synchronous response, no background execution
+- **Task**: asynchronous, has status tracking, supports `waiting` state
+- **Daemon**: cron trigger + HEARTBEAT.md injection + alert routing
+
+Forcing `type: chat | task | daemon` at the agent level means:
+1. A "researcher" agent defined as `type: task` cannot be casually chatted with. Want to ask it "what approach would you take for X?" before assigning a task? Can't — it's a task agent.
+2. A "monitor" agent defined as `type: daemon` can't be given ad-hoc tasks. Want to say "run your monitoring check right now on this specific file"? The spec says you can (Section 9.3), but the type system says it's a daemon.
+3. Code duplication across three lifecycle managers that share the same agent loop.
+
+### Why Not Option B (Unified with Invocation Modes)
+
+Making daemon a "mode" implies that any agent can be trivially invoked as a daemon, and that daemon is a peer concept to chat/task. It isn't. Daemon requires:
+- Cron configuration (infrastructure)
+- Heartbeat routing (infrastructure)
+- HEARTBEAT.md as injected context (content, not lifecycle)
+- Conflict resolution on overlapping ticks (scheduler concern)
+- Auto-start on runtime boot (infrastructure)
+
+None of these are properties of how an agent processes a request. They're properties of **when and why** the agent is triggered. A daemon invocation is just a task invocation with extra scheduling around it.
+
+Putting `mode: "daemon"` alongside `mode: "chat" | "task"` in a unified invoke endpoint conflates two different axes:
+- **Chat vs Task** = synchronous vs asynchronous agent execution
+- **Daemon** = scheduled recurring trigger of agent execution
+
+### Why Not Option C (Hybrid with defaultMode)
+
+`defaultMode` adds a concept that doesn't pull its weight. If an agent can be invoked in any mode, what does `defaultMode` mean operationally? The API consumer already knows which mode they want — they're either sending a message (chat) or assigning a job (task). `defaultMode` is documentation, not behavior. Put it in `description` instead.
+
+---
+
+## The Proposed Architecture
+
+### Agent Definition
+
+Remove the `type` field entirely. An agent is just behavior — prompt, persona, memory, skills, tools.
+
+```yaml
+---
+name: researcher
+description: Deep research agent that investigates topics and produces reports
+model: anthropic/claude-3.5-sonnet
+max_iterations: 50
+max_duration_seconds: 300
+---
+
+You are a research agent. Your job is to...
+```
+
+No `type`. No `defaultMode`. Any agent can be chatted with or given a task.
+
+### Two Invocation Modes: Chat and Task
+
+These are the only two invocation modes. They differ only in lifecycle:
+
+| Aspect | Chat | Task |
+|---|---|---|
+| **Trigger** | API call with message | API call with task input |
+| **Execution** | Synchronous, blocks until response | Asynchronous, returns task ID immediately |
+| **State tracking** | Session only | Session + Task (status, iterations, output) |
+| **Persistence** | `~/.khabot/sessions/` | `~/.khabot/sessions/` + `~/.khabot/tasks/` |
+| **Lifecycle** | Request → Response | pending → processing → waiting → finished/failed/canceled |
+| **Multi-turn** | Send more messages to same session | Respond to waiting task, or read output |
+
+Both share:
+- Same prompt compilation pipeline
+- Same agent loop (LLM call → tool execution → repeat)
+- Same permission system
+- Same hooks
+- Same session storage
+
+### Daemon as a Schedule (Not an Agent Concept)
+
+A daemon schedule is a **runtime-level configuration** that says: "Trigger a task invocation of agent X on this cron interval, injecting HEARTBEAT.md as additional context."
+
+Daemon config moves **out of the agent definition** and into `settings.json` (or a dedicated schedules config):
+
+```json
+{
+  "schedules": {
+    "monitor-heartbeat": {
+      "agent": "monitor",
+      "cron": "*/30 * * * *",
+      "onConflict": "skip",
+      "heartbeat": true,
+      "alertChannel": "slack"
+    },
+    "daily-report": {
+      "agent": "researcher",
+      "cron": "0 9 * * 1",
+      "input": {
+        "prompt": "Generate weekly research summary from memory"
+      },
+      "onConflict": "skip"
+    }
+  }
+}
+```
+
+When a schedule fires:
+1. Runtime creates a task for the specified agent (same as `POST /tasks`)
+2. If `heartbeat: true`, HEARTBEAT.md content is prepended to the task input
+3. Task runs through normal task lifecycle
+4. If output matches `HEARTBEAT_OK` → silently log
+5. If output matches `HEARTBEAT_ALERT: ...` → route to `alertChannel`
+6. Schedule tracks: `lastTick`, `nextTick`, `lastResult`, `tickCount`
+
+This means:
+- The "monitor" agent **is just an agent**. You can chat with it. You can give it ad-hoc tasks. The schedule is what makes it behave like a daemon.
+- The "researcher" agent can also be scheduled (e.g., weekly summary) without being "a daemon."
+- HEARTBEAT.md is just additional context, not a type-level concern. Any agent can have one if it's going to be scheduled.
+- All daemon-specific infrastructure (cron, conflict resolution, auto-start) lives in the scheduler, not in agent code.
+
+---
+
+## API Design
+
+### Simplified Endpoints
+
+**Invoke an agent (replaces `/agents/:name/spawn`):**
+
+```
+POST /agents/:name/chat
+{
+  "message": "Hello, can you help me with...",
+  "sessionId": "sess_xxx"            // optional: resume session
+}
+
+→ 200 {
+  "sessionId": "sess_xxx",
+  "response": "...",
+  "agentName": "researcher"
+}
+```
+
+```
+POST /agents/:name/task
+{
+  "input": {
+    "prompt": "Research quantum computing in 2025",
+    "files": [],
+    "context": {}
+  },
+  "sessionId": "sess_xxx"            // optional: attach to session
+}
+
+→ 202 {
+  "taskId": "task_xxx",
+  "sessionId": "sess_xxx",
+  "status": "pending"
+}
+```
+
+Two verbs, not three. Clear intent. No `mode` field needed — the endpoint IS the mode.
+
+**Session and Task endpoints remain the same** as current spec (Sections 15.2, 15.3). No changes needed.
+
+**Schedule endpoints (replaces `/daemons/`):**
+
+```
+GET    /schedules                     → list all schedules
+GET    /schedules/:name               → schedule details + history
+POST   /schedules/:name/start         → activate schedule
+POST   /schedules/:name/stop          → deactivate schedule
+POST   /schedules/:name/trigger       → manually fire one tick (creates a task)
+```
+
+The `/schedules/:name/trigger` response returns a `taskId` — because that's what it creates. You can then track it with `GET /tasks/:id` like any other task.
+
+**Agent listing no longer includes type:**
+
+```json
+{
+  "agents": [
+    {
+      "name": "researcher",
+      "description": "...",
+      "model": "anthropic/claude-3.5-sonnet",
+      "source": "local",
+      "hasHeartbeat": true,
+      "activeSessions": 2,
+      "activeTasks": 1,
+      "scheduledBy": ["monitor-heartbeat"]
+    }
+  ]
+}
+```
+
+`hasHeartbeat` indicates HEARTBEAT.md exists (useful for UI). `scheduledBy` shows which schedules reference this agent. No `type` field.
+
+---
+
+## Handling Edge Cases
+
+### "Won't a chat-optimized prompt behave weirdly as a task?"
+
+Yes, potentially — but this is a **prompt design concern, not an architecture concern**. The solution is to write prompts that work in both modes, or to use the input context to signal mode:
+
+```markdown
+You are a research agent.
+
+When given a direct task, execute it to completion and return structured results.
+When engaged in conversation, discuss your approach and findings interactively.
+```
+
+The runtime can also inject a small mode hint into the system prompt automatically:
+
+```
+[Runtime: This agent was invoked in TASK mode. Execute the given input to completion.]
+```
+
+or
+
+```
+[Runtime: This agent was invoked in CHAT mode. Engage conversationally.]
+```
+
+This is one line of injected context, not a separate type system.
+
+### "What about HEARTBEAT.md — does every agent need one?"
+
+No. HEARTBEAT.md is only needed if the agent will be referenced by a schedule with `heartbeat: true`. It's optional additional context, just like SOUL.md. The schedule config references the agent; the agent doesn't know or care that it's being scheduled.
+
+If a schedule references an agent that has no HEARTBEAT.md and `heartbeat: true` is set, the runtime can either:
+- Warn on startup and skip the heartbeat injection, or
+- Error on startup (stricter, probably better for v1)
+
+### "Doesn't this lose the simplicity of `type: daemon`?"
+
+It **gains** simplicity. The API consumer now has two concepts instead of three:
+1. **Agent** — a thing with behavior
+2. **Schedule** — a cron trigger that creates tasks for agents
+
+Instead of asking "is this a chat agent or a task agent or a daemon agent?", the consumer asks "what can I do with this agent?" and the answer is always "chat with it or give it a task." Schedules are an operational concern configured by the admin, not something the API consumer typically interacts with.
+
+### "What about the one-shot CLI mode?"
+
+`khabot run --agent researcher --input "..."` creates a task, runs it to completion, exits. Unchanged. The agent has no type, the CLI mode is just a task invocation.
+
+---
+
+## Summary of Changes to Current Spec
+
+| Current Spec | Proposed Change |
+|---|---|
+| `type: chat \| task \| daemon` in AGENT.md frontmatter | **Remove.** No type field. |
+| Section 9 "Agent Types — Detailed Behavior" | Rename to "Invocation Modes." Two subsections: Chat, Task. |
+| Section 9.3 Daemon Agent | Move to new Section: "Schedules." Daemon is a schedule, not an agent type. |
+| `POST /agents/:name/spawn` | Split into `POST /agents/:name/chat` and `POST /agents/:name/task` |
+| `POST /tasks` with `{ agent }` | Keep, but also support `/agents/:name/task` as sugar |
+| `/daemons/*` endpoints | Replace with `/schedules/*` endpoints |
+| `heartbeat` in settings.json | Move to `schedules` block in settings.json |
+| `agentType` in meta.json / task.json | Replace with `invocationMode: "chat" \| "task"` |
+| HEARTBEAT.md "daemon agents only" | HEARTBEAT.md = optional file, injected by schedule when `heartbeat: true` |
+
+---
+
+## Final Verdict
+
+**Chat and Task are invocation modes. Daemon is a schedule. Agent is just agent.**
+
+This decomposition is cleaner, more composable, and already implied by your existing spec's behavior (daemons responding to chat calls, tasks spawning sessions). It eliminates a false taxonomy and replaces it with orthogonal concepts that combine freely.