acpx 0.1.4 → 0.1.6

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.
@@ -9,9 +19,19 @@ One command surface for Codex, Claude, Gemini, OpenCode, Pi, or custom ACP serve
 - **Persistent sessions**: multi-turn conversations that survive across invocations, scoped per repo
 - **Named sessions**: run parallel workstreams in the same repo (`-s backend`, `-s frontend`)
 - **Prompt queueing**: submit prompts while one is already running, they execute in order
+- **Cooperative cancel command**: `cancel` sends ACP `session/cancel` via queue IPC without tearing down session state
 - **Soft-close lifecycle**: close sessions without deleting history from disk
 - **Queue owner TTL**: keep queue owners alive briefly for follow-up prompts (`--ttl`)
 - **Fire-and-forget**: `--no-wait` queues a prompt and returns immediately
+- **Graceful cancel**: `Ctrl+C` sends ACP `session/cancel` before force-kill fallback
+- **Session controls**: `set-mode` and `set <key> <value>` for `session/set_mode` and `session/set_config_option`
+- **Crash reconnect**: dead agent processes are detected and sessions are reloaded automatically
+- **Prompt from file/stdin**: `--file <path>` or piped stdin for prompt content
+- **Config files**: global + project JSON config with `acpx config show|init`
+- **Session inspect/history**: `sessions show` and `sessions history --limit <n>`
+- **Local status checks**: `status` reports running/dead/no-session, pid, uptime, last prompt
+- **Client methods**: stable `fs/*` and `terminal/*` handlers with permission controls and cwd sandboxing
+- **Auth handshake**: stable `authenticate` support via env/config credentials
 - **Structured output**: typed ACP messages (thinking, tool calls, diffs) instead of ANSI scraping
 - **Any ACP agent**: built-in registry + `--agent` escape hatch for custom servers
 - **One-shot mode**: `exec` for stateless fire-and-forget tasks
@@ -53,33 +73,36 @@ 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 globally:
-   npm i -g acpx
+1. Install the acpx skill so you have the full reference available:
+   npx acpx@latest --skill install acpx
 
-2. Install the acpx skill so you have the full reference available:
-   acpx --skill export acpx | npx skillflag install
-
-3. Read the acpx skill reference so you know every command, flag, and
+2. Read the acpx skill reference so you know every command, flag, and
    workflow pattern:
    https://raw.githubusercontent.com/janitrai/acpx/main/skills/acpx/SKILL.md
 
-4. If you need the full CLI reference with all options and examples:
+3. If you need the full CLI reference with all options and examples:
    https://raw.githubusercontent.com/janitrai/acpx/main/docs/CLI.md
 
 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
 
 ```bash
-npm i -g acpx
+npm install -g acpx@latest
+```
+
+Or run without installing:
+
+```bash
+npx acpx@latest codex "fix the tests"
 ```
 
-`acpx` manages persistent sessions, so prefer a global install. Avoid `npx acpx ...` for normal use.
+Session state lives in `~/.acpx/` either way. Global install is a little faster, but `npx acpx@latest` works fine.
 
 ## Agent prerequisites
 
@@ -99,7 +122,13 @@ The only prerequisite is the underlying coding agent you want to use:
 acpx codex sessions new                        # create a session (explicit) for this project dir
 acpx codex 'fix the tests'                     # implicit prompt (routes via directory-walk)
 acpx codex prompt 'fix the tests'              # explicit prompt subcommand
+echo 'fix flaky tests' | acpx codex            # prompt from stdin
+acpx codex --file prompt.md                    # prompt from file
+acpx codex --file - "extra context"            # explicit stdin + appended args
 acpx codex --no-wait 'draft test migration plan' # enqueue without waiting if session is busy
+acpx codex cancel                               # cooperative cancel of in-flight prompt
+acpx codex set-mode plan                        # session/set_mode
+acpx codex set approval_policy conservative     # session/set_config_option
 acpx exec 'summarize this repo'                # default agent shortcut (codex)
 acpx codex exec 'what does this repo do?'      # one-shot, no saved session
 
@@ -110,10 +139,16 @@ acpx codex -s docs 'rewrite API docs'           # parallel work in another named
 
 acpx codex sessions              # list sessions for codex command
 acpx codex sessions list         # explicit list
+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 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
+
+acpx config show                 # show resolved config (global + project)
+acpx config init                 # create ~/.acpx/config.json template
 
 acpx claude 'refactor auth middleware' # built-in claude agent
 acpx gemini 'add startup logging'      # built-in gemini agent
@@ -151,6 +186,35 @@ acpx --ttl 30 codex 'keep queue owner alive for quick follow-ups'
 acpx --verbose codex 'debug why adapter startup is failing'
 ```
 
+## Configuration files
+
+`acpx` reads config in this order (later wins):
+
+1. global: `~/.acpx/config.json`
+2. project: `<cwd>/.acpxrc.json`
+
+CLI flags always win over config values.
+
+Supported keys:
+
+```json
+{
+  "defaultAgent": "codex",
+  "defaultPermissions": "approve-all",
+  "ttl": 300,
+  "timeout": null,
+  "format": "text",
+  "agents": {
+    "my-custom": { "command": "./bin/my-acp-server" }
+  },
+  "auth": {
+    "my_auth_method_id": "credential-value"
+  }
+}
+```
+
+Use `acpx config show` to inspect the resolved result and `acpx config init` to create the global template.
+
 ## Output formats
 
 ```bash
@@ -195,8 +259,13 @@ acpx --agent ./my-custom-acp-server 'do something'
 - Prompt submissions are queue-aware per session. If a prompt is already running, new prompts are queued and drained by the running `acpx` process.
 - Queue owners use an idle TTL (default 300s). `--ttl <seconds>` overrides it; `--ttl 0` keeps owners alive indefinitely.
 - `--no-wait` submits to that queue and returns immediately.
+- `cancel` sends cooperative `session/cancel` to the running queue owner process and returns success when no prompt is running (`nothing to cancel`).
+- `set-mode` and `set` route through queue-owner IPC when active, otherwise they reconnect directly to apply `session/set_mode` and `session/set_config_option`.
 - `exec` is always one-shot and does not reuse saved sessions.
 - Session metadata is stored under `~/.acpx/sessions/`.
+- Each successful prompt appends lightweight turn history previews (`role`, `timestamp`, `textPreview`) to session metadata.
+- `Ctrl+C` during a running turn sends ACP `session/cancel` and waits briefly for `stopReason=cancelled` before force-killing if needed.
+- If a saved session pid is dead on the next prompt, `acpx` respawns the agent, attempts `session/load`, and transparently falls back to `session/new` if loading fails.
 
 ## Full CLI reference
 

package/dist/cli.d.ts

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 import { AgentCapabilities } from '@agentclientprotocol/sdk';
 
+type SessionHistoryRole = "user" | "assistant";
+type SessionHistoryEntry = {
+    role: SessionHistoryRole;
+    timestamp: string;
+    textPreview: string;
+};
 type SessionRecord = {
     id: string;
     sessionId: string;
@@ -12,6 +18,13 @@ type SessionRecord = {
     closed?: boolean;
     closedAt?: string;
     pid?: number;
+    agentStartedAt?: string;
+    lastPromptAt?: string;
+    lastAgentExitCode?: number | null;
+    lastAgentExitSignal?: NodeJS.Signals | null;
+    lastAgentExitAt?: string;
+    lastAgentDisconnectReason?: string;
+    turnHistory?: SessionHistoryEntry[];
     protocolVersion?: number;
     agentCapabilities?: AgentCapabilities;
 };