diff --git a/AGENTS.md b/AGENTS.md index 5f17ba5..2ad6a7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,15 +36,23 @@ npm run lint:fix # biome check --write - `src/launch-orchestrator.ts` — Parallel multi-adapter launch orchestration (group IDs, worktree creation, parallel dispatch) - `src/matrix-parser.ts` — YAML matrix file parser + cross-product expansion for sweep launches - `src/worktree.ts` — Git worktree create/list/clean utilities -- `src/hooks.ts` — Lifecycle hook runner (env vars: SESSION_ID, CWD, ADAPTER, BRANCH, EXIT_CODE, GROUP, MODEL) +- `src/hooks.ts` — Lifecycle hook runner (env vars: AGENTCTL_SESSION_ID, AGENTCTL_CWD, AGENTCTL_ADAPTER, AGENTCTL_BRANCH, AGENTCTL_EXIT_CODE, AGENTCTL_GROUP, AGENTCTL_MODEL) - `src/cli.ts` — CLI entry point (commander) - `src/daemon/server.ts` — Daemon: Unix socket server + HTTP metrics +- `src/daemon/supervisor.ts` — Daemon supervisor (auto-restart on crash) - `src/daemon/session-tracker.ts` — Session lifecycle tracking - `src/daemon/lock-manager.ts` — Auto + manual directory locks - `src/daemon/fuse-engine.ts` — Generic directory-scoped TTL fuse timers with configurable on-expire actions +- `src/daemon/webhook.ts` — Webhook event emission (session.stopped) - `src/daemon/metrics.ts` — Prometheus metrics registry - `src/daemon/state.ts` — State persistence layer - `src/client/daemon-client.ts` — Unix socket client for CLI +- `src/file-context.ts` — File context builder (--file/--spec flags) +- `src/utils/config.ts` — Configuration loading (~/.agentctl/config.json) +- `src/utils/resolve-binary.ts` — Binary path resolution +- `src/utils/prompt-file.ts` — Prompt file handling (large prompts via temp files) +- `src/utils/spawn-with-retry.ts` — Spawn with ENOENT retry +- `src/utils/display.ts` — Display formatting utilities - `src/migration/migrate-locks.ts` — Migration from ~/.openclaw/locks ## Conventions @@ -65,7 +73,7 @@ npm run lint:fix # biome check --write ./scripts/release.sh [patch|minor|major] ``` -Bumps version, builds, tags, and runs `npm link`. No npm publish (local tool). +Bumps version, builds, and pushes release branch. Tag push triggers npm publish via GitHub Actions. See RELEASING.md for full workflow. ## CI diff --git a/CHANGELOG.md b/CHANGELOG.md index 9148776..deec9c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] -## [1.5.0] - 2026-02-26 +### Added + +- Phase 1 ACP adoption — Codex adapter via ACP transport (#125, #127) +- Lifecycle webhooks for `session.stopped` payloads (#123) +- Callback metadata (`--callback-session`, `--callback-agent`) for orchestration (#123) +- Spawn ENOENT retry for adapter launch resilience (#123) +- Complete stateless daemon core — eliminate remaining shadow state (#117) + +### Fixed + +- Eliminate pending- session IDs — resolve real ID at launch (#131) +- Webhook emit numeric `exit_status` + compatible HMAC headers (#128) +- Eliminate daemon-env.json — derive env at spawn time (#119) +- Update resolve-binary util (#121) + +### Docs + +- ADR-001: adopt ACP as primary agent interface (#126) + +## [1.6.0] - 2026-03-06 + +### Added + +- `--file` flag to include context files in launch prompts (#95) +- Use `history.jsonl` for Claude Code discover(), batch `lsof` calls (#96) + +### Fixed + +- Insert `--` separator before positional prompt args in codex/opencode/pi-rust (#106) +- Peek/status timeout on opencode sessions (#100) +- Use temp file for large prompts instead of CLI args (#101) + +## [1.5.2] - 2026-03-02 + +### Fixed + +- OpenCode detach, matrix prompt override, persistent config defaults (#87) +- Worktree slug collisions, pi-rust `--provider`/`--append-system-prompt` (#83) +- Pass `--model` flag when launching OpenCode (#79) + +## [1.5.1] - 2026-02-27 + +### Fixed + +- Resolve P0+P1 launcher/docs regressions (#76) + +## [1.5.0] - 2026-02-25 ### Added diff --git a/README.md b/README.md index 6471e37..adc318c 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,11 @@ Universal interface for supervising coding agents. Launch, monitor, resume, inte agentctl reads from native sources (Claude Code's `~/.claude/` directory, Pi's `~/.pi/` directory, running processes) and provides a standard control plane to list, inspect, stop, launch, and resume agent sessions. It never replicates state — it reads what's actually happening. -## Layer Model +## Design Philosophy -| Layer | Role | -|-------|------| -| **agentctl** | Read/control interface. Discovers sessions, emits lifecycle events. | -| **OrgLoop** | Routes lifecycle events to mechanical reactions (cluster fuse, notifications). | -| **OpenClaw** | Reasoning layer. Makes judgment calls about what to do. | +agentctl intentionally does **not** maintain its own session registry — it reads native agent sources and cross-references running processes. The daemon tracks only launch metadata, directory locks, and fuse timers. This keeps agentctl grounded in what is actually running, not a shadow copy that drifts out of date. -agentctl intentionally does **not**: -- Maintain its own session registry (reads native sources) -- Have a hook/reaction system (that's OrgLoop) -- Make judgment calls about what to do (that's OpenClaw) +agentctl provides lightweight operational hooks (lifecycle hooks, webhooks) for reacting to session events, but leaves higher-level judgment — what to do about a failed run, whether to retry, how to route work — to systems above it. ## Why agentctl? @@ -23,7 +16,7 @@ You can use `claude code` (or any agent CLI) directly — agentctl is not a repl The practical value is simple: launch work, see what's running, resume interrupted sessions, stop the ones that went sideways, and compare outcomes across adapters without learning a different control surface for each one. That operator UX matters whether the supervisor is a human juggling multiple sessions or another agent coordinating work on your behalf. -What it adds today: session discovery across running agents, lifecycle tracking that persists session info even after processes exit, a daemon with directory locks to prevent duplicate launches on the same working directory, fuse timers for automated resource cleanup, and a standard interface that works the same regardless of which coding agent is underneath. The adapter model means support for additional agent runtimes can be added without changing the CLI or daemon interface. +What it adds today: session discovery across running agents, lifecycle tracking that persists session info even after processes exit, a daemon with directory locks to prevent duplicate launches on the same working directory, fuse timers for automated resource cleanup, webhooks for external integrations, and a standard interface that works the same regardless of which coding agent is underneath. The adapter model means support for additional agent runtimes can be added without changing the CLI or daemon interface. The bigger idea is modest but useful: agentctl is a universal control plane for coding agents. It focuses on the operational layer — launch, monitor, resume, interrupt, compare — while leaving native execution to each adapter and higher-level judgment to systems above it. @@ -65,6 +58,9 @@ agentctl launch -p "Read the spec and implement phase 2" # Launch in a specific directory agentctl launch -p "Fix the auth bug" --cwd ~/code/mono +# Launch with context files +agentctl launch -p "Implement the feature" --file spec.md --file examples.ts + # Launch a new Pi session agentctl launch pi -p "Refactor the auth module" @@ -149,8 +145,9 @@ Array values in `model` are expanded via cross-product. ```bash agentctl list [options] - --adapter Filter by adapter (claude-code, codex, opencode, pi, pi-rust, openclaw) + --adapter Filter by adapter (claude-code, codex, codex-acp, opencode, pi, pi-rust, openclaw) --status Filter by status (running|stopped|idle|error) + --group Filter by launch group (e.g. g-a1b2c3) -a, --all Include stopped sessions (last 7 days) --json Output as JSON @@ -158,18 +155,29 @@ agentctl status [options] --adapter Adapter to use --json Output as JSON -agentctl peek|logs [options] +agentctl peek [options] -n, --lines Number of recent messages (default: 20) --adapter Adapter to use +agentctl logs [options] + -n, --lines Number of recent messages (default: 50) + --adapter Adapter to use + agentctl launch [adapter] [options] -p, --prompt Prompt to send (required) --spec Spec file path + --file File to include in context (repeatable) + --max-file-size Max file size in bytes (default: 51200) --cwd Working directory (default: current directory) --model Model to use (e.g. sonnet, opus) --adapter Adapter to launch (repeatable for parallel launch) --matrix YAML matrix file for advanced sweep launch - --group Filter by launch group (for list command) + --worktree Auto-create git worktree for isolation + --branch Branch name for worktree + --on-create