acpx 0.1.6 → 0.1.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Janitr AI
+Copyright (c) 2025 OpenClaw Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,10 +6,13 @@
 
 [![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)
+[![CI](https://github.com/openclaw/acpx/actions/workflows/ci.yml/badge.svg)](https://github.com/openclaw/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)
 
+> Alpha notice: `acpx` is in alpha and the CLI/runtime interfaces are likely to change.
+> ACP coverage status: see [ACP Spec Coverage Roadmap](docs/2026-02-19-acp-coverage-roadmap.md).
+
 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.
@@ -73,15 +76,21 @@ 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 the acpx skill so you have the full reference available:
+1. Install acpx globally (recommended) or use npx:
+   npm install -g acpx@latest
+
+   Or without installing:
+   npx acpx@latest
+
+2. Install the acpx skill so you have the full reference available:
    npx acpx@latest --skill install acpx
 
-2. Read the acpx skill reference so you know every command, flag, and
+3. 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
+   https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md
 
-3. If you need the full CLI reference with all options and examples:
-   https://raw.githubusercontent.com/janitrai/acpx/main/docs/CLI.md
+4. If you need the full CLI reference with all options and examples:
+   https://raw.githubusercontent.com/openclaw/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:
@@ -143,6 +152,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
@@ -175,10 +186,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'
@@ -201,6 +214,8 @@ Supported keys:
 {
   "defaultAgent": "codex",
   "defaultPermissions": "approve-all",
+  "nonInteractivePermissions": "deny",
+  "authPolicy": "skip",
   "ttl": 300,
   "timeout": null,
   "format": "text",
@@ -225,10 +240,29 @@ 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"
+}
+```
+
+Session-control JSON payloads (`sessions new|ensure`, `status`) may also include
+`runtimeSessionId` when the adapter exposes a provider-native session ID.
+
 ## Built-in agents and custom servers
 
 Built-ins:
@@ -249,11 +283,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.

package/dist/cli.d.ts

@@ -10,6 +10,7 @@ type SessionHistoryEntry = {
 type SessionRecord = {
     id: string;
     sessionId: string;
+    runtimeSessionId?: string;
     agentCommand: string;
     cwd: string;
     name?: string;