@timqi/pier 0.0.5 → 0.0.7

package/README.md

@@ -17,6 +17,7 @@ versioned from `0.0.1` on — earlier databases are not migrated. Read
 ## Requirements
 
 - Node 24 or newer (`node:sqlite` is used unflagged)
+- Linux: Python 3, `make` and a C/C++ compiler for `node-pty`
 - A provider account (Anthropic, OpenAI, …) — configure its API key or OAuth
   login from Console → Settings → Providers after signing in
 - A user-writable global npm prefix if `pier update` should update a service

package/dist/agent/events.js

@@ -2,6 +2,7 @@
 // purpose: no @earendil-works/pi-* imports, so it stays unit-testable without Pi
 // and Pi types never leak past the seam. The golden-table test in
 // events.test.ts is the mapping's spec; extend types.ts before adding events.
+import { MAX_STEP_OUTPUT } from "../core/types.js";
 export function textOf(content) {
     if (typeof content === "string")
         return content;
@@ -101,8 +102,12 @@ export function toChatTurns(messages) {
         if (m.role === "toolResult") {
             const step = pendingTools.get(m.toolCallId ?? "");
             if (step) {
-                step.output = textOf(m.content);
+                // Capped where the transcript is rebuilt, not where it is rendered: a
+                // long session's tool results are megabytes nobody ever sees.
+                const output = textOf(m.content);
+                step.output = output.length > MAX_STEP_OUTPUT ? output.slice(0, MAX_STEP_OUTPUT) + "…" : output;
                 step.isError = m.isError ?? false;
+                step.done = true;
                 pendingTools.delete(m.toolCallId ?? "");
             }
             continue;

package/dist/agent/pi.js

@@ -203,6 +203,11 @@ export class PiAgentFactory {
     }
     /** One runtime for the whole process; catalogs are global, not per session. */
     catalog;
+    /** Where each listed session lives. `listAll` reads the head of every
+     *  session file on disk (~250ms at 200 sessions, and it only grows), which
+     *  `resume` paid on every cold open — web selection, an IM message, a task
+     *  run. The sidebar's own listing keeps this warm; a miss still lists. */
+    located = new Map();
     refreshQueue = Promise.resolve();
     builtinProviderIds;
     /** Structural fit: CredentialStore mirrors pi-ai's interface of the same
@@ -414,7 +419,7 @@ export class PiAgentFactory {
         return this.open(opts.cwd, SessionManager.create(opts.cwd), opts);
     }
     async fork(sourceSessionId, opts) {
-        const infos = await SessionManager.listAll();
+        const infos = await this.listed();
         const source = infos.find((session) => session.id === sourceSessionId);
         if (!source)
             throw new Error(`unknown session: ${sourceSessionId}`);
@@ -433,14 +438,34 @@ export class PiAgentFactory {
         return this.open(opts.cwd, manager, opts);
     }
     async resume(sessionId) {
-        const infos = await SessionManager.listAll();
+        const known = this.located.get(sessionId);
+        if (known) {
+            try {
+                return await this.open(known.cwd, SessionManager.open(known.path));
+            }
+            catch (err) {
+                // The file moved or went away under us: the cache was the only thing
+                // that claimed otherwise, so drop it and take the slow, true path.
+                log.warn(`cached path for session ${sessionId} did not open; re-listing`, err);
+                this.located.delete(sessionId);
+            }
+        }
+        const infos = await this.listed();
         const info = infos.find((s) => s.id === sessionId);
         if (!info)
             throw new Error(`unknown session: ${sessionId}`);
         return this.open(info.cwd || process.cwd(), SessionManager.open(info.path));
     }
-    async list() {
+    /** Every listing goes through here, so it also refreshes `located`. */
+    async listed() {
         const infos = await SessionManager.listAll();
+        for (const s of infos) {
+            this.located.set(s.id, { path: s.path, cwd: s.cwd || process.cwd() });
+        }
+        return infos;
+    }
+    async list() {
+        const infos = await this.listed();
         return infos.map((s) => ({
             id: s.id,
             cwd: s.cwd,

package/dist/channels/chunk.js

@@ -26,3 +26,37 @@ export function chunkText(text, max) {
         parts.push(rest);
     return parts;
 }
+/**
+ * Close a fence a chunk left open, and reopen it on the next one. Telegram can
+ * be cut mid-`<pre>` and shrug — its parser closes the tag itself — but Slack
+ * and Lark both swallow the rest of a message after an unterminated ```, and
+ * the next chunk starts *outside* a fence, so the tail of a long code block
+ * renders as prose.
+ *
+ * Fences are tracked by line-leading runs with their *length*, per CommonMark:
+ * a ```` fence (used to quote a ``` block) only closes on a run at least as
+ * long, so counting bare ``` occurrences would see the inner block close the
+ * outer one and mangle both halves of the cut.
+ */
+export function balanceFences(parts) {
+    /** Backticks of the fence currently open across the boundary; 0 = closed. */
+    let open = 0;
+    const fence = (n) => "`".repeat(n);
+    return parts.map((part) => {
+        const reopened = open ? `${fence(open)}\n${part}` : part;
+        // The prepended fence counts too — the scan restarts from "closed" and
+        // reads it as the opener, so a chunk that closes the block it inherited
+        // comes out even.
+        open = 0;
+        for (const line of reopened.split("\n")) {
+            const run = /^\s*(`{3,})/.exec(line)?.[1]?.length ?? 0;
+            if (!run)
+                continue;
+            if (!open)
+                open = run;
+            else if (run >= open)
+                open = 0; // a closing run must match the opener
+        }
+        return open ? `${reopened}\n${fence(open)}` : reopened;
+    });
+}

package/dist/channels/control.js

@@ -5,21 +5,15 @@
 // prompt and must not become a second seam. So the channel layer — which owns
 // the router already — hands adapters this narrow, platform-blind interface.
 // Everything here is a thin wrapper over core; no policy lives in it.
-import { parseConversation as parseSlack } from "./slack.js";
-import { parseConversation as parseTelegram } from "./telegram.js";
+import { chatOf, isChannelPlatform } from "./types.js";
 export function createControl({ router, factory, conversations, store }) {
     const launchFor = (key) => {
-        const platform = key.channelId;
-        // Decoding a conversation id back to a chat id is the adapter layer's
-        // business, never core's — so each platform's own parser is used here.
-        const chatId = platform === "telegram"
-            ? parseTelegram(key.conversationId).chatId
-            : platform === "slack"
-                ? parseSlack(key.conversationId).channel
-                : undefined;
-        if (chatId === undefined)
+        // Decoding a conversation id back to a chat id is the channel layer's
+        // business, never core's; the chat half of every platform's id has one
+        // decoder (chatOf), so no adapter import is needed here.
+        if (!isChannelPlatform(key.channelId))
             return {};
-        const policy = store.policy(platform, chatId);
+        const policy = store.policy(key.channelId, chatOf(key.conversationId));
         return {
             cwd: policy.cwd || undefined,
             model: policy.model ?? undefined,

package/dist/channels/dedup.js

@@ -0,0 +1,45 @@
+// At-least-once delivery, deduplicated: both push transports (Slack Socket
+// Mode, Lark's long connection) redeliver an event the platform did not see
+// acknowledged, so the same id can arrive twice. One implementation, because
+// the second copy had already appeared and the map has an invariant that is
+// easy to lose on a rewrite: it is fed by every message in every chat the bot
+// is in, so it must be bounded and time-limited, never grow-only.
+export class Dedup {
+    log;
+    ttlMs;
+    max;
+    seen = new Map();
+    constructor(log, ttlMs, max) {
+        this.log = log;
+        this.ttlMs = ttlMs;
+        this.max = max;
+    }
+    /** True when this id was already delivered inside the TTL. */
+    duplicate(eventId, now = Date.now()) {
+        if (!eventId)
+            return false;
+        if (this.seen.size >= this.max) {
+            for (const [id, at] of this.seen) {
+                if (now - at > this.ttlMs)
+                    this.seen.delete(id);
+            }
+            // Pruning expired entries is not enough under a burst of live ones —
+            // `max` must be a real bound, so the oldest entries go next. The cost
+            // is a forgotten id under extreme load (a redelivery slips through,
+            // which downstream handling tolerates); unbounded memory is worse.
+            // Map iterates in insertion order, so the front is the oldest.
+            for (const [id] of this.seen) {
+                if (this.seen.size < this.max)
+                    break;
+                this.seen.delete(id);
+            }
+        }
+        const at = this.seen.get(eventId);
+        if (at !== undefined && now - at <= this.ttlMs) {
+            this.log(`duplicate event ${eventId} ignored`);
+            return true;
+        }
+        this.seen.set(eventId, now);
+        return false;
+    }
+}

package/dist/channels/lark-api.js

@@ -0,0 +1,233 @@
+// Thin Lark (Feishu) client: API shapes and the WebSocket transport, no policy.
+// The one file in channels/ that talks to open.feishu.cn, so the adapter stays
+// testable against `LarkClient`.
+//
+// Unlike Slack's Socket Mode — JSON frames a while loop can own — Lark's long
+// connection is a protobuf-framed proprietary protocol with server-pushed
+// reconnect/ping config, so the official SDK carries the transport (and its
+// tenant-token refresh). It is confined to this file; nothing SDK-shaped leaks
+// past `LarkClient`. Domain is fixed to Feishu (open.feishu.cn) on purpose:
+// this instance's operator uses Feishu, and a Lark-international switch is a
+// config field we would carry for nobody.
+//
+// Two credentials, like Slack but for a different reason: every call and the
+// socket itself authenticate as `app_id` + `app_secret`, so ChannelConfig's
+// `token` carries the App ID and `appToken` the App Secret.
+//
+// One transport fact that shaped the adapter: the SDK sends the WS response
+// frame only *after* the registered handler resolves, and Lark redelivers what
+// it never saw answered — so handlers here must return once the event is
+// queued, never once it is handled ("ack is not handling", paid for on Slack).
+import * as Lark from "@larksuiteoapi/node-sdk";
+/** Lark answers HTTP 200 with a business code; non-zero is the real error. */
+function ok(what, res) {
+    if (res.code !== 0)
+        throw new Error(`lark ${what}: ${res.code} ${res.msg ?? ""}`.trim());
+    return res;
+}
+export class LarkApi {
+    log;
+    client;
+    /** Our own open_id, remembered from botOpenId() — reaction removal must
+     *  only ever touch a reaction *this* app made. */
+    me = "";
+    constructor(appId, appSecret, log = () => { }) {
+        this.log = log;
+        this.client = new Lark.Client({
+            appId,
+            appSecret,
+            domain: Lark.Domain.Feishu,
+            loggerLevel: Lark.LoggerLevel.error,
+        });
+        this.appId = appId;
+        this.appSecret = appSecret;
+    }
+    appId;
+    appSecret;
+    async botOpenId() {
+        const res = await this.client.request({
+            url: "/open-apis/bot/v3/info",
+            method: "GET",
+        });
+        this.me = ok("bot info", res).bot?.open_id ?? "";
+        return this.me;
+    }
+    // --- long connection ---------------------------------------------------------
+    /**
+     * The SDK owns the loop: endpoint discovery, protobuf frames, ping/pong and
+     * the reconnect pacing the server itself pushes down. `card.action.trigger`
+     * is registered through `register`'s generic because IHandles types events
+     * only, not callbacks; its payload shape is pinned by the adapter's golden
+     * tests instead.
+     */
+    connect(handlers) {
+        const dispatcher = new Lark.EventDispatcher({
+            loggerLevel: Lark.LoggerLevel.error,
+        }).register({
+            "im.message.receive_v1": (data) => {
+                handlers.onMessage({
+                    eventId: data.event_id,
+                    senderId: data.sender?.sender_id?.open_id,
+                    senderType: data.sender?.sender_type,
+                    message: {
+                        messageId: data.message.message_id,
+                        rootId: data.message.root_id,
+                        chatId: data.message.chat_id,
+                        chatType: data.message.chat_type,
+                        messageType: data.message.message_type,
+                        content: data.message.content,
+                        mentions: data.message.mentions,
+                    },
+                });
+                // Resolve now: the SDK answers the frame only after this returns, and
+                // a turn outlives Lark's redelivery deadline.
+                return Promise.resolve();
+            },
+            "card.action.trigger": (data) => {
+                handlers.onCardAction({
+                    eventId: data.event_id,
+                    messageId: data.context?.open_message_id ?? data.open_message_id ?? "",
+                    chatId: data.context?.open_chat_id ?? data.open_chat_id ?? "",
+                    operatorId: data.operator?.open_id ?? "",
+                    value: data.action?.value,
+                    name: data.action?.name,
+                    formValue: data.action?.form_value,
+                });
+                return Promise.resolve();
+            },
+        });
+        const ws = new Lark.WSClient({
+            appId: this.appId,
+            appSecret: this.appSecret,
+            domain: Lark.Domain.Feishu,
+            loggerLevel: Lark.LoggerLevel.error,
+        });
+        // Fire and forget, deliberately: start() settles on the SDK's schedule —
+        // it retries a busy endpoint and can sit in that loop for a long time —
+        // and ChannelRuntime serializes reloads, so awaiting here would let one
+        // unreachable network block every later Console save. Credentials were
+        // already proven by botOpenId() before connect() is called; a transport
+        // failure after that is the reconnect loop's job, and is logged.
+        void ws.start({ eventDispatcher: dispatcher })
+            .catch((err) => this.log(`lark long connection failed: ${String(err)}`));
+        return Promise.resolve({
+            close: () => {
+                try {
+                    ws.close();
+                }
+                catch (err) {
+                    this.log(`lark socket close failed: ${String(err)}`);
+                }
+                return Promise.resolve();
+            },
+        });
+    }
+    // --- messages ------------------------------------------------------------------
+    async replyCard(messageId, card) {
+        const res = await this.client.im.v1.message.reply({
+            path: { message_id: messageId },
+            data: {
+                msg_type: "interactive",
+                content: JSON.stringify(card),
+                // What makes the reply land in the message's own topic instead of the
+                // chat's main flow — Lark's equivalent of posting to a thread_ts.
+                reply_in_thread: true,
+            },
+        });
+        return { messageId: ok("message.reply", res).data?.message_id ?? "" };
+    }
+    async patchCard(messageId, card) {
+        ok("message.patch", await this.client.im.v1.message.patch({
+            path: { message_id: messageId },
+            data: { content: JSON.stringify(card) },
+        }));
+    }
+    async deleteMessage(messageId) {
+        ok("message.delete", await this.client.im.v1.message.delete({ path: { message_id: messageId } }));
+    }
+    // --- reactions -------------------------------------------------------------------
+    async addReaction(messageId, emojiType) {
+        ok("reaction.create", await this.client.im.v1.messageReaction.create({
+            path: { message_id: messageId },
+            data: { reaction_type: { emoji_type: emojiType } },
+        }));
+    }
+    /**
+     * Lark deletes reactions by `reaction_id`, and several parties may have
+     * used the same emoji — so list, keep only the entry *this app* owns
+     * (`operator_type` alone is not ownership: another bot's 👀 is an app
+     * reaction too, and deleting it would strand our own), delete that.
+     */
+    async removeReaction(messageId, emojiType) {
+        let pageToken;
+        do {
+            const res = ok("reaction.list", await this.client.im.v1.messageReaction.list({
+                path: { message_id: messageId },
+                params: { reaction_type: emojiType, page_size: 50, page_token: pageToken },
+            }));
+            for (const item of res.data?.items ?? []) {
+                const op = item.operator;
+                if (op?.operator_type !== "app")
+                    continue;
+                // The list reports an app operator by open_id or app_id depending on
+                // surface; accept either of ours, never a blank (avibe's rule).
+                const id = (op.operator_id ?? "").trim();
+                if (!id || (id !== this.me && id !== this.appId))
+                    continue;
+                if (item.reaction_id) {
+                    ok("reaction.delete", await this.client.im.v1.messageReaction.delete({
+                        path: { message_id: messageId, reaction_id: item.reaction_id },
+                    }));
+                    return;
+                }
+            }
+            pageToken = res.data?.has_more ? res.data?.page_token : undefined;
+        } while (pageToken);
+    }
+    // --- lookups ---------------------------------------------------------------------
+    async chatName(chatId) {
+        const res = ok("chat.get", await this.client.im.v1.chat.get({ path: { chat_id: chatId } }));
+        return res.data?.name || undefined;
+    }
+    async userName(openId) {
+        // Needs contact:user.base:readonly; without it the id is the honest label.
+        try {
+            const res = ok("user.get", await this.client.contact.v3.user.get({
+                path: { user_id: openId },
+                params: { user_id_type: "open_id" },
+            }));
+            return res.data?.user?.name || openId;
+        }
+        catch (err) {
+            this.log(`lark user lookup failed for ${openId}: ${String(err)}`);
+            return openId;
+        }
+    }
+    // --- files ----------------------------------------------------------------------
+    /**
+     * `maxBytes` is enforced *while streaming*: the receive event often omits
+     * `file_size`, so the metadata check upstream cannot be the only cap, and
+     * buffering an unbounded stream whole into memory is the exact failure the
+     * cap exists for. The error message carries "too large" — the adapter's
+     * lost-marker wording keys on it.
+     */
+    async download(messageId, fileKey, type, maxBytes) {
+        const res = await this.client.im.v1.messageResource.get({
+            path: { message_id: messageId, file_key: fileKey },
+            params: { type },
+        });
+        const stream = res.getReadableStream();
+        const parts = [];
+        let size = 0;
+        for await (const part of stream) {
+            const buf = Buffer.isBuffer(part) ? part : Buffer.from(part);
+            size += buf.length;
+            if (size > maxBytes) {
+                stream.destroy?.();
+                throw new Error(`lark resource ${fileKey}: too large (>${maxBytes} bytes)`);
+            }
+            parts.push(buf);
+        }
+        return { bytes: new Uint8Array(Buffer.concat(parts)) };
+    }
+}

package/dist/channels/lark-outbound.js

@@ -0,0 +1,101 @@
+// How a turn becomes cards in a Lark thread.
+//
+// Split from the adapter the way slack-outbound.ts is: what a turn renders as
+// — one card per chunk, footer and buttons on the last, and what an empty turn
+// still has to say — is a different decision from routing inbound traffic. The
+// adapter keeps the 👀 receipts, because those are about the turn ending, not
+// about what was said.
+import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
+import { button, buttonRow, card, chunk, footer, LARK_MAX, markdown, OFFER_PREFIX, withFooter, withoutButtons, } from "./lark-render.js";
+/** How many sent cards the retire cache remembers (avibe keeps 200). */
+const SENT_CACHE = 200;
+export class LarkOutbound {
+    api;
+    log;
+    /**
+     * The cards this process sent with buttons on them, for retiring the row
+     * once an option is taken — a 2.0 card cannot be read back from the
+     * platform (see LarkActionValue), so what we sent is the only copy.
+     * In-memory and bounded, copied from avibe: purely cosmetic state. A click
+     * after a restart still *works* (the label rides in the value); the buttons
+     * merely stay up, and the skip is logged.
+     */
+    sent = new Map();
+    constructor(api, log) {
+        this.api = api;
+        this.log = log;
+    }
+    /**
+     * Post one turn as replies into the conversation's thread, empty text
+     * included: a turn that produced nothing still posts its footer and says
+     * which kind of nothing it was — total silence is indistinguishable from a
+     * crash, and the person watching the 👀 come off has no way to tell.
+     *
+     * The footer folds into the last body chunk's own markdown element (a
+     * second element renders a blank gap); only a bodiless turn gets it as the
+     * standalone muted element. Buttons ride the last chunk, like every other
+     * platform — the card is remembered so retire() can rebuild it without them.
+     */
+    async reply(root, reply) {
+        const text = reply.text.trim();
+        const meta = reply.meta ? formatTurnMeta(reply.meta) : "";
+        const quiet = isSilentReply(reply) ? quietLabel(reply.silence) : "";
+        const note = [quiet, meta].filter(Boolean).join(" · ");
+        if (!(text || reply.suggestions.length || note))
+            return;
+        const row = reply.suggestions.length
+            ? buttonRow(reply.suggestions.map((label, index) => button(label, { key: `${OFFER_PREFIX}${index}`, root, label })))
+            : undefined;
+        const parts = text ? chunk(text, LARK_MAX) : [""];
+        for (const [i, part] of parts.entries()) {
+            const last = i === parts.length - 1;
+            const elements = [];
+            if (part)
+                elements.push(last && note ? withFooter(part, note) : markdown(part));
+            else if (last && note)
+                elements.push(footer(note));
+            if (last && row)
+                elements.push(row);
+            if (!elements.length)
+                continue;
+            const { messageId } = await this.api.replyCard(root, card(elements));
+            if (last && row && messageId)
+                this.remember(messageId, card(elements));
+        }
+    }
+    /**
+     * Take the buttons off a card one option was just taken from — the rest
+     * answer a question the conversation has moved past. Best-effort by design:
+     * an unremembered card (sent before a restart) keeps its row, logged.
+     */
+    async retire(messageId) {
+        const known = this.sent.get(messageId);
+        if (!known) {
+            this.log(`options on ${messageId} not retired: sent before this process`);
+            return;
+        }
+        this.sent.delete(messageId);
+        const kept = withoutButtons(known);
+        await this.api.patchCard(messageId, kept.body.elements.length ? kept : card([footer("Option taken.")])).catch((err) => this.log(`retiring options failed: ${String(err)}`));
+    }
+    remember(messageId, sent) {
+        this.sent.set(messageId, sent);
+        while (this.sent.size > SENT_CACHE) {
+            const oldest = this.sent.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.sent.delete(oldest);
+        }
+    }
+    /**
+     * A system note: quoted, labelled with where it came from, and deliberately
+     * plain — no buttons and no turn footer, because the turn this input
+     * triggers has not ended yet.
+     */
+    async note(root, note) {
+        const body = note.text.split("\n").map((line) => `> ${line}`).join("\n");
+        for (const part of chunk(`*${originLabel(note.origin)}*\n${body}`, LARK_MAX)) {
+            await this.api.replyCard(root, card([markdown(part)]));
+        }
+    }
+}

package/dist/channels/lark-panel.js

@@ -0,0 +1,95 @@
+// Lark's half of the settings panel: card markup, flow button rows, and a form
+// card for the one typed answer. The panel itself lives in `panel.ts`.
+//
+// Lark has no modal a WebSocket app can open — a "modal" here is the panel
+// message patched into a form card (an input plus a submit button), which is
+// avibe's verified pattern. The submit button's `name` carries the thread root
+// the same way every other panel button's callback value does, so a submission
+// needs no adapter-side state to find its conversation — the map below only
+// remembers where the panel message itself lives.
+import { button as cardButton, buttonRow, card, footer, formInput, markdown, } from "./lark-render.js";
+import { ChatPanel, CWD_PLACEHOLDER, CWD_TAIL, PANEL_PREFIX, } from "./panel.js";
+/** A form-submit button name: `cwdgo:<thread root>`. */
+export const CWD_SUBMIT_PREFIX = "cwdgo:";
+/** The form input's field name, the key `form_value` answers under. */
+export const CWD_FIELD = "cwd";
+export class LarkPanel extends ChatPanel {
+    deps;
+    platform = "lark";
+    fence = ["`", "`"];
+    constructor(deps) {
+        super(deps);
+        this.deps = deps;
+    }
+    /** Lark's markdown treats what it cannot parse as literal text; there is no
+     *  escape syntax to apply (see lark-render.ts). */
+    esc(text) {
+        return text;
+    }
+    // --- rendering -------------------------------------------------------------
+    btn(b, root) {
+        return cardButton(b.label, { key: `${PANEL_PREFIX}${b.action}`, root });
+    }
+    render(view, root, note) {
+        const elements = [
+            ...view.groups.map((g) => markdown([`**${g.title}**${g.suffix ?? ""}`, ...g.lines].join("\n"))),
+            // A flow row wraps, so a page of models lays out like Slack's one row.
+            ...(view.picks?.length ? [buttonRow(view.picks.map((p) => this.btn(p, root)))] : []),
+            ...view.rows.filter((r) => r.length).map((row) => buttonRow(row.map((b) => this.btn(b, root)))),
+        ];
+        if (note)
+            elements.push(footer(note));
+        return card(elements);
+    }
+    /** Open a fresh panel, replacing whichever one this conversation had. */
+    async open(key, chatId, root) {
+        const sent = await this.deps.api.replyCard(root, this.render(await this.view(key, chatId), root));
+        this.remember(key, { chatId, root, messageId: sent.messageId, models: [] });
+    }
+    async draw(state, view, note) {
+        await this.deps.api.patchCard(state.messageId, this.render(view, state.root, note))
+            .catch((err) => this.deps.log(`panel edit failed: ${String(err)}`));
+    }
+    async erase(state) {
+        await this.deps.api.deleteMessage(state.messageId)
+            .catch((err) => this.deps.log(`panel close failed: ${String(err)}`));
+    }
+    // --- actions ---------------------------------------------------------------
+    /**
+     * Handle a `cfg:` click. Returns false when the action is not ours, so the
+     * caller can treat it as one of the agent's next-step labels instead.
+     */
+    async onAction(action, key, payload, root) {
+        return this.dispatch(key, payload, action, () => this.open(key, action.chatId, root));
+    }
+    // --- working directory (one typed answer, in a form card) -------------------
+    async promptCwd(key, state, _action) {
+        const form = {
+            tag: "form",
+            name: "cwd_form",
+            elements: [
+                formInput(CWD_FIELD, "Working directory", CWD_PLACEHOLDER),
+                markdown(`An absolute path. ${CWD_TAIL}`),
+                {
+                    tag: "button",
+                    text: { tag: "plain_text", content: "Start" },
+                    type: "primary",
+                    action_type: "form_submit",
+                    name: `${CWD_SUBMIT_PREFIX}${state.root}`,
+                },
+            ],
+        };
+        await this.deps.api.patchCard(state.messageId, card([form, buttonRow([this.btn({ label: "Cancel", action: "panel" }, state.root)])])).catch((err) => this.deps.log(`cwd form failed: ${String(err)}`));
+    }
+    /**
+     * Consume a form submission. The adapter routes any `cwdgo:` submit here;
+     * a panel that outlived its process is re-remembered from the event itself,
+     * so the outcome still lands on the card the user is looking at.
+     */
+    async onCwdSubmit(key, action, root) {
+        if (!this.state(key)) {
+            this.remember(key, { chatId: action.chatId, root, messageId: action.messageId, models: [] });
+        }
+        await this.startSessionIn(key, String(action.formValue?.[CWD_FIELD] ?? "").trim());
+    }
+}