@aman_asmuei/aman-agent 0.30.0 → 0.31.0-next.0

package/README.md

@@ -8,7 +8,8 @@
 <h1 align="center">aman-agent</h1>
 
 <p align="center">
-  <strong>The AI companion that actually remembers you.</strong>
+  <strong>The AI companion that actually remembers you.</strong><br/>
+  <sub>Learns from every conversation. Recalls what matters. Runs locally. Works with any LLM.</sub>
 </p>
 
 <p align="center">
@@ -16,30 +17,41 @@
   &nbsp;
   <a href="https://github.com/amanasmuei/aman-agent/actions"><img src="https://img.shields.io/github/actions/workflow/status/amanasmuei/aman-agent/ci.yml?style=for-the-badge&logo=github&label=CI" alt="CI status" /></a>
   &nbsp;
+  <img src="https://img.shields.io/badge/tests-429_passing-brightgreen?style=for-the-badge&logo=vitest&logoColor=white" alt="429 tests passing" />
+  &nbsp;
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT License" /></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 20+" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/typescript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="Strict TypeScript" />
   &nbsp;
-  <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 20+" />
+  <img src="https://img.shields.io/badge/bundle-340_KB-informational?style=flat-square" alt="Bundle size: 340 KB" />
   &nbsp;
-  <a href="https://github.com/amanasmuei/aman"><img src="https://img.shields.io/badge/part_of-aman_ecosystem-ff6b35?style=for-the-badge" alt="aman ecosystem" /></a>
+  <img src="https://img.shields.io/badge/LLMs-6_providers-8a2be2?style=flat-square" alt="6 LLM providers" />
+  &nbsp;
+  <a href="https://github.com/amanasmuei/aman"><img src="https://img.shields.io/badge/part_of-aman_ecosystem-ff6b35?style=flat-square" alt="aman ecosystem" /></a>
 </p>
 
 <p align="center">
-  An AI companion that learns from every conversation, recalls relevant memories per message,<br/>
-  extracts knowledge silently, and adapts to your time of day — all running locally.
+  <img src="https://raw.githubusercontent.com/amanasmuei/aman-agent/main/docs/demo/demo.gif" alt="aman-agent demo" width="760" />
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/amanasmuei/aman-agent/main/docs/demo/demo.gif" alt="aman-agent demo" width="720" />
+  <a href="#quick-start"><kbd> Quick Start </kbd></a>
+  <a href="#architecture-at-a-glance"><kbd> Architecture </kbd></a>
+  <a href="#features"><kbd> Features </kbd></a>
+  <a href="#commands"><kbd> Commands </kbd></a>
+  <a href="#supported-llms"><kbd> LLMs </kbd></a>
+  <a href="#the-ecosystem"><kbd> Ecosystem </kbd></a>
+  <a href="#faq"><kbd> FAQ </kbd></a>
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick Start</a> &bull;
-  <a href="#features">Features</a> &bull;
-  <a href="#how-it-works">How It Works</a> &bull;
-  <a href="#commands">Commands</a> &bull;
-  <a href="#supported-llms">LLMs</a> &bull;
-  <a href="#the-ecosystem">Ecosystem</a> &bull;
-  <a href="#faq">FAQ</a>
+  <sub>
+    <b>Try it in 10 seconds →</b>&nbsp;&nbsp;<code>npx @aman_asmuei/aman-agent</code>
+  </sub>
 </p>
 
 ---
