acpx 0.1.0 → 0.1.3

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "acpx",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Headless CLI client for the Agent Client Protocol (ACP) — talk to coding agents from the command line",
   "type": "module",
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -13,9 +14,18 @@
   },
   "scripts": {
     "build": "tsup src/cli.ts --format esm --dts --clean",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test dist-test/test/*.test.js",
+    "prepare": "husky",
+    "precommit": "npm exec -- lint-staged && npm run -s build",
     "prepack": "npm run build",
     "dev": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings=0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "release": "release-it",
+    "release:ci": "release-it --ci"
   },
   "keywords": [
     "acp",
@@ -27,7 +37,7 @@
     "ai"
   ],
   "author": "Janitr AI",
-  "license": "Apache-2.0",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/janitrai/acpx.git"
@@ -37,12 +47,30 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.14.1",
-    "commander": "^13.0.0"
+    "commander": "^13.0.0",
+    "skillflag": "^0.1.3"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.0.0",
+    "globals": "^17.3.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "release-it": "^19.2.4",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "typescript-eslint": "^8.56.0"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "prettier --write --ignore-unknown",
+      "eslint --fix"
+    ],
+    "*.{json,md}": [
+      "prettier --write --ignore-unknown"
+    ]
   }
 }

package/skills/acpx/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: acpx
+description: Use acpx as a headless ACP CLI for agent-to-agent communication, including prompt/exec/sessions workflows, session scoping, queueing, permissions, and output formats.
+---
+
+# acpx
+
+## When to use this skill
+
+Use this skill when you need to run coding agents through `acpx`, manage persistent ACP sessions, queue prompts, or consume structured agent output from scripts.
+
+## What acpx is
+
+`acpx` is a headless, scriptable CLI client for the Agent Client Protocol (ACP). It is built for agent-to-agent communication over the command line and avoids PTY scraping.
+
+Core capabilities:
+
+- Persistent multi-turn sessions per repo/cwd
+- One-shot execution mode (`exec`)
+- Named parallel sessions (`-s/--session`)
+- Queue-aware prompt submission with optional fire-and-forget (`--no-wait`)
+- Structured streaming output (`text`, `json`, `quiet`)
+- Built-in agent registry plus raw `--agent` escape hatch
+
+## Install
+
+```bash
+npm i -g acpx
+```
+
+For normal session reuse, prefer a global install over `npx`.
+
+## Command model
+
+`prompt` is the default verb.
+
+```bash
+acpx [global_options] [prompt_text...]
+acpx [global_options] prompt [prompt_options] [prompt_text...]
+acpx [global_options] exec [prompt_text...]
+acpx [global_options] sessions [list | new [--name <name>] | close [name]]
+
+acpx [global_options] <agent> [prompt_options] [prompt_text...]
+acpx [global_options] <agent> prompt [prompt_options] [prompt_text...]
+acpx [global_options] <agent> exec [prompt_text...]
+acpx [global_options] <agent> sessions [list | new [--name <name>] | close [name]]
+```
+
+If prompt text is omitted and stdin is piped, `acpx` reads prompt text from stdin.
+
+## Built-in agent registry
+
+Friendly agent names resolve to commands:
+
+- `codex` -> `npx @zed-industries/codex-acp`
+- `claude` -> `npx @zed-industries/claude-agent-acp`
+- `gemini` -> `gemini`
+- `opencode` -> `npx opencode-ai`
+- `pi` -> `npx pi-acp`
+
+Rules:
+
+- Default agent is `codex` for top-level `prompt`, `exec`, and `sessions`.
+- Unknown positional agent tokens are treated as raw agent commands.
+- `--agent <command>` explicitly sets a raw ACP adapter command.
+- Do not combine a positional agent and `--agent` in the same command.
+
+## Commands
+
+### Prompt (default, persistent session)
+
+Implicit:
+
+```bash
+acpx codex 'fix flaky tests'
+```
+
+Explicit:
+
+```bash
+acpx codex prompt 'fix flaky tests'
+acpx prompt 'fix flaky tests'   # defaults to codex
+```
+
+Behavior:
+
+- Uses a saved session for the session scope key
+- Auto-resumes prior session when one exists for that scope
+- Creates a new session record when none exists
+- Is queue-aware when another prompt is already running for the same session
+
+Prompt options:
+
+- `-s, --session <name>`: use a named session within the same cwd
+- `--no-wait`: enqueue and return immediately when session is already busy
+
+### Exec (one-shot)
+
+```bash
+acpx exec 'summarize this repo'
+acpx codex exec 'summarize this repo'
+```
+
+Behavior:
+
+- Runs a single prompt in a temporary ACP session
+- Does not reuse or save persistent session state
+
+### Sessions
+
+```bash
+acpx sessions
+acpx sessions list
+acpx sessions new
+acpx sessions new --name backend
+acpx sessions close
+acpx sessions close backend
+
+acpx codex sessions
+acpx codex sessions new --name backend
+acpx codex sessions close backend
+```
+
+Behavior:
+
+- `sessions` and `sessions list` are equivalent
+- `new` creates a fresh session for the current `(agentCommand, cwd, optional name)` scope
+- `new --name <name>` targets a named session scope
+- when `new` replaces an existing open session in that scope, the old one is soft-closed
+- `close` targets current cwd default session
+- `close <name>` targets current cwd named session
+
+## Global options
+
+- `--agent <command>`: raw ACP agent command (escape hatch)
+- `--cwd <dir>`: working directory for session scope (default: current directory)
+- `--approve-all`: auto-approve all permission requests
+- `--approve-reads`: auto-approve reads/searches, prompt for writes (default mode)
+- `--deny-all`: deny all permission requests
+- `--format <fmt>`: output format (`text`, `json`, `quiet`)
+- `--timeout <seconds>`: max wait time (positive number)
+- `--ttl <seconds>`: queue owner idle TTL before shutdown (default `300`, `0` disables TTL)
+- `--verbose`: verbose ACP/debug logs to stderr
+
+Permission flags are mutually exclusive.
+
+## Session behavior
+
+Persistent prompt sessions are scoped by:
+
+- `agentCommand`
+- absolute `cwd`
+- optional session `name`
+
+Persistence:
+
+- Session records are stored in `~/.acpx/sessions/*.json`.
+- `-s/--session` creates parallel named conversations in the same repo.
+- Changing `--cwd` changes scope and therefore session lookup.
+- closed sessions are retained on disk with `closed: true` and `closedAt`.
+- auto-resume by scope skips closed sessions.
+
+Resume behavior:
+
+- Prompt mode attempts to reconnect to saved session.
+- If adapter-side session is invalid/not found, `acpx` creates a fresh session and updates the saved record.
+- explicitly selected session records can still be resumed via `loadSession` even if previously closed.
+
+## Prompt queueing and `--no-wait`
+
+Queueing is per persistent session.
+
+- The active `acpx` process for a running prompt becomes the queue owner.
+- Other invocations submit prompts over local IPC.
+- On Unix-like systems, queue IPC uses a Unix socket under `~/.acpx/queues/<hash>.sock`.
+- Ownership is coordinated with a lock file under `~/.acpx/queues/<hash>.lock`.
+- On Windows, named pipes are used instead of Unix sockets.
+- after the queue drains, owner shutdown is governed by TTL (default 300s, configurable with `--ttl`).
+
+Submission behavior:
+
+- Default: enqueue and wait for queued prompt completion, streaming updates back.
+- `--no-wait`: enqueue and return after queue acknowledgement.
+
+## Output formats
+
+Use `--format <fmt>`:
+
+- `text` (default): human-readable stream with updates/tool status and done line
+- `json`: NDJSON event stream (good for automation)
+- `quiet`: final assistant text only
+
+Example automation:
+
+```bash
+acpx --format json codex exec 'review changed files' \
+  | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'
+```
+
+## Permission modes
+
+- `--approve-all`: no interactive permission prompts
+- `--approve-reads` (default): approve reads/searches, prompt for writes
+- `--deny-all`: deny all permission requests
+
+If every permission request is denied/cancelled and none approved, `acpx` exits with permission-denied status.
+
+## Practical workflows
+
+Persistent repo assistant:
+
+```bash
+acpx codex 'inspect failing tests and propose a fix plan'
+acpx codex 'apply the smallest safe fix and run tests'
+```
+
+Parallel named streams:
+
+```bash
+acpx codex -s backend 'fix API pagination bug'
+acpx codex -s docs 'draft changelog entry for release'
+```
+
+Queue follow-up without waiting:
+
+```bash
+acpx codex 'run full test suite and investigate failures'
+acpx codex --no-wait 'after tests, summarize root causes and next steps'
+```
+
+One-shot script step:
+
+```bash
+acpx --format quiet exec 'summarize repo purpose in 3 lines'
+```
+
+Machine-readable output for orchestration:
+
+```bash
+acpx --format json codex 'review current branch changes' > events.ndjson
+```
+
+Raw custom adapter command:
+
+```bash
+acpx --agent './bin/custom-acp-server --profile ci' 'run validation checks'
+```
+
+Repo-scoped review with permissive mode:
+
+```bash
+acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
+  'review PR #842 for regressions and propose minimal patch'
+```