acpx 0.1.3 → 0.1.4

package/README.md

@@ -17,6 +17,7 @@ One command surface for Codex, Claude, Gemini, OpenCode, Pi, or custom ACP serve
 - **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
@@ -44,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
@@ -67,13 +96,16 @@ 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
@@ -153,8 +185,10 @@ 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.

package/dist/cli.d.ts

@@ -1,5 +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 { main, parseTtlSeconds };
+export { formatPromptSessionBannerLine, main, parseTtlSeconds };

package/dist/cli.js

@@ -706,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";
@@ -1448,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;
@@ -2490,6 +2520,40 @@ async function findSession(options) {
     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) {
@@ -2519,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)) {
@@ -2747,32 +2818,67 @@ 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,
@@ -2861,6 +2967,7 @@ async function handleSessionsNew(explicitAgentName, flags, command) {
     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}
@@ -2971,6 +3078,7 @@ async function main(argv = process.argv) {
     "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"
@@ -3004,6 +3112,11 @@ 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}
 `);
@@ -3026,6 +3139,7 @@ if (isCliEntrypoint(process.argv)) {
   void main(process.argv);
 }
 export {
+  formatPromptSessionBannerLine,
   main,
   parseTtlSeconds
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acpx",
-  "version": "0.1.3",
+  "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": [