acpx 0.1.2 → 0.1.4

package/README.md

@@ -9,12 +9,15 @@ 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
+- **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
 - **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
 
 ```bash
+$ acpx codex sessions new
 $ acpx codex "find the flaky test and fix it"
 
 [thinking] Investigating test suite for flaky failures
@@ -42,6 +45,34 @@ reading stale state from the previous run.
 [done] end_turn
 ```
 
+## Quick setup — tell your agent about acpx
+
+Copy the block below and paste it into your OpenClaw, Pi, Claude Code, or similar agent harness. It will install acpx, read the skill reference, and know how to use ACP for all future coding agent tasks.
+
+```text
+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
+
+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
+   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:
+   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"
+```
+
 ## Install
 
 ```bash
@@ -65,17 +96,22 @@ The only prerequisite is the underlying coding agent you want to use:
 ## Usage examples
 
 ```bash
-acpx codex 'fix the tests'                     # implicit prompt (persistent session)
+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
 acpx codex --no-wait 'draft test migration plan' # enqueue without waiting if session is busy
 acpx exec 'summarize this repo'                # default agent shortcut (codex)
 acpx codex exec 'what does this repo do?'      # one-shot, no saved session
 
-acpx codex -s api 'implement cursor pagination' # named session
+acpx codex sessions new --name api              # create named session
+acpx codex -s api 'implement cursor pagination' # prompt in named session
+acpx codex sessions new --name docs             # create another named session
 acpx codex -s docs 'rewrite API docs'           # parallel work in another named session
 
 acpx codex sessions              # list sessions for codex command
 acpx codex sessions list         # explicit list
+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
 
@@ -111,6 +147,7 @@ acpx --format json codex exec 'review changed files'
 acpx --format quiet codex 'final recommendation only'
 
 acpx --timeout 90 codex 'investigate intermittent test timeout'
+acpx --ttl 30 codex 'keep queue owner alive for quick follow-ups'
 acpx --verbose codex 'debug why adapter startup is failing'
 ```
 
@@ -148,9 +185,15 @@ acpx --agent ./my-custom-acp-server 'do something'
 
 ## Session behavior
 
-- Prompt commands use saved sessions scoped to `(agent command, cwd, optional name)`.
-- `-s <name>` creates/selects a parallel named session in the same repo.
+- Prompt commands require an existing saved session record (created via `sessions new`).
+- 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 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.
+- 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.
 - `exec` is always one-shot and does not reuse saved sessions.
 - Session metadata is stored under `~/.acpx/sessions/`.

package/dist/cli.d.ts

@@ -1 +1,23 @@
 #!/usr/bin/env node
+import { AgentCapabilities } from '@agentclientprotocol/sdk';
+
+type SessionRecord = {
+    id: string;
+    sessionId: string;
+    agentCommand: string;
+    cwd: string;
+    name?: string;
+    createdAt: string;
+    lastUsedAt: string;
+    closed?: boolean;
+    closedAt?: string;
+    pid?: number;
+    protocolVersion?: number;
+    agentCapabilities?: AgentCapabilities;
+};
+
+declare function parseTtlSeconds(value: string): number;
+declare function formatPromptSessionBannerLine(record: SessionRecord, currentCwd: string): string;
+declare function main(argv?: string[]): Promise<void>;
+
+export { formatPromptSessionBannerLine, main, parseTtlSeconds };

package/dist/cli.js

@@ -2,7 +2,10 @@
 
 // src/cli.ts
 import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { realpathSync } from "fs";
 import path3 from "path";
+import { pathToFileURL } from "url";
+import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";
 
 // src/agent-registry.ts
 var AGENT_REGISTRY = {
@@ -703,6 +706,7 @@ function createOutputFormatter(format, options = {}) {
 
 // src/session.ts
 import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { statSync } from "fs";
 import fs2 from "fs/promises";
 import net from "net";
 import os from "os";
@@ -1300,7 +1304,7 @@ var PROCESS_EXIT_GRACE_MS = 1500;
 var PROCESS_POLL_MS = 50;
 var QUEUE_CONNECT_ATTEMPTS = 40;
 var QUEUE_CONNECT_RETRY_MS = 50;
-var QUEUE_IDLE_DRAIN_WAIT_MS = 150;
+var DEFAULT_QUEUE_OWNER_TTL_MS = 3e5;
 var TimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Timed out after ${timeoutMs}ms`);
