agent-afk 2.3.0 → 2.3.2

package/README.md

@@ -1,18 +1,23 @@
 # Agent AFK CLI
 
-> A TypeScript CLI, daemon, and Telegram bot for running Claude via `@anthropic-ai/claude-agent-sdk` — ships seven orchestration skills as subagents and mirrors the `agent-framework-private` plugin surface.
+> A TypeScript CLI, daemon, and Telegram bot for running Claude (via `@anthropic-ai/sdk`) or OpenAI Codex — ships four orchestration skills as built-in subagent dispatchers with cross-session memory, DAG-composed waves, and background-task support.
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
 
 ## Features
 
-- 🚀 **Real Claude Agent SDK integration** — native subagents, hooks, elicitations, cost guardrails
-- 🧩 **Seven orchestration skills as CLI subagents** — `/mint`, `/diagnose`, `/shadow-verify`, `/forge`, `/parallelize`, `/forge-gate-check`, `/forge-l2-eval`
-- 🔌 **Plugin skill-router** — skills under `~/.afk/plugins/*/skills/` auto-exposed as slash commands
-- 🏠 **AFK-scoped config** — `~/.afk/` independent of `~/.claude/`, with `afk plugin install/update/list/remove`
+- 🚀 **Provider abstraction** — Anthropic (direct) and OpenAI Codex; native subagents, hooks, elicitations, cost guardrails
+- 🧩 **Four built-in orchestration skills** — `/mint`, `/diagnose`, `/forge`, `/audit-fit`, each dispatched as an isolated subagent
+- 🧠 **Cross-session memory** — `memory_search`, `memory_update`, `procedure_write` tools backed by SQLite + `HOT.md`
+- 🕸️ **DAG-composed parallel waves** — built-in `compose` tool runs subagent nodes with dependency edges and fail-fast
+- ⏱️ **Background tasks** — Ctrl+B detaches the current turn; `/bg`, `/tasks`, `/attach` manage long-running work
+- 📲 **`send_telegram` built-in tool** — agents can push terminal-state notifications to the operator
+- 🔌 **Plugin & marketplace install** — `afk plugin install` / `afk marketplace add` keep everything under `~/.afk/`
+- 🏠 **AFK-scoped config** — `~/.afk/` independent of `~/.claude/`, with sessions, plugins, agents, commands, skills
 - 💬 **Three surfaces** — interactive REPL, daemon, Telegram bot sharing one session manager
 - 📊 **Routing telemetry** — every subagent dispatch appended to `~/.afk/agent-framework/routing-decisions.jsonl`
-- 🤖 **Multiple Claude models** — Opus, Sonnet, Haiku
+- 🤖 **Multiple models** — Opus, Sonnet, Haiku (Anthropic); GPT-5 family via Codex
+- 🧠 **Extended thinking on by default** — controllable via `AFK_THINKING` / `--thinking`
 - 🔓 **Bypass permissions mode** — no prompts, fully automated tool execution
 - 🛡️ **Type-safe** — TypeScript strict mode
 
@@ -35,7 +40,7 @@
 
 ### Prerequisites
 
-- **Node.js ≥ 18.0.0**
+- **Node.js ≥ 20.0.0** (enforced by `package.json#engines`)
 - **pnpm** — this project's lockfile is pnpm-specific. Running `npm install` will desync it.
   - Fastest path: `corepack enable` (bundled with Node ≥ 16.9), then use `pnpm` directly.
   - Or install globally: `npm install -g pnpm@latest`.
@@ -90,17 +95,21 @@ pnpm build
 
 ### CLI Commands
 
-The `afk` CLI exposes seven top-level commands registered in `src/cli/index.ts`:
+The `afk` CLI exposes eleven top-level commands registered in `src/cli/index.ts`:
 
 | Command | Purpose |
 |---|---|
 | `chat` | Single-turn message |
-| `interactive` | REPL with full Agent SDK features |
+| `interactive` | REPL with full Agent SDK features (default when invoked without a subcommand) |
 | `status` | Connection, API-key, model, bypass-mode status |
 | `config` | Dump resolved configuration |
 | `daemon` | Long-running headless agent (see `src/agent/daemon/`) |
 | `login` | OAuth flow for `console.anthropic.com` |
 | `plugin` | Manage `~/.afk/plugins/` (install / update / list / remove / enable / disable) |
+| `marketplace` | Add / list / remove plugin marketplaces under `~/.afk/marketplaces/` |
+| `doctor` | Environment self-check (Node version, API keys, paths, config) |
+| `completion` | Print a shell completion script (`zsh`, `bash`, `fish`) |
+| `telegram` | Manage the Telegram bot daemon (start, stop, status, logs, setup) |
 
 #### Chat (single message)
 
@@ -200,32 +209,32 @@ pnpm telegram:restart
 
 ## Orchestration Skills
 
-agent-afk ships seven built-in subagent orchestrators plus `devils-advocate` (in development). These are **skill-router-dispatched**: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a skill handler under `src/skills/<name>/`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.afk/agent-framework/routing-decisions.jsonl`.
+agent-afk ships four built-in subagent orchestrators. These are **built-in skills** exposed through the slash registry: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a TypeScript handler under `src/skills/<name>/index.ts`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.afk/agent-framework/routing-decisions.jsonl`.
+
+The canonical list lives in `src/skills/all.ts`:
 
 | Skill | Purpose |
 |---|---|
 | `/mint` | End-to-end feature/refactor pipeline: spec → research → plan → parallelize → build → verify → heal → ship |
 | `/diagnose` | Parallel hypothesis generation + validation for bugs and failing tests |
-| `/shadow-verify` | Adversarial re-derivation of sub-agent claims before you act on them |
-| `/forge` | Generate new skills autonomously, gated by L1 capability evals |
-| `/parallelize` | Transform a linear plan into dependency-aware parallel waves |
-| `/forge-gate-check` | Report whether `/forge` is thawed; rerun the L1 eval harness |
-| `/forge-l2-eval` | Run L2 capability evals (live sub-agent verdict probes) |
+| `/forge` | Generate new skills autonomously, gated by L1/L2 capability evals (gate-check is inlined; no separate `/forge-gate-check` skill) |
+| `/audit-fit` | Audit `~/.afk` artifacts (skills, commands, agents, hooks) for correct type categorization |
 
