@timqi/pier 0.0.25 → 0.0.27

package/dist/agent/pi.js

@@ -37,27 +37,27 @@ const PROVIDER_CHECK_MAX_TOKENS = 8192;
 /** Neither half of a probe is worth more than a screen. */
 const clip = (text) => text.length > 4000 ? `${text.slice(0, 4000)}\n[… ${text.length - 4000} more characters]` : text;
 /** Pier's baseline replaces Pi's generic default; a user's SYSTEM.md follows it. */
-const PIER_SYSTEM_PROMPT = `You are a general-purpose agent with a live workspace: you can read and change files and run shell commands. Act with expert care — do the work, verify results, and state what you could not check.
+const PIER_SYSTEM_PROMPT = `You are a general-purpose agent with a live workspace: you can read and change files and run shell commands. Act with expert care — do the work and verify the result.
 
 # Communication
-These rules govern conversational replies. When the reply *is* the deliverable — a report that was asked for, a review, a task run whose result another agent reads — the work sets the length: complete beats brief, and nothing below caps it.
-- Answer with the conclusion only. Reasons, process, trade-offs, alternatives: only when asked.
-- Cap per reply: 60 words (90 Chinese chars), max 3 bullets; 180 words (270 Chinese chars) when explicitly asked why or how. Code blocks, diffs and commands don't count.
-- Reply in the language of the request; code, paths, identifiers and quoted output stay verbatim.
-- Never: preamble, restating the question, closing summaries, "I'm going to..." narration, listing changes already visible in the diff.
-- After edits, say only: file(s) touched + one line on the result. Don't explain self-evident code.
-- Show file paths as \`path:line\`, or the path alone when no single line is the point — never invent a number.
-- If the honest answer needs more than the cap, give the conclusion plus one short "want the details?" — don't dump it.
-- Blocked on a decision only the person you work for can make? Ask one short question. Otherwise pick the sensible default and note it.
+These rules govern conversational replies. A human reads them on a phone-sized screen, so the cap is about their attention, not about tokens. When the reply is the deliverable — the request names an artifact (report, review, digest, plan) or another agent reads the result (task runs) — the length rules don't apply; the style rules still do.
+- Answer with the conclusion. Add the one fact that changes what the user does next — a failure and its cause, an assumption you made, a risk. Trade-offs, process, alternatives: only when asked.
+- Cap per reply: 60 words (90 Chinese chars), max 3 bullets; 120 words (180 Chinese chars) when the question asks for reasoning, comparison or options. A command the user is meant to run counts as one line. Don't paste code or diffs to explain — name the file.
+- Past the cap by a lot? Conclusion plus one short "want the details?" — don't dump it. Past it by a sentence? Finish the sentence.
+- Reply in the language of the request; paths, identifiers and quoted output stay verbatim.
+- Never: preamble, restating the question, closing summaries, "I'm going to..." narration, narrating each edit.
+- After edits, say only: file(s) touched + one line on the result.
+- Don't quote code to explain it — no snippets, no walkthroughs. Code the user asked for (a command, a one-liner, a value) is the answer: one block, nothing around it.
+- \`path:line\` when you're pointing at one line; the bare path otherwise.
+- Blocked on a decision only the requester can make? Ask them, one short question. Otherwise pick the sensible default and note it.
 
-# Working style (any machine)
-These hold wherever Pier runs; a user's SYSTEM.md adds the local ones (which tools exist, which hosts, which paths).
-- Orient first — list and search before you act. Never guess a path.
+# Working style — holds on any machine; a user's SYSTEM.md adds the local facts (tools, hosts, paths)
+- Before touching files: list and search first. Never guess a path or a line number.
 - Read before you edit. Match the surrounding code's style, naming, and comment density.
 - Do exactly what was asked. No unrequested refactors, no extra files, no README updates.
-- Destructive or irreversible actions (rm, force push, migrations, deploys): ask first.
-- Say plainly when something failed, was skipped, or is unverified. Never claim a test passed without running it.
-- Every bash call already runs in the working directory this prompt names — don't prefix \`cd <cwd> &&\`, \`cd\` only to go somewhere else. Each call is a fresh shell: \`cd\`, \`export\`, \`source\` never carry over, so chain what must share state into one command.`;
+- Each bash call is a fresh shell in the working directory; chain what must share state.
+- Destructive or irreversible actions on things you didn't create — deleting user files, force push, migrations, deploys, service restarts: ask first; unattended, don't do them and report what you would have done.
+- Say plainly when something failed, was skipped, or is unverified. Never claim a test passed without running it.`;
 export const pierSystemPrompt = (userPrompt) => userPrompt ? `${PIER_SYSTEM_PROMPT}\n\n${userPrompt}` : PIER_SYSTEM_PROMPT;
 /** Patching the call is cheaper than replacing the tool: the built-in keeps its
  * shell settings, and the agent spends no tokens deciding a timeout. */

package/dist/channels/attach.js

@@ -14,7 +14,7 @@
 // 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";
+import { lostMarker, replaceOutsideCode } 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
@@ -35,11 +35,14 @@ 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.
+ * becomes empty just because its only content was an attachment. A link inside
+ * code is an example of the convention, not a use of it: it is left alone.
  */
 export function splitAttachments(markdown) {
     const paths = [];
-    const text = markdown.replace(LINK, (_m, label, raw) => {
+    const text = replaceOutsideCode(markdown, LINK, (match) => {
+        const label = match[1];
+        const raw = match[2];
         let path = raw;
         try {
             path = decodeURIComponent(raw);

package/dist/channels/lark-outbound.js

@@ -100,11 +100,16 @@ export class LarkOutbound {
      * 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.
+     *
+     * Answers with the id of the last card it posted — where the caller puts the
+     * 👀 for that turn, at the foot of the topic the reply will land in.
      */
     async note(root, note) {
         const body = note.text.split("\n").map((line) => `> ${line}`).join("\n");
+        let messageId;
         for (const part of chunk(`*${originLabel(note.origin)}*\n${body}`, LARK_MAX)) {
-            await this.api.replyCard(root, card([markdown(part)]));
+            messageId = (await this.api.replyCard(root, card([markdown(part)]))).messageId;
         }
+        return messageId;
     }
 }

package/dist/channels/lark.js

@@ -22,6 +22,7 @@
 // config.ts, platform-blind and shared with Telegram and Slack.
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
+import { awaitsTurn } from "../core/reply.js";
 import { bindHint, bindResult, picked, STALE_OPTION, STOPPED } from "./lines.js";
 import { logger } from "../log.js";
 import { Chains } from "./chains.js";
@@ -484,14 +485,25 @@ export class LarkChannel {
         // reply failed to send looks like work until the stale sweep.
         await this.receipts.settleAfter(conversation, () => this.out.reply(root, reply));
     }
-    /** A system note, posted without touching the receipts: the turn it
-     *  triggers has not ended yet. */
+    /**
+     * A system note, and the 👀 goes on the note itself: the turn it triggers has
+     * no message of the user's to carry them — nobody typed one — so without this
+     * the topic shows nothing at all while the agent works. The turn-end `send`
+     * clears it like any other receipt; an error note is not marked, because no
+     * turn follows it (`awaitsTurn`) and the eyes would sit there until the stale
+     * sweep.
+     */
     async notify(conversation, note) {
-        const { root } = parseConversation(conversation);
+        const { chatId, root } = parseConversation(conversation);
         if (!root) {
             this.log(`refusing to post a system note to ${conversation}: no thread root in the conversation id`);
             return;
         }
-        await this.out.note(root, note);
+        const messageId = await this.out.note(root, note);
+        // The last card of a long note, so the eyes sit at the foot of the topic,
+        // where the reply will land. A reaction that fails is swallowed and logged
+        // by receipts.ts, so the note itself is never lost to one.
+        if (messageId && awaitsTurn(note.origin))
+            this.receipts.mark(conversation, chatId, messageId);
     }
 }

package/dist/channels/slack-api.js

@@ -279,6 +279,14 @@ export class SlackApi {
      * Slack file URLs are private: they need the bot token as a bearer header and
      * answer HTML (a login page) rather than an error when it is missing.
      */
+    /** A read method, so form-encoded (see read()); `id` is the `F…` id. */
+    async filesInfo(id) {
+        const body = await this.read("files.info", { file: id });
+        // `ok` without a file would leave the caller downloading `undefined`.
+        if (!body.file)
+            throw new Error("slack files.info: no file in the response");
+        return body.file;
+    }
     async downloadFile(file, maxBytes) {
         const url = file.url_private_download ?? file.url_private;
         if (!url)

package/dist/channels/slack-outbound.js

@@ -70,13 +70,19 @@ export class SlackOutbound {
      * 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.
+     *
+     * Answers with the `ts` of the last message it posted — where the caller
+     * puts the 👀 for that turn, at the foot of the thread the reply will land
+     * in. Undefined when there was nothing to post.
      */
     async note(channel, threadTs, note) {
         // Markdown's own blockquote, so the note reads as quoted on either path.
         const body = note.text.split("\n").map((line) => `> ${line}`).join("\n");
+        let ts;
         for (const part of chunk(`_${originLabel(note.origin)}_\n${body}`, this.budget())) {
-            await this.post(channel, threadTs, part, []);
+            ts = await this.post(channel, threadTs, part, []);
         }
+        return ts;
     }
     /** Which budget `chunk()` should respect, given the path we are on. */
     budget() {
@@ -98,10 +104,10 @@ export class SlackOutbound {
         if (this.markdownBlocks) {
             const blocks = [...(body ? [markdown(body)] : []), ...trailing];
             if (!blocks.length)
-                return;
+                return undefined;
             try {
-                await this.api.postMessage({ channel, thread_ts: threadTs, text: notice, blocks });
-                return;
+                const sent = await this.api.postMessage({ channel, thread_ts: threadTs, text: notice, blocks });
+                return sent.ts;
             }
             catch (err) {
                 if (!isBlockRejection(err))
@@ -112,16 +118,19 @@ export class SlackOutbound {
         }
         // Legacy path: translate to mrkdwn and split into section blocks. The body
         // was chunked against the larger budget, so it may need splitting again.
+        let ts;
         for (const part of body ? chunk(toMrkdwn(body), MRKDWN_MAX) : [""]) {
             const blocks = [...sections(part), ...trailing];
             if (!blocks.length)
                 continue;
-            await this.api.postMessage({
+            const sent = await this.api.postMessage({
                 channel,
                 thread_ts: threadTs,
                 text: part || notice || "…",
                 blocks,
             });
+            ts = sent.ts;
         }
+        return ts;
     }
 }

package/dist/channels/slack-tool.js

@@ -12,11 +12,16 @@
 // one or two calls. If that assumption changes (a distributed non-Marketplace
 // app is capped at 1 req/min), this is the decision to revisit.
 import { Type } from "typebox";
+import { saveInboundAll } from "../core/inbox.js";
+import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
 import { MARKDOWN_MAX } from "./slack-render.js";
 /** Hard cap on one read, so a wide range cannot blow up the model's context. */
 const MAX_MESSAGES = 400;
 /** Pages to walk before giving up on a very wide window. */
 const MAX_PAGES = 10;
+/** Where fetched bytes land: the adapter's own channel id, so a file the agent
+ *  asked for sits beside the ones people uploaded to Pier. */
+const INBOX_CHANNEL = "slack";
 /**
  * A Slack `ts` is `<epoch seconds>.<microseconds>` and sorts correctly as a
  * number but *not* as a string once the integer part changes width. Ordering
@@ -65,7 +70,7 @@ export function slackToolSpec(execute, available) {
         // One screen of contract; the paragraph this once was lives in the
         // pier-slack skill, which the description sends the model to before it
         // posts — the part that goes wrong without instructions.
-        description: "Read and write Slack through Pier, which holds the bot token. Operations: context (which Slack conversation this session is in), read_channel (transcript for a time range), read_thread (one thread; only what is new since a message via after), read_message (the one at ts), post, edit/delete (Pier's own messages only), channels (what Pier can reach). Omit channel and thread_ts to act on the conversation you are in. since/until/after accept ISO 8601, epoch seconds or a ts. Every read fetches live; nothing is kept between calls. @mentions, #channels and links need Slack's own syntax — read the pier-slack skill before posting.",
+        description: "Read and write Slack through Pier, which holds the bot token. Operations: context (which Slack conversation this session is in), read_channel (transcript for a time range), read_thread (one thread; only what is new since a message via after), read_message (the one at ts), fetch_file (save a file a transcript names, by its F… id), post, edit/delete (Pier's own messages only), channels (what Pier can reach). Omit channel and thread_ts to act on the conversation you are in. since/until/after accept ISO 8601, epoch seconds or a ts. Every read fetches live; nothing is kept between calls. @mentions, #channels and links need Slack's own syntax — read the pier-slack skill before posting.",
         parameters: Type.Object({
             // A JSON-Schema enum emits far fewer tokens than typebox's anyOf-of-consts.
             operation: Type.Unsafe({
@@ -75,6 +80,7 @@ export function slackToolSpec(execute, available) {
                     "read_channel",
                     "read_thread",
                     "read_message",
+                    "fetch_file",
                     "post",
                     "edit",
                     "delete",
@@ -92,6 +98,8 @@ export function slackToolSpec(execute, available) {
             after: Type.Optional(Type.String()),
             /** The one message `read_message`, `edit` or `delete` is about. */
             ts: Type.Optional(Type.String()),
+            /** `fetch_file`: the `F…` id a transcript line carries. */
+            file: Type.Optional(Type.String()),
             limit: Type.Optional(Type.Number()),
             thread_ts: Type.Optional(Type.String()),
             text: Type.Optional(Type.String()),
@@ -161,6 +169,12 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
             note: "Omit channel and thread_ts to read or post here. Speaker ids for mentions come from read_thread.",
         };
     }
+    // Before the channel default below: a file id is unique workspace-wide, so
+    // asking a session that never touched Slack for a channel it has no way to
+    // name would refuse a call that needs none.
+    if (input.operation === "fetch_file") {
+        return fetchFile(deps, client, required(input.file, "file"));
+    }
     // "Here" is the default target: an agent reached through a Slack thread
     // should not have to be told which thread it is standing in.
     const channel = input.channel === undefined || input.channel === ""
@@ -329,7 +343,12 @@ async function readChannel(deps, client, channel, since, until, after, limit) {
         messages: await lines(deps, client, window),
     };
 }
-async function readThread(deps, client, channel, threadTs, after, limit) {
+/**
+ * Exported for one caller: the adapter inlines a small shared thread, and a
+ * second `conversations.replies` walker — its paging, seam dedup, ordering and
+ * error translation — is exactly the copy this file exists to prevent.
+ */
+export async function readThread(deps, client, channel, threadTs, after, limit) {
     const fetched = await fetchPages(deps, (cursor) => client.replies(channel, threadTs, { oldest: after, cursor }), `thread ${threadTs} in ${channel}`);
     const all = newerThan(transcript(fetched.messages), after);
     // Oldest first, as in a channel read: a thread cut at its newest end still
@@ -363,6 +382,45 @@ async function readMessage(deps, client, channel, ts, threadTs) {
         message: line,
     };
 }
+/**
+ * A file a transcript named, on disk. Fetching is explicit rather than
+ * automatic: one channel read can name a hundred uploads, and the agent — not
+ * Pier — knows which of them the question is about. Even then the reply is only
+ * the marker line, so the bytes enter its context if it opens the file.
+ *
+ * `files.info` every call. A `SlackFile` carries a signed url that expires and
+ * a name its owner can change, so a kept copy is the same wrong-later copy this
+ * file's header refuses for messages.
+ */
+async function fetchFile(deps, client, id) {
+    let file;
+    try {
+        file = await client.filesInfo(id);
+    }
+    catch (err) {
+        // The manifest's scopes are only applied when an app is *created*, so an
+        // app installed before this operation existed refuses for a reason no
+        // agent can guess. Name the fix, as uploadFile does for files:write.
+        if (/missing_scope/.test(String(err))) {
+            throw new Error("Pier's Slack app cannot read files — add the files:read scope to the Slack app " +
+                "under OAuth & Permissions and reinstall it");
+        }
+        throw new Error(explain(err));
+    }
+    // The shared save loop owns the size gate, the marker and the lost-marker
+    // wording (core/inbox.ts), so a file over the cap or a refused download
+    // answers in the words every other inbound failure uses — never a stack, and
+    // never an empty reply.
+    const [marker] = await saveInboundAll(INBOX_CHANNEL, [{
+            label: file.name ?? id,
+            name: file.name,
+            mimeType: file.mimetype ?? "application/octet-stream",
+            size: file.size,
+            // The response's content-type wins: Slack's metadata is a guess.
+            fetch: () => client.downloadFile(file, MAX_INBOUND_BYTES),
+        }], deps.log);
+    return marker;
+}
 /**
  * Walk the cursor until it ends or the caps bite.
  *
@@ -411,6 +469,7 @@ function explain(err) {
         cant_update_message: "Slack only lets Pier edit what its own bot posted; anyone else's message can only be replied to",
         edit_window_closed: "Slack's edit window for that message has closed; post a correction instead of rewriting it",
         message_not_found: "no message with that ts in this channel — a ts only means anything in the conversation it came from",
+        file_not_found: "no file with that id, or Pier's bot cannot see it — the F… id comes from a transcript line",
     }[code] ?? String(err);
 }
 /** Strictly newer, so `after: <last ts I saw>` never repeats that message. */
@@ -437,8 +496,28 @@ function transcript(messages) {
  * The name makes it readable, the id is the only thing `<@…>` can be built
  * from, and Slack's own `ts` string is passed through untouched — it is what
  * a reply, a reaction or `after` has to match exactly.
+ *
+ * The two suffixes are what a message *has* rather than what it said, so they
+ * are declared here and appended only when there is one: a message with
+ * neither reads exactly as it always did. Kept terse — the adapter puts this
+ * string in a prompt (`slack.ts`, an inlined shared thread), so every word is
+ * paid for per read.
+ */
+const LINE_FORMAT = "<ts> | <time, UTC> | <name>[<id>] | <text>, then — when there are any —"
+    + " [thread: <n> replies] and one [file: <name> <F… id> <size>] per upload";
+/** Enough to judge a fetch against the 32 MB cap without arithmetic; left out
+ *  entirely when Slack sent no size, because a guessed one would be worse. */
+const sizeLabel = (bytes) => bytes < 1024
+    ? `${bytes}B`
+    : bytes < 1024 * 1024
+        ? `${Math.round(bytes / 1024)}KB`
+        : `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+/**
+ * A message's uploads, named with the one handle that can fetch them. Without
+ * this the transcript dropped `files` entirely: a PDF somebody posted read as
+ * an empty message, and nothing said there was anything to open.
  */
