@softov/ahpc 0.3.0 → 0.4.0

package/README.md

@@ -74,7 +74,7 @@ Inside a session, the header shows the model, thinking level, permission mode, w
 
 ![Starting a session, and the questions the host asks first](docs/img/compose.svg)
 
-Before the first message, a new session asks the agent, the model and its options, the permission mode and the workspace. The questions come from the host's `configSchema`, so options `ahpc` has never seen still get a row.
+Before the first message, a new session asks the agent, the model and its options, the permission mode and the workspace. The workspace is picked by looking: the chip opens a folder dialog over the host's own directories (`resourceList`, the same request VS Code's folder picker makes), starting where the chip points when the host will list that and in a directory some session is in otherwise; `Workspace path` in the palette still takes one typed, for a served directory the dialog cannot walk to. The questions come from the host's `configSchema`, so options `ahpc` has never seen still get a chip. Two rows under the field: what runs on the first, and where it runs on the second - the directory, in place or in a worktree of it, and the branch a worktree starts from. What the host marks `readOnly` is shown and not asked, and the worktree seeds the reference client never draws (`worktreeBranchPrefix`, `worktreeCreateNewBranch`, `worktreeBranchTrack`, `worktreeIncludeFiles`, `shellInitScripts`) are not drawn here either.
 
 ### Keys
 
@@ -82,14 +82,15 @@ Before the first message, a new session asks the agent, the model and its option
 |---|---|
 | `enter` | Send |
 | `alt+enter` | Newline |
-| `tab` | Move to the options row |
-| `esc` | Close the menu, then leave the field, then go back |
+| `tab` | Move through the option rows |
+| `esc` | Close the menu, then leave the field, then go back. On an option, back to the field |
 | `/` | Slash commands, from the host and from `ahpc` — `/config` opens the settings palette |
 | `@` | Complete a file path on the host |
 | `ctrl+g` | Edit the message in `$VISUAL` or `$EDITOR` |
 | `ctrl+p` | Command palette |
 | `f1` | Every key that works where you are |
 | `ctrl+f` | Filter the session list, or find in the open conversation |
+| `l` | Follow an `agent-host-session://` link in the open conversation: the links the agent's session tools answered with, as a list, and one chosen opens the session or the chat it names. `--session` and every `<uri>` on the command line take a link too |
 | `ctrl+n` | New session |
 | `ctrl+r` | Refresh |
 | `alt+t` | Theme |
@@ -223,6 +224,7 @@ Writes are guarded by the file's etag unless you pass `--force`, so two clients
 | Command | | |
 |---|---|---|
 | `dispatch <uri> <type>` | Send a raw protocol action | `--field k=v` `--chat` |
+| `wire <file>` | Watch a `--wire` capture as it is written, from either end: one row per frame, a row opens to the frame. Off a terminal, one line per frame | `--follow` `--filter text` `--json` |
 | `config` | Show the config file path and current values | `--json` |
 | `--version` | What version this is | |
 | `help` | Print this command list | |