-The same seven skills ship in two surfaces:
+Skills surface in two shapes:
 
-- **CLI surface** (this repo) — TypeScript handlers under `src/skills/<name>/` invoked via `skill-router`.
-- **Plugin surface** — prompt-based `SKILL.md` files under `agent-framework-private/skills/<name>/`, invoked inside a Claude Code session.
+- **Built-in (this repo)** — TypeScript handlers under `src/skills/<name>/`, registered via `src/skills/all.ts` and bridged into the slash registry by `src/cli/slash/builtin-skills.ts`.
+- **Plugin / user** — `SKILL.md` files discovered under `~/.afk/plugins/<plugin>/skills/<skill>/` or `~/.afk/skills/<skill>/`, scanned at session start and auto-exposed as slash commands.
 
-Vendored subagents (`qualify`, `research-agent`, `contract`) live under `src/skills/_agents/` and are kept byte-equal with the upstream copies — drift is caught by `src/skills/_agents/vendored.test.ts`.
+Vendored subagents (`qualify`, `research-agent`, `contract`) live under `src/skills/_agents/` and are kept byte-equal with the upstream copies — drift is caught by tests in `src/skills/_agents/`.
 
-See the workspace-root [`SYSTEM.md`](../SYSTEM.md) for the topology, skill dependency graph, and multi-prompt loading convention.
+See [`AGENTS.md`](AGENTS.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md) for repo conventions; the workspace-root [`SYSTEM.md`](../SYSTEM.md) covers the broader topology when present.
 
 ## Scripts
 
 ```bash
 # Build / dev
 pnpm build                  # tsc && node scripts/copy-prompts.js (markdown prompts → dist/)
+pnpm build:dist             # esbuild bundle into dist/ for release artifacts
 pnpm dev                    # tsx watch src/cli/index.ts
 pnpm start                  # node dist/cli/index.js
 pnpm start:chat             # shortcut for `chat`
@@ -235,26 +244,27 @@ pnpm clean                  # rm -rf dist
 
 # Testing
 pnpm test                   # vitest run (all)
-pnpm test:integration       # integration tests only
-pnpm test:e2e               # end-to-end tests only
+pnpm test:integration       # vitest run tests/integration  (note: dir not yet populated)
+pnpm test:e2e               # vitest run tests/e2e          (note: dir not yet populated)
 pnpm test:coverage          # with coverage report
 pnpm test:watch             # watch mode
 pnpm lint                   # tsc --noEmit (type-check only)
 
 # Telegram daemon
 pnpm telegram               # run in foreground
+pnpm telegram:setup         # interactive setup wizard (bot token, allowed chat IDs)
 pnpm telegram:start         # background service (launchd/systemd-style wrapper)
 pnpm telegram:stop
 pnpm telegram:status
 pnpm telegram:restart
+pnpm telegram:logs          # tail the background-service log
 
-# SDK dependency auditing
-pnpm audit:sdk              # regenerate docs/sdk-dependency.md snapshot
-pnpm audit:sdk:check        # CI gate — fail if new SDK symbols appear without a lock update
-pnpm audit:sdk:update-lock  # update .sdk-dependency.lock.json allowlist
+# Release
+pnpm release                # scripts/release.mjs — version bump + publish flow
+pnpm release:dry            # dry-run release flow (no git push / no npm publish)
 ```
 
-agent-afk is the only subrepo in its workspace that imports `@anthropic-ai/claude-agent-sdk` / `@anthropic-ai/sdk` directly. The `audit:sdk*` scripts track that surface mechanically and fail CI on unauthorized drift. See [`docs/sdk-dependency.md`](docs/sdk-dependency.md) and [`.sdk-dependency.lock.json`](.sdk-dependency.lock.json). When adding a new SDK import, run `pnpm audit:sdk:update-lock` and edit the lock entry's `reason` with a one-line justification before committing.
+> Note: `tests/integration/` and `tests/e2e/` directories are not yet populated — the live test suites live under `tests/agent/`, `tests/telegram/`, and colocated `*.test.ts` files in `src/`. The `test:integration` / `test:e2e` scripts are kept as placeholders for the planned split.
 
 ## Configuration
 
@@ -283,12 +293,17 @@ You can delete `~/.claude/` entirely and agent-afk still runs.
 Create a `.env` file in the project root:
 
 ```env
-# Required
+# Required (Anthropic provider)
 ANTHROPIC_API_KEY=sk-ant-api03-...
 
-# Optional
-CLAUDE_MODEL=sonnet                # opus | sonnet | haiku (default sonnet)
-TELEGRAM_BOT_TOKEN=1234567890:ABC...
+# Provider / model selection
+AFK_MODEL=sonnet                   # opus | sonnet | haiku (Anthropic) or codex (default sonnet)
+AFK_DEFAULT_SUBAGENT_MODEL=        # override default subagent model
+AFK_THINKING=on                    # on | off | <budget-tokens> — extended thinking (on by default)
+AFK_EFFORT=                        # low | medium | high — reasoning effort (Codex provider)
+AFK_MAX_OUTPUT_TOKENS=             # cap on output tokens per turn
+AFK_TEMPERATURE=                   # numeric override; provider-default if unset
+AFK_TIMEOUT_MS=                    # per-turn timeout
 
 # Cost guardrails (see SDK-native features below)
 AFK_MAX_BUDGET_USD=5.00
@@ -298,12 +313,32 @@ AFK_TASK_BUDGET=100000
 AFK_DISABLE_PROMPT_CACHE=          # 1 | true | yes | on disables; unset = enabled
 AFK_PROMPT_CACHE_TTL=1h            # 5m | 1h (default 1h)
 
-# Optional: Color output control
-# Set NO_COLOR=1 to disable colors (per https://no-color.org)
-# Unset or leave empty for auto-detection (disables in CI or piped output)
-NO_COLOR=
+# Cross-session memory & system prompt
+AFK_SYSTEM_PROMPT=                 # raw string — highest-priority override of AFK.md
+AFK_HOME=                          # override ~/.afk
+AFK_STATE_DIR=                     # override ~/.afk/state
+AFK_FRAMEWORK_DIR=                 # override ~/.afk/agent-framework
+AFK_AUTO_ROUTING=                  # auto-route bare slash inputs to skills
+
+# Telegram bot (foreground + background daemon + send_telegram tool)
+TELEGRAM_BOT_TOKEN=1234567890:ABC...
+AFK_TELEGRAM_BOT_TOKEN=            # alternative name accepted by setup wizard
+AFK_TELEGRAM_ALLOWED_CHAT_IDS=     # comma-separated chat IDs allowed to push to / receive from
+TELEGRAM_DATA_DIR=                 # override Telegram state dir (defaults under ~/.afk/state)
+TELEGRAM_VERBOSE=                  # 1 to log per-message details
+AFK_TELEGRAM_TRACE=                # 1 to dump raw bridge traffic
+
+# Debug / dev
+AFK_DEBUG=                         # 1 enables verbose logging
+AFK_DEBUG_CLIPBOARD=               # debug bracketed-paste / image-paste handling
+AFK_DUMP_PROMPT=                   # write resolved system prompt to a file
+
+# Color output (per https://no-color.org)
+NO_COLOR=                          # set to disable colors; unset = auto-detect (CI / pipes)
 ```
 