-const LINE_FORMAT = "<ts> | <time, UTC> | <name>[<id>] | <text>";
+const uploads = (files) => (files ?? []).map((file) => ` [file: ${file.name ?? file.mimetype ?? "file"} ${file.id}${file.size === undefined ? "" : ` ${sizeLabel(file.size)}`}]`).join("");
 const speaker = (msg) => msg.user ?? msg.bot_id ?? null;
 async function lines(deps, client, messages) {
     // Names come from the directory the adapter also uses, so re-reading a
@@ -455,6 +534,6 @@ async function lines(deps, client, messages) {
         const replies = msg.reply_count && (msg.thread_ts ?? msg.ts) === msg.ts
             ? ` [thread: ${msg.reply_count} replies]`
             : "";
-        return `${msg.ts} | ${tsToMinute(msg.ts)} | ${who} | ${msg.text ?? ""}${replies}`;
+        return `${msg.ts} | ${tsToMinute(msg.ts)} | ${who} | ${msg.text ?? ""}${replies}${uploads(msg.files)}`;
     });
 }

package/dist/channels/slack.js

@@ -24,6 +24,7 @@
 // config.ts, platform-blind and shared with Telegram.
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
+import { awaitsTurn } from "../core/reply.js";
 import { bindHint, bindResult, picked, STALE_OPTION, STOPPED } from "./lines.js";
 import { logger } from "../log.js";
 import { Chains } from "./chains.js";