@@ -353,7 +355,7 @@ npm run schema              # a strict JSON Schema from the package's own declar
 npm run wire -- <capture>   # check a recording against it
 ```
 
-`AHPC_RECORD=<file>` appends every frame sent and received. `test/conformance.test.ts` runs the same check against frames produced by the test run itself, so it cannot pass on a stale recording.
+`--wire <file>` (or `AHPC_RECORD=<file>`) appends every frame sent and received as one JSON line each, `{ at, from, peer, frame }`, the lines `ahpd --wire` writes, so a capture from either end reads the same and `jq` reads both. `ahpc wire <file>` watches one as it is written: a row per frame with the time, the direction, the method or action type and the channel, a filter over all of them, and the frame itself beside the list or, on a narrow terminal, under enter. Reading the host's capture and this client's side by side is what it is for. `test/conformance.test.ts` runs the same check against frames produced by the test run itself, so it cannot pass on a stale recording.
 
 The screens, widgets and input handling come from [TextUI](https://github.com/softov/textui) — `@textui/core` for components and state, `@textui/widgets` for the catalog, `@textui/terminal` for rendering and key decoding, and `@textui/testing` for the harness the tests run in. `ahpc` began as an example inside it.
 

package/dist/src/ahp/fake.js

@@ -17,7 +17,16 @@ const EFFORTS = [
     { value: 'xhigh', label: 'Extra High' },
     { value: 'max', label: 'Max' },
 ];
-const CONFIG = [
+/**
+ * The session's questions, as the reference host asks them.
+ *
+ * A function of the answers so far rather than a table: `branch` is a
+ * question only while a worktree is being made, and the reference host marks
+ * it read-only otherwise, because a folder session works on whatever is
+ * checked out. `worktreeCreateNewBranch` is one of the values it seeds from
+ * the client's own settings and never asks about.
+ */
+const configOf = (values, branch) => [
     {
         key: 'branch',
         title: 'Branch',
@@ -26,6 +35,19 @@ const CONFIG = [
         // reference host marks exactly this property this way.
         values: [],
         enumDynamic: true,
+        default: branch,
+        ...(values.isolation === 'worktree' ? {} : { readOnly: true }),
+        sessionMutable: false,
+    },
+    {
+        key: 'worktreeCreateNewBranch',
+        title: 'Create a branch',
+        values: [
+            { value: 'true', label: 'Create one' },
+            { value: 'false', label: 'Continue the chosen branch' },
+        ],
+        default: 'true',
+        readOnly: true,
         sessionMutable: false,
     },
     {
@@ -51,6 +73,19 @@ const CONFIG = [
         ],
     },
 ];
+const DEFAULTS = { permissionMode: 'default', isolation: 'workspace' };
+/**
+ * The questions, answered so far, about one directory.
+ *
+ * `branch` is the directory's: a real host starts from the branch that is
+ * checked out there, so asking about another directory is asking a different
+ * question, and this fixture answers it from what the session in that
+ * directory said it was on.
+ */
+const configFor = (values, branch = 'main') => {
+    const held = { ...DEFAULTS, branch, ...values };
+    return { properties: configOf(held, branch), values: held };
+};
 let counter = 0;
 const nextId = (prefix) => `${prefix}${++counter}`;
 const AT = '2026-08-22T10:00:00.000Z';
@@ -468,6 +503,19 @@ export function fakeHost() {
                     outgoingChanges: options.drift?.[0] ?? 0,
                     uncommittedChanges: options.drift?.[2] ?? 0,
                 },
+                // The reference host's other well-known key: what GitHub knows about
+                // the branch. Copied from a capture the same way `git` is.
+                ...(options.pullRequest
+                    ? {
+                        github: {
+                            pullRequestUrls: [options.pullRequest.url],
+                            pullRequestBranchName: options.branch ?? 'main',
+                            ...(options.pullRequest.state
+                                ? { pullRequestState: options.pullRequest.state, pullRequestStateUrl: options.pullRequest.url }
+                                : {}),
+                        },
+                    }
+                    : {}),
             },
             ...(options.activity ? { activity: options.activity } : {}),
             ...(options.origin ? { origin: options.origin } : {}),
@@ -640,6 +688,8 @@ export function fakeHost() {
         dir: 'file:///brb_main/src/brb_backend',
         model: 'claude-sonnet-5',
         archived: true,
+        branch: 'cleanup/compile-script',
+        pullRequest: { url: 'https://github.com/brbyte/brb_backend/pull/412', state: 'merged' },
         turns: [
             {
                 id: 's5-t1', role: 'user', message: 'Delete compileFramework.sh from the Linux path.',
@@ -1126,11 +1176,14 @@ export function fakeHost() {
         agents: async () => AGENTS,
         // Iterative, as a real host's is: what has been answered comes back
         // answered. A fixture that returns its defaults every time quietly undoes
-        // every choice the moment anything asks the question again.
-        resolveConfig: async ({ values }) => ({
-            properties: CONFIG,
-            values: { permissionMode: 'default', isolation: 'workspace', ...values },
-        }),
+        // every choice the moment anything asks the question again. About the
+        // directory asked about, as a real host's is: the branch is what is
+        // checked out there.
+        resolveConfig: async ({ workingDirectory, values }) => {
+            const there = [...summaries.values()].find((one) => one.workingDirectories[0] === `file://${workingDirectory ?? ''}`);
+            const meta = there?._meta;
+            return configFor(values ?? {}, meta?.git?.branchName ?? 'main');
+        },
         automations: async () => [...automations.values()],
         onAutomations: (observer) => {
             automationWatchers.add(observer);
@@ -1961,10 +2014,7 @@ export function fakeHost() {
                 chat,
                 chats: chatsOf(uri),
                 lifecycle: summaries.has(uri) ? 'ready' : 'creating',
-                config: {
-                    properties: CONFIG,
-                    values: { permissionMode: 'default', isolation: 'workspace', ...(configs.get(uri) ?? {}) },
-                },
+                config: configFor(configs.get(uri) ?? {}),
                 // The id a turn named, resolved against the catalogue - which is what
                 // the live host does, and a fixture that answered a bare id would be
                 // one where the screens were never asked to resolve anything.
@@ -1972,10 +2022,7 @@ export function fakeHost() {
                 ...(summaries.get(uri)?.activity ? { activity: summaries.get(uri)?.activity } : {}),
             };
         },
-        config: async (uri) => ({
-            properties: CONFIG,
-            values: { permissionMode: 'default', isolation: 'workspace', ...(configs.get(uri) ?? {}) },
-        }),
+        config: async (uri) => configFor(configs.get(uri) ?? {}),
         setConfig: (uri, key, value) => {
             // One key, merged. Writing the whole object back is how a value another
             // client changed a moment ago is quietly reverted.

package/dist/src/ahp/live.d.ts

@@ -33,6 +33,13 @@ export interface LiveHostOptions {
     /** A bearer token, if the host is behind one. Appended as `?tkn=`. */
     token?: string;
     clientId?: string;
+    /**
+     * A file every frame is appended to, both directions, one JSON line each.
+     *
+     * `{ at, from, peer, frame }`, the lines `ahpd --wire` writes. `AHPC_RECORD`
+     * in the environment is the same thing spelt for a shell.
+     */
+    wire?: string;
     /** Told when the socket drops, so the badge can stop claiming otherwise. */
     onState?(state: 'connecting' | 'connected' | 'offline'): void;
     /**

package/dist/src/ahp/live.js

@@ -48,20 +48,23 @@ function isRpcRefusal(error) {
 /**
  * Versions to offer at `initialize`, most preferred first.
  *
- * A host picks the first entry it also speaks, so this is a preference rather
- * than a floor. Offering one the installed library has no types for is safe:
- * every command used here is stable across all of them.
+ * A host picks the highest entry it also speaks, so this is a preference
+ * rather than a floor. `0.9.0` is the newest published and the version the
+ * package below is built from; the two behind it are what an older host
+ * answers with, and every command used here is stable across all three.
  *
- * `1.0.0` is not published - VS Code's host vendors the protocol from its
- * repository and runs ahead of npm - and it accepts `^1.0.0` and nothing 0.x.
- * Leaving it out is therefore not the conservative choice: it is every entry
- * refused with `-32005`, which arrives here looking like a host that is not
- * there. `0.9.0` is the newest published, and the version the package below
- * is built from.
+ * `1.0.0` was here for two weeks, first. VS Code's host vendors the protocol
+ * from its repository and for that long carried a `1.0.0` that never reached
+ * the repository's `main`; it accepted `^1.0.0` and refused every `0.x` with
+ * `-32005`, so offering it was the only way in. It has since resynced to the
+ * published `0.9.0`. Offering a version the installed types do not describe is
+ * the wrong kind of forward-compatibility - a host that took it could answer
+ * in a shape nothing here has heard of - so it came out the day no host
+ * needed it.
  *
  * This list is load-bearing, because there is no fallback behind it.
  */
-const VERSIONS = ['1.0.0', '0.9.0', '0.8.0', '0.7.0'];
+const VERSIONS = ['0.9.0', '0.8.0', '0.7.0'];
 const ROOT = 'ahp-root://';
 const AUTOMATIONS = 'ahp-automations://';
 export class MissingProtocolPackage extends Error {
@@ -90,22 +93,32 @@ function locale() {
         return undefined;
     return tag;
 }
-function tee(inner, heard) {
+function tee(inner, heard, wire) {
     /*
-     * Every frame, to a file, when `AHPC_RECORD` names one.
+     * Every frame, to a file, when `--wire` or `AHPC_RECORD` names one.
      *
      * Both directions: `tools/validate.mjs` checks what a host sent *and* what
      * this client sent, and until this existed the only captures to check were
-     * another client's traffic. Appended synchronously and deliberately - a
-     * recording that lost the frame a crash happened on would be a recording of
-     * everything except the interesting part.
+     * another client's traffic. The lines are the ones `ahpd --wire` writes -
+     * `at`, `from`, `peer`, `frame` - so one reader serves a capture from either
+     * end, and `peer` is the host's URL so a capture across two hosts can be
+     * read apart. Appended synchronously and deliberately - a recording that
+     * lost the frame a crash happened on would be a recording of everything
+     * except the interesting part.
      */
-    const recording = process.env.AHPC_RECORD;
-    const write = (from, frame) => {
+    const recording = wire.file ?? process.env.AHPC_RECORD;
+    const write = (from, text) => {
         if (recording === undefined || recording === '')
             return;
+        // Parsed, so `jq` reads the file; kept as text when it is not JSON, since
+        // a frame that is not is exactly what a capture is for.
+        let frame = text;
         try {
-            appendFileSync(recording, `${JSON.stringify({ at: new Date().toISOString(), from, frame })}\n`);
+            frame = JSON.parse(text);
+        }
+        catch { /* kept as text */ }
+        try {
+            appendFileSync(recording, `${JSON.stringify({ at: new Date().toISOString(), from, peer: wire.peer, frame })}\n`);
         }
         catch { /* a recording is a convenience, never a reason to fail a call */ }
     };
@@ -119,7 +132,7 @@ function tee(inner, heard) {
             const frame = await inner.recv();
             if (frame === null)
                 return null;
-            write('host', frame.kind === 'text' ? frame.text : JSON.stringify(frame.message));
+            write('host', frame.kind === 'text' ? frame.text ?? '' : JSON.stringify(frame.message));
             try {
                 const message = frame.kind === 'parsed'
                     ? bag(frame.message)
@@ -302,17 +315,20 @@ function toolCall(value) {
     const files = content
         .map((entry) => str(bag(bag(entry).file).uri) ?? str(bag(entry).uri))
         .filter((entry) => entry !== undefined);
+    const status = (str(call.status) ?? 'running');
+    const progress = status === 'running' ? plain(bag(call._meta).progressMessage) : undefined;
     return {
         id: str(call.toolCallId) ?? randomUUID(),
         name: str(call.displayName) ?? str(call.toolName) ?? 'tool',
         toolName: str(call.toolName) ?? 'tool',
-        status: (str(call.status) ?? 'running'),
+        status,
         // A `ContentRef` is a promise of content rather than content: reporting
         // nothing is better than reporting the reference as if it were the command.
         ...(typeof input === 'string' ? { input } : {}),
         ...(plain(call.intention) ?? plain(call.invocationMessage)
             ? { intention: (plain(call.intention) ?? plain(call.invocationMessage)) }
             : {}),
+        ...(progress !== undefined ? { progress } : {}),
         ...(plain(call.pastTenseMessage) ? { outcome: plain(call.pastTenseMessage) } : {}),
         ...(text ? { output: text } : {}),
         ...(files.length > 0 ? { files } : {}),
@@ -430,8 +446,11 @@ function transcript(chat) {
     const built = (value, running) => {
         const rows = [];
         const found = bag(value);
+        const hidden = hiddenOf(bag(found.message));
+        if (hidden === 'turn')
+            return rows;
         const said = str(bag(found.message).text);
-        if (said) {
+        if (said && hidden !== 'request') {
             rows.push({
                 id: `${str(found.id) ?? ''}:said`,
                 role: 'user',
@@ -503,6 +522,28 @@ function transcript(chat) {
         out.push(...built(chat.activeTurn, true));
     return out;
 }
+/**
+ * Whether the reference client would draw a message, and how much of it.
+ *
+ * Two well-known keys on a message's `_meta`, VS Code's own, each with a
+ * text-prefix spelling for a host that cannot write `_meta`: one hides the
+ * whole turn, the other only the request row and leaves the answer. They are
+ * how the editor keeps its own house out of the transcript - a "Couldn't open
+ * session" notice, an Agent Merge status - which the host appended as a turn
+ * because that is the one thing a host can append. Read at the projection
+ * rather than the view: a turn nobody would draw is a turn that is not there.
+ */
+function hiddenOf(message) {
+    const meta = bag(message._meta);
+    const text = str(message.text) ?? '';
+    if (meta['vscode.chat.hiddenFromTranscript'] === true
+        || text.startsWith('<!-- vscode-hidden-from-transcript -->\n'))
+        return 'turn';
+    if (meta['vscode.chat.requestHiddenFromTranscript'] === true
+        || text.startsWith('<!-- vscode-request-hidden-from-transcript -->\n'))
+        return 'request';
+    return undefined;
+}
 /** What `transcript` has already built for a finished turn. See the note in it. */
 const ready = new WeakMap();
 /** And for a whole `turns` array, which is what a streaming reply does not change. */
@@ -722,10 +763,17 @@ function config(value) {
                 })),
                 sessionMutable: property.sessionMutable === true,
                 ...(property.enumDynamic === true ? { enumDynamic: true } : {}),
+                ...(property.readOnly === true ? { readOnly: true } : {}),
                 ...(str(property.default) ? { default: str(property.default) } : {}),
             };
         }),
-        values: Object.fromEntries(Object.entries(values).map(([key, entry]) => [key, String(entry)])),
+        // What is on a chip, and what goes back to the host as answered: one
+        // value each. `permissions` is an object and `shellInitScripts` a list,
+        // and neither is a control here - stringified they went back to the host
+        // as `[object Object]`, an answer to a question nobody was asked.
+        values: Object.fromEntries(Object.entries(values)
+            .filter(([, entry]) => typeof entry === 'string' || typeof entry === 'number' || typeof entry === 'boolean')
+            .map(([key, entry]) => [key, String(entry)])),
     };
 }
 /**
@@ -975,6 +1023,7 @@ export async function liveHost(options) {
      */
     const clientId = options.clientId ?? `ahpc-${randomUUID().slice(0, 8)}`;
     const openTransport = options.connect ?? (() => ahp.connect(endpoint));
+    const wiring = { ...(options.wire !== undefined ? { file: options.wire } : {}), peer: options.url };
     const backoff = options.backoff ?? BACKOFF;
     const keepaliveMs = options.keepaliveMs ?? KEEPALIVE_MS;
     /**
@@ -1030,7 +1079,7 @@ export async function liveHost(options) {
         working.set(token, `${said}${share}`);
         options.onProgress?.(token, `${said}${share}`);
     };
-    const transport = tee(await openTransport(), notified);
+    const transport = tee(await openTransport(), notified, wiring);
     let client = new ahp.Client(transport, {});
     /*
      * What a host may ask this client for.
@@ -1172,20 +1221,19 @@ export async function liveHost(options) {
      * become a different answer on the next keystroke.
      */
     /**
-     * The automations catalogue, under whichever name the host's version gives it.
+     * The automations catalogue, under whichever name the host gives it.
      *
-     * This is the whole of what changed between protocol 0.9.0 and 1.0.0 in
-     * anything this client reads. 0.9.0 calls the catalogue `AutomationState`
-     * and puts the automations in `entries`; 1.0.0 renames the catalogue to
-     * `AutomationCatalogState` and the field to `automations`, and moves the
-     * name `AutomationState` onto a single automation. The automations
-     * themselves did not move - 0.9.0's `AutomationEntry` and 1.0.0's
-     * `AutomationState` have the same fields, and every action on the channel
-     * kept its name and its shape.
+     * The protocol's `AutomationState` puts the automations in `entries`. For
+     * two weeks VS Code's vendored copy called the catalogue
+     * `AutomationCatalogState` with the field named `automations`, and moved
+     * the name `AutomationState` onto a single automation; it has since gone
+     * back, but Insiders builds from that window are still out there, and the
+     * automations themselves never moved - the same fields either way, and
+     * every action on the channel kept its name and its shape.
      *
      * So one field is normalised here, at the edge, and everything past this
-     * point - the reducer included, which is the 0.9.0 one and reads `entries` -
-     * carries on unaware there was ever a second spelling.
+     * point - the reducer included, which reads `entries` - carries on unaware
+     * there was ever a second spelling. It costs one line to keep.
      */
     const automationCatalogue = (state) => {
         if (state === null)
@@ -1320,7 +1368,7 @@ export async function liveHost(options) {
                 if (finished)
                     return;
                 try {
-                    const socket = tee(await openTransport(), notified);
+                    const socket = tee(await openTransport(), notified, wiring);
                     const fresh = new ahp.Client(socket, {});
                     fresh.setServerRequestHandler(answering);
                     fresh.connect();
@@ -1495,7 +1543,12 @@ export async function liveHost(options) {
          */
         resourceList: async (uri) => {
             const result = bag(await client.request('resourceList', { channel: ROOT, uri }));
-            const parent = uri.replace(/\/+$/, '');
+            // A root's trailing slash is its whole path: `file:///` trimmed like a
+            // folder is `file:`, and every entry under it - and every folder walked
+            // to from there - was `file:/name`, which no host lists or starts a
+            // session in.
+            const root = /^[a-z][\w+.-]*:\/*$/i.test(uri);
+            const parent = root ? uri.replace(/\/*$/, '//') : uri.replace(/\/+$/, '');
             return list(result.entries).map((raw) => {
                 const entry = bag(raw);
                 return {
@@ -2183,7 +2236,10 @@ export async function liveHost(options) {
                     turns: all.filter((found) => found !== active),
                     ...(active ? { active } : {}),
                     ...(asked ? { input: asked } : {}),
-                    status: activityOf(typeof session.status === 'number' ? session.status : 1, Boolean(asked), active !== undefined, all[all.length - 1]?.state === 'failed'),
+                    status: activityOf(typeof session.status === 'number' ? session.status : 1, Boolean(asked), 
+                    // From the wire, not from `active`: a running turn the reference
+                    // client hides is still a turn the session is working on.
+                    Boolean(chat.activeTurn), all[all.length - 1]?.state === 'failed'),
                     queued: queued(chat),
                     // What the host is holding as the message being composed. Shared
                     // state: another client typing here is visible, and it outlives

package/dist/src/ahp/publish.js

@@ -188,6 +188,13 @@ export function publish(options = {}) {
                 flags |= constants.O_CREAT;
             if (createOnly && ifMatch === undefined)
                 flags |= constants.O_EXCL;
+            // `O_NOFOLLOW` is what refuses a final link, and Windows has no such
+            // flag: `constants.O_NOFOLLOW` is undefined there and the `|` above is a
+            // no-op. That end is asked about the link first, which is the best it
+            // offers; where the flag exists the open itself is the check.
+            if (constants.O_NOFOLLOW === undefined && await lstat(at).then((found) => found.isSymbolicLink(), () => false)) {
+                throw new PublishRefusal(PERMISSION_DENIED, `${String(uri)} is a symbolic link.`);
+            }
             const file = await open(at, flags).catch((error) => {
                 if (createOnly && error.code === 'EEXIST') {
                     throw new PublishRefusal(ALREADY_EXISTS, `${String(uri)} already exists.`);
@@ -210,6 +217,12 @@ export function publish(options = {}) {
                 throw new PublishRefusal(PERMISSION_DENIED, `Could not write ${String(uri)}: ${error.message}`);
             });
             try {
+                // Windows opens a directory for writing and fails at the first write
+                // instead, with an `EISDIR` the catch above never sees; asked here so
+                // both ends refuse before anything is touched.
+                if (process.platform === 'win32' && (await file.stat()).isDirectory()) {
+                    throw new PublishRefusal(PERMISSION_DENIED, `${String(uri)} is a directory.`);
+                }
                 if (createOnly && ifMatch !== undefined) {
                     throw new PublishRefusal(ALREADY_EXISTS, `${String(uri)} already exists.`);
                 }

package/dist/src/ahp/types.d.ts

@@ -141,6 +141,16 @@ export interface ToolCall {
     input?: string;
     /** What it meant to do. Markdown. */
     intention?: string;
+    /**
+     * What it is doing right now, while it runs.
+     *
+     * `_meta.progressMessage`, the reference host's key for a line drawn on a
+     * running row and dropped when the row ends: a subagent's own summary of
+     * how far it has got, the last tool it reached for. Read only while
+     * `running`; a host that leaves it on a finished call is still describing
+     * a state the call is no longer in.
+     */
+    progress?: string;
     /** What it did, past tense. */
     outcome?: string;
     /** What came back. */
@@ -572,6 +582,16 @@ export interface ConfigProperty {
      * the schema says "ask me" and `sessionConfigCompletions` is the asking.
      */
     enumDynamic?: boolean;
+    /**
+     * Shown, never asked.
+     *
+     * The reference host puts this on a value the client seeds rather than a
+     * person picks - a branch prefix, whether a worktree gets a branch of its
+     * own - and on `branch` while isolation is `folder`, where the checkout
+     * decides and a control would change nothing. Offered anyway it produces a
+     * refusal, not an edit.
+     */
+    readOnly?: boolean;
     /**
      * What the host opens with, where it said.
      *

package/dist/src/app.js

@@ -3,19 +3,15 @@ import { createBag, defineComponent, useApp, useTheme, useStoreSubtree, useStore
 import { KeyHints, Row, registerBuiltins } from '@textui/widgets';
 import { CONTROLLER, createController } from './control.js';
 import { fakeHost } from './ahp/fake.js';
+import { hostResources } from './resources.js';
 import { BOOD, BOOD_FLOAT, BOOD_FLOOR, BOOD_INLINE, FOCUS, HOST, HOST_ERROR, INPUT, INPUT_STATUS, OPEN, RUNNING, SCREEN, SESSIONS, SPLIT_AT, SPLIT_DEFAULT, STATUS, WORKSPACE, boodFloor, openSession, workspaceName, } from './state.js';
 import { decodeStatus } from './ahp/status.js';
 import { AutomationsScreen, ChangesScreen, ChatScreen, FilesScreen, HostsScreen, McpScreen, NewAutomationScreen, NewSessionScreen, SessionsScreen, TerminalScreen, SettingsScreen, SkillsScreen, } from './screens.js';
-import { ChatBubble, ReasoningBlock, StreamingText } from './view/bubble.js';
-import { ChatComposer } from './view/composer.js';
-import { ChatHitl } from './view/hitl.js';
-import { ChatTranscript } from './view/transcript.js';
+import { ChatBubble, ChatComposer, ChatHitl, ChatTranscript, ConnectionBadge, ReasoningBlock, SEND_ID, SessionList, StreamingText, ToolCallRow, } from '@textui/chat';
 import { BoodSprite, Creature, moodOf, pickBood } from './view/creature.js';
 import { ChangesList } from './view/changes.js';
 import { FileList } from './view/files.js';
 import { AutomationList } from './view/automations.js';
-import { ConnectionBadge, SessionList } from './view/sessions.js';
-import { ToolCallRow } from './view/toolcall.js';
 /**
  * A chat client for an agent host.
  *
@@ -124,6 +120,7 @@ const Header = defineComponent('ChatHeader', () => {
  */
 const Hints = defineComponent('ChatHints', (props) => {
     const theme = useTheme();
+    const app = useApp();
     /**
      * Which key the footer names for a newline.
      *
@@ -153,8 +150,19 @@ const Hints = defineComponent('ChatHints', (props) => {
     // it, escape leaves the field; from the transcript, escape leaves the
     // screen - and a hint row that said one of those in both places is wrong
     // half the time.
-    const focused = useStoreValue(FOCUS, null);
+    const focused = useStoreValue(FOCUS, null) ?? null;
     const composing = focused === 'chat.composer';
+    // The control rows under the field are their own place: enter there opens
+    // a chip's panel or sends, and "alt+enter newline" is a key for a field
+    // the keyboard has left.
+    const onChip = focused !== null && focused.startsWith('chat.option.');
+    const onSend = focused === SEND_ID;
+    // A panel over the screen - a chip's picker, the palette - holds the
+    // keyboard, and the keys are the panel's until it closes. Read off the
+    // layers when the focus moves, which a panel that traps it does on the way
+    // in and on the way out; the layers themselves are not something a
+    // component can subscribe to.
+    const inPanel = app.layers.entries().some((entry) => entry.trapFocus === true);
     // A question is not a confirmation, and the keys are not the same either.
     // Offering "a approve" over an elicitation is the same mistake as rendering
     // one as the other, made in the one row that is supposed to explain it.
@@ -174,6 +182,22 @@ const Hints = defineComponent('ChatHints', (props) => {
                 { keys: 'esc', label: 'read' },
             ] }));
     }
+    if (inPanel) {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: upDown, label: 'move' },
+                { keys: 'enter', label: 'choose' },
+                { keys: 'esc', label: 'back' },
+                { keys: 'ctrl+c', label: running ? 'stop' : 'quit' },
+            ] }));
+    }
+    if ((screen === 'chat' || screen === 'new') && (onChip || onSend)) {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: 'enter', label: onSend ? (screen === 'new' ? 'start' : running ? 'queue' : 'send') : 'open' },
+                { keys: 'tab', label: 'next option' },
+                { keys: 'esc', label: 'write' },
+                { keys: 'ctrl+c', label: running ? 'stop' : 'quit' },
+            ] }));
+    }
     if (screen === 'chat') {
         return (_jsx(KeyHints, { ...props, hints: composing
                 ? [
@@ -293,6 +317,9 @@ export function registerChat(app, options = {}) {
     app.store.set(BOOD_FLOAT, options.boodFloat ?? false);
     bag.add(controller);
     bag.add(app.services.provide(CONTROLLER, controller));
+    // `file:` is the host's disk from here on, for the picker and anything
+    // else in textui that reads the resource registry.
+    bag.add(app.resources.registerProvider(hostResources(host)));
     for (const [component, render] of [
         ['ChatBubble', ChatBubble],
         ['StreamingText', StreamingText],