+The authoritative list of supported env vars lives in `src/` — search for `process.env.AFK_` or `process.env.TELEGRAM_` for the full surface. `.env.example` mirrors the most common ones.
+
 ### System Prompt Auto-Discovery
 
 agent-afk resolves the session system prompt through a 4-tier precedence chain (highest tier wins):
@@ -317,6 +352,8 @@ agent-afk resolves the session system prompt through a 4-tier precedence chain (
 
 **AFK.md format:** Plain Markdown, no frontmatter. The entire file content (trimmed) becomes the system prompt. Empty or whitespace-only files are treated as absent (tier 4 applies instead).
 
+**Bootstrapping AFK.md:** run `/init` in the REPL to scan the current project and generate a tailored `AFK.md` at the repo root. See `src/cli/slash/commands/init.ts`.
+
 **Provenance tracking:** When using `--dump-prompt`, the `systemPromptSource` field in the dump shows which tier won:
 - `"env:AFK_SYSTEM_PROMPT"` — tier 1
 - `"file:/abs/path/afk.config.json"` — tier 2
@@ -335,12 +372,19 @@ Defaults are tuned for `agent-afk`'s long-lived surfaces (daemon, Telegram bot)
 
 Markers never leak back into stored history — `cache-policy.ts` clones-and-stamps so the canonical `messages` array stays marker-free across iterations (accumulating markers would break prefix-hash matching). Implementation: [`src/agent/providers/anthropic-direct/cache-policy.ts`](src/agent/providers/anthropic-direct/cache-policy.ts).
 
-### Supported Models
+### Supported Models & Providers
+
+agent-afk speaks to two providers through a single abstraction (`src/agent/providers/`):
 
+**Anthropic (direct)** — default. Selects from:
 - **opus** — most capable, for complex tasks
 - **sonnet** — balanced performance and speed (default)
 - **haiku** — fastest, best for simple tasks
 
+**OpenAI Codex** (`@openai/codex-sdk`) — set `AFK_MODEL=codex` (or pass `--model codex`). Implementation lives in `src/agent/providers/openai-codex.ts`. Tune reasoning effort via `AFK_EFFORT=low|medium|high`.
+
+Per-session overrides: `--model <name>`, `--thinking <on|off|N>`, `--max-output-tokens <n>`, `--temperature <n>`.
+
 ## Plugins & Slash Commands
 
 ### Installing plugins
@@ -375,26 +419,66 @@ Advanced: AFK still auto-discovers any plugin dropped into `~/.afk/plugins/<name
 
 Plugin state (telemetry, ledger, briefs) writes to `~/.afk/agent-framework/` in the AFK runtime.
 
-### Plugin skills as slash commands
+### REPL slash commands
 
-Every skill loaded from `~/.afk/plugins/<plugin>/skills/*/SKILL.md` is exposed automatically in the interactive REPL as `/<skill-name>`. There is no per-skill handler code — agent-afk asks the SDK for its skill catalog at session start (`session.supportedCommands()`) and registers a passthrough handler per entry. Typing `/mint add dark mode` pipes the raw line into the SDK turn loop; the subprocess parses the slash form natively and dispatches to the plugin's skill, exactly the way Claude Code does it.
+The interactive REPL registers slash commands directly in TypeScript (`src/cli/slash/`) — they don't pass through to any external Claude Code subprocess. Categories:
 
+**Core / session control**
 - `/help` — list all available slash commands (built-in + plugin-loaded)
-- `/skills` — discover skills loaded from plugins
-- `/reload-plugins` — reload after editing SKILL.md files on disk
-
-Implementation lives in `src/cli/slash/plugin-skills.ts`; see the module header for the flow.
-
-### SDK-native features surfaced in the REPL
-
-agent-afk wires several Claude Agent SDK capabilities that Claude Code exposes natively, so they feel the same here:
-
-- **`/agents`** — lists Task-tool subagents loaded by the SDK (plugin + user + project scope). Agents are not user-invokable slashes; they're dispatch targets the model picks via the Task tool. The list shows name, description, and model override when present. Refresh with `/reload-plugins` after editing `~/.afk/agents/` or plugin agent definitions.
-- **`/tokens`** — renders the authoritative SDK breakdown of context usage: total vs model max, auto-compact threshold, top categories, system tools, MCP tools, agents, skills, slash commands, and the last-turn API usage. Falls back to local-stats aggregation when the SDK call can't be served (e.g., before the subprocess is warm).
-- **Status-line context %** — sampled every 3 turns from `session.getContextUsage()`, cached between samples, degrades gracefully on transient failures. See `src/cli/context-sampler.ts`.
-- **Progress banners** — when the SDK emits `task_progress` events (long subagent runs, multi-tool flows), they render inline as `◦ description (stats)` plus an indented summary when present. Telegram forwards the same lines with the existing edit-throttle, and prompt suggestions trail as `💡` lines below the response. Enabled by default via `agentProgressSummaries: true`.
-- **Cost guardrails** — pass `--max-budget-usd <n>` (or set `AFK_MAX_BUDGET_USD`) to abort the session cleanly on cost breach. `--task-budget <tokens>` (or `AFK_TASK_BUDGET`) is an advisory per-task token hint surfaced to the model so it can pace itself. Both work across `afk interactive`, `afk chat`, and the Telegram bot.
-- **MCP elicitations** — when an MCP server requests OAuth consent (e.g. Supabase re-auth), the REPL prints the server name, message, and URL, then asks `Continue? [y/N]`. Empty answer cancels; `n` declines; `y` accepts. Form-mode elicitations are auto-declined in v1 (tracked in `todo.md`). Handler is installed via `elicitationRouter.install(...)`; bridges can install their own.
+- `/exit`, `/quit` — leave the REPL
+- `/clear` — clear screen
+- `/compact` — manually compact conversation history
+- `/reset` — start a fresh session, discarding history
+
+**Information**
+- `/cost` — running cost for the session
+- `/tokens` (alias `/ctx`) — SDK breakdown of context usage
+- `/history` — print prior turns
+- `/model` — show or switch active model
+- `/tools` — list registered tools
+- `/mcp` — show MCP server status
+- `/limits` — show rate-limit / budget state
+- `/debug` — toggle verbose debug output
+
+**Planning & state**
+- `/plan` — open the plan editor
+- `/todo` — manage the persistent todo list
+- `/save` — snapshot session state to disk
+- `/resume` — resume a saved session
+- `/init` — scan the current project and write `AFK.md`
+- `/changelog` — render `CHANGELOG.md` paginated
+
+**Background tasks** (Ctrl+B detaches the current turn)
+- `/bg` — list backgrounded tasks
+- `/tasks` — show running/queued tasks with status
+- `/attach <id>` — re-attach to a backgrounded task
+
+**Skills (built-in)** — see [Orchestration Skills](#orchestration-skills)
+- `/mint`, `/diagnose`, `/forge`, `/audit-fit`
+
+**Plugins / marketplaces**
+- `/skills` (alias `/builtin-skills`) — discover skills loaded from plugins & user scope
+- `/agents` — list Task-tool subagents loaded by the SDK
+- `/reload-plugins` — re-scan plugin and user directories after edits
+
+Implementation: `src/cli/slash/index.ts` (`registerAll()`), individual command modules under `src/cli/slash/commands/`. Plugin-discovered skills (`~/.afk/plugins/<plugin>/skills/<skill>/SKILL.md` and `~/.afk/skills/<skill>/SKILL.md`) are registered via `src/cli/slash/builtin-skills.ts` and `src/cli/slash/plugin-skills.ts`.
+
+### Runtime features surfaced in the REPL
+
+agent-afk wires several capabilities on top of the provider abstraction:
+
+- **Cross-session memory** — three built-in tools (`memory_search`, `memory_update`, `procedure_write`) backed by SQLite at `~/.afk/agent-framework/memory/`. `HOT.md` is injected into every future session's system prompt for durable essentials. See `src/agent/memory/` and `src/agent/tools/handlers/memory-*.ts`.
+- **`compose` tool — DAG-based orchestration** — agents (and the main session) can dispatch up to 20 subagent nodes with explicit dependency edges. Independent nodes run in parallel; dependent nodes wait. Fail-fast cancels downstream nodes by default. See `src/agent/tools/compose-executor.ts` and `src/agent/dag.ts`.
+- **Background tasks** — Ctrl+B in the REPL detaches the current turn into a tracked background task. `/bg` lists tasks, `/tasks` shows status, `/attach <id>` re-attaches. Status bar at the bottom of the REPL surfaces running task counts. Implementation: `src/cli/background-status-bar.ts`, `src/cli/commands/interactive/background.js`.
+- **`send_telegram` built-in tool** — agents can push terminal-state notifications to the operator. Recipients are gated by `AFK_TELEGRAM_ALLOWED_CHAT_IDS`; safe to attempt unconditionally (returns an error if Telegram is unconfigured). Handler: `src/agent/tools/handlers/send-telegram.ts`.
+- **Extended thinking on by default** — Anthropic's thinking budget is auto-enabled. Override per-session with `--thinking on|off|<budget-tokens>` or globally with `AFK_THINKING`.
+- **`/tokens`** — authoritative breakdown of context usage: total vs model max, auto-compact threshold, top categories, system tools, MCP tools, agents, skills, slash commands, and the last-turn API usage.
+- **Status-line context %** — sampled every few turns from `session.getContextUsage()`, cached between samples, degrades gracefully on transient failures. See `src/cli/context-sampler.ts`.
+- **Progress banners** — when the provider emits `task_progress` events (long subagent runs, multi-tool flows), they render inline as `◦ description (stats)` with an indented summary when present. Telegram forwards the same lines with edit-throttling, and prompt suggestions trail as `💡` lines below the response.
+- **Cost guardrails** — `--max-budget-usd <n>` / `AFK_MAX_BUDGET_USD` aborts on cost breach. `--task-budget <tokens>` / `AFK_TASK_BUDGET` is an advisory per-task hint surfaced to the model.
+- **MCP elicitations** — when an MCP server requests OAuth consent (e.g. Supabase re-auth), the REPL prints the server name, message, and URL, then asks `Continue? [y/N]`. Empty cancels; `n` declines; `y` accepts. Form-mode elicitations are auto-declined in v1. Handler: `src/agent/elicitation-router.ts`.
+- **Clipboard image paste** — paste images directly into the REPL (macOS pasteboard; bracketed-paste-aware). See `src/cli/input/clipboard-image.ts`.
+- **Auto-update check** — startup checks for a newer published version and prints a notice. Suppress with `afk --no-update-check`. Policy field `updatePolicy` (`notify`|`auto`|`off`) lives in `afk.config.json`. Implementation: `src/cli/update-checker.ts`.
 
 ## Bypass Permissions Mode
 
@@ -457,7 +541,17 @@ agent-afk/
 ├── src/
 │   ├── cli/
 │   │   ├── index.ts                # CLI entry (commander)
-│   │   └── commands/               # chat, interactive, status, config, daemon, login, plugin, skill-router
+│   │   ├── commands/               # chat, interactive, status, config, daemon,
+│   │   │                           # login, plugin, marketplace, doctor,
+│   │   │                           # completion, telegram, etc.
+│   │   ├── slash/                  # REPL slash registry + commands/
+│   │   │                           # (help, plan, todo, bg, tasks, attach,
+│   │   │                           #  init, changelog, builtin-skills, …)
+│   │   ├── input/                  # raw-mode, bracketed paste, clipboard images
+│   │   ├── background-status-bar.ts
+│   │   ├── context-sampler.ts
+│   │   ├── update-checker.ts
+│   │   └── config.ts, shared-helpers.ts
 │   ├── agent/
 │   │   ├── session.ts              # AgentSession barrel
 │   │   ├── session/                # agent-session, query-options, …
@@ -466,8 +560,13 @@ agent-afk/
 │   │   ├── subagent-hooks.ts
 │   │   ├── routing-telemetry.ts    # appends routing-decisions.jsonl
 │   │   ├── daemon/                 # long-running headless agent
-│   │   ├── plugins/                # afk plugin install / update / remove / index-store
-│   │   ├── providers/              # provider abstraction
+│   │   ├── plugins/                # afk plugin install / update / remove
+│   │   ├── marketplaces/           # marketplace install / resolve / manifest
+│   │   ├── providers/              # anthropic-direct, openai-codex
+│   │   ├── memory/                 # cross-session memory + HOT.md loader
+│   │   ├── tools/                  # built-in tool dispatcher + handlers
+│   │   │                           # (compose, subagent, skills, memory_*,
+│   │   │                           #  send_telegram, …)
 │   │   ├── elicitation-router.ts
 │   │   ├── hook-registry.ts, hooks.ts, default-hook-registry.ts
 │   │   ├── permissions.ts, abort-graph.ts, dag.ts, message-queue.ts
@@ -475,33 +574,42 @@ agent-afk/
 │   │   ├── shadow-verify-nudge.ts
 │   │   └── types.ts, types/
 │   ├── skills/
+│   │   ├── all.ts                  # canonical skill registry
 │   │   ├── mint/                   # /mint
 │   │   ├── diagnose/               # /diagnose
-│   │   ├── shadow-verify/          # /shadow-verify
-│   │   ├── forge/                  # /forge
-│   │   ├── parallelize/            # /parallelize
-│   │   ├── forge-gate-check/       # /forge-gate-check
-│   │   ├── forge-l2-eval/          # /forge-l2-eval
-│   │   ├── devils-advocate/        # in development
-│   │   ├── _agents/                # vendored subagents (qualify, research-agent, contract)
+│   │   ├── forge/                  # /forge (gate-check inlined)
+│   │   ├── audit-fit/              # /audit-fit
+│   │   ├── _agents/                # vendored subagents (qualify,
+│   │   │                           #  research-agent, contract)
 │   │   ├── _lib/                   # prompt-loader, shared helpers
 │   │   ├── example-template/       # scaffold for new skills
-│   │   └── index.ts
-│   ├── telegram/                   # telegram bridge
+│   │   └── user-skills.ts          # lazy scan of ~/.afk/skills + project skills
+│   ├── telemetry/                  # shared telemetry schemas
+│   ├── telegram/                   # telegram bridge (setup wizard, push, etc.)
 │   ├── telegram.ts                 # telegram bot entry
 │   ├── utils/
 │   ├── paths.ts
 │   └── index.ts
 ├── tests/
-│   ├── integration/
-│   └── e2e/
+│   ├── agent/                      # cross-cutting integration suites
+│   └── telegram/                   # telegram bridge tests
 ├── scripts/
 │   ├── copy-prompts.js             # bundles src/**/*.md into dist/ after tsc
-│   ├── audit-sdk-dependency.ts
-│   └── telegram-manager.sh
-├── docs/
-│   └── sdk-dependency.md           # committed SDK symbol snapshot
-├── .sdk-dependency.lock.json       # SDK symbol allowlist (CI-gated)
+│   ├── build-dist.mjs              # esbuild release bundle
+│   ├── release.mjs                 # version bump + publish flow
+│   ├── generate-changelog.mjs
+│   ├── audit-sdk-dependency.ts     # (not yet wired into package.json)
+│   ├── colocate-tests.mjs
+│   ├── telegram-manager.sh
+│   └── verify-install.sh
+├── docs/                           # design notes, audits, failure geometry
+├── landing/                        # marketing site assets
+├── AGENTS.md
+├── CHANGELOG.md
+├── CLAUDE.md
+├── CONTRIBUTING.md
+├── afk.config.json.example
+├── verify.sh
 ├── pnpm-lock.yaml
 ├── package.json
 ├── tsconfig.json
@@ -519,26 +627,18 @@ pnpm lint                   # type-check without emitting
 
 `pnpm build` runs `tsc` and then `scripts/copy-prompts.js`, which copies every `src/**/*.md` file into `dist/` at matching relative paths. Skills read their prompts via `readFileSync` at import time, so those markdown files must live next to the compiled `.js` output.
 
-### SDK Dependency Tracking
-
-agent-afk is the only subrepo in its workspace that imports from `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/sdk`. That surface is tracked mechanically:
-
-- [`docs/sdk-dependency.md`](docs/sdk-dependency.md) — committed snapshot of every tracked symbol, its files, and runtime-vs-type classification.
-- [`.sdk-dependency.lock.json`](.sdk-dependency.lock.json) — allowlist with per-symbol `reason` fields. CI fails when a new symbol or kind-change appears without a lock update.
-- `~/.afk/agent-framework/sdk-dependency-telemetry.jsonl` — append-only log of symbol-count deltas and SHA over time.
-
-When adding a new SDK import: run `pnpm audit:sdk:update-lock`, then edit the generated lock entry's `reason` with a one-line justification before committing.
-
 ### Testing
 
 ```bash
-pnpm test                   # all
+pnpm test                   # all (vitest run)
 pnpm test:coverage          # with coverage
 pnpm test:watch             # watch mode
-pnpm test:integration       # integration only
-pnpm test:e2e               # e2e only
+pnpm test:integration       # vitest run tests/integration  (dir not yet populated)
+pnpm test:e2e               # vitest run tests/e2e          (dir not yet populated)
 ```
 
+Tests are colocated as `*.test.ts` next to the implementation under `src/`, plus cross-cutting suites under `tests/agent/` and `tests/telegram/`.
+
 ## Troubleshooting
 
 ### API Key Issues
@@ -667,16 +767,15 @@ type SessionState = 'idle' | 'processing' | 'streaming' | 'closed';
 
 ## Contributing
 
-Contributions welcome. Standard flow:
+Contributions welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md) for repo conventions. Standard flow:
 
 1. Fork the repository
 2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Run `pnpm test && pnpm lint`