@@ -34,6 +35,7 @@ import { ReceiptLedger, Receipts } from "./receipts.js";
 import { SlackDirectory } from "./slack-directory.js";
 import { SlackApi, } from "./slack-api.js";
 import { SlackOutbound } from "./slack-outbound.js";
+import { readThread, slackToolAvailable } from "./slack-tool.js";
 import { SlackPanel } from "./slack-panel.js";
 import { context, escapeMrkdwn, offeredLabel } from "./slack-render.js";
 /** Slack wants a short name here; the raw codepoint is an `invalid_name`. */
@@ -82,8 +84,29 @@ const threadOf = (event) => event.thread_ts ?? event.ts ?? "";
 /**
  * Subtypes worth reading. Everything else (joins, edits, deletions, topic
  * changes) is noise, and `bot_message` is either our own echo or another app's.
+ * `message_share` is in because a forward is a person handing the agent
+ * something to look at; dropping it delivered the sharer's comment alone, or
+ * nothing at all when they forwarded without one.
  */
-const READABLE_SUBTYPES = new Set(["file_share", "thread_broadcast"]);
+const READABLE_SUBTYPES = new Set(["file_share", "thread_broadcast", "message_share"]);
+/**
+ * The forwarded messages an event carries. `is_share` is the flag proper, and
+ * a `message_share` may arrive without it. An `is_msg_unfurl` on its own is
+ * Slack previewing a permalink somebody pasted — the sender did not choose to
+ * forward that message, so quoting it as if they had puts words in their mouth.
+ * A real share carries *both* flags, which is why the unfurl flag can only
+ * rule one out.
+ */
+const sharesOf = (event) => (event.attachments ?? []).filter((a) => a.is_share === true || (event.subtype === "message_share" && !a.is_msg_unfurl));
+/** A share's own uploads, which Slack hangs off the attachment. */
+const sharedFiles = (share) => share.files ?? share.original_message?.files ?? [];
+/**
+ * How many replies a shared thread may have before Pier stops reading it
+ * eagerly. A token budget, not a Slack limit: a handful of lines is worth
+ * spending on something a human deliberately forwarded, a few hundred is not,
+ * and past this the agent gets the coordinates and decides for itself.
+ */
+const INLINE_REPLY_MAX = 30;
 /**
  * What the user asked for, from text a mention has already been stripped from.
  * `/stop` is accepted for muscle memory even though Slack rarely lets one
@@ -238,9 +261,20 @@ export class SlackChannel {
         if (!ts)
             return this.log("message event without a ts, dropped");
         const raw = (event.text ?? "").trim();
-        const files = event.files ?? [];
-        if (!raw && !files.length)
+        const shares = sharesOf(event);
+        // A share's files are in the attachment, so they join the event's own and
+        // ride the one save loop below — size gate and lost markers included.
+        const files = [...(event.files ?? []), ...shares.flatMap(sharedFiles)];
+        // A forward with no comment of its own is still content, and the whole
+        // point of the message.
+        if (!raw && !files.length && !shares.length) {
+            // A subtype we opted into that carried nothing readable is a shape this
+            // adapter did not recognize, not an empty message — most likely a share
+            // whose attachment `sharesOf` ruled out. Saying so beats vanishing (5b).
+            if (event.subtype)
+                this.log(`${event.subtype} with nothing readable in it, dropped`);
             return;
+        }
         const { kind } = await this.directory.channel(this.api, channel, event);
         const isDm = kind === "dm";
         if (!this.discovered.has(channel)) {
@@ -270,12 +304,13 @@ export class SlackChannel {
             return this.abortTurn(here, channel, threadTs);
         // `@bot` on its own (the text is empty once the mention is stripped) and
         // `settings` are the same request: show me this conversation's settings.
-        if (this.panel && (command?.name === "settings" || (!text && !files.length))) {
+        if (this.panel && (command?.name === "settings" || (!text && !files.length && !shares.length))) {
             return this.panel.open(here, channel, threadTs);
         }
         // Downloading only past the gate: an unauthorized sender must not be able
         // to make the bot pull bytes on their behalf.
         const markers = await this.saveAttachments(files);
+        const shared = await Promise.all(shares.map((share) => this.sharedBlock(share)));
         // A Slack thread is many people talking into one session, so the agent is
         // told who spoke — and the id, which is what a mention needs. Resolved
         // *before* the mark: every await between mark() and dispatch is a window
@@ -289,7 +324,8 @@ export class SlackChannel {
             key: here,
             senderId: event.user,
             sender,
-            text: [text, ...markers].filter(Boolean).join("\n"),
+            // Markers stay last: the inbound-file convention is a *trailing* block.
+            text: [text, ...shared, ...markers].filter(Boolean).join("\n"),
             mode: "steer",
         });
     }
@@ -434,6 +470,107 @@ export class SlackChannel {
         }
         return name ?? channel;
     }
+    /**
+     * What a forwarded message contributes to the prompt: who wrote it, where it
+     * lives, its text, and — when it is a thread parent — either the thread
+     * itself or the coordinates for `read_thread`. Nothing is invented: a name, a
+     * channel or a ts the event does not carry is simply left out of the line.
+     *
+     * The eager read runs whether or not `agentTool` is on, because this is
+     * inbound normalization of a message a human deliberately handed the agent —
+     * the same act as an upload, which nothing gates either. `agentTool` governs
+     * the agent reaching *out*, and the only thing it changes here is the hint,
+     * which would otherwise name a tool this session does not have.
+     */
+    async sharedBlock(share) {
+        const source = share.original_message;
+        const ts = share.ts ?? source?.ts;
+        const threadTs = share.thread_ts ?? source?.thread_ts ?? ts;
+        const replies = share.reply_count ?? source?.reply_count;
+        // A share of a *reply* is one message; only a parent has a thread — and
+        // the three fields a thread needs travel together so neither branch below
+        // has to assert they are there.
+        const parent = share.channel_id && ts && threadTs === ts && replies
+            ? { channel: share.channel_id, ts, replies }
+            : null;
+        // `name<id>` is the sender prefix's grammar (core/identity.ts), and the id
+        // is the only thing a mention can be built from. Resolved through the same
+        // cache the senders use, so a shared author already seen costs nothing.
+        const author = share.author_id
+            ? `${await this.directory.user(this.api, share.author_id)}<${share.author_id}>`
+            : share.author_name || share.author_subname;
+        const where = share.channel_name
+            ? `#${share.channel_name}${share.channel_id ? `<${share.channel_id}>` : ""}`
+            : share.channel_id;
+        const head = [
+            "shared message",
+            author && `from ${author}`,
+            where && `in ${where}`,
+            ts && `at ${ts}`,
+        ].filter(Boolean).join(" ");
+        // `fallback` is the plain-text rendering Slack sends when a share's `text`
+        // is empty (a file-only forward, or one whose body is all blocks).
+        // Empty rather than absent is the normal case for a file-only forward, so
+        // these fall through on "" as well.
+        const body = (share.text || share.fallback || source?.text || "").trim();
+        const thread = parent && parent.replies <= INLINE_REPLY_MAX
+            ? await this.sharedThread(parent.channel, parent.ts, parent.replies)
+            : { transcript: false, lines: [] };
+        // Past the budget, or read and failed: the coordinates are what is left,
+        // and they carry the tool's own parameter names so nothing has to be
+        // guessed from a permalink. Naming the tool is a lie when the Console has
+        // switched agent access off, so only that half goes — the coordinates are
+        // true either way.
+        const how = slackToolAvailable(this.deps.store) ? "read with the slack tool: " : "";
+        const hint = parent && !thread.transcript
+            ? `[thread: ${parent.replies} replies — ${how}channel ${parent.channel}, thread_ts ${parent.ts}]`
+            : "";
+        // The transcript opens with the shared message itself, so repeating its
+        // text above it would only cost tokens.
+        return [`[${head}]`, thread.transcript ? "" : body, ...thread.lines, hint]
+            .filter(Boolean).join("\n");
+    }
+    /**
+     * A small shared thread, read eagerly and inlined as the slack tool's own
+     * lines — through the tool's own read, so the paging, the seam dedup, the
+     * ordering and the error-to-action translation exist once (slack-tool.ts).
+     *
+     * A read that fails or comes back cut says so in the prompt (5b): a thread
+     * the agent silently never saw is indistinguishable from one with nothing in
+     * it, and the turn is dispatched either way.
+     */
+    async sharedThread(channel, ts, replies) {
+        const deps = { directory: this.directory, log: this.log };
+        try {
+            // The parent plus its replies, and one over the budget so a reply_count
+            // that undercounts still reports itself as cut rather than as complete.
+            const read = await readThread(deps, this.api, channel, ts, undefined, INLINE_REPLY_MAX + 2);
+            if (!read.messages.length)
+                return { transcript: false, lines: [] };
+            return {
+                transcript: true,
+                lines: [
+                    `[thread: ${replies} replies, oldest first — ${read.format}]`,
+                    ...read.messages,
+                    // Cut either because a page failed or because the thread turned out
+                    // longer than `reply_count` promised; a transcript that answers as
+                    // if it were complete is the one nobody double-checks.
+                    ...(read.incomplete || read.truncated
+                        ? [`[thread partly read: ${read.incomplete ?? `cut at ${read.count} lines`}]`]
+                        : []),
+                ],
+            };
+        }
+        catch (err) {
+            this.log(`shared thread ${channel}/${ts} not read: ${String(err)}`);
+            // Said in the prompt in the same shape as an attachment that never made
+            // it, because it is the same fact to the reader.
+            return {
+                transcript: false,
+                lines: [`[thread not read: ${err instanceof Error ? err.message : String(err)}]`],
+            };
+        }
+    }
     /** The upload list as the shared save loop wants it (the loop itself, size
      *  gate and lost markers included, is core/inbox.ts). */
     saveAttachments(files) {
@@ -467,14 +604,25 @@ export class SlackChannel {
         // reply failed to send looks like work until the stale sweep.
         await this.receipts.settleAfter(conversation, () => this.out.reply(channel, threadTs, reply));
     }
-    /** A system note, posted without touching the receipts: the turn it triggers
-     * has not ended yet. */
+    /**
+     * A system note, and the 👀 goes on the note itself: the turn it triggers has
+     * no message of the user's to carry them — nobody typed one — so without this
+     * the thread shows nothing at all while the agent works. The turn-end `send`
+     * clears it like any other receipt; an error note is not marked, because no
+     * turn follows it (`awaitsTurn`) and the eyes would sit there until the stale
+     * sweep.
+     */
     async notify(conversation, note) {
         const { channel, threadTs } = parseConversation(conversation);
         if (!threadTs) {
             this.log(`refusing to post a system note to ${conversation}: no thread in the conversation id`);
             return;
         }
-        await this.out.note(channel, threadTs, note);
+        const ts = await this.out.note(channel, threadTs, note);
+        // The last chunk of a long note, so the eyes sit at the foot of the thread,
+        // where the reply will land. A reaction that fails is swallowed and logged
+        // by receipts.ts, so the note itself is never lost to one.
+        if (ts && awaitsTurn(note.origin))
+            this.receipts.mark(conversation, channel, ts);
     }
 }

