@openape/apes 0.6.1 → 0.7.2

package/README.md

@@ -35,9 +35,12 @@ apes grants list
 
 ## ape-shell: Grant-Secured Shell Wrapper
 
-`ape-shell` is a drop-in shell replacement that routes every command through a DDISA grant. Useful for sandboxing AI coding agents (OpenClaw, Claude Code, etc.) so they can only execute pre-approved commands.
+`ape-shell` is a drop-in shell that routes every command through a DDISA grant. It has two modes:
 
-### How it works
+1. **One-shot mode** (`ape-shell -c "<command>"`) — the historical wrapper. Runs a single command through the grant flow and exits. Used by `$SHELL -c` patterns (e.g. `openclaw tui`, `xargs`, git hooks, sshd non-interactive sessions, etc.).
+2. **Interactive mode** (`ape-shell` with no args, or as a login shell) — a full interactive REPL with a persistent bash backend. Every line the user types is routed through the grant flow **before** bash sees it, and executed in bash's persistent state (so `cd`, `export`, aliases, functions, pipes, TUI apps like `vim`/`less`/`top` all work natively).
+
+### How the one-shot mode works
 
 ```
 $SHELL -c "git status"
@@ -51,16 +54,50 @@ apes run --shell -- bash -c "git status"
 3. No grant → request + wait for human approval → execute
 ```
 
-### Setup for an AI agent session
+### How the interactive mode works
+
+```
+ape-shell
+  ↓
+┌─ PROMPT ─────────────────────────────────────────┐
+│ apes$ <user types here>                          │
+│   → multi-line detection via `bash -n` dry-parse │
+│   → grant dispatch (adapter or ape-shell session)│
+│   → on approval: write line to persistent bash   │
+│   → stream output, detect prompt marker          │
+└──────────────────────────────────────────────────┘
+```
+
+Every line is audited in `~/.config/apes/audit.jsonl` (session id, line, grant id, exit code).
+
+### Setup for an AI agent session (one-shot mode)
 
 ```bash
-# Point the agent's SHELL at ape-shell
-SHELL=$(which ape-shell) openclaw
+# Point the agent's SHELL at ape-shell — each spawned command
+# goes through the one-shot grant flow.
+SHELL=$(which ape-shell) openclaw tui
 ```
 
 The first command requests a session grant. After the human approves it (with `grant_type: timed, duration: 8h`), all subsequent commands reuse the same grant without interaction.
 
-### Example
+### Setup as a login shell (interactive mode)
+
+```bash
+# 1. Register ape-shell as a valid login shell (once per host)
+echo "$(which ape-shell)" | sudo tee -a /etc/shells
+
+# 2. Set it as the login shell for a user (e.g. openclaw)
+sudo chsh -s "$(which ape-shell)" openclaw
+```
+
+After this:
+
+- `ssh openclaw@host` — sshd starts ape-shell as an interactive REPL (sshd passes the login shell with a `-` prefix on argv[0], which ape-shell detects)
+- `ssh openclaw@host "ls"` — sshd invokes `ape-shell -c "ls"`, which still flows through the **one-shot** path (no regression)
+- `su - openclaw` — drops into the interactive REPL
+- Terminal / console login — same as SSH interactive
+
+### Example (one-shot)
 
 ```bash
 $ apes login
@@ -78,6 +115,31 @@ def456 Previous commit
 ...
 ```
 
+### Example (interactive)
+
+```bash
+$ ape-shell
+apes interactive shell
+Ctrl-D to exit.
+
+apes$ cd /tmp
+# (grant approved, reused for free)
+
+apes$ ls
+# structured adapter grant for `ls` → approve → output
+
+apes$ for i in 1 2 3; do
+>   echo $i
+> done
+# single grant for the whole compound, bash runs it natively
+
+apes$ vim notes.md
+# grant approved → full TUI vim, raw-mode passthrough
+
+apes$ ^D
+Goodbye.
+```
+
 ## Commands
 
 ### Authentication