@@ -1375,7 +1379,9 @@ function parseSessionRecord(raw) {
   const record = raw;
   const name = record.name == null ? void 0 : typeof record.name === "string" && record.name.trim().length > 0 ? record.name.trim() : null;
   const pid = record.pid == null ? void 0 : Number.isInteger(record.pid) && record.pid > 0 ? record.pid : null;
-  if (typeof record.id !== "string" || typeof record.sessionId !== "string" || typeof record.agentCommand !== "string" || typeof record.cwd !== "string" || name === null || typeof record.createdAt !== "string" || typeof record.lastUsedAt !== "string" || pid === null) {
+  const closed = record.closed == null ? false : typeof record.closed === "boolean" ? record.closed : null;
+  const closedAt = record.closedAt == null ? void 0 : typeof record.closedAt === "string" ? record.closedAt : null;
+  if (typeof record.id !== "string" || typeof record.sessionId !== "string" || typeof record.agentCommand !== "string" || typeof record.cwd !== "string" || name === null || typeof record.createdAt !== "string" || typeof record.lastUsedAt !== "string" || pid === null || closed === null || closedAt === null) {
     return null;
   }
   return {
@@ -1387,6 +1393,8 @@ function parseSessionRecord(raw) {
     name,
     createdAt: record.createdAt,
     lastUsedAt: record.lastUsedAt,
+    closed,
+    closedAt,
     pid
   };
 }
@@ -1441,6 +1449,35 @@ function toPromptResult(stopReason, sessionId, client) {
 function absolutePath(value) {
   return path2.resolve(value);
 }
+function hasGitDirectory(dir) {
+  const gitPath = path2.join(dir, ".git");
+  try {
+    return statSync(gitPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function isWithinBoundary(boundary, target) {
+  const relative = path2.relative(boundary, target);
+  return relative.length === 0 || !relative.startsWith("..") && !path2.isAbsolute(relative);
+}
+function findGitRepositoryRoot(startDir) {
+  let current = absolutePath(startDir);
+  const root = path2.parse(current).root;
+  for (; ; ) {
+    if (hasGitDirectory(current)) {
+      return current;
+    }
+    if (current === root) {
+      return void 0;
+    }
+    const parent = path2.dirname(current);
+    if (parent === current) {
+      return void 0;
+    }
+    current = parent;
+  }
+}
 function normalizeName(value) {
   if (value == null) {
     return void 0;
@@ -1451,6 +1488,15 @@ function normalizeName(value) {
 function isoNow() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function normalizeQueueOwnerTtlMs(ttlMs) {
+  if (ttlMs == null) {
+    return DEFAULT_QUEUE_OWNER_TTL_MS;
+  }
+  if (!Number.isFinite(ttlMs) || ttlMs < 0) {
+    return DEFAULT_QUEUE_OWNER_TTL_MS;
+  }
+  return Math.round(ttlMs);
+}
 function formatError(error) {
   if (error instanceof Error) {
     return error.message;
@@ -1906,7 +1952,8 @@ var SessionQueueOwner = class _SessionQueueOwner {
       return void 0;
     }
     return await new Promise((resolve) => {
-      const timer = setTimeout(
+      const shouldTimeout = timeoutMs != null;
+      const timer = shouldTimeout && setTimeout(
         () => {
           const index = this.waiters.indexOf(waiter);
           if (index >= 0) {
@@ -1917,7 +1964,9 @@ var SessionQueueOwner = class _SessionQueueOwner {
         Math.max(0, timeoutMs)
       );
       const waiter = (task) => {
-        clearTimeout(timer);
+        if (timer) {
+          clearTimeout(timer);
+        }
         resolve(task);
       };
       this.waiters.push(waiter);
@@ -2268,6 +2317,8 @@ async function runSessionPrompt(options) {
         output.onDone(response.stopReason);
         output.flush();
         record.lastUsedAt = isoNow();
+        record.closed = false;
+        record.closedAt = void 0;
         record.protocolVersion = client.initializeResult?.protocolVersion;
         record.agentCapabilities = client.initializeResult?.agentCapabilities;
         await writeSessionRecord(record);
@@ -2343,6 +2394,8 @@ async function createSession(options) {
           name: normalizeName(options.name),
           createdAt: now,
           lastUsedAt: now,
+          closed: false,
+          closedAt: void 0,
           pid: client.getAgentPid(),
           protocolVersion: client.initializeResult?.protocolVersion,
           agentCapabilities: client.initializeResult?.agentCapabilities
@@ -2360,6 +2413,7 @@ async function createSession(options) {
 }
 async function sendSession(options) {
   const waitForCompletion = options.waitForCompletion !== false;
+  const queueOwnerTtlMs = normalizeQueueOwnerTtlMs(options.ttlMs);
   const queuedToOwner = await trySubmitToRunningOwner({
     sessionId: options.sessionId,
     message: options.message,
@@ -2401,9 +2455,16 @@ async function sendSession(options) {
         timeoutMs: options.timeoutMs,
         verbose: options.verbose
       });
+      const idleWaitMs = queueOwnerTtlMs === 0 ? void 0 : Math.max(0, queueOwnerTtlMs);
       while (true) {
-        const task = await owner.nextTask(QUEUE_IDLE_DRAIN_WAIT_MS);
+        const task = await owner.nextTask(idleWaitMs);
         if (!task) {
+          if (queueOwnerTtlMs > 0 && options.verbose) {
+            process.stderr.write(
+              `[acpx] queue owner TTL expired after ${Math.round(queueOwnerTtlMs / 1e3)}s for session ${options.sessionId}; shutting down
+`
+            );
+          }
           break;
         }
         await runQueuedTask(options.sessionId, task, options.verbose);
@@ -2450,12 +2511,49 @@ async function findSession(options) {
     if (session.cwd !== normalizedCwd) {
       return false;
     }
+    if (!options.includeClosed && session.closed) {
+      return false;
+    }
     if (normalizedName == null) {
       return session.name == null;
     }
     return session.name === normalizedName;
   });
 }
+async function findSessionByDirectoryWalk(options) {
+  const normalizedName = normalizeName(options.name);
+  const normalizedStart = absolutePath(options.cwd);
+  const normalizedBoundary = absolutePath(options.boundary ?? normalizedStart);
+  const walkBoundary = isWithinBoundary(normalizedBoundary, normalizedStart) ? normalizedBoundary : normalizedStart;
+  const sessions = await listSessionsForAgent(options.agentCommand);
+  const matchesScope = (session, dir2) => {
+    if (session.cwd !== dir2) {
+      return false;
+    }
+    if (session.closed) {
+      return false;
+    }
+    if (normalizedName == null) {
+      return session.name == null;
+    }
+    return session.name === normalizedName;
+  };
+  let dir = normalizedStart;
+  for (; ; ) {
+    const match = sessions.find((session) => matchesScope(session, dir));
+    if (match) {
+      return match;
+    }
+    if (dir === walkBoundary) {
+      return void 0;
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) {
+      return void 0;
+    }
+    dir = parent;
+  }
+}
 async function terminateQueueOwnerForSession(sessionId) {
   const owner = await readQueueOwnerRecord(sessionId);
   if (!owner) {
@@ -2472,8 +2570,10 @@ async function closeSession(sessionId) {
   if (record.pid != null && isProcessAlive(record.pid) && await isLikelyMatchingProcess(record.pid, record.agentCommand)) {
     await terminateProcess(record.pid);
   }
-  const file = sessionFilePath(record.id);
-  await fs2.unlink(file);
+  record.pid = void 0;
+  record.closed = true;
+  record.closedAt = isoNow();
+  await writeSessionRecord(record);
   return record;
 }
 
@@ -2483,12 +2583,19 @@ var EXIT_CODES = {
   ERROR: 1,
   USAGE: 2,
   TIMEOUT: 3,
-  PERMISSION_DENIED: 4,
+  NO_SESSION: 4,
+  PERMISSION_DENIED: 5,
   INTERRUPTED: 130
 };
 var OUTPUT_FORMATS = ["text", "json", "quiet"];
 
 // src/cli.ts
+var NoSessionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NoSessionError";
+  }
+};
 var TOP_LEVEL_VERBS = /* @__PURE__ */ new Set(["prompt", "exec", "sessions", "help"]);
 function parseOutputFormat(value) {
   if (!OUTPUT_FORMATS.includes(value)) {
@@ -2505,6 +2612,13 @@ function parseTimeoutSeconds(value) {
   }
   return Math.round(parsed * 1e3);
 }
+function parseTtlSeconds(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new InvalidArgumentError("TTL must be a non-negative number of seconds");
+  }
+  return Math.round(parsed * 1e3);
+}
 function parseSessionName(value) {
   const trimmed = value.trim();
   if (trimmed.length === 0) {
@@ -2569,6 +2683,10 @@ function addGlobalFlags(command) {
     "--timeout <seconds>",
     "Maximum time to wait for agent response",
     parseTimeoutSeconds
+  ).option(
+    "--ttl <seconds>",
+    "Queue owner idle TTL before shutdown (0 = keep alive forever) (default: 300)",
+    parseTtlSeconds
   ).option("--verbose", "Enable verbose debug logs");
 }
 function addSessionOption(command) {
@@ -2587,6 +2705,7 @@ function resolveGlobalFlags(command) {
     agent: opts.agent,
     cwd: opts.cwd ?? process.cwd(),
     timeout: opts.timeout,
+    ttl: opts.ttl ?? DEFAULT_QUEUE_OWNER_TTL_MS,
     verbose: opts.verbose,
     format: opts.format ?? "text",
     approveAll: opts.approveAll,
@@ -2617,7 +2736,8 @@ function printSessionsByFormat(sessions, format) {
   }
   if (format === "quiet") {
     for (const session of sessions) {
-      process.stdout.write(`${session.id}
+      const closedMarker = session.closed ? " [closed]" : "";
+      process.stdout.write(`${session.id}${closedMarker}
 `);
     }
     return;
@@ -2627,8 +2747,9 @@ function printSessionsByFormat(sessions, format) {
     return;
   }
   for (const session of sessions) {
+    const closedMarker = session.closed ? " [closed]" : "";
     process.stdout.write(
-      `${session.id}	${session.name ?? "-"}	${session.cwd}	${session.lastUsedAt}
+      `${session.id}${closedMarker}	${session.name ?? "-"}	${session.cwd}	${session.lastUsedAt}
 `
     );
   }
@@ -2652,6 +2773,33 @@ function printClosedSessionByFormat(record, format) {
   process.stdout.write(`${record.id}
 `);
 }
+function printNewSessionByFormat(record, replaced, format) {
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify({
+        type: "session_created",
+        id: record.id,
+        sessionId: record.sessionId,
+        name: record.name,
+        replacedSessionId: replaced?.id
+      })}
+`
+    );
+    return;
+  }
+  if (format === "quiet") {
+    process.stdout.write(`${record.id}
+`);
+    return;
+  }
+  if (replaced) {
+    process.stdout.write(`${record.id}	(replaced ${replaced.id})
+`);
+    return;
+  }
+  process.stdout.write(`${record.id}
+`);
+}
 function printQueuedPromptByFormat(result, format) {
   if (format === "json") {
     process.stdout.write(
@@ -2670,38 +2818,74 @@ function printQueuedPromptByFormat(result, format) {
   process.stdout.write(`[queued] ${result.requestId}
 `);
 }
+function formatSessionLabel(record) {
+  return record.name ?? "cwd";
+}
+function formatRoutedFrom(sessionCwd, currentCwd) {
+  const relative = path3.relative(sessionCwd, currentCwd);
+  if (!relative || relative === ".") {
+    return void 0;
+  }
+  return relative.startsWith(".") ? relative : `.${path3.sep}${relative}`;
+}
+function formatPromptSessionBannerLine(record, currentCwd) {
+  const label = formatSessionLabel(record);
+  const normalizedSessionCwd = path3.resolve(record.cwd);
+  const normalizedCurrentCwd = path3.resolve(currentCwd);
+  const routedFrom = normalizedSessionCwd === normalizedCurrentCwd ? void 0 : formatRoutedFrom(normalizedSessionCwd, normalizedCurrentCwd);
+  if (routedFrom) {
+    return `[acpx] session ${label} (${record.id}) \xB7 ${normalizedSessionCwd} (routed from ${routedFrom})`;
+  }
+  return `[acpx] session ${label} (${record.id}) \xB7 ${normalizedSessionCwd}`;
+}
+function printPromptSessionBanner(record, currentCwd, format) {
+  if (format === "quiet") {
+    return;
+  }
+  process.stderr.write(`${formatPromptSessionBannerLine(record, currentCwd)}
+`);
+}
+function printCreatedSessionBanner(record, agentName, format) {
+  if (format === "quiet") {
+    return;
+  }
+  const label = formatSessionLabel(record);
+  process.stderr.write(`[acpx] created session ${label} (${record.id})
+`);
+  process.stderr.write(`[acpx] agent: ${agentName}
+`);
+  process.stderr.write(`[acpx] cwd: ${record.cwd}
+`);
+}
 async function handlePrompt(explicitAgentName, promptParts, flags, command) {
   const globalFlags = resolveGlobalFlags(command);
   const permissionMode = resolvePermissionMode(globalFlags);
   const prompt = await readPrompt(promptParts);
   const outputFormatter = createOutputFormatter(globalFlags.format);
   const agent = resolveAgentInvocation(explicitAgentName, globalFlags);
-  let record = await findSession({
+  const gitRoot = findGitRepositoryRoot(agent.cwd);
+  const walkBoundary = gitRoot ?? agent.cwd;
+  const record = await findSessionByDirectoryWalk({
     agentCommand: agent.agentCommand,
     cwd: agent.cwd,
-    name: flags.session
+    name: flags.session,
+    boundary: walkBoundary
   });
   if (!record) {
-    record = await createSession({
-      agentCommand: agent.agentCommand,
-      cwd: agent.cwd,
-      name: flags.session,
-      permissionMode,
-      timeoutMs: globalFlags.timeout,
-      verbose: globalFlags.verbose
-    });
-    if (globalFlags.verbose) {
-      const scope = flags.session ? `named session "${flags.session}"` : "cwd session";
-      process.stderr.write(`[acpx] created ${scope}: ${record.id}
-`);
-    }
+    const createCmd = flags.session ? `acpx ${agent.agentName} sessions new --name ${flags.session}` : `acpx ${agent.agentName} sessions new`;
+    throw new NoSessionError(
+      `\u26A0 No acpx session found (searched up to ${walkBoundary}).
+Create one: ${createCmd}`
+    );
   }
+  printPromptSessionBanner(record, agent.cwd, globalFlags.format);
   const result = await sendSession({
     sessionId: record.id,
     message: prompt,
     permissionMode,
     outputFormatter,
     timeoutMs: globalFlags.timeout,
+    ttlMs: globalFlags.ttl,
     verbose: globalFlags.verbose,
     waitForCompletion: flags.wait !== false
   });
@@ -2759,14 +2943,49 @@ async function handleSessionsClose(explicitAgentName, sessionName, command) {
   const closed = await closeSession(record.id);
   printClosedSessionByFormat(closed, globalFlags.format);
 }
+async function handleSessionsNew(explicitAgentName, flags, command) {
+  const globalFlags = resolveGlobalFlags(command);
+  const permissionMode = resolvePermissionMode(globalFlags);
+  const agent = resolveAgentInvocation(explicitAgentName, globalFlags);
+  const replaced = await findSession({
+    agentCommand: agent.agentCommand,
+    cwd: agent.cwd,
+    name: flags.name
+  });
+  if (replaced) {
+    await closeSession(replaced.id);
+    if (globalFlags.verbose) {
+      process.stderr.write(`[acpx] soft-closed prior session: ${replaced.id}
+`);
+    }
+  }
+  const created = await createSession({
+    agentCommand: agent.agentCommand,
+    cwd: agent.cwd,
+    name: flags.name,
+    permissionMode,
+    timeoutMs: globalFlags.timeout,
+    verbose: globalFlags.verbose
+  });
+  printCreatedSessionBanner(created, agent.agentName, globalFlags.format);
+  if (globalFlags.verbose) {
+    const scope = flags.name ? `named session "${flags.name}"` : "cwd session";
+    process.stderr.write(`[acpx] created ${scope}: ${created.id}
+`);
+  }
+  printNewSessionByFormat(created, replaced, globalFlags.format);
+}
 function registerSessionsCommand(parent, explicitAgentName) {
-  const sessionsCommand = parent.command("sessions").description("List or close sessions for this agent");
+  const sessionsCommand = parent.command("sessions").description("List, create, or close sessions for this agent");
   sessionsCommand.action(async function() {
     await handleSessionsList(explicitAgentName, this);
   });
   sessionsCommand.command("list").description("List sessions").action(async function() {
     await handleSessionsList(explicitAgentName, this);
   });
+  sessionsCommand.command("new").description("Create a fresh session for current cwd").option("--name <name>", "Session name", parseSessionName).action(async function(flags) {
+    await handleSessionsNew(explicitAgentName, flags, this);
+  });
   sessionsCommand.command("close").description("Close session for current cwd").argument("[name]", "Session name", parseSessionName).action(async function(name) {
     await handleSessionsClose(explicitAgentName, name, this);
   });
@@ -2817,11 +3036,11 @@ function detectAgentToken(argv) {
       hasAgentOverride = true;
       continue;
     }
-    if (token === "--cwd" || token === "--format" || token === "--timeout") {
+    if (token === "--cwd" || token === "--format" || token === "--timeout" || token === "--ttl") {
       index += 1;
       continue;
     }
-    if (token.startsWith("--cwd=") || token.startsWith("--format=") || token.startsWith("--timeout=")) {
+    if (token.startsWith("--cwd=") || token.startsWith("--format=") || token.startsWith("--timeout=") || token.startsWith("--ttl=")) {
       continue;
     }
     if (token === "--approve-all" || token === "--approve-reads" || token === "--deny-all" || token === "--verbose") {
@@ -2831,7 +3050,11 @@ function detectAgentToken(argv) {
   }
   return { hasAgentOverride };
 }
-async function main() {
+async function main(argv = process.argv) {
+  await maybeHandleSkillflag(argv, {
+    skillsRoot: findSkillsRoot(import.meta.url),
+    includeBundledSkill: false
+  });
   const program = new Command();
   program.name("acpx").description("Headless CLI client for the Agent Client Protocol").showHelpAfterError();
   addGlobalFlags(program);
@@ -2840,7 +3063,7 @@ async function main() {
     registerAgentCommand(program, agentName);
   }
   registerDefaultCommands(program);
-  const scan = detectAgentToken(process.argv.slice(2));
+  const scan = detectAgentToken(argv.slice(2));
   if (!scan.hasAgentOverride && scan.token && !TOP_LEVEL_VERBS.has(scan.token) && !builtInAgents.includes(scan.token)) {
     registerAgentCommand(program, scan.token);
   }
@@ -2855,13 +3078,16 @@ async function main() {
     "after",
     `
 Examples:
+  acpx codex sessions new
   acpx codex "fix the tests"
   acpx codex prompt "fix the tests"
   acpx codex --no-wait "queue follow-up task"
   acpx codex exec "what does this repo do"
   acpx codex -s backend "fix the API"
   acpx codex sessions
+  acpx codex sessions new --name backend
   acpx codex sessions close backend
+  acpx --ttl 30 codex "investigate flaky tests"
   acpx claude "refactor auth"
   acpx gemini "add logging"
   acpx --agent ./my-custom-server "do something"`
@@ -2870,7 +3096,7 @@ Examples:
     throw error;
   });
   try {
-    await program.parseAsync(process.argv);
+    await program.parseAsync(argv);
   } catch (error) {
     if (error instanceof CommanderError) {
       if (error.code === "commander.helpDisplayed" || error.code === "commander.version") {
@@ -2886,10 +3112,34 @@ Examples:
 `);
       process.exit(EXIT_CODES.TIMEOUT);
     }
+    if (error instanceof NoSessionError) {
+      process.stderr.write(`${error.message}
+`);
+      process.exit(EXIT_CODES.NO_SESSION);
+    }
     const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(`${message}
 `);
     process.exit(EXIT_CODES.ERROR);
   }
 }
-void main();
+function isCliEntrypoint(argv) {
+  const entry = argv[1];
+  if (!entry) {
+    return false;
+  }
+  try {
+    const resolved = pathToFileURL(realpathSync(entry)).href;
+    return import.meta.url === resolved;
+  } catch {
+    return false;
+  }
+}
+if (isCliEntrypoint(process.argv)) {
+  void main(process.argv);
+}
+export {
+  formatPromptSessionBannerLine,
+  main,
+  parseTtlSeconds
+};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "acpx",
-  "version": "0.1.2",
-  "description": "Headless CLI client for the Agent Client Protocol (ACP) \u2014 talk to coding agents from the command line",
+  "version": "0.1.4",
+  "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,6 +14,10 @@
   },
   "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",
@@ -42,13 +47,16 @@
   },
   "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",
@@ -56,21 +64,13 @@
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.56.0"
   },
-  "release-it": {
-    "git": {
-      "requireCleanWorkingDir": true,
-      "requireBranch": "main",
-      "commitMessage": "chore(release): ${version}",
-      "tagName": "v${version}",
-      "push": true
-    },
-    "npm": {
-      "publish": true,
-      "skipChecks": true
-    },
-    "github": {
-      "release": true,
-      "autoGenerate": true
-    }
+  "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'
+```