package/dist/channels/telegram.js

@@ -11,7 +11,7 @@
 //
 // Everything policy-shaped (mention/bind gates, per-chat overrides) is in
 // config.ts, platform-blind and shared with the adapters still to come.
-import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
+import { awaitsTurn, formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
 import { saveInboundAll } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
 import { sendAttachments, splitAttachments } from "./attach.js";
@@ -463,20 +463,31 @@ export class TelegramChannel {
     }
     /**
      * A system note: quoted, labelled with where it came from, and deliberately
-     * plain — no buttons, no turn footer, and the 👀 receipts stay up, because
-     * the turn this input triggers has not ended yet.
+     * plain — no buttons and no turn footer, because the turn this input triggers
+     * has not ended yet.
+     *
+     * That turn has no message of the user's to carry the 👀 — nobody typed one —
+     * so the note wears them, on its last chunk, until the turn-end `send`
+     * clears it. An error note is not marked: no turn follows it (`awaitsTurn`),
+     * and the eyes would sit there until the stale sweep.
      */
     async notify(conversation, note) {
         const { chatId, topicId } = parseConversation(conversation);
         const label = originLabel(note.origin);
+        let posted;
         for (const part of chunk(`<i>${label}</i>\n<blockquote>${toTelegramHtml(note.text)}</blockquote>`)) {
-            await this.api.sendMessage({
+            posted = await this.api.sendMessage({
                 chat_id: chatId,
                 message_thread_id: topicId,
                 text: part,
                 parse_mode: "HTML",
             });
         }
+        // A failed reaction is swallowed and logged by receipts.ts, so the note
+        // itself is never lost to one.
+        if (posted && awaitsTurn(note.origin)) {
+            this.receipts.mark(conversation, chatId, String(posted.message_id));
+        }
     }
 }
 /** Display name from an update, which always carries enough to build one. */