package/dist/auth-lock-SRUFWJC3.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import {
+  CONFIG_DIR
+} from "./chunk-TBYYREL6.js";
+
+// src/auth-lock.ts
+import { open, rm, stat } from "fs/promises";
+import { join } from "path";
+var LOCK_FILE = join(CONFIG_DIR, "auth.json.lock");
+async function acquireAuthLock(opts = {}) {
+  const deadline = Date.now() + (opts.timeoutMs ?? 5e3);
+  while (Date.now() < deadline) {
+    try {
+      const handle = await open(LOCK_FILE, "wx");
+      return { handle };
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+      try {
+        const s = await stat(LOCK_FILE);
+        if (Date.now() - s.mtimeMs > 3e4)
+          await rm(LOCK_FILE, { force: true });
+      } catch {
+      }
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  return null;
+}
+async function releaseAuthLock(lock) {
+  try {
+    await lock.handle.close();
+  } finally {
+    await rm(LOCK_FILE, { force: true });
+  }
+}
+export {
+  acquireAuthLock,
+  releaseAuthLock
+};
+//# sourceMappingURL=auth-lock-SRUFWJC3.js.map

package/dist/auth-lock-SRUFWJC3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/auth-lock.ts"],"sourcesContent":["import type { FileHandle } from 'node:fs/promises'\nimport { open, rm, stat } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport { CONFIG_DIR } from './config'\n\nconst LOCK_FILE = join(CONFIG_DIR, 'auth.json.lock')\n\nexport interface AuthLock {\n  handle: FileHandle\n}\n\n/**\n * Best-effort exclusive file lock to serialize concurrent token refreshes\n * between parallel apes / ape-shell invocations. Uses O_CREAT|O_EXCL which\n * is atomic on POSIX. Returns null on timeout so the caller can fall back\n * to \"just re-read auth.json\" (the assumption being that another process\n * successfully refreshed in the meantime).\n *\n * A stale lock older than 30s is considered abandoned (from a crashed\n * process) and is removed so the next acquire can proceed.\n */\nexport async function acquireAuthLock(\n  opts: { timeoutMs?: number } = {},\n): Promise<AuthLock | null> {\n  const deadline = Date.now() + (opts.timeoutMs ?? 5000)\n  while (Date.now() < deadline) {\n    try {\n      const handle = await open(LOCK_FILE, 'wx')\n      return { handle }\n    }\n    catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== 'EEXIST')\n        throw err\n      // Stale lock? If the file is older than 30s, remove it and retry.\n      try {\n        const s = await stat(LOCK_FILE)\n        if (Date.now() - s.mtimeMs > 30_000)\n          await rm(LOCK_FILE, { force: true })\n      }\n      catch {\n        // File gone between stat and rm — next iteration will retry the open.\n      }\n      await new Promise(r => setTimeout(r, 100))\n    }\n  }\n  return null\n}\n\nexport async function releaseAuthLock(lock: AuthLock): Promise<void> {\n  try {\n    await lock.handle.close()\n  }\n  finally {\n    await rm(LOCK_FILE, { force: true })\n  }\n}\n"],"mappings":";;;;;;AACA,SAAS,MAAM,IAAI,YAAY;AAC/B,SAAS,YAAY;AAGrB,IAAM,YAAY,KAAK,YAAY,gBAAgB;AAgBnD,eAAsB,gBACpB,OAA+B,CAAC,GACN;AAC1B,QAAM,WAAW,KAAK,IAAI,KAAK,KAAK,aAAa;AACjD,SAAO,KAAK,IAAI,IAAI,UAAU;AAC5B,QAAI;AACF,YAAM,SAAS,MAAM,KAAK,WAAW,IAAI;AACzC,aAAO,EAAE,OAAO;AAAA,IAClB,SACO,KAAK;AACV,UAAK,IAA8B,SAAS;AAC1C,cAAM;AAER,UAAI;AACF,cAAM,IAAI,MAAM,KAAK,SAAS;AAC9B,YAAI,KAAK,IAAI,IAAI,EAAE,UAAU;AAC3B,gBAAM,GAAG,WAAW,EAAE,OAAO,KAAK,CAAC;AAAA,MACvC,QACM;AAAA,MAEN;AACA,YAAM,IAAI,QAAQ,OAAK,WAAW,GAAG,GAAG,CAAC;AAAA,IAC3C;AAAA,EACF;AACA,SAAO;AACT;AAEA,eAAsB,gBAAgB,MAA+B;AACnE,MAAI;AACF,UAAM,KAAK,OAAO,MAAM;AAAA,EAC1B,UACA;AACE,UAAM,GAAG,WAAW,EAAE,OAAO,KAAK,CAAC;AAAA,EACrC;AACF;","names":[]}