acpx 0.1.5 → 0.1.7

package/README.md

@@ -1,5 +1,15 @@
+<p align="center">
+  <img src="acpx_banner.svg" alt="acpx banner" width="100%" />
+</p>
+
 # acpx
 
+[![npm version](https://img.shields.io/npm/v/acpx.svg)](https://www.npmjs.com/package/acpx)
+[![npm downloads](https://img.shields.io/npm/dm/acpx.svg)](https://www.npmjs.com/package/acpx)
+[![CI](https://github.com/janitrai/acpx/actions/workflows/ci.yml/badge.svg)](https://github.com/janitrai/acpx/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/node/v/acpx.svg)](https://nodejs.org)
+
 Your agents love acpx! 🤖❤️ They hate having to scrape characters from a PTY session 😤
 
 `acpx` is a headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com), so AI agents and orchestrators can talk to coding agents over a structured protocol instead of PTY scraping.
@@ -63,14 +73,14 @@ Copy the block below and paste it into your OpenClaw, Pi, Claude Code, or simila
 I want you to use acpx to run coding agents over the Agent Client Protocol
 (ACP) instead of scraping PTY sessions. Please do the following:
 
-1. Install acpx (global is recommended for frequent use, but npx works fine too):
+1. Install acpx globally (recommended) or use npx:
    npm install -g acpx@latest
 
-   Or, run without installing:
+   Or without installing:
    npx acpx@latest
 
 2. Install the acpx skill so you have the full reference available:
-   acpx --skill export acpx | npx skillflag install
+   npx acpx@latest --skill install acpx
 
 3. Read the acpx skill reference so you know every command, flag, and
    workflow pattern:
@@ -81,9 +91,9 @@ I want you to use acpx to run coding agents over the Agent Client Protocol
 
 From now on, when you need to delegate work to a coding agent, use acpx
 instead of spawning raw terminal sessions. For example:
-  acpx codex "fix the failing tests"
-  acpx claude "refactor the auth module"
-  acpx codex exec "one-shot: summarize this repo"
+  npx acpx@latest codex "fix the failing tests"
+  npx acpx@latest claude "refactor the auth module"
+  npx acpx@latest codex exec "one-shot: summarize this repo"
 ```
 
 ## Install
@@ -139,6 +149,8 @@ acpx codex sessions show         # inspect cwd session metadata
 acpx codex sessions history      # show recent turn history
 acpx codex sessions new          # create fresh cwd-scoped default session
 acpx codex sessions new --name api # create fresh named session
+acpx codex sessions ensure       # return existing scoped session or create one
+acpx codex sessions ensure --name api # ensure named scoped session
 acpx codex sessions close        # close cwd-scoped default session
 acpx codex sessions close api    # close cwd-scoped named session
 acpx codex status                # local process status for current session
@@ -171,10 +183,12 @@ acpx codex -s release 'draft release notes from recent commits'
 acpx --approve-all codex 'apply the patch and run tests'
 acpx --approve-reads codex 'inspect repo structure and suggest plan' # default mode
 acpx --deny-all codex 'explain what you can do without tool access'
+acpx --non-interactive-permissions fail codex 'fail instead of deny in non-TTY'
 
 acpx --cwd ~/repos/backend codex 'review recent auth changes'
 acpx --format text codex 'summarize your findings'
 acpx --format json codex exec 'review changed files'
+acpx --format json --json-strict codex exec 'machine-safe JSON only'
 acpx --format quiet codex 'final recommendation only'
 
 acpx --timeout 90 codex 'investigate intermittent test timeout'
@@ -197,6 +211,8 @@ Supported keys:
 {
   "defaultAgent": "codex",
   "defaultPermissions": "approve-all",
+  "nonInteractivePermissions": "deny",
+  "authPolicy": "skip",
   "ttl": 300,
   "timeout": null,
   "format": "text",
@@ -221,10 +237,26 @@ acpx codex 'review this PR'
 acpx --format json codex exec 'review this PR' \
   | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'
 
+# json-strict: suppresses non-JSON stderr output (requires --format json)
+acpx --format json --json-strict codex exec 'review this PR'
+
 # quiet: final assistant text only
 acpx --format quiet codex 'give me a 3-line summary'
 ```
 
+JSON events include a stable envelope for correlation:
+
+```json
+{
+  "eventVersion": 1,
+  "sessionId": "abc123",
+  "requestId": "req-42",
+  "seq": 7,
+  "stream": "prompt",
+  "type": "tool_call"
+}
+```
+
 ## Built-in agents and custom servers
 
 Built-ins:
@@ -245,11 +277,12 @@ acpx --agent ./my-custom-acp-server 'do something'
 
 ## Session behavior
 
-- Prompt commands require an existing saved session record (created via `sessions new`).
+- Prompt commands require an existing saved session record (created via `sessions new` or `sessions ensure`).
 - Prompts route by walking up from `cwd` (or `--cwd`) to the nearest git root (inclusive) and selecting the nearest active session matching `(agent command, dir, optional name)`.
 - If no git root is found, prompts only match an exact `cwd` session (no parent-directory walk).
 - `-s <name>` selects a parallel named session during that directory walk.
 - `sessions new [--name <name>]` creates a fresh session for that scope and soft-closes the prior one.
+- `sessions ensure [--name <name>]` is idempotent: it returns an existing scoped session or creates one when missing.
 - `sessions close [name]` soft-closes the session: queue owner/processes are terminated, record is kept with `closed: true`.
 - Auto-resume for cwd scope skips sessions marked closed.
 - Prompt submissions are queue-aware per session. If a prompt is already running, new prompts are queued and drained by the running `acpx` process.