agentlings 0.2.0__tar.gz → 0.2.2__tar.gz

agentlings-0.2.2/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

{agentlings-0.2.0/.claude/worktrees/agent-af4d7e32 → agentlings-0.2.2}/.gitignore

@@ -10,3 +10,5 @@ build/
 .pytest_cache/
 .venv/
 venv/
+.idea/
+.DS_Store

{agentlings-0.2.0 → agentlings-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlings
-Version: 0.2.0
+Version: 0.2.2
 Summary: Lightweight A2A + MCP single-process agent framework
 Project-URL: Homepage, https://github.com/andyjmorgan/DonkeyWork-Agentlings
 Project-URL: Repository, https://github.com/andyjmorgan/DonkeyWork-Agentlings
@@ -52,33 +52,77 @@ Description-Content-Type: text/markdown
 
 Each agentling is a small, focused AI agent whose identity is defined by a YAML config file — name, description, system prompt, tools, and skills. The framework handles protocol compliance, conversation journaling, and context management. The LLM is the agent; the framework records and replays.
 
+## Install
+
+```bash
+pip install agentlings
+# or, isolated in a managed venv:
+uv tool install agentlings
+```
+
 ## Quick start
 
 ```bash
-pip install -e ".[dev]"
+# Scaffold a new agent in ./my-agent/
+agentling init my-agent
+cd my-agent
 
-# Create your agent definition
-cp agent.example.yaml agent.yaml
+# Add your Anthropic key (or leave blank to point at Ollama via ANTHROPIC_BASE_URL)
+$EDITOR .env
 
-# Run with mock LLM (no API key needed)
-AGENT_CONFIG=./agent.yaml AGENT_LLM_BACKEND=mock AGENT_API_KEY=dev agentling
+# Run from the agent dir
+agentling run
+```
 
-# Run with Anthropic
-AGENT_CONFIG=./agent.yaml ANTHROPIC_API_KEY=sk-ant-... AGENT_API_KEY=your-key agentling
+`agentling init` produces a self-contained directory:
 
-# See available tools
-agentling --list-tools
+```
+my-agent/
+├── agent.yaml           # identity, system prompt, tools, sleep config
+├── .env                 # AGENT_API_KEY auto-generated; ANTHROPIC_API_KEY blank for you
+├── .env.example         # checked into source control as a template
+├── .framework-version   # the framework version that scaffolded this dir
+└── data/                # journals, memory, conversations
+    └── .migrations      # applied-migrations log
 ```
 
-The agent serves:
+`agentling run` reads `agent.yaml`, `.env`, and `data/` from the current directory. To operate on a different dir without `cd`-ing in: `agentling run --dir /path/to/agent`.
+
+Bumping the framework version preserves your data — `pip install --upgrade agentlings && agentling upgrade` runs any pending data migrations against `data/` without touching `agent.yaml` or `.env`.
+
+The running agent serves:
 - `GET /.well-known/agent-card.json` — A2A Agent Card (public, no auth)
 - `POST /a2a` — A2A JSON-RPC endpoint
 - `POST /mcp` — MCP Streamable HTTP endpoint
 
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `agentling init <name>` | Scaffold a new agent directory from a bundled template |
+| `agentling run [--dir]` | Run the agent server from CWD or the given directory |
+| `agentling upgrade [--dir]` | Apply pending data migrations after upgrading the framework |
+| `agentling memory show` | Print the long-term memory store for the agent in CWD |
+| `agentling sleep [--date]` | Run a one-off sleep cycle |
+| `agentling list-tools` | List available tools and groups |
+
 ## Running as a daemon
 
+The framework deliberately stays out of service-management — `agentling run` is just a long-running foreground process that reads `agent.yaml`, `.env`, and `data/` from its working directory. Wire it into whatever supervisor you already use.
+
 ### systemd (Linux)
 
+Set up the agent dir once:
+
+```bash
+sudo useradd -r -s /bin/false agentling
+sudo mkdir -p /opt/agentling && sudo chown agentling: /opt/agentling
+sudo -u agentling python3 -m venv /opt/agentling/venv
+sudo -u agentling /opt/agentling/venv/bin/pip install agentlings
+sudo -u agentling /opt/agentling/venv/bin/agentling init . --dir /opt/agentling --force
+sudo $EDITOR /opt/agentling/.env   # add ANTHROPIC_API_KEY
+```
+
 Create `/etc/systemd/system/agentling.service`:
 
 ```ini
@@ -90,8 +134,7 @@ After=network.target
 Type=simple
 User=agentling
 WorkingDirectory=/opt/agentling
-EnvironmentFile=/opt/agentling/.env
-ExecStart=/opt/agentling/venv/bin/agentling
+ExecStart=/opt/agentling/venv/bin/agentling run
 Restart=on-failure
 RestartSec=5
 
@@ -100,25 +143,16 @@ WantedBy=multi-user.target
 ```
 
 ```bash
-# Set up
-sudo useradd -r -s /bin/false agentling
-sudo mkdir -p /opt/agentling
-sudo python3 -m venv /opt/agentling/venv
-sudo /opt/agentling/venv/bin/pip install agentlings
-
-# Copy your config
-sudo cp agent.yaml /opt/agentling/agent.yaml
-sudo cp .env /opt/agentling/.env    # ANTHROPIC_API_KEY, AGENT_API_KEY, AGENT_CONFIG=./agent.yaml
-
-# Start
 sudo systemctl daemon-reload
 sudo systemctl enable --now agentling
 sudo journalctl -u agentling -f
 ```
 
+To upgrade: `sudo -u agentling /opt/agentling/venv/bin/pip install --upgrade agentlings && sudo -u agentling /opt/agentling/venv/bin/agentling upgrade --dir /opt/agentling && sudo systemctl restart agentling`.
+
 ### launchd (macOS)
 
-Create `~/Library/LaunchAgents/com.donkeywork.agentling.plist`:
+Set up the agent dir once with `agentling init ~/.agentlings/my-agent`, then create `~/Library/LaunchAgents/com.donkeywork.agentling.plist`:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -130,18 +164,10 @@ Create `~/Library/LaunchAgents/com.donkeywork.agentling.plist`:
     <key>ProgramArguments</key>
     <array>
         <string>/path/to/venv/bin/agentling</string>
+        <string>run</string>
     </array>
     <key>WorkingDirectory</key>
-    <string>/path/to/agentling</string>
-    <key>EnvironmentVariables</key>
-    <dict>
-        <key>AGENT_CONFIG</key>
-        <string>./agent.yaml</string>
-        <key>ANTHROPIC_API_KEY</key>
-        <string>sk-ant-...</string>
-        <key>AGENT_API_KEY</key>
-        <string>your-key</string>
-    </dict>
+    <string>/Users/you/.agentlings/my-agent</string>
     <key>KeepAlive</key>
     <true/>
     <key>StandardErrorPath</key>
@@ -200,18 +226,32 @@ Tools are off by default. Run `agentling --list-tools` for details.
 
 ## Docker
 
+The simplest containerised setup uses the same `init` + `run` flow:
+
+```dockerfile
+FROM python:3.12-slim
+WORKDIR /agent
+RUN pip install agentlings
+RUN agentling init . --api-key dev
+VOLUME ["/agent/data"]
+EXPOSE 8420
+CMD ["agentling", "run"]
+```
+
 ```bash
 docker build -t agentling:latest .
-docker run -e AGENT_API_KEY=your-key -e AGENT_LLM_BACKEND=mock -p 8420:8420 agentling
+docker run -e ANTHROPIC_API_KEY=sk-ant-... -p 8420:8420 -v ./data:/agent/data agentling:latest
 ```
 
+For production, mount your own `agent.yaml` and `.env` over the scaffolded ones (or skip the `agentling init` build step entirely and bind-mount a host directory with everything pre-populated).
+
 ## Environment variables
 
-Secrets and runtime settings stay in env vars (or `.env` file):
+Secrets and runtime settings stay in env vars or, more commonly, the `.env` file inside the agent directory. `agentling init` creates an `.env` with `AGENT_API_KEY` already populated; everything else is opt-in.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `AGENT_CONFIG` | — | Path to agent YAML definition |
+| `AGENT_CONFIG` | `./agent.yaml` (when present) | Path to agent YAML definition |
 | `ANTHROPIC_API_KEY` | — | Anthropic API key (required for api.anthropic.com; optional with `ANTHROPIC_BASE_URL` pointed at e.g. Ollama) |
 | `ANTHROPIC_BASE_URL` | — | Override the Messages endpoint. Use `http://localhost:11434` to target Ollama's Anthropic-compatible API |
 | `AGENT_API_KEY` | — | API key for authenticating clients |

{agentlings-0.2.0 → agentlings-0.2.2}/README.md

@@ -14,33 +14,77 @@
 
 Each agentling is a small, focused AI agent whose identity is defined by a YAML config file — name, description, system prompt, tools, and skills. The framework handles protocol compliance, conversation journaling, and context management. The LLM is the agent; the framework records and replays.
 
+## Install
+
+```bash
+pip install agentlings
+# or, isolated in a managed venv:
+uv tool install agentlings
+```
+
 ## Quick start
 
 ```bash
-pip install -e ".[dev]"
+# Scaffold a new agent in ./my-agent/
+agentling init my-agent
+cd my-agent
 
-# Create your agent definition
-cp agent.example.yaml agent.yaml
+# Add your Anthropic key (or leave blank to point at Ollama via ANTHROPIC_BASE_URL)
+$EDITOR .env
 
-# Run with mock LLM (no API key needed)
-AGENT_CONFIG=./agent.yaml AGENT_LLM_BACKEND=mock AGENT_API_KEY=dev agentling
+# Run from the agent dir
+agentling run
+```
 
-# Run with Anthropic
-AGENT_CONFIG=./agent.yaml ANTHROPIC_API_KEY=sk-ant-... AGENT_API_KEY=your-key agentling
+`agentling init` produces a self-contained directory:
 
-# See available tools
-agentling --list-tools
+```
+my-agent/
+├── agent.yaml           # identity, system prompt, tools, sleep config
+├── .env                 # AGENT_API_KEY auto-generated; ANTHROPIC_API_KEY blank for you
+├── .env.example         # checked into source control as a template
+├── .framework-version   # the framework version that scaffolded this dir
+└── data/                # journals, memory, conversations
+    └── .migrations      # applied-migrations log
 ```
 
-The agent serves:
+`agentling run` reads `agent.yaml`, `.env`, and `data/` from the current directory. To operate on a different dir without `cd`-ing in: `agentling run --dir /path/to/agent`.
+
+Bumping the framework version preserves your data — `pip install --upgrade agentlings && agentling upgrade` runs any pending data migrations against `data/` without touching `agent.yaml` or `.env`.
+
+The running agent serves:
 - `GET /.well-known/agent-card.json` — A2A Agent Card (public, no auth)
 - `POST /a2a` — A2A JSON-RPC endpoint
 - `POST /mcp` — MCP Streamable HTTP endpoint
 
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `agentling init <name>` | Scaffold a new agent directory from a bundled template |
+| `agentling run [--dir]` | Run the agent server from CWD or the given directory |
+| `agentling upgrade [--dir]` | Apply pending data migrations after upgrading the framework |
+| `agentling memory show` | Print the long-term memory store for the agent in CWD |
+| `agentling sleep [--date]` | Run a one-off sleep cycle |
+| `agentling list-tools` | List available tools and groups |
+
 ## Running as a daemon
 
+The framework deliberately stays out of service-management — `agentling run` is just a long-running foreground process that reads `agent.yaml`, `.env`, and `data/` from its working directory. Wire it into whatever supervisor you already use.
+
 ### systemd (Linux)
 
+Set up the agent dir once:
+
+```bash
+sudo useradd -r -s /bin/false agentling
+sudo mkdir -p /opt/agentling && sudo chown agentling: /opt/agentling
+sudo -u agentling python3 -m venv /opt/agentling/venv
+sudo -u agentling /opt/agentling/venv/bin/pip install agentlings
+sudo -u agentling /opt/agentling/venv/bin/agentling init . --dir /opt/agentling --force
+sudo $EDITOR /opt/agentling/.env   # add ANTHROPIC_API_KEY
+```
+
 Create `/etc/systemd/system/agentling.service`:
 
 ```ini
@@ -52,8 +96,7 @@ After=network.target
 Type=simple
 User=agentling
 WorkingDirectory=/opt/agentling
-EnvironmentFile=/opt/agentling/.env
-ExecStart=/opt/agentling/venv/bin/agentling
+ExecStart=/opt/agentling/venv/bin/agentling run
 Restart=on-failure
 RestartSec=5
 
@@ -62,25 +105,16 @@ WantedBy=multi-user.target
 ```
 
 ```bash
-# Set up
-sudo useradd -r -s /bin/false agentling
-sudo mkdir -p /opt/agentling
-sudo python3 -m venv /opt/agentling/venv
-sudo /opt/agentling/venv/bin/pip install agentlings
-
-# Copy your config
-sudo cp agent.yaml /opt/agentling/agent.yaml
-sudo cp .env /opt/agentling/.env    # ANTHROPIC_API_KEY, AGENT_API_KEY, AGENT_CONFIG=./agent.yaml
-
-# Start
 sudo systemctl daemon-reload
 sudo systemctl enable --now agentling
 sudo journalctl -u agentling -f
 ```
 
+To upgrade: `sudo -u agentling /opt/agentling/venv/bin/pip install --upgrade agentlings && sudo -u agentling /opt/agentling/venv/bin/agentling upgrade --dir /opt/agentling && sudo systemctl restart agentling`.
+
 ### launchd (macOS)
 
-Create `~/Library/LaunchAgents/com.donkeywork.agentling.plist`:
+Set up the agent dir once with `agentling init ~/.agentlings/my-agent`, then create `~/Library/LaunchAgents/com.donkeywork.agentling.plist`:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -92,18 +126,10 @@ Create `~/Library/LaunchAgents/com.donkeywork.agentling.plist`:
     <key>ProgramArguments</key>
     <array>
         <string>/path/to/venv/bin/agentling</string>
+        <string>run</string>
     </array>
     <key>WorkingDirectory</key>
-    <string>/path/to/agentling</string>
-    <key>EnvironmentVariables</key>
-    <dict>
-        <key>AGENT_CONFIG</key>
-        <string>./agent.yaml</string>
-        <key>ANTHROPIC_API_KEY</key>
-        <string>sk-ant-...</string>
-        <key>AGENT_API_KEY</key>
-        <string>your-key</string>
-    </dict>
+    <string>/Users/you/.agentlings/my-agent</string>
     <key>KeepAlive</key>
     <true/>
     <key>StandardErrorPath</key>
@@ -162,18 +188,32 @@ Tools are off by default. Run `agentling --list-tools` for details.
 
 ## Docker
 
+The simplest containerised setup uses the same `init` + `run` flow:
+
+```dockerfile
+FROM python:3.12-slim
+WORKDIR /agent
+RUN pip install agentlings
+RUN agentling init . --api-key dev
+VOLUME ["/agent/data"]
+EXPOSE 8420
+CMD ["agentling", "run"]
+```
+
 ```bash
 docker build -t agentling:latest .
-docker run -e AGENT_API_KEY=your-key -e AGENT_LLM_BACKEND=mock -p 8420:8420 agentling
+docker run -e ANTHROPIC_API_KEY=sk-ant-... -p 8420:8420 -v ./data:/agent/data agentling:latest
 ```
 
+For production, mount your own `agent.yaml` and `.env` over the scaffolded ones (or skip the `agentling init` build step entirely and bind-mount a host directory with everything pre-populated).
+
 ## Environment variables
 
-Secrets and runtime settings stay in env vars (or `.env` file):
+Secrets and runtime settings stay in env vars or, more commonly, the `.env` file inside the agent directory. `agentling init` creates an `.env` with `AGENT_API_KEY` already populated; everything else is opt-in.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `AGENT_CONFIG` | — | Path to agent YAML definition |
+| `AGENT_CONFIG` | `./agent.yaml` (when present) | Path to agent YAML definition |
 | `ANTHROPIC_API_KEY` | — | Anthropic API key (required for api.anthropic.com; optional with `ANTHROPIC_BASE_URL` pointed at e.g. Ollama) |
 | `ANTHROPIC_BASE_URL` | — | Override the Messages endpoint. Use `http://localhost:11434` to target Ollama's Anthropic-compatible API |
 | `AGENT_API_KEY` | — | API key for authenticating clients |

{agentlings-0.2.0 → agentlings-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentlings"
-version = "0.2.0"
+version = "0.2.2"
 description = "Lightweight A2A + MCP single-process agent framework"
 readme = "README.md"
 license = { text = "MIT" }

{agentlings-0.2.0 → agentlings-0.2.2}/src/agentlings/protocol/a2a_task_store.py

@@ -18,6 +18,7 @@ from typing import Any
 from a2a.server.context import ServerCallContext
 from a2a.server.tasks.task_store import TaskStore
 from a2a.types import (
+    Artifact,
     ListTasksRequest,
     ListTasksResponse,
     Message,
@@ -50,11 +51,12 @@ _STATE_MAP: dict[TaskStatus, int] = {
 def task_state_to_a2a_task(state: TaskState) -> Task:
     """Render an engine ``TaskState`` as an A2A ``Task`` for the wire.
 
-    Completed tasks carry their final assistant message in ``history`` so
-    ``GetTask`` responses are self-contained — the client doesn't need a
-    separate call to retrieve the result.
+    Completed tasks carry their final assistant message in both ``artifacts``
+    (per the A2A spec, which says results SHOULD be returned via Artifacts)
+    and ``history`` (kept for backward compatibility with existing clients).
     """
     history: list[Message] = []
+    artifacts: list[Artifact] = []
     if state.status == TaskStatus.COMPLETED and state.content:
         text = _extract_text(state.content)
         if text:
@@ -67,6 +69,12 @@ def task_state_to_a2a_task(state: TaskState) -> Task:
                     message_id=f"{state.task_id}-final",
                 )
             )
+            artifacts.append(
+                Artifact(
+                    artifact_id=f"{state.task_id}-result",
+                    parts=[Part(text=text)],
+                )
+            )
 
     status_kwargs: dict[str, Any] = {"state": _STATE_MAP[state.status]}
     if state.error and state.status in (TaskStatus.FAILED, TaskStatus.CANCELLED):
@@ -82,6 +90,7 @@ def task_state_to_a2a_task(state: TaskState) -> Task:
         id=state.task_id,
         context_id=state.context_id,
         status=A2ATaskStatus(**status_kwargs),
+        artifacts=artifacts,
         history=history,
     )
 

agentlings-0.2.2/src/agentlings/templates/default/agent.yaml

@@ -0,0 +1,41 @@
+name: {{NAME}}
+description: A lightweight AI agent
+
+system_prompt: |
+  You are {{NAME}}, a lightweight AI agent.
+
+  Use the tools available to you to accomplish tasks. When a tool returns
+  output, incorporate it into your response. Be concise. Use code blocks for
+  command output. Respond in plain text unless the user asks for a specific
+  format.
+
+  You operate under strict time constraints — every request has a limited
+  execution window. Follow these rules:
+  1. PLAN FIRST: Before touching any tool, state what you will do and roughly
+     how many steps it requires. If more than a few tool calls are needed,
+     say so upfront.
+  2. STAY FOCUSED: Do exactly what was asked. Do not explore, refactor, or
+     improve things that were not requested.
+  3. DELIVER INCREMENTALLY: After each meaningful step, summarize what you
+     completed and what remains. If the remaining work is non-trivial, ask
+     whether to continue rather than pressing on silently.
+  4. PREFER COMPLETE OVER AMBITIOUS: A small, finished result is better than
+     a large, half-done one. If the request is too broad to finish, do the
+     most valuable slice and report what is left.
+  5. CLARIFY EARLY: If the request is ambiguous, ask before acting — do not
+     guess and waste cycles.
+
+  Edit or remove these rules to taste — they are operator-owned, not
+  framework-imposed.
+
+tools: []
+
+skills: []
+
+memory:
+  token_budget: 2000
+  inject_into_prompt: true
+
+sleep:
+  enabled: true
+  schedule: "0 2 * * *"

{agentlings-0.2.0 → agentlings-0.2.2}/tests/unit/test_a2a_task_store.py

@@ -49,6 +49,22 @@ class TestTaskStateTranslation:
         # Part carries text directly (no nested TextPart wrapper in 1.0).
         assert msg.parts[0].text == "the final answer"
 
+    def test_completed_artifacts_contain_final_response(self) -> None:
+        """A2A spec: results SHOULD be returned via Artifacts on the Task."""
+        state = TaskState(
+            task_id="t1",
+            context_id="c1",
+            status=TaskStatus.COMPLETED,
+            content=[{"type": "text", "text": "the final answer"}],
+        )
+        a2a_task = task_state_to_a2a_task(state)
+        assert len(a2a_task.artifacts) == 1
+        artifact = a2a_task.artifacts[0]
+        assert artifact.artifact_id == "t1-result"
+        assert artifact.parts[0].text == "the final answer"
+        # History remains populated for backward compatibility.
+        assert len(a2a_task.history) == 1
+
     def test_working_maps_to_working(self) -> None:
         state = TaskState(
             task_id="t1",

agentlings-0.2.0/.claude/worktrees/agent-ac15d433/.git

@@ -1 +0,0 @@
-gitdir: /Users/andrewmorgan/Personal/source/DonkeyWork-Agentlings/.git/worktrees/agent-ac15d433

agentlings-0.2.0/.claude/worktrees/agent-ac15d433/.gitignore

@@ -1,12 +0,0 @@
-data/
-.env
-__pycache__/
-*.py[cod]
-*.egg-info/
-dist/
-build/
-.eggs/
-*.egg
-.pytest_cache/
-.venv/
-venv/

agentlings-0.2.0/.claude/worktrees/agent-ac15d433/CLAUDE.md

@@ -1,128 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project
-
-Agentlings — a lightweight single-process Python framework for running AI agents that expose both A2A (Agent-to-Agent Protocol v1.0) and MCP (Model Context Protocol) on a single HTTP port. Each agentling is a small, focused agent whose identity is defined by configuration (name, description, system prompt, tools), not code.
-
-## Architecture
-
-Two protocol interfaces (A2A JSON-RPC at `/a2a`, MCP Streamable HTTP at `/mcp`) feed into a shared **task engine**. Every request becomes a task with its own sub-journal; the HTTP handler awaits up to `AGENT_TASK_AWAIT_SECONDS` (default 60) and either returns the final result inline (fast path) or yields a task handle the caller polls (slow path). FIFO ordering is preserved per context — only one task can run per context at a time, so concurrent requests are rejected with `context_busy` for the LLM to retry.
-
-Data layout:
-
-- Parent journal: `{data_dir}/{contextId}/journal.jsonl` (conversation history)
-- Sub-journal:    `{data_dir}/{contextId}/tasks/{taskId}.jsonl` (task execution trace)
-- Legacy `{data_dir}/{contextId}.jsonl` files are auto-migrated on first access.
-
-Package structure under `src/agentlings/`:
-- `config.py` — Pydantic BaseSettings, all config via env vars + `.env`
-- `log.py` — console-first logging setup
-- `server.py` — Starlette app wiring A2A + MCP routes, API key middleware, startup crash-recovery
-- `core/` — task engine
-  - `task.py` — `TaskEngine`, `TaskRegistry`, `TaskWorker`, merge-back, crash recovery
-  - `loop.py` — synchronous facade over `TaskEngine` for legacy callers
-  - `llm.py` — LLM client abstraction (Anthropic + mock backends)
-  - `store.py` — JSONL append/replay with compaction cursor + `TaskJournal` (sub-journal)
-  - `models.py` — journal entry types (messages, compaction, task markers, merge wrappers)
-  - `prompt.py` — system prompt builder
-  - `completion.py` — shared LLM completion cycle with per-turn callback + cancellation
-- `protocol/` — protocol adapters
-  - `a2a.py` — `AgentlingExecutor` bridging A2A SDK to the task engine
-  - `mcp.py` — MCP server exposing a single task-aware tool
-  - `agent_card.py` — Agent Card generation from config
-- `tools/` — pluggable tool system
-  - `registry.py` — `ToolRegistry` with group-based registration
-  - `builtins.py` — bash and filesystem tool implementations
-
-The Agent Card at `/.well-known/agent.json` is the single source of truth — the MCP tool schema is derived from it.
-
-### Task engine lifecycle
-
-1. **Ingress**: `engine.spawn(message, contextId?)` atomically admits one task per context, writes a `TaskDispatched` audit marker to the parent journal, creates a sub-journal with `TaskStarted`, and spawns a worker.
-2. **Execution**: the worker snapshots the parent journal (replay from latest compaction cursor), runs the LLM loop via `compact_20260112`, writes each turn to the sub-journal.
-3. **Merge-back (success)**: under the per-context lock, the engine atomically writes `MergeStarted` → user message → latest sub-journal compaction (if any) → assistant final response → `MergeCommitted` to the parent journal.
-4. **Cancel/fail**: only a `TaskCancelled` or `TaskFailed` audit marker lands on the parent. No conversational content leaks.
-5. **Replay**: audit markers (`task_dispatch`, `task_cancel`, `task_fail`, `merge_start`, `merge_commit`) are stripped by the store's `replay()` — they never reach the LLM.
-6. **Crash recovery**: on startup, orphaned sub-journals get `TaskFailed { reason: "process_crash_recovery" }` and partial merge-backs are completed idempotently.
-
-## Commands
-
-```bash
-# Install in dev mode
-pip install -e ".[dev]"
-
-# Run the agent
-agentling
-
-# Run with overrides
-AGENT_NAME="my-agent" AGENT_PORT=9000 agentling
-
-# Build container
-docker build -t agentling:latest .
-
-# Run container
-docker run -e ANTHROPIC_API_KEY=... -e AGENT_API_KEY=... -v ./data:/data -p 8420:8420 agentling:latest
-```
-
-## Configuration
-
-All via environment variables (loaded from `.env` via python-dotenv):
-- `ANTHROPIC_API_KEY` (required)
-- `AGENT_API_KEY` (required) — checked via `X-API-Key` header
-- `AGENT_MODEL` (default `claude-sonnet-4-6`)
-- `AGENT_MAX_TOKENS` (default `4096`)
-- `AGENT_HOST` / `AGENT_PORT` (default `0.0.0.0:8420`)
-- `AGENT_DATA_DIR` (default `./data`) — JSONL journal storage
-- `AGENT_NAME` / `AGENT_DESCRIPTION` — identity for Agent Card + MCP tool
-- `AGENT_SYSTEM_PROMPT_FILE` — optional path to override default system prompt
-- `AGENT_LOG_LEVEL` (default `INFO`)
-- `AGENT_TASK_AWAIT_SECONDS` (default `60`) — HTTP handler await timeout before yielding a task handle to the caller
-
-## Logging
-
-Console-only, format: `datetime - level - path - message`. All modules use `logging.getLogger(__name__)`. No third-party logging libraries.
-
-## Design Constraints
-
-- **Task-enabled, message-shape.** Every request becomes a task with its own sub-journal. Protocol surfaces expose task handles for long-running work, but A2A/MCP interactions are still carried as messages — no artifacts, no push notifications, no streaming.
-- **One task per context.** FIFO is architectural, not configurable. Concurrent requests to a busy context are rejected with `context_busy`; the LLM retries.
-- **Parent journal records only successful completions.** Cancel/fail leave only audit markers, never conversational content. Replay strips audit markers unconditionally.
-- **contextId is the conversation handle; taskId is the execution handle.** ContextId maps to a directory; taskId is UUID4 and path-bound via `{contextId}/tasks/{taskId}.jsonl` — the filesystem enforces `(contextId, taskId)` pairing.
-- **Confirmation is conversation** — no `input-required` state, just natural language turns.
-- **The LLM is the agent** — the framework records and replays, it does not orchestrate.
-- **Tools are pluggable** — register at startup, errors returned to LLM as tool results (not exceptions).
-- **JSONL is append-only**, never modified or deleted; compaction markers are replay cursors, task compactions are ported to parent on merge-back.
-- **Merge-back is atomic** via `MergeStarted`/`MergeCommitted` wrappers so startup recovery can repair partial writes idempotently.
-- **MCP Session ID and contextId are independent concepts**, never cross-referenced.
-
-## Development Methodology
-
-**Write → Test → Continue.** Every piece of code gets tested before moving on.
-
-- Bug workflow: write a failing test that reproduces the bug → verify it fails → fix the code → verify the test passes. No exceptions.
-- Each task ends with tests that prove the task works.
-- Each milestone ends with rigorous integration testing.
-- Tests run in Docker via `docker compose` — the test harness spins up the agentling container and runs an MCP client and A2A client against it.
-- Unit tests (pytest) for internal modules; integration tests for protocol-level behaviour.
-- All LLM responses are mocked — tests never call the real Anthropic API or require a real key. The agentling container in integration tests runs with a mock LLM backend.
-
-```bash
-# Run unit tests
-pytest tests/unit/
-
-# Run integration tests (builds + runs container)
-docker compose -f docker-compose.test.yml up --build --abort-on-container-exit
-
-# Run all tests
-pytest tests/unit/ && docker compose -f docker-compose.test.yml up --build --abort-on-container-exit
-```
-
-## Dependencies
-
-- `anthropic` — LLM backend with `compact_20260112`
-- `starlette` + `uvicorn` — HTTP server
-- `pydantic` — config and models
-- `mcp` — MCP SDK (Streamable HTTP)
-- `python-dotenv` — env file loading