@@ -50,6 +62,7 @@
 - [What's New](#whats-new-in-v0300)
 - [The Problem](#the-problem)
 - [The Solution](#the-solution)
+- [Architecture at a Glance](#architecture-at-a-glance)
 - [Quick Start](#quick-start)
 - [Usage Guide](#usage-guide)
   - [Your First Conversation](#your-first-conversation)
@@ -64,6 +77,7 @@
   - [Profiles](#your-profile-vs-agent-profiles)
   - [Delegation](#agent-delegation)
   - [Teams](#agent-teams)
+  - [Multi-agent (A2A)](#multi-agent-a2a)
   - [Daily Workflow](#daily-workflow-summary)
 - [Features](#features)
 - [How It Works](#how-it-works)
@@ -82,15 +96,34 @@
 
 ## What's New in v0.30.0
 
-> **Agent hardening — trust, durability, and insight.**
+> **Agent hardening — trust, durability, insight.**<br/>
+> The agent now asks before delegating, persists background tasks across crashes, and ships a real analytics dashboard in `/eval report`.
 
-The agent now asks before delegating, persists background task state across crashes, and gives you a real analytics dashboard in `/eval report`.
+<table>
+<tr>
+<td width="33%" valign="top">
 
-| Feature | What it does |
-|:---|:---|
-| **Delegation confirmation** | Agent prompts you before executing `delegate_task` or `team_run` — no silent autonomous work |
-| **Persistent background tasks** | Background task state saved to `~/.aman-agent/bg-tasks.json` — survives crashes, visible in `/eval report` |
-| **Rich `/eval report`** | Shows trust score, sentiment trend, energy distribution, burnout risk, frustration correlations, and background task stats |
+**Delegation confirmation**
+
+The agent now prompts you before executing `delegate_task` or `team_run`. No more silent autonomous sub-agents — you stay in the loop on every hand-off.
+
+</td>
+<td width="33%" valign="top">
+
+**Persistent background tasks**
+
+Background task state is written to `~/.aman-agent/bg-tasks.json` on every transition — survives crashes, terminal closures, and reboots. Visible in `/eval report`.
+
+</td>
+<td width="33%" valign="top">
+
+**Rich `/eval report`**
+
+Trust score, sentiment trend, energy distribution, burnout risk, frustration correlations, and background-task stats — all in one dashboard.
+
+</td>
+</tr>
+</table>
 
 <details>
 <summary><strong>Highlights from earlier releases</strong></summary>
@@ -162,6 +195,60 @@ npx @aman_asmuei/aman-agent
 
 ---
 
+## Architecture at a Glance
+
+aman-agent is the **runtime** at the center of the aman ecosystem — 38 focused TypeScript modules that stitch together 7 portable memory/identity/skill layers with any LLM you want.
+
+```mermaid
+flowchart LR
+    User([You]) <--> CLI[aman-agent CLI<br/>chat loop]
+
+    CLI --> Agent[agent.ts<br/>message orchestration]
+    Agent --> Hooks[hooks.ts<br/>lifecycle events]
+
+    Agent -->|recall &amp; extract| Memory[(amem-core<br/>SQLite + vectors)]
+    Agent -->|who &amp; prefs| Identity[(acore-core<br/>identity)]
+    Agent -->|boundaries| Rules[(arules-core<br/>guardrails)]
+    Agent -->|auto-trigger| Skills[skill-engine<br/>+ crystallization]
+    Agent -->|telemetry| Obs[observation<br/>+ postmortem]
+
+    Agent --> LLM{LLM Router}
+    LLM --> Claude[Anthropic]
+    LLM --> GPT[OpenAI]
+    LLM --> Copilot[GH Copilot]
+    LLM --> Ollama[Ollama local]
+
+    Agent <--> MCP[MCP tools<br/>aman-mcp · amem]
+
+    classDef core fill:#58a6ff22,stroke:#58a6ff,color:#e6edf3,stroke-width:2px;
+    classDef store fill:#3fb95022,stroke:#3fb950,color:#e6edf3,stroke-width:2px;
+    classDef llm fill:#d29f2222,stroke:#d29f22,color:#e6edf3,stroke-width:1px;
+    class CLI,Agent,Hooks,Skills,Obs core
+    class Memory,Identity,Rules store
+    class Claude,GPT,Copilot,Ollama,LLM llm
+```
+
+<details>
+<summary><strong>How the pieces work together</strong></summary>
+
+| Piece | What it does | Where it lives |
+|:---|:---|:---|
+| `agent.ts` | The main event loop — reads your message, recalls memories, streams the LLM response, executes tools, extracts new memories | `src/agent.ts` (40 KB) |
+| `commands.ts` | 58+ slash commands (`/memory`, `/skills`, `/plan`, `/delegate`, `/eval`, `/observe`, `/postmortem`, …) | `src/commands.ts` (98 KB) |
+| `hooks.ts` | 5 lifecycle hooks that fire at startup, before/after tools, on workflow match, on session end | `src/hooks.ts` (26 KB) |
+| `memory.ts` + `memory-extractor.ts` | Per-message recall and silent, non-blocking extraction of preferences, decisions, patterns, corrections | delegates to `@aman_asmuei/amem-core@0.5` |
+| `skill-engine.ts` + `crystallization.ts` | Auto-triggers domain skills from context; promotes post-mortem lessons into reusable, versioned skills | `src/skill-engine.ts`, `src/crystallization.ts` |
+| `user-model.ts` + `personality.ts` | Cross-session trust (EMA), sentiment baseline, burnout risk, time-of-day tone shifts, wellbeing nudges | `src/user-model.ts`, `src/personality.ts` |
+| `observation.ts` + `postmortem.ts` | Passive session telemetry + LLM-generated structured post-mortems on session end | `src/observation.ts`, `src/postmortem.ts` |
+| `llm/` | 6 pluggable providers — Anthropic, OpenAI, Ollama, GitHub Copilot, OpenAI-compatible, Claude Code CLI | `src/llm/` |
+| `mcp/` | MCP v1.27 client with stdio transport and auto-reconnect | `src/mcp/` |
+
+**Stateless by default.** All state lives in `~/.acore`, `~/.arules`, `~/.aflow`, `~/.askill`, `~/.aeval`, and `~/.amem` — portable, inspectable markdown + a local SQLite file. Nothing leaves your machine except what you send to your chosen LLM.
+
+</details>
+
+---
+
 ## Quick Start
 
 ### 1. Run
@@ -691,6 +778,62 @@ The AI auto-suggests teams when appropriate — always asks permission first.
 
 </details>
 
+<details>
+<summary><strong>Multi-agent (A2A)</strong> (new in v0.31)</summary>
+
+### Multi-agent (A2A)
+
+Run aman-agent as a local MCP server so other aman-agent instances — on the same machine — can delegate tasks to it via the `@name` syntax. No new protocol, no new daemon, no broker — just MCP over localhost using the existing `@modelcontextprotocol/sdk` bits.
+
+**Start a specialist agent in server mode:**
+
+```bash
+aman-agent serve --name coder --profile coder
+  ✓ Ecosystem loaded
+  ✓ registered as @coder
+  ✓ port 52341 (127.0.0.1) — token is in ~/.aman-agent/registry.json
+```
+
+Leave it running. The process binds an ephemeral localhost port and writes its `{name, pid, port, token}` into `~/.aman-agent/registry.json` (mode `0600`). On `SIGINT`/`SIGTERM` it cleans up the registry entry.
+
+**From another aman-agent instance, delegate to it:**
+
+```
+You > /agents list
+
+  Running agents:
+    @coder         coder         pid=4512   port=52341  up 34s
+
+You > /delegate @coder Refactor src/auth.ts to use async/await
+
+  [delegating to @coder...]
+  ✓ @coder completed in 12.4s
+  ...
+```
+
+**Commands:**
+
+| Command | What it does |
+|:---|:---|
+| `aman-agent serve --name X --profile Y` | Run as a local A2A server |
+| `/agents list` | Show running agents on this machine |
+| `/agents info <name>` | Call `agent.info` MCP tool on the named agent |
+| `/agents ping <name>` | Bearer-authed `/health` latency check |
+| `/delegate @<name> <task>` | Delegate via MCP to another running agent |
+
+**How it works:** Each `serve` process binds an ephemeral localhost port, mounts an MCP `StreamableHTTPServerTransport`, and writes its `{name, profile, pid, port, token}` into `~/.aman-agent/registry.json` (mode `0600`). The calling agent looks up the target in the registry, dials via `StreamableHTTPClientTransport` with the bearer token, and invokes the `agent.delegate` MCP tool. Three tools are exposed on every `serve` instance: `agent.info`, `agent.delegate`, `agent.send`.
+
+**Trust model:** Same-user, same-machine. OS file permissions on `~/.aman-agent/registry.json` are the trust boundary — if you can read the registry, you know the tokens. Cross-machine A2A is a future addition; it will need explicit auth and is out of scope for v0.31.
+
+**Known limitations (v0.31):**
+
+- **Event-loop leak on `delegateRemote`** — the MCP SDK's `StreamableHTTPClientTransport` keeps an internal resource alive after `close()` / `terminateSession()`, so a Node script that calls `delegateTask("@name", ...)` and expects clean exit must call `process.exit(0)` explicitly. The interactive REPL is unaffected (it exits via `/quit`). Follow-up investigation planned.
+- **No cross-machine A2A** — registry is a local JSON file; LAN/remote agents not supported yet.
+- **`agent.send` is in-memory only** — messages are lost if the target agent crashes before draining them.
+- **No proactive push to humans** — delivering a message to Telegram/Discord/etc. is `achannel`'s job, not aman-agent's.
+
+</details>
+
 <details>
 <summary><strong>Session Telemetry & Post-Mortems</strong> (new in v0.24)</summary>
 
@@ -987,59 +1130,92 @@ On session end, if any smart trigger fires (≥3 tool errors, ≥2 blockers, &gt
 
 ## How It Works
 
+### Per-message flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant U as You
+    participant A as aman-agent
+    participant M as amem (memory)
+    participant L as LLM
+    participant T as MCP tools
+
+    U->>A: your message
+    A->>M: semantic recall (top 5)
+    M-->>A: compact index (~50–100 tok)
+    A->>A: build prompt: identity + rules + skills + memories
+    A->>L: stream request
+    L-->>A: response + tool calls
+    par parallel execution
+        A->>T: tool call 1 (guardrail-checked)
+    and
+        A->>T: tool call 2 (guardrail-checked)
+    end
+    T-->>A: results
+    A-->>U: streamed response
+    A->>M: extract memories (non-blocking)
+    A->>A: update user model + sentiment + skills
+```
+
+<details>
+<summary><strong>ASCII version (for terminals / no-Mermaid viewers)</strong></summary>
+
 ```
 ┌───────────────────────────────────────────────────────────┐
 │                    Your Terminal                          │
-│                                                          │
-│   You > tell me about our auth decisions                 │
-│                                                          │
-│   [recalling memories...]                                │
-│   Agent > Based on your previous decisions:              │
-│   - OAuth2 with PKCE (decided 2 weeks ago)               │
-│   - JWT for API tokens...                                │
-│                                                          │
-│   [1 memory stored]                                      │
+│                                                           │
+│   You > tell me about our auth decisions                  │
+│                                                           │
+│   [recalling memories...]                                 │
+│   Agent > Based on your previous decisions:               │
+│   - OAuth2 with PKCE (decided 2 weeks ago)                │
+│   - JWT for API tokens...                                 │
+│                                                           │
+│   [1 memory stored]                                       │
 └──────────────────────┬────────────────────────────────────┘
                        │
 ┌──────────────────────▼────────────────────────────────────┐
-│              aman-agent runtime                          │
-│                                                          │
-│   On Startup                                             │
-│   ┌────────────────────────────────────────────────┐     │
-│   │ 1. Load ecosystem (identity, tools, rules...)  │     │
-│   │ 2. Connect MCP servers (aman-mcp + amem)       │     │
-│   │ 3. Consolidate memory (merge/prune/promote)    │     │
-│   │ 4. Check reminders (overdue/today/upcoming)    │     │
-│   │ 5. Inject time context (morning/evening/...)   │     │
-│   │ 6. Recall session context from memory          │     │
-│   └────────────────────────────────────────────────┘     │
-│                                                          │
-│   Per Message                                            │
-│   ┌────────────────────────────────────────────────┐     │
-│   │ 1. Semantic memory recall (top 5 relevant)     │     │
-│   │ 2. Augment system prompt with memories         │     │
-│   │ 3. Stream LLM response (with retry)            │     │
-│   │ 4. Execute tools in parallel (with guardrails) │     │
-│   │ 5. Extract memories from response              │     │
-│   │    - Auto-store: preferences, facts, patterns  │     │
-│   │    - All types auto-stored silently             │     │
-│   └────────────────────────────────────────────────┘     │
-│                                                          │
-│   Context Management                                     │
-│   ┌────────────────────────────────────────────────┐     │
-│   │ Auto-trim at 80K tokens                        │     │
-│   │ LLM-powered summarization (not truncation)     │     │
-│   │ Fallback to text preview if LLM call fails     │     │
-│   └────────────────────────────────────────────────┘     │
-│                                                          │
-│   MCP Integration                                        │
-│   ┌────────────────────────────────────────────────┐     │
-│   │ aman-mcp  →  identity, tools, workflows, eval  │     │
-│   │ amem      →  memory, knowledge graph, reminders │     │
-│   └────────────────────────────────────────────────┘     │
+│              aman-agent runtime                           │
+│                                                           │
+│   On Startup                                              │
+│   ┌────────────────────────────────────────────────┐      │
+│   │ 1. Load ecosystem (identity, tools, rules...)  │      │
+│   │ 2. Connect MCP servers (aman-mcp + amem)       │      │
+│   │ 3. Consolidate memory (merge/prune/promote)    │      │
+│   │ 4. Check reminders (overdue/today/upcoming)    │      │
+│   │ 5. Inject time context (morning/evening/...)   │      │
+│   │ 6. Recall session context from memory          │      │
+│   └────────────────────────────────────────────────┘      │
+│                                                           │
+│   Per Message                                             │
+│   ┌────────────────────────────────────────────────┐      │
+│   │ 1. Semantic memory recall (top 5 relevant)     │      │
+│   │ 2. Augment system prompt with memories         │      │
+│   │ 3. Stream LLM response (with retry)            │      │
+│   │ 4. Execute tools in parallel (with guardrails) │      │
+│   │ 5. Extract memories from response              │      │
+│   │    - Auto-store: preferences, facts, patterns  │      │
+│   │    - All types auto-stored silently            │      │
+│   └────────────────────────────────────────────────┘      │
+│                                                           │
+│   Context Management                                      │
+│   ┌────────────────────────────────────────────────┐      │
+│   │ Auto-trim at 80K tokens                        │      │
+│   │ LLM-powered summarization (not truncation)     │      │
+│   │ Fallback to text preview if LLM call fails     │      │
+│   └────────────────────────────────────────────────┘      │
+│                                                           │
+│   MCP Integration                                         │
+│   ┌────────────────────────────────────────────────┐      │
+│   │ aman-mcp  →  identity, tools, workflows, eval  │      │
+│   │ amem      →  memory, knowledge graph, reminders│      │
+│   └────────────────────────────────────────────────┘      │
 └───────────────────────────────────────────────────────────┘
 ```
 
+</details>
+
 ### Session Lifecycle
 
 | Phase | What happens |
@@ -1060,6 +1236,7 @@ On session end, if any smart trigger fires (≥3 tool errors, ≥2 blockers, &gt
 | `/plan` | Show active plan `[create\|done\|undo\|list\|switch\|show]` |
 | `/profile` | Your profile + agent profiles `[me\|edit\|setup\|create\|list\|show\|delete]` |
 | `/delegate` | Delegate task to a profile `[<profile> <task>\|pipeline]` |
+| `/agents` | Multi-agent A2A `[list\|info <name>\|ping <name>]` |
 | `/team` | Manage agent teams `[create\|run\|list\|show\|delete]` |
 | `/identity` | View identity `[update <section>]` `[dynamics [--json\|--reset]]` |
 | `/rules` | View guardrails `[add\|remove\|toggle ...]` |
@@ -1339,16 +1516,47 @@ This usually means an MCP server crashed on startup. Run `npx @aman_asmuei/aman-
 ```bash
 git clone https://github.com/amanasmuei/aman-agent.git
 cd aman-agent && npm install
-npm run build   # zero errors
-npm test        # 304 tests pass
+
+npm run lint    # tsc --noEmit — strict TypeScript, zero errors
+npm run build   # tsup → 340 KB ESM bundle
+npm test        # vitest run — 429 tests across 21 files
 ```
 
 PRs welcome. See [Issues](https://github.com/amanasmuei/aman-agent/issues).
 
 **Project standards:**
-- All new modules ship with tests (TDD encouraged)
-- Type errors block merge — `npm run build` must be clean
-- Commits follow conventional format (`feat:`, `fix:`, `chore:`, `docs:`)
+
+| Standard | Enforced by |
+|:---|:---|
+| All new modules ship with tests (TDD encouraged) | code review |
+| Type errors block merge | `npm run lint` in CI |
+| Build must be clean | `npm run build` in CI |
+| Commits follow conventional format (`feat:`, `fix:`, `chore:`, `docs:`) | commit history |
+| No MCP round-trips for read paths — use `@aman_asmuei/*-core` libraries directly | Engine v1 convention |
+
+<details>
+<summary><strong>Repo layout</strong></summary>
+
+```
+aman-agent/
+├── src/
+│   ├── agent.ts                  main event loop (40 KB)
+│   ├── commands.ts               58+ slash commands (98 KB)
+│   ├── hooks.ts                  lifecycle hooks (26 KB)
+│   ├── memory.ts / memory-extractor.ts
+│   ├── skill-engine.ts / crystallization.ts
+│   ├── user-model.ts / personality.ts / postmortem.ts
+│   ├── observation.ts / onboarding.ts / background.ts
+│   ├── delegate.ts / teams.ts / plans.ts
+│   ├── llm/                      6 provider implementations
+│   ├── mcp/                      MCP client (stdio + auto-reconnect)
+│   └── layers/                   ecosystem parsers
+├── test/                         21 test files, 429 tests
+├── bin/aman-agent.js             CLI entry point
+└── dist/                         built bundle (tsup)
+```
+
+</details>
 
 ---
 

package/dist/delegate-remote.d.ts

@@ -0,0 +1,18 @@
+import { DelegationResult } from './delegate.js';
+
+interface RemoteDelegateOptions {
+    context?: string;
+    timeoutMs?: number;
+}
+/**
+ * Dial another aman-agent running as an A2A server on the same machine
+ * and run a task through its `agent.delegate` MCP tool. Returns a
+ * DelegationResult matching the shape of the local `delegateTask` so
+ * callers can treat local and remote delegation uniformly.
+ *
+ * Trust model: same user, same machine — bearer comes from the local
+ * registry file (mode 0600). See plan docs for the broader discussion.
+ */
+declare function delegateRemote(task: string, agentName: string, options?: RemoteDelegateOptions): Promise<DelegationResult>;
+
+export { type RemoteDelegateOptions, delegateRemote };