agent-devkit 0.8.3 → 0.8.9

package/README.md

@@ -9,8 +9,11 @@ of truth; this document does not promise a specific release.
 ## Status
 
 Active development. The runtime ships a personality-driven chat and task
-agent (CLI, TUI and MCP), multi-provider brains with fallback, persisted
-runs/goals/memory and multi-agent delegation.
+agent, CLI and MCP adapters, multi-provider brains with fallback, persisted
+runs/goals/memory, multi-agent delegation, catalog-driven tooling management,
+environment inventory and project scaffolding.
+It also includes a local background runtime for queued jobs, schedules,
+memory processing, reusable automations and maintenance.
 
 ## Install
 
@@ -57,6 +60,13 @@ npm run docker:agent -- --help
 npm run --silent docker:agent -- doctor --json
 npm run --silent docker:agent -- init --dry-run
 npm run --silent docker:agent -- install node --verify --json
+npm run --silent docker:agent -- scaffold list --json
+npm run --silent docker:agent -- scaffold plan react-vite --name demo --dir /tmp --json
+npm run --silent docker:agent -- background status --json
+npm run --silent docker:agent -- background run-once --json
+npm run --silent docker:agent -- watch --once --json
+npm run --silent docker:agent -- automations list --json
+npm run --silent docker:agent -- automations fit "create markdown document" --automation document-template --json
 npm run --silent docker:agent -- reset --dry-run
 npm run --silent docker:agent -- update --latest --dry-run
 npm run --silent docker:agent -- tools --json
@@ -114,6 +124,10 @@ src/
     helpers/
 
   assets/
+    mcp/
+    scaffolds/
+    automations/
+    tooling/
     fonts/
     i18n/
     images/
@@ -129,6 +143,9 @@ Rules:
 - A module surface is the canonical agentic interface for that domain.
 - Surface capability metadata is derived from capability configs to avoid drift.
 - The tool runtime is the canonical execution socket for CLI, MCP, TUI and future agent loops.
+- The background runtime is the canonical async execution socket. Features dispatch
+  jobs through `BackgroundDispatcherPort`; retry, locks, pid/process control,
+  permissions, worker pool status and audit belong to `src/infra/background`.
 - A capability owns its entities, service, repository implementation, view model and tests.
 - `infra` contains only global low-level bases and reusable helpers.
 - Capability services must return `Result<left, right>` from `infra/bases/result.ts`.
@@ -140,6 +157,10 @@ Rules:
 - Postgres and Redis clients must use injected executors.
 - File serialization lives in `infra/files` and supports JSON, TXT, MD and PDF/binary payloads.
 - Asset loading lives in `infra/assets` and reads from the canonical `src/assets` folders.
+- Canonical external integration catalogs live in `src/assets/tooling`, `src/assets/mcp` and
+  `src/assets/scaffolds`; canonical reusable automations live in
+  `src/assets/automations`; local learned definitions live under
+  `~/.agent-devkit/data/`.
 - `app` calls module bindings instead of reaching into filesystem, npm or process details directly.
 
 ## Distribution
@@ -173,6 +194,9 @@ Runtime data uses a canonical local store layout:
     logs/
     secrets/
     context/
+    automations/
+      audit.jsonl
+      candidates/
   keys/
 ```
 
@@ -203,20 +227,39 @@ agent runs
 agent runs show <run-id>
 agent runs events <run-id>
 agent runs resume <run-id>
+agent watch
+agent watch --once --json
+agent watch --background --memory --logs
+agent automations list
+agent automations search "task"
+agent automations fit "task" --automation document-template
+agent automations run document-template --input '{"outputPath":"./doc.md"}' --yes
+agent automations candidate create ./my-automation --yes
+agent automations curator status
 agent goals
 agent goals create "Ship the release"
 agent memory
 agent memory learn "User prefers concise replies" --kind preference
 agent integrations
+agent integrations mcp catalog
+agent integrations mcp register-catalog playwright --yes
 agent tools
 agent tools --json
+agent env scan --scope full --persist --json
+agent env inventory
+agent env background status
 agent install node --dry-run
 agent install node --verify
 agent tooling list
 agent tooling plan-install gemini
 agent tooling upgrade claude --yes
+agent scaffold list
+agent scaffold show flutter-app
+agent scaffold plan react-vite --name food-delivery --dir .
+agent scaffold create node-cli --name demo-cli --dir /tmp --yes
 agent run project.doctor --input '{}' --json
 agent run environment.tooling --input '{"action":"detect","toolingId":"node"}' --json
+agent run project.scaffold --input '{"action":"plan","id":"react-vite","variables":{"name":"demo","directory":"."}}' --json
 agent run project.reset --input '{"confirmed":true,"dryRun":false,"homeDirectory":"/tmp/home","projectRoot":"/tmp/project","scope":"project"}' --approve --json
 agent mcp
 agent mcp stdio
@@ -283,6 +326,11 @@ Runs are inspectable and resumable through `agent runs` and `agent goals`.
 Direct capability calls from the TUI and CLI act with the user's own
 privileges; the approval gates protect the agentic path.
 
+`agent watch` provides a live terminal snapshot of the runtime: background
+queue and workers, memory manager, recent runs, automations and recent log
+errors/warnings. The same data is available as the read-only `runtime.watch`
+capability, so CLI, MCP and the agent consume one shared observability contract.
+
 Global memory lives in the `memory` module: records have kind
 (`fact`, `preference`, `pattern`, `decision`, `episode`), status
 (`candidate`, `active`, `rejected`, `forgotten`), confidence, evidence refs
@@ -378,6 +426,47 @@ Official tooling definitions live in `src/assets/tooling/`. User-learned or
 promoted definitions live under `~/.agent-devkit/data/tooling/` and are loaded
 through the same catalog.
 
+## Environment Inventory and MCP Catalog
+
+The environment module can scan the local machine, persist an inventory and let
+the agent answer later without rescanning every time.
+
+```bash
+agent env scan --scope quick --json
+agent env scan --scope full --persist --root ~/dev --json
+agent env inventory
+agent env inventory projects
+agent env inventory mcp
+agent env background enable --root ~/dev --cadence weekly --yes
+agent env background run-now --yes
+```
+
+Full scans can discover PATH commands, supported tooling, project markers and
+external MCP config files. Persisted inventory is stored under
+`~/.agent-devkit/data/environment/`. `agent env background run-now` queues an
+`environment.scan` job in the background runtime; use `agent background run-once`
+or a running background process to execute it.
+
+Canonical MCP server definitions live in `src/assets/mcp/`. User-added or
+imported MCP definitions live under `~/.agent-devkit/data/mcp/` and are managed
+through `agent integrations mcp`.
+
+## Project Scaffolding
+
+Project scaffolds are catalog definitions consumed by CLI, MCP and the agent
+runtime through the `project.scaffold` capability.
+
+```bash
+agent scaffold list
+agent scaffold show next-app
+agent scaffold plan flutter-app --name delivery_app --dir ~/dev
+agent scaffold create node-cli --name demo-cli --dir /tmp --yes
+agent scaffold validate react-vite --name demo --dir /tmp
+```
+
+Built-in definitions live in `src/assets/scaffolds/`. Local draft and promoted
+definitions live under `~/.agent-devkit/data/scaffolds/`.
+
 ## Internal Docs
 
 The local `docs/` folder is intentionally ignored by Git. Public documentation