-6. Open a pull request
+3. Make your changes (add or update tests alongside)
+4. Run `pnpm test && pnpm lint`
+5. Open a pull request
 
-New orchestration skills, CI gate changes, and ceiling-ledger conventions are documented in the workspace-root [`SYSTEM.md`](../SYSTEM.md).
+New orchestration skills, CI gate changes, and ceiling-ledger conventions are documented in [`AGENTS.md`](AGENTS.md). A change log is maintained in [`CHANGELOG.md`](CHANGELOG.md) (also viewable in-REPL via `/changelog`).
 
 ## License
 
@@ -684,8 +783,10 @@ MIT © Griffin Long
 
 ## Acknowledgments
 
-- Built with [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+- Anthropic API client: [@anthropic-ai/sdk](https://www.npmjs.com/package/@anthropic-ai/sdk)
+- OpenAI Codex client: [@openai/codex-sdk](https://www.npmjs.com/package/@openai/codex-sdk)
 - CLI framework: [Commander.js](https://github.com/tj/commander.js)
+- Telegram: [Telegraf](https://telegraf.js.org/)
 - Testing: [Vitest](https://vitest.dev/)
 
 ---

package/dist/cli.mjs

@@ -1606,7 +1606,9 @@ ${wy}`}import Or from"chalk";import{Lexer as Sc}from"marked";import Sy from"stri
 `+c+`
 `)):l.depth===2?d.bold(d.user(`
 `+c+`
-`)):d.bold(c)}case"paragraph":return o(i.tokens)+`
+`)):d.bold(`
+`+c+`
+`)}case"paragraph":return o(i.tokens)+`
 
 `;case"code":{let l=i,c=l.lang||"text",p=bc(l.text,c).split(`
 `);p.length>0&&p[p.length-1]===""&&p.pop();let m=d.dim("\u2502 "),f=p.map(y=>m+y).join(`
@@ -1905,7 +1907,7 @@ complete -c afk -l trigger -x -a '${n}' -d 'Trigger type'`}function Tp(e){e.comm
 `);return r.length>0&&r[r.length-1]===""&&r.pop(),r.slice(-t)}catch{return[]}}function Lv(e){try{if(process.platform==="linux"){let t=`/proc/${e}/stat`;if(!$t(t))return{};let r=Mo(t,"utf-8").split(" "),o=Number.parseInt(r[21]??"0",10),l=Rv("/proc/1").mtimeMs/1e3+o/100,c=Math.floor(Date.now()/1e3-l),p=Mo(`/proc/${e}/status`,"utf-8").match(/VmRSS:\s+(\d+)\s+kB/),m=p?Math.round(Number.parseInt(p[1]??"0",10)/1024):void 0;return{uptimeSec:c,memoryMb:m}}if(process.platform==="darwin"){let{execFileSync:t}=Bp("child_process"),n=t("ps",["-p",String(e),"-o","etime=,rss="],{encoding:"utf-8",stdio:["ignore","pipe","ignore"]}).trim(),[r,o]=n.split(/\s+/);return{uptimeSec:Fv(r??""),memoryMb:o?Math.round(Number.parseInt(o,10)/1024):void 0}}}catch{}return{}}function Fv(e){if(!e)return;let t=e.split("-"),n=0,r=e;t.length===2&&(n=Number.parseInt(t[0]??"0",10),r=t[1]??"");let o=r.split(":").map(l=>Number.parseInt(l,10));if(o.some(l=>!Number.isFinite(l)))return;let s=0,a=0,i=0;if(o.length===3)[s,a,i]=o;else if(o.length===2)[a,i]=o;else if(o.length===1)[i]=o;else return;return n*86400+s*3600+a*60+i}import{createInterface as Nv}from"readline";import te from"chalk";var Cp="https://api.telegram.org";async function Pp(e){try{let t=await fetch(`${Cp}/bot${e}/getMe`);if(!t.ok)return null;let n=await t.json();return!n.ok||!n.result?.id||!n.result?.first_name?null:{id:n.result.id,...n.result.username!==void 0?{username:n.result.username}:{},firstName:n.result.first_name}}catch{return null}}function Uv(e){let t=new Map;for(let n of e){let o=(n.message??n.edited_message)?.chat;!o||typeof o.id!="number"||t.set(o.id,{chatId:o.id,type:o.type??"unknown",...o.username!==void 0?{username:o.username}:{},...o.first_name!==void 0?{firstName:o.first_name}:{}})}return[...t.values()].reverse()}async function jv(e){try{let t=await fetch(`${Cp}/bot${e}/getUpdates`);if(!t.ok)return[];let n=await t.json();return!n.ok||!Array.isArray(n.result)?[]:n.result}catch{return[]}}async function Bv(e,t={}){let n=t.maxAttempts??30,r=t.intervalMs??2e3;for(let o=0;o<n;o++){let s=await jv(e),a=Uv(s);if(a.length>0)return a;o<n-1&&await new Promise(i=>setTimeout(i,r))}return[]}function bi(e){let t=Nv({input:process.stdin,output:process.stdout});return new Promise(n=>{t.question(e,r=>{t.close(),n(r.trim())})})}async function Ip(){let e=Ke();console.log(""),console.log(te.bold("\u{1F916} Telegram bot setup")),console.log(""),console.log(te.gray(`Config will be written to ${e}`)),console.log("");let t=process.env.TELEGRAM_BOT_TOKEN?.trim()??"",n=null;for(t&&(console.log(te.gray("Validating existing TELEGRAM_BOT_TOKEN...")),n=await Pp(t),n?console.log(te.green(`\u2713 Token valid for @${n.username??n.firstName} (id ${n.id})`)):(console.log(te.yellow("\u26A0 Existing TELEGRAM_BOT_TOKEN is invalid; prompting for a new one")),t=""));!n;)t=await bi("Paste your bot token (from @BotFather): "),t||(console.error(te.red("No token provided. Aborting.")),process.exit(1)),n=await Pp(t),n||console.log(te.red("\u2717 Token rejected by getMe. Try again or Ctrl-C to abort."));on(e,"TELEGRAM_BOT_TOKEN",t),console.log(te.green(`\u2713 Saved TELEGRAM_BOT_TOKEN \u2192 ${e}`)),console.log(""),console.log(te.bold("Now DM your bot to authorize your account."));let r=n.username?`@${n.username}`:`"${n.firstName}"`;console.log(`  1. Open Telegram and find ${te.cyan(r)}`),console.log('  2. Send any message (e.g. "hi")'),console.log(""),console.log(te.gray("Polling for your chat ID (up to 60s)..."));let o=await Bv(t);if(o.length===0){console.error(te.red("\u2717 No chats found after 60s.")),console.error(te.gray("  Send a message to the bot and run `afk telegram setup` again,")),console.error(te.gray("  or paste your chat ID manually:"));let a=await bi("Chat ID: "),i=Number.parseInt(a,10);return Number.isFinite(i)||(console.error(te.red("Invalid chat ID. Aborting.")),process.exit(1)),on(e,"AFK_TELEGRAM_ALLOWED_CHAT_IDS",String(i)),console.log(te.green(`\u2713 Saved AFK_TELEGRAM_ALLOWED_CHAT_IDS=${i}`)),{envPath:e,bot:n,chatId:i}}let s=o[0];if(o.length>1){console.log(te.bold(`
 Multiple chats found:`)),o.forEach((l,c)=>{let u=l.username?`@${l.username}`:l.firstName??l.type;console.log(`  [${c+1}] ${u} (id ${l.chatId}, ${l.type})`)});let a=await bi("Which chat should be allowed? [1]: "),i=Number.parseInt(a||"1",10)-1;Number.isFinite(i)&&i>=0&&i<o.length&&(s=o[i])}else{let a=s.username?`@${s.username}`:s.firstName??s.type;console.log(te.green(`\u2713 Found chat with ${a} (id ${s.chatId})`))}return on(e,"AFK_TELEGRAM_ALLOWED_CHAT_IDS",String(s.chatId)),console.log(te.green(`\u2713 Saved AFK_TELEGRAM_ALLOWED_CHAT_IDS=${s.chatId} \u2192 ${e}`)),console.log(""),console.log(te.bold("Setup complete. Start the bot with:")),console.log(te.cyan("  afk telegram start")),console.log(""),{envPath:e,bot:n,chatId:s.chatId}}function _p(e){let t=e.command("telegram").description("Manage the Agent AFK Telegram bot (setup, start, stop, status)");t.command("setup").description("Interactive setup: validate bot token, discover chat ID, persist to ~/.afk/config/afk.env").action(async()=>{try{await Ip()}catch(n){console.error(Q.red(`Setup failed: ${n.message}`)),process.exit(1)}}),t.command("start").description("Start the bot as a background daemon").action(async()=>{let n=await hi();if(n.kind==="started"){console.log(Q.green(`\u2713 Bot started (PID ${n.pid})`)),console.log(Q.gray(`  Logs: ${n.logFile}`)),console.log(Q.gray("  Tail with: afk telegram logs --follow"));return}if(n.kind==="already-running"&&(console.log(Q.yellow(`\u26A0 ${n.message}`)),process.exit(1)),n.kind==="exited-immediately"){if(console.error(Q.red(`\u2717 ${n.message}`)),n.logTail&&n.logTail.length>0){console.error(""),console.error(Q.bold("Last log entries:"));for(let r of n.logTail)console.error(Q.gray(`  ${r}`))}process.exit(1)}console.error(Q.red(`\u2717 ${n.message}`)),process.exit(1)}),t.command("stop").description("Stop the bot (SIGTERM, then SIGKILL after 5s)").action(async()=>{let n=await yi();if(n.kind==="not-running"){console.log(Q.yellow("\u26A0 Bot is not running"));return}if(n.kind==="stopped"){console.log(Q.green(`\u2713 Bot stopped (PID ${n.pid})`));return}console.log(Q.yellow(`\u26A0 Bot force-killed (PID ${n.pid}); graceful shutdown timed out`))}),t.command("restart").description("Stop and restart the bot").action(async()=>{let n=await yi();(n.kind==="stopped"||n.kind==="force-killed")&&console.log(Q.gray(`Stopped (PID ${n.pid})`));let r=await hi();if(r.kind==="started"){console.log(Q.green(`\u2713 Bot restarted (PID ${r.pid})`));return}console.error(Q.red(`\u2717 Restart failed: ${r.message}`)),process.exit(1)}),t.command("status").description("Show running state, uptime, memory, and recent log entries").action(()=>{let n=ki();Gv(n)}),t.command("logs").description("Show or follow the bot log").option("-f, --follow","Stream new log entries (like tail -f)",!1).option("-n, --lines <count>","Number of trailing lines to show","50").action(n=>{let{logFile:r}=ki();if(!Wv(r)){console.log(Q.yellow(`No log file at ${r}`)),console.log(Q.gray("Start the bot first: afk telegram start"));return}let o=Number.parseInt(n.lines??"50",10);if(n.follow){Hv("tail",["-n",String(o),"-f",r],{stdio:"inherit"}).on("error",i=>{console.error(Q.red(`Failed to spawn tail: ${i.message}`))});return}let s=Kv(r,"utf-8").split(`
 `).slice(-o-1);console.log(s.join(`
-`))})}function Gv(e){if(console.log(Q.bold("\u{1F4CA} Telegram Bot Status")),console.log(""),e.running?(console.log(`  ${Q.green("\u25CF")} Running  (PID ${e.pid})`),e.uptimeSec!==void 0&&console.log(`  Uptime:  ${zv(e.uptimeSec)}`),e.memoryMb!==void 0&&console.log(`  Memory:  ${e.memoryMb} MB`)):console.log(`  ${Q.red("\u25CF")} Stopped`),console.log(`  PID:     ${e.pidFile}`),console.log(`  Logs:    ${e.logFile}`),e.logTail&&e.logTail.length>0){console.log(""),console.log(Q.bold("Recent log entries:"));for(let t of e.logTail)console.log(Q.gray(`  ${t}`))}}function zv(e){if(e<60)return`${e}s`;let t=Math.floor(e/60);if(t<60)return`${t}m ${e%60}s`;let n=Math.floor(t/60);return n<24?`${n}h ${t%60}m`:`${Math.floor(n/24)}d ${n%24}h`}import{readFileSync as qv}from"fs";import{dirname as Vv,join as Yv}from"path";import{fileURLToPath as Jv}from"url";function Wn(){try{return"2.3.0"}catch{}try{let e=Vv(Jv(import.meta.url));for(let t of["../../package.json","../package.json"])try{let n=JSON.parse(qv(Yv(e,t),"utf-8"));if(typeof n.version=="string")return n.version}catch{}}catch{}return"0.0.0-unknown"}import{spawn as Mp}from"child_process";import{existsSync as Xv,mkdirSync as Qv,readFileSync as Rp,unlinkSync as Zv,writeFileSync as ex}from"fs";import{join as $p}from"path";var tx=1440*60*1e3,nx="update-check.json",rx="pending-update.json";function Op(){return $p(Vn(),nx)}function wi(){return $p(Vn(),rx)}function Dp(){let e=Vn();Xv(e)||Qv(e,{recursive:!0})}function ox(e,t){let n=e.split(".").map(Number),r=t.split(".").map(Number),o=Math.max(n.length,r.length);for(let s=0;s<o;s++){let a=n[s]??0,i=r[s]??0;if(i>a)return!0;if(i<a)return!1}return!1}function sx(){try{let e=Rp(Op(),"utf-8"),t=JSON.parse(e);if(typeof t.latestVersion=="string"&&typeof t.checkedAt=="number")return t}catch{}return null}function ix(){try{Dp();let e=`
+`))})}function Gv(e){if(console.log(Q.bold("\u{1F4CA} Telegram Bot Status")),console.log(""),e.running?(console.log(`  ${Q.green("\u25CF")} Running  (PID ${e.pid})`),e.uptimeSec!==void 0&&console.log(`  Uptime:  ${zv(e.uptimeSec)}`),e.memoryMb!==void 0&&console.log(`  Memory:  ${e.memoryMb} MB`)):console.log(`  ${Q.red("\u25CF")} Stopped`),console.log(`  PID:     ${e.pidFile}`),console.log(`  Logs:    ${e.logFile}`),e.logTail&&e.logTail.length>0){console.log(""),console.log(Q.bold("Recent log entries:"));for(let t of e.logTail)console.log(Q.gray(`  ${t}`))}}function zv(e){if(e<60)return`${e}s`;let t=Math.floor(e/60);if(t<60)return`${t}m ${e%60}s`;let n=Math.floor(t/60);return n<24?`${n}h ${t%60}m`:`${Math.floor(n/24)}d ${n%24}h`}import{readFileSync as qv}from"fs";import{dirname as Vv,join as Yv}from"path";import{fileURLToPath as Jv}from"url";function Wn(){try{return"2.3.2"}catch{}try{let e=Vv(Jv(import.meta.url));for(let t of["../../package.json","../package.json"])try{let n=JSON.parse(qv(Yv(e,t),"utf-8"));if(typeof n.version=="string")return n.version}catch{}}catch{}return"0.0.0-unknown"}import{spawn as Mp}from"child_process";import{existsSync as Xv,mkdirSync as Qv,readFileSync as Rp,unlinkSync as Zv,writeFileSync as ex}from"fs";import{join as $p}from"path";var tx=1440*60*1e3,nx="update-check.json",rx="pending-update.json";function Op(){return $p(Vn(),nx)}function wi(){return $p(Vn(),rx)}function Dp(){let e=Vn();Xv(e)||Qv(e,{recursive:!0})}function ox(e,t){let n=e.split(".").map(Number),r=t.split(".").map(Number),o=Math.max(n.length,r.length);for(let s=0;s<o;s++){let a=n[s]??0,i=r[s]??0;if(i>a)return!0;if(i<a)return!1}return!1}function sx(){try{let e=Rp(Op(),"utf-8"),t=JSON.parse(e);if(typeof t.latestVersion=="string"&&typeof t.checkedAt=="number")return t}catch{}return null}function ix(){try{Dp();let e=`
       const https = require('https');
       const fs = require('fs');
       const url = 'https://registry.npmjs.org/agent-afk/latest';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-afk",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "CLI tool for interacting with AI agents via multiple interfaces",
   "main": "dist/index.mjs",
   "type": "module",
@@ -58,20 +58,18 @@
     "postinstall": "node dist/postinstall.mjs || true",
     "build": "tsc && node scripts/copy-prompts.js",
     "dev": "tsx watch src/cli/index.ts",
-    "start": "node dist/cli.mjs",
-    "start:chat": "node dist/cli.mjs chat",
-    "start:interactive": "node dist/cli.mjs interactive",
-    "start:status": "node dist/cli.mjs status",
-    "telegram": "node dist/cli.mjs telegram start",
-    "telegram:setup": "node dist/cli.mjs telegram setup",
-    "telegram:start": "node dist/cli.mjs telegram start",
-    "telegram:stop": "node dist/cli.mjs telegram stop",
-    "telegram:status": "node dist/cli.mjs telegram status",
-    "telegram:restart": "node dist/cli.mjs telegram restart",
-    "telegram:logs": "node dist/cli.mjs telegram logs",
+    "start": "node dist/cli/index.js",
+    "start:chat": "node dist/cli/index.js chat",
+    "start:interactive": "node dist/cli/index.js interactive",
+    "start:status": "node dist/cli/index.js status",
+    "telegram": "node dist/cli/index.js telegram start",
+    "telegram:setup": "node dist/cli/index.js telegram setup",
+    "telegram:start": "node dist/cli/index.js telegram start",
+    "telegram:stop": "node dist/cli/index.js telegram stop",
+    "telegram:status": "node dist/cli/index.js telegram status",
+    "telegram:restart": "node dist/cli/index.js telegram restart",
+    "telegram:logs": "node dist/cli/index.js telegram logs",
     "test": "vitest run",
-    "test:integration": "vitest run tests/integration",
-    "test:e2e": "vitest run tests/e2e",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest watch",
     "lint": "tsc --noEmit",