@timqi/pier 0.0.9 → 0.0.15

package/dist/agent/pi.js

@@ -6,14 +6,29 @@ import { inlineExtensions } from "../extensions/index.js";
 import { logger } from "../log.js";
 import { toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
 import { defaultAgentDir, PiConfigStore } from "./config.js";
+import { IndexedListing } from "./listing.js";
 import { curateModels, pinFirst } from "./models.js";
 const log = logger("agent");
+/** A listed record as the seam reports it. The one mapping, because `list` and
+ *  `find` answer with the same shape and drifting would mean two answers about
+ *  one session. */
+const summaryOf = (s) => ({
+    id: s.id,
+    cwd: s.cwd,
+    createdAt: s.created,
+    modified: s.modified,
+    ...(s.title ? { title: s.title } : {}),
+});
 /** Pi's bash tool has no default timeout, so a hung command holds the turn
  * until someone aborts it — nobody is watching in a scheduled task. Kept below
  * the default task-run timeout so a stuck command comes back as
  * a tool error the agent can retry with an explicit longer timeout, instead of
  * killing the whole run. */
 const BASH_DEFAULT_TIMEOUT_SECONDS = 600;
+/** How long a session listing stays usable: long enough that one workspace
+ *  event, which several surfaces answer at once, scans disk once; short enough
+ *  that a title no invalidation covers is never stale on screen. */
+const LIST_TTL_MS = 3_000;
 /** A probe nobody is watching is a hung page: the Console waits on this. */
 const PROVIDER_CHECK_TIMEOUT_MS = 20_000;
 /** An ordinary budget, not a token: a 1-token cap is a request no real turn
@@ -68,11 +83,21 @@ export const standDownShadowed = (base) => {
 export class PiSession {
     pi;
     pinned;
+    wrote;
+    retention;
     constructor(pi, 
     /** Operator pins, read per call — the menu can change while we run. */
-    pinned = () => []) {
+    pinned = () => [], 
+    /** "What I just wrote is not in your listing yet." The factory retains a
+     *  scan for a few seconds, which is exactly the window a rename lands in:
+     *  every surface would re-read the old title and keep it until some
+     *  unrelated event moved the list again. Same drop `create` and `fork`
+     *  do — a callback only because the session is what knows it happened. */
+    wrote = () => { }, retention = { value: "long" }) {
         this.pi = pi;
         this.pinned = pinned;
+        this.wrote = wrote;
+        this.retention = retention;
     }
     /** Pi's dispose unhooks the one listener that persists and emits, so a turn
      *  started after it runs for real — model call, tools and all — and lands
@@ -128,6 +153,9 @@ export class PiSession {
     setThinkingLevel(level) {
         this.pi.setThinkingLevel(level);
     }
+    setCacheRetention(retention) {
+        this.retention.value = retention;
+    }
     async pendingQueue() {
         return {
             steering: [...this.pi.getSteeringMessages()],
@@ -158,11 +186,73 @@ export class PiSession {
         if (cancelled)
             throw new Error("rewind cancelled");
     }
+    /** The compaction running right now, or null. Pi keeps no lock of its own —
+     *  a second `compact()` aborts the first's turn and summarizes a transcript
+     *  that is being replaced under it — and two POSTs a millisecond apart both
+     *  pass the route's idle check, so the gate has to be here. */
+    compacting = null;
+    /** Pi's own compaction, minus its `CompactionResult`: the numbers reach
+     *  surfaces as the `context-compacted` event the seam already emits for the
+     *  automatic one, so a caller has nothing to do with them. Refused while one
+     *  is running, rather than run twice over one context. */
+    async compact() {
+        this.live();
+        if (this.compacting)
+            throw new Error(`session ${this.pi.sessionId} is already compacting`);
+        // Started and recorded in the same tick, with no await between: that is
+        // what makes the check above a gate and not a hint.
+        const running = this.pi.compact().then(() => undefined);
+        this.compacting = running;
+        try {
+            await running;
+        }
+        finally {
+            this.compacting = null;
+        }
+    }
+    /** One `session_info` entry, which Pi's own reader takes the latest of — so
+     *  a rename is an append like everything else in a transcript, and nothing
+     *  has to be rewritten. Never refused for being busy: a name has nothing to
+     *  do with the turn running.
+     *
+     *  Returns nothing, because the transcript is the answer: what the session is
+     *  called after this — the name, or the title a cleared one falls back to —
+     *  is what the next listing reads off the file, and deriving it here as well
+     *  was a second copy of a rule agent/listing.ts already owns.
+     *
+     *  TODO: renaming a cold session costs a whole resume, because the route
+     *  reaches it through `ensure` and this method needs a live Pi session to
+     *  append through. The work is one line in a file. Revisit when Pi offers a
+     *  lightweight append to a session it has not loaded. */
+    async rename(name) {
+        this.live();
+        this.pi.sessionManager.appendSessionInfo(name);
+        this.wrote();
+    }
+    /** Compaction replaces the context a turn would run against, so a dispatch
+     *  that lands mid-compaction waits for the summary instead of starting a turn
+     *  over it — the follow-up promise ("delivered when idle") without Pi's
+     *  follow-up queue, which is only drained by the *next* turn: a message
+     *  parked there while nothing is running would sit unsent, and Pi's own
+     *  `prompt()` guard would have thrown the user's message away (§5b). */
+    async whenCompacted() {
+        while (this.compacting)
+            await this.compacting.catch(() => undefined);
+    }
     // Async, so a refusal is a rejected promise: the seam promises callers they
     // may only `.catch()` (core/types.ts), and dispatch does exactly that.
     async prompt(text) {
         this.live();
-        return this.pi.prompt(text);
+        await this.whenCompacted();
+        // Re-checked: the wait above is long enough for a dispose to land.
+        this.live();
+        // A turn may have started since the caller read the state this prompt was
+        // decided against — two messages arriving together, or several released at
+        // once by the wait above. Bare, Pi throws that back as "already
+        // processing" and the message is gone (§5b); queued, it is the same
+        // "delivered when idle" the core's own policy picks for an auto message
+        // that lands mid-turn (core/queue.ts).
+        return this.pi.prompt(text, { streamingBehavior: "followUp" });
     }
     async steer(text) {
         this.live();
@@ -173,6 +263,11 @@ export class PiSession {
         return this.pi.followUp(text);
     }
     async systemInput(text, origin, mode) {
+        this.live();
+        // Same gate as prompt(): an idle session takes a system input as a turn
+        // whatever the mode says, so a callback landing mid-compaction would race
+        // the summary too.
+        await this.whenCompacted();
         this.live();
         return this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: true, deliverAs: mode === "prompt" ? undefined : mode });
     }
@@ -208,6 +303,7 @@ export class PiAgentFactory {
     providerConfig;
     pinned;
     enabledExtensions;
+    listings;
     constructor(extraTools = [], 
     /** Appended as a virtual context file, so Pi's own prompt stays intact.
      * Read per session, not captured once: it carries settings a user can
@@ -227,7 +323,10 @@ export class PiAgentFactory {
     pinned = () => [], 
     /** Which bundled extensions the Console has switched on. A getter for the
      * same reason again: the toggle takes effect on the next session open. */
-    enabledExtensions = () => []) {
+    enabledExtensions = () => [], 
+    /** What exists on disk. Injected so a test can hand this factory a listing
+     * instead of a session directory and a database. */
+    listings = new IndexedListing()) {
         this.extraTools = extraTools;
         this.instructions = instructions;
         this.skillPaths = skillPaths;
@@ -235,14 +334,20 @@ export class PiAgentFactory {
         this.providerConfig = providerConfig;
         this.pinned = pinned;
         this.enabledExtensions = enabledExtensions;
+        this.listings = listings;
     }
     /** 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. */
+    /** Where each listed session lives. A scan still stats every session file on
+     *  disk, which `resume` would pay 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();
+    /** That same scan, retained for LIST_TTL_MS instead of paid once per asking
+     *  surface — one workspace event has three (sidebar, Activity, task lookups).
+     *  Dropped on create/fork; ids appear for reasons this factory never sees, so
+     *  a miss that decides something re-lists rather than trusts it (`resume`). */
+    listing;
     refreshQueue = Promise.resolve();
     builtinProviderIds;
     /** Structural fit: CredentialStore mirrors pi-ai's interface of the same
@@ -457,8 +562,12 @@ export class PiAgentFactory {
     }
     async open(cwd, sessionManager, opts = { cwd }) {
         let live;
+        // Asked per open, not captured at wiring: a tool whose channel is not
+        // configured yet would otherwise cost context on every turn of every
+        // session and be able to answer nothing.
+        const active = this.extraTools.filter((tool) => tool.available?.() ?? true);
         // Generic translation only — tool contracts are data owned by their feature.
-        const customTools = this.extraTools.map((tool) => defineTool({
+        const customTools = active.map((tool) => defineTool({
             name: tool.name,
             label: tool.label,
             description: tool.description,
@@ -493,19 +602,27 @@ export class PiAgentFactory {
         this.credentials?.assertUnlocked();
         if (opts.name)
             sessionManager.appendSessionInfo(opts.name);
-        const tools = opts.capabilities === "read"
-            ? ["read", "grep", "find", "ls", ...this.extraTools.map((tool) => tool.name)]
-            : undefined;
+        // This runtime serves exactly this one session, so shadowing its
+        // streamSimple is the per-session seam for the Anthropic cache TTL:
+        // interactive sessions keep "long" (1h — turns arrive minutes apart),
+        // tasks downgrade to "short" (5m) via setCacheRetention. The default sits
+        // before the spread so an explicit per-request value still wins —
+        // compaction passes cacheRetention: "none" and must keep it.
+        const runtime = await this.createRuntime();
+        const retention = { value: "long" };
+        const stream = runtime.streamSimple.bind(runtime);
+        runtime.streamSimple = ((model, context, options) => stream(model, context, { cacheRetention: retention.value, ...options }));
         const created = await createAgentSession({
             cwd,
             sessionManager,
             customTools,
-            tools,
-            modelRuntime: await this.createRuntime(),
+            modelRuntime: runtime,
             resourceLoader: await this.resourceLoader(cwd),
         });
         live = created.session;
-        const session = new PiSession(live, this.pinned);
+        const session = new PiSession(live, this.pinned, () => {
+            this.listing = undefined;
+        }, retention);
         if (opts.model)
             await session.setModel(opts.model);
         if (opts.thinking)
@@ -514,6 +631,7 @@ export class PiAgentFactory {
         return session;
     }
     async create(opts) {
+        this.listing = undefined;
         return this.open(opts.cwd, SessionManager.create(opts.cwd), opts);
     }
     async fork(sourceSessionId, opts) {
@@ -533,6 +651,7 @@ export class PiAgentFactory {
         if (!leafId)
             throw new Error("cannot fork a session before its first persisted input");
         manager.createBranchedSession(leafId);
+        this.listing = undefined;
         return this.open(opts.cwd, manager, opts);
     }
     async resume(sessionId) {
@@ -548,27 +667,57 @@ export class PiAgentFactory {
                 this.located.delete(sessionId);
             }
         }
-        const infos = await this.listed();
-        const info = infos.find((s) => s.id === sessionId);
+        const info = await this.locate(sessionId);
         if (!info)
             throw new Error(`unknown session: ${sessionId}`);
         return this.open(info.cwd || process.cwd(), SessionManager.open(info.path));
     }
+    /** The listed record for one id, and the one place "no such session" is
+     *  decided. A retained listing is not evidence that a session is gone: it may
+     *  have been written since — by another Pier, or by the first turn of a
+     *  session this factory opened. The miss is what earns a fresh scan, because
+     *  callers read it as permission to start a replacement session
+     *  (channels/conversations.ts), which costs a conversation its history, or as
+     *  a session that no longer exists (tasks/, web/files.ts). `reused` is how we
+     *  know a scan is owed: same entry back, same disk state. */
+    async locate(sessionId) {
+        const find = (infos) => infos.find((s) => s.id === sessionId);
+        const reused = this.listing;
+        return find(await this.listed()) ??
+            (reused && this.listing === reused ? find(await this.listed(true)) : undefined);
+    }
+    async find(sessionId) {
+        const info = await this.locate(sessionId);
+        return info ? summaryOf(info) : undefined;
+    }
+    /** Once per process, after the first listing: agent/listing.ts reads Pi's
+     *  transcripts with a parser of its own, and only a comparison notices when
+     *  that format moves under it. */
+    audited = false;
     /** 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() });
-        }
+    listed(force = false) {
+        const now = Date.now();
+        if (!force && this.listing && now - this.listing.at < LIST_TTL_MS)
+            return this.listing.infos;
+        const infos = this.listings.scan().then((listed) => {
+            for (const s of listed) {
+                this.located.set(s.id, { path: s.path, cwd: s.cwd || process.cwd() });
+            }
+            if (!this.audited && this.listings.audit) {
+                this.audited = true;
+                void this.listings.audit(() => SessionManager.listAll()).then((wrong) => wrong || log.debug("session index agrees with Pi's own listing"), (err) => log.warn("session index cross-check failed", err));
+            }
+            return listed;
+        });
+        // A failed scan is not an answer to hand the next caller for three seconds.
+        void infos.catch(() => {
+            if (this.listing?.infos === infos)
+                this.listing = undefined;
+        });
+        this.listing = { at: now, infos };
         return infos;
     }
     async list() {
-        const infos = await this.listed();
-        return infos.map((s) => ({
-            id: s.id,
-            cwd: s.cwd,
-            createdAt: s.created.getTime(),
-            title: s.name ?? (s.firstMessage ? s.firstMessage.slice(0, 80) : undefined),
-        }));
+        return (await this.listed()).map(summaryOf);
     }
 }

package/dist/boards/boards.js

@@ -5,7 +5,10 @@
 // Only <board>/site is reachable over HTTP: sources, README and the manifest
 // itself stay off the wire, so a public board leaks nothing about how it was
 // made. `/boards/*` is authenticated; `/p/*` additionally requires the
-// manifest's `public` flag and runs as sandboxed active content.
+// manifest's `public` flag and runs as sandboxed active content — and is the
+// only password-free prefix, stylesheet included, so one firewall rule covers
+// everything a logged-out reader may fetch.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { readdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
 import { extname, join, resolve, sep } from "node:path";
 import { logger } from "../log.js";
@@ -14,6 +17,13 @@ export const defaultBoardsDir = () => pierPath("boards");
 /** Deleted boards keep their bytes under `<slug>.deleted-<ts>`, which this
  *  pattern excludes from every scan — one rename is the whole delete path. */
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** A published board is addressed by `<slug>-<token>`: the slug alone is a
+ *  guessable word, so without the 32 bits after it `/p/` could be walked with
+ *  a dictionary. Minted the first time a manifest is seen public, by whichever
+ *  path published it — the Console's toggle or an agent editing board.json —
+ *  so a board cannot be public and enumerable at the same time. */
+const TOKEN = /^[a-f0-9]{8}$/;
+const mintToken = () => randomBytes(4).toString("hex");
 // A board ships fonts and images, so the list is wider than the attachment
 // route's — but still a whitelist: an unlisted extension is not served at all.
 const TYPES = {
@@ -49,7 +59,10 @@ const warned = new Set();
  *  here and nowhere else: an unvalidated `../../etc` would read outside the
  *  boards dir, and a NUL byte would throw instead of 404. Unknown fields get
  *  defaults, a broken file is skipped whole, and extra keys are the agent's
- *  business — they survive a write. */
+ *  business — they survive a write. The one manifest this writes back is a
+ *  public board that arrived without a token: minting is the same decision as
+ *  reading `public`, and doing it anywhere else leaves the agent's own publish
+ *  path — editing `board.json` — with no URL. */
 async function readManifest(dir, slug) {
     if (!SLUG.test(slug))
         return null;
@@ -69,14 +82,29 @@ async function readManifest(dir, slug) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw))
         return null;
     const m = raw;
-    return {
+    const manifest = {
         ...m,
         title: typeof m.title === "string" && m.title ? m.title : slug,
         description: typeof m.description === "string" ? m.description : "",
         sessions: Array.isArray(m.sessions) ? m.sessions.filter((s) => typeof s === "string") : [],
         public: m.public === true,
+        token: typeof m.token === "string" && TOKEN.test(m.token) ? m.token : "",
     };
+    if (manifest.public && !manifest.token) {
+        manifest.token = mintToken();
+        try {
+            await writeManifest(dir, slug, manifest);
+        }
+        catch (err) {
+            // A token that cannot be stored would differ on the next request, so the
+            // board stays unreachable on /p/ rather than handing out a dead link.
+            logger("boards").warn(`cannot mint a public token for ${slug}`, err);
+            manifest.token = "";
+        }
+    }
+    return manifest;
 }
+const writeManifest = (dir, slug, manifest) => writeFile(join(dir, slug, "board.json"), `${JSON.stringify(manifest, null, 2)}\n`);
 /** Freshness is the site's mtime, not a manifest field — the filesystem
  *  already knows, and an agent rewriting a page cannot forget to say so. */
 async function updatedAt(dir, slug) {
@@ -99,8 +127,8 @@ export async function listBoards(dir) {
         const manifest = await readManifest(dir, slug);
         if (!manifest)
             continue;
-        const { title, description, sessions, public: isPublic } = manifest;
-        boards.push({ slug, title, description, sessions, public: isPublic, updatedAt: await updatedAt(dir, slug) });
+        const { title, description, sessions, public: isPublic, token } = manifest;
+        boards.push({ slug, title, description, sessions, public: isPublic, token, updatedAt: await updatedAt(dir, slug) });
     }
     return boards;
 }
@@ -139,11 +167,28 @@ async function resolveFile(dir, slug, rest) {
         return resolveFile(dir, slug, `${relative}/`);
     return info.isFile() ? file : null;
 }
-async function serveFile(c, dir, slug, rest, publicOnly) {
+/** `/p/` addresses a board as `<slug>-<token>`; a slug may itself contain
+ *  hyphens, so the last one is the cut. */
+function publicKey(key) {
+    const cut = key.lastIndexOf("-");
+    return cut < 1 ? { slug: "", token: "" } : { slug: key.slice(0, cut), token: key.slice(cut + 1) };
+}
+/** Digested first: the token is a secret, and a URL's half may be any length
+ *  or encoding, which a raw comparison would either leak or throw on. */
+const sameToken = (want, got) => {
+    if (!want)
+        return false;
+    const digest = (s) => createHash("sha256").update(s).digest();
+    return timingSafeEqual(digest(want), digest(got));
+};
+async function serveFile(c, dir, key, rest, publicOnly) {
+    const { slug, token } = publicOnly ? publicKey(key) : { slug: key, token: "" };
     const manifest = await readManifest(dir, slug);
-    // 404, never 403: a private board's existence is not public information.
-    if (!manifest || (publicOnly && !manifest.public))
+    // 404, never 403: a private board's existence is not public information, and
+    // a wrong token is the same non-answer as a wrong name.
+    if (!manifest || (publicOnly && (!manifest.public || !sameToken(manifest.token, token)))) {
         return c.notFound();
+    }
     const file = await resolveFile(dir, slug, rest);
     if (!file)
         return c.notFound();
@@ -179,8 +224,12 @@ export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
         if (!manifest)
             return c.json({ error: "no such board" }, 404);
         manifest.public = body.public;
-        await writeFile(join(dir, slug, "board.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-        return c.json({ public: manifest.public });
+        // Publishing an unpublished board is the case readManifest cannot mint for:
+        // it read the manifest while it was still private.
+        if (manifest.public && !manifest.token)
+            manifest.token = mintToken();
+        await writeManifest(dir, slug, manifest);
+        return c.json({ public: manifest.public, token: manifest.token });
     });
     app.delete("/api/boards/:slug", async (c) => {
         const slug = c.req.param("slug");
@@ -190,7 +239,7 @@ export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
         return c.json({ deleted: slug });
     });
     // Declared before the wildcards below: `_assets` is not a slug.
-    app.get("/boards/_assets/pier.css", async (c) => {
+    app.get("/p/_assets/pier.css", async (c) => {
         const file = new URL("./pier.css", import.meta.url);
         return c.body(await readFile(file), 200, {
             "content-type": "text/css; charset=utf-8",
@@ -200,11 +249,11 @@ export function registerBoardRoutes(app, dir = defaultBoardsDir()) {
     // Trailing slash matters: without it a board's relative asset paths resolve
     // against /boards instead of the board.
     for (const prefix of ["/boards", "/p"]) {
-        app.get(`${prefix}/:slug`, (c) => c.redirect(`${prefix}/${c.req.param("slug")}/`));
-        app.get(`${prefix}/:slug/*`, (c) => {
-            const slug = c.req.param("slug");
-            const rest = c.req.path.slice(`${prefix}/${slug}/`.length);
-            return serveFile(c, dir, slug, rest, prefix === "/p");
+        app.get(`${prefix}/:key`, (c) => c.redirect(`${prefix}/${c.req.param("key")}/`));
+        app.get(`${prefix}/:key/*`, (c) => {
+            const key = c.req.param("key");
+            const rest = c.req.path.slice(`${prefix}/${key}/`.length);
+            return serveFile(c, dir, key, rest, prefix === "/p");
         });
     }
 }

package/dist/boards/pier.css

@@ -1,5 +1,5 @@
 /* pier.css — the one stylesheet every Board can link, served at
-   /boards/_assets/pier.css. Classless on purpose: plain semantic HTML must
+   /p/_assets/pier.css. Classless on purpose: plain semantic HTML must
    look finished, so a board needs no build step and no framework. A handful of
    named helpers cover the shapes a report actually asks for. */
 

package/dist/channels/attach.js

@@ -0,0 +1,87 @@
+// Outbound attachments: which links in a turn are files the platform has to
+// carry, and the bytes behind them.
+//
+// The agent links a file it produced by absolute `file://` URL — the
+// convention core/reply.ts hands it, spelled the same way inbound
+// (core/inbound-file.ts). The web chat renders that link as a card because the
+// browser can fetch the bytes back over an authenticated route; an IM client
+// cannot, and a `file:///…` link in Slack is a dead path on someone else's
+// machine. So an adapter uploads the file to the platform instead, and the
+// link's label stays behind as the words around it.
+//
+// The upload itself is per-platform and stays in each `*-api.ts`; what is
+// shared — the grammar, the caps, and the line a failed attachment still owes
+// the conversation — lives here so three adapters do not each have a copy.
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+import { lostMarker } from "../core/inbound-file.js";
+/**
+ * One cap for every platform: Telegram refuses a photo past 10 MB, which is
+ * the smallest of the three, and a turn that lands on one chat and not on
+ * another is worse than a turn that is honest everywhere.
+ */
+export const MAX_ATTACH_BYTES = 10 * 1024 * 1024;
+/** Per turn. Linking a directory's worth of files is a mistake, not a plan. */
+const MAX_ATTACHMENTS = 5;
+/** Extensions the platforms show inline. Everything else goes as a document —
+ *  svg included, deliberately: it is markup, and it renders as a file. */
+const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp"]);
+/** `[label](file:///abs/path)`, inline or on a line of its own. The optional
+ *  `!` is an image embed, which is the same request with a different sigil. */
+const LINK = /!?\[([^\]\n]*)\]\(\s*<?file:\/\/(\/[^)>\s]*)>?\s*\)/g;
+/** A trailing slash or a bare root would otherwise leave an unnamed file. */
+const nameOf = (path) => basename(path) || "file";
+/**
+ * Split a turn's markdown into the text an IM chat should show and the files
+ * it linked. Each link collapses to its label — or to the file's name when the
+ * agent wrote none — so the sentence it sat in still reads, and the turn never
+ * becomes empty just because its only content was an attachment.
+ */
+export function splitAttachments(markdown) {
+    const paths = [];
+    const text = markdown.replace(LINK, (_m, label, raw) => {
+        let path = raw;
+        try {
+            path = decodeURIComponent(raw);
+        }
+        catch {
+            /* not percent-encoded — take the path as written */
+        }
+        if (!paths.includes(path))
+            paths.push(path);
+        return label || nameOf(path);
+    });
+    return { text, paths };
+}
+/**
+ * Upload every file a turn linked, and return the line the conversation still
+ * owes: an attachment that never arrived must not look like an attachment that
+ * was never mentioned (AGENTS.md 5b), so each failure is named in the chat as
+ * well as in the log. Empty string when everything landed.
+ */
+export async function sendAttachments(paths, upload, log) {
+    const lost = [];
+    const fail = (path, reason) => {
+        log(`attachment ${path} not sent: ${reason}`);
+        lost.push(lostMarker(nameOf(path), reason));
+    };
+    for (const path of paths.slice(0, MAX_ATTACHMENTS)) {
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                throw new Error("not a file");
+            if (info.size > MAX_ATTACH_BYTES)
+                throw new Error(`too large (>${MAX_ATTACH_BYTES} bytes)`);
+            const name = nameOf(path);
+            const ext = extname(name).slice(1).toLowerCase();
+            await upload({ name, bytes: await readFile(path), image: IMAGE_EXT.has(ext) });
+        }
+        catch (err) {
+            fail(path, err instanceof Error ? err.message : String(err));
+        }
+    }
+    for (const path of paths.slice(MAX_ATTACHMENTS)) {
+        fail(path, `more than ${MAX_ATTACHMENTS} files in one turn`);
+    }
+    return lost.join("\n");
+}

package/dist/channels/control.js

@@ -29,11 +29,11 @@ export function createControl({ router, factory, conversations, store }) {
             if (!session)
                 return null;
             // AgentSession has no cwd; the factory's listing is where it lives.
-            const listed = await factory.list();
+            const summary = await factory.find(session.id);
             const usage = session.contextUsage;
             return {
                 sessionId: session.id,
-                cwd: listed.find((s) => s.id === session.id)?.cwd ?? "",
+                cwd: summary?.cwd ?? "",
                 state: session.state,
                 model: session.model,
                 thinking: session.thinkingLevel,

package/dist/channels/lark-api.js

@@ -136,6 +136,44 @@ export class LarkApi {
         });
         return { messageId: ok("message.reply", res).data?.message_id ?? "" };
     }
+    /**
+     * Two calls: the bytes go to the platform first and come back as a key,
+     * then the key is posted as a message. Images take the image endpoint so
+     * they render inline; everything else is a `stream` file, which is Lark's
+     * name for "a file whose type I am not claiming to know".
+     *
+     * The SDK unwraps an upload response to its `data`, so a business failure
+     * arrives as a missing key rather than as a code — hence the explicit throw
+     * instead of `ok()`.
+     */
+    async uploadFile(rootId, file) {
+        const bytes = Buffer.from(file.bytes);
+        let content;
+        if (file.image) {
+            const res = await this.client.im.v1.image.create({
+                data: { image_type: "message", image: bytes },
+            });
+            if (!res?.image_key)
+                throw new Error(`lark image.create: no image_key for ${file.name}`);
+            content = { image_key: res.image_key };
+        }
+        else {
+            const res = await this.client.im.v1.file.create({
+                data: { file_type: "stream", file_name: file.name, file: bytes },
+            });
+            if (!res?.file_key)
+                throw new Error(`lark file.create: no file_key for ${file.name}`);
+            content = { file_key: res.file_key };
+        }
+        ok("message.reply", await this.client.im.v1.message.reply({
+            path: { message_id: rootId },
+            data: {
+                msg_type: file.image ? "image" : "file",
+                content: JSON.stringify(content),
+                reply_in_thread: true,
+            },
+        }));
+    }
     async patchCard(messageId, card) {
         ok("message.patch", await this.client.im.v1.message.patch({
             path: { message_id: messageId },