zcode-acp-server 0.64.0 → 0.65.0

package/docs/REMOTE-CLIENTS.md

@@ -57,6 +57,7 @@ ACP editor ────── stdio ──────────┘
 | `GET /api/quota`                                       | required | Account-level usage stats — same payload as `account/usage_stats`, no ACP connection needed.                                                                      |
 | `POST /api/upgrade`                                    | required | Trigger the hub's own staleness check — see [Hub self-upgrade](#hub-self-upgrade).                                                                                |
 | `GET /api/projects`                                    | required | Known-project list (remote session-create whitelist) — see below.                                                                                                 |
+| `GET /api/fs/list?path=`                               | required | One directory level for the browse-and-create flow — see [Starting a session in a new directory](#starting-a-session-in-a-new-directory).                         |
 | `GET /api/projects/sessions?workspacePath=`            | required | A project's full session store incl. closed ones — see [Resuming a closed session](#resuming-a-closed-session).                                                   |
 | `POST /api/projects/delete {workspacePath}`            | required | Soft-delete a project and all its sessions (hidden from every listing) — see [Deleting a project or session](#deleting-a-project-or-session).                     |
 | `POST /api/instances {workspacePath[, sessionId]}`     | required | Create a bridge for one known project — a visible terminal TUI window (session-create) or one that boots into a closed session (resume, `sessionId`) — see below. |
@@ -177,6 +178,14 @@ POST {hub}/api/instances  body {"workspacePath":"/Users/me/proj"}
   bound, not a security boundary: a token holder can already run any
   editor-bridge session in an arbitrary cwd; the trust boundary is the
   token itself.
+- **`remote.projectRoots` widening** (bridge ≥0.65, browse-and-create): the
+  machine's user config may list absolute directory roots
+  (`"remote": {"projectRoots": ["~/Develop"]}`, `~` expanded, read live;
+  env fallback `ZCODE_ACP_PROJECT_ROOTS`, a `:`-separated path-list). The
+  POST then also accepts any existing subdirectory under a configured
+  root, not just known projects. Unconfigured, the known list alone stays
+  the whitelist. See [Starting a session in a new
+  directory](#starting-a-session-in-a-new-directory).
 - On create the hub incubates a VISIBLE interactive TUI (Martty) in the machine's
   terminal (ADR-0016, macOS): the project's owner gets a real local CLI
   window, and its bridge registers with the hub like any serve instance (it
@@ -212,6 +221,42 @@ POST {hub}/api/instances  body {"workspacePath":"/Users/me/proj"}
   ~10 minutes after the last client detaches AND the last running turn
   finishes. Treat any vanished instance like a dead bridge.
 
+## Starting a session in a new directory
+
+The known-project list only ever holds directories that already ran a
+session. To start one somewhere new, browse the machine's directory tree
+(bridge ≥0.65) and create in the picked directory — it must sit under a
+configured `remote.projectRoots` root (see above):
+
+```text
+GET {hub}/api/fs/list?path=/Users/me          (path optional — default: home)
+  → 200 {"path":"/Users/me","parent":"/Users",
+         "creatable":false,
+         "entries":[{"name":"Develop"},{"name":"Documents"}, …],
+         "truncated":false}
+  → 400 "absolute path required"   (relative path)
+  → 404 "directory not found"      (missing path, or a file)
+
+POST {hub}/api/instances  body {"workspacePath":"/Users/me/Develop/newproj"}
+  → 200 {"id":"47073","reused":false}   (exactly the known-project create flow)
+```
+
+- One directory level per call; walk down via `entries[].name`, up via
+  `parent` (null at `/`). `path` in the answer is the RESOLVED (realpath)
+  spelling — navigate by it, not by what you sent (symlinks).
+- Only subdirectories are listed (cap 2000; `truncated` flags the cut);
+  hidden (`.`-prefixed) entries ARE included — filter client-side if the
+  UI wants them gone.
+- `creatable` tells whether a NEW session may start in the LISTED
+  directory itself: a known project, or under a configured project root.
+  With no roots configured everything still browses, but `creatable` is
+  true only on known projects. A create that ignores it gets the normal
+  403 "unknown project".
+- The create itself is the ordinary session-create flow above (visible
+  terminal TUI on the machine, ~20s budget). After the first session runs,
+  the directory enters the tasks index and appears in `GET /api/projects`
+  like any known project.
+
 ## Resuming a closed session
 
 Discovery lists only currently-running conversations. To find and reopen a
@@ -1000,6 +1045,14 @@ everything below and you get the full replay):
   redundant full replay on every re-entry. Null on an empty store or an
   id-less tail.
 
+  A metadata-only attach (`limit 0`) is deliberately FAST over complete: the
+  bridge skips the hydration settle for it, so on a freshly-resumed backend
+  the meta may describe a mid-hydration PREFIX (smaller `totalMessages`,
+  prefix-tail `lastMessageId`). Treat reconcile conservatively — a mismatch
+  is "unknown, re-attach with a real limit"; only an exact tail-id match
+  means "nothing changed". The follow-up full attach is where the settle
+  runs, so it always sees the complete history.
+
 - **`session/load_earlier`** (`{ sessionId, before, limit }`, limit defaults
   to 50) delivers one page of `session/update`s strictly older than `before`,
   oldest → newest — prepend them. Same `replayMeta` shape in the result;

package/docs/REMOTE.md

@@ -110,7 +110,13 @@ ran a session (system temp trees, `~/.zcode` itself, and vanished
 directories filtered out), newest activity first. The list gates the POST —
 paths outside it get 403 (a convenience bound, not a security boundary: a
 token holder can already drive an editor-bridge session in any cwd; the
-trust boundary is the token). On create the hub incubates a VISIBLE
+trust boundary is the token). The gate is WIDENED by the optional
+`remote.projectRoots` config (an array of absolute directory roots, `~`
+expanded, read live from the config file with the
+`ZCODE_ACP_PROJECT_ROOTS` path-list as the env fallback): any existing
+subdirectory under a configured root is accepted too, powering the mobile
+app's browse-and-create flow. Unconfigured, the known list alone stays the
+whitelist. On create the hub incubates a VISIBLE
 interactive TUI window in the machine's terminal (ADR-0016 as amended by
 ADR-0020, macOS; headless/SSH, `remote.terminal.enabled: false` in the config
 file, or `ZCODE_ACP_HUB_TERMINAL=0` falls back to the detached headless
@@ -148,6 +154,24 @@ the project's serve bridge on first listing and reuses it after. Resume is
 the normal attach flow with `session/load` on a listed backend id. See
 `docs/REMOTE-CLIENTS.md` ("Resuming a closed session") for the client contract.
 
+**Directory browsing** (browse-and-create). A remote client may walk the
+machine's directory tree to pick a working directory no session has used
+yet:
+
+```text
+GET /api/fs/list?path=<abs> → {path, parent, creatable, entries:[{name}], truncated}
+```
+
+One directory level per call; an absent `path` (or `~`) lists the home dir,
+the answer carries the RESOLVED (realpath) spelling. Only subdirectories
+are listed (2000 cap, `truncated` flags the cut). Browsing is read-only and
+unscoped — the token is the boundary, like every hub route. `creatable`
+flags whether a NEW session may start in the listed directory itself: a
+known project, or under a configured `remote.projectRoots` root. With no
+roots configured every directory browses fine but `creatable` stays false
+outside the known list. See `docs/REMOTE-CLIENTS.md` ("Starting a session
+in a new directory") for the client contract.
+
 **Remote project/session delete** (ADR-0031). Both are soft deletes
 (tombstones in the App's tasks-index, upstream `deleteTask` semantics — the
 backend store keeps every conversation byte):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",