@timqi/pier 0.0.1

package/dist/channels/types.js

@@ -0,0 +1,27 @@
+// IM channel configuration types — the wire contract shared by the store, the
+// adapters and the Console view (which type-only imports it, so this file must
+// stay free of node builtins, exactly like core/types.ts).
+//
+// Defaults are least-privilege: mention AND bind are required. The platform
+// values are *seeds*, copied into a chat when the bot first sees it — not a
+// fallback consulted at runtime. So every chat carries its own answer and a
+// switch means what it says, instead of a three-state "inherit" nobody can
+// read off the screen.
+const PLATFORMS = ["telegram", "slack", "lark"];
+/** Validate at the boundary: an unknown platform is a 404, not a new row. */
+export const isChannelPlatform = (v) => typeof v === "string" && PLATFORMS.includes(v);
+export const defaultChannelConfig = () => ({
+    enabled: false,
+    token: "",
+    appToken: "",
+    agentTool: true,
+    requireMention: true,
+    requireBind: true,
+    topicMode: true,
+    cwd: "",
+    model: null,
+    thinking: null,
+    users: [],
+    chats: [],
+    bindCode: null,
+});

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// What `pier` does when typed. Dispatch only — no logic, and no imports of the
+// server until a command that needs it: `pier service install` on a machine
+// with no database should not open one.
+//
+// Hand-rolled against node:util's parseArgs rather than a CLI framework: three
+// commands and four flags do not earn a dependency (AGENTS.md 8).
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+const { version } = createRequire(import.meta.url)("../package.json");
+const HELP = `pier ${version} — a self-hosted workspace for coding agents
+
+Usage
+  pier                        run the workbench in this terminal
+  pier service install        write and start a systemd user unit (Linux)
+  pier service uninstall      stop it and remove the unit
+  pier service status         what systemd thinks of it
+  pier --version | --help
+
+Options for "service install"
+  --port <n>       what to listen on            (default 3141)
+  --host <addr>    what to bind                 (default 127.0.0.1, loopback)
+  --pier-home <d>  where state lives            (default ~/.pier)
+  --force          replace a unit already there
+
+The workbench is behind a password generated on first run and printed once.
+Under systemd that print lands in the journal: journalctl --user -u pier -e
+`;
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    strict: false,
+    options: {
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        force: { type: "boolean" },
+        port: { type: "string" },
+        host: { type: "string" },
+        "pier-home": { type: "string" },
+    },
+});
+const [command, subcommand] = positionals;
+if (values.help || command === "help") {
+    process.stdout.write(HELP);
+}
+else if (values.version || command === "version") {
+    process.stdout.write(`${version}\n`);
+}
+else if (!command) {
+    // The server starts on import; this file stays a dispatcher.
+    await import("./main.js");
+}
+else if (command === "service") {
+    await service(subcommand);
+}
+else {
+    process.stderr.write(`pier: unknown command "${command}"\n\n${HELP}`);
+    process.exit(2);
+}
+async function service(action = "status") {
+    const { install, uninstall, UNIT_NAME } = await import("./service.js");
+    const say = (message) => void process.stdout.write(`${message}\n`);
+    if (action !== "status" && process.platform !== "linux") {
+        process.stderr.write(`pier service is systemd, so Linux only — this is ${process.platform}.\n` +
+            `Run "pier" in a terminal, or under whatever supervisor you already use;\n` +
+            `it needs no arguments and keeps its state in $PIER_HOME (~/.pier).\n`);
+        process.exit(2);
+    }
+    switch (action) {
+        case "install":
+            install({
+                // The node running this command, not whatever systemd would find on a
+                // minimal PATH — and the entry beside this file, not a checkout.
+                execPath: process.execPath,
+                entry: fileURLToPath(new URL("./main.js", import.meta.url)),
+                host: typeof values.host === "string" ? values.host : "127.0.0.1",
+                port: typeof values.port === "string" ? Number(values.port) : 3141,
+                pierHome: typeof values["pier-home"] === "string" ? values["pier-home"] : undefined,
+                force: values.force === true,
+                say,
+            });
+            return;
+        case "uninstall":
+            uninstall(undefined, say);
+            return;
+        case "status":
+            try {
+                // Inherited, not captured: systemctl's own output is the answer, and
+                // its exit code is nonzero for a service that is merely stopped.
+                execFileSync("systemctl", ["--user", "status", UNIT_NAME], { stdio: "inherit" });
+            }
+            catch {
+                process.exitCode = 1;
+            }
+            return;
+        default:
+            process.stderr.write(`pier service: unknown action "${action}"\n\n${HELP}`);
+            process.exit(2);
+    }
+}

package/dist/core/hub.js

@@ -0,0 +1,53 @@
+// Per-session event fan-out with a replay ring buffer. The single stamping
+// point for seq/ts — nothing else in the system numbers events.
+const RING_SIZE = 1000;
+export class EventHub {
+    buses = new Map();
+    // Workspace bus: no seq, no replay — a client that missed events just
+    // re-lists on reconnect, so there is nothing to renumber.
+    workspace = new Set();
+    bus(sessionId) {
+        let b = this.buses.get(sessionId);
+        if (!b) {
+            b = { seq: 0, buffer: [], subscribers: new Set() };
+            this.buses.set(sessionId, b);
+        }
+        return b;
+    }
+    emit(sessionId, payload) {
+        const b = this.bus(sessionId);
+        const event = {
+            seq: ++b.seq,
+            ts: Date.now(),
+            sessionId,
+            ...payload,
+        };
+        b.buffer.push(event);
+        if (b.buffer.length > RING_SIZE)
+            b.buffer.shift();
+        for (const fn of b.subscribers)
+            fn(event);
+        return event;
+    }
+    subscribe(sessionId, fn) {
+        const b = this.bus(sessionId);
+        b.subscribers.add(fn);
+        return () => b.subscribers.delete(fn);
+    }
+    /** Events with seq > afterSeq still held in the ring buffer. */
+    replay(sessionId, afterSeq) {
+        return this.bus(sessionId).buffer.filter((e) => e.seq > afterSeq);
+    }
+    emitWorkspace(event) {
+        for (const fn of this.workspace)
+            fn(event);
+    }
+    subscribeWorkspace(fn) {
+        this.workspace.add(fn);
+        return () => this.workspace.delete(fn);
+    }
+    /** Highest seq stamped so far (0 if none). */
+    lastSeq(sessionId) {
+        return this.buses.get(sessionId)?.seq ?? 0;
+    }
+}

package/dist/core/identity.js

@@ -0,0 +1,66 @@
+// Who is talking, and when — prefixed onto an inbound prompt.
+//
+// A session reached through a group chat sees a stream of messages from several
+// people, and without this it cannot tell them apart or mention anyone back.
+// The identity is per-*turn* information and deliberately never baked into a
+// session's instructions: a thread is shared, so pinning the first speaker
+// misattributes everyone who follows.
+//
+// The whole design constraint is token cost. A header on every message is
+// ~15 wasted tokens per turn in a DM where the counterpart never changes, so a
+// line is emitted only when it carries news: a different speaker, or a gap long
+// enough that "when" matters. Nothing changed means nothing is sent.
+/** A gap this long makes the timestamp worth its tokens. */
+const GAP_MS = 10 * 60_000;
+/**
+ * Strip the delimiters the format itself uses, plus newlines, and cap the
+ * length. Without this a display name of `x<U9] [admin<U1` forges a second
+ * speaker — the prefix is untrusted input wearing a trusted shape.
+ */
+export function sanitizeIdentity(value) {
+    const token = (value || "")
+        .replace(/[\r\n]+/g, " ")
+        .replace(/[[\]<>]/g, "")
+        .trim();
+    return token.slice(0, 60) || "unknown";
+}
+const two = (n) => String(n).padStart(2, "0");
+const hhmm = (d) => `${two(d.getHours())}:${two(d.getMinutes())}`;
+const day = (d) => `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+/**
+ * Tracks what each session has already been told, so a prefix is only spent on
+ * a change. In-memory on purpose: after a restart one redundant header is a
+ * rounding error, and persisting it would be bookkeeping for nothing.
+ */
+export class SenderPrefix {
+    seen = new Map();
+    /**
+     * The line to put above this message, or `""` when the session already knows.
+     * Same speaker, no real time gap, same day → nothing.
+     */
+    next(sessionId, sender, at = Date.now()) {
+        if (!sender?.id)
+            return "";
+        const last = this.seen.get(sessionId);
+        this.seen.set(sessionId, { senderId: sender.id, at });
+        const now = new Date(at);
+        const newSpeaker = last?.senderId !== sender.id;
+        const gap = !last || at - last.at >= GAP_MS;
+        const newDay = !last || day(new Date(last.at)) !== day(now);
+        if (!newSpeaker && !gap && !newDay)
+            return "";
+        // The id rides along with the name because it is the only thing a mention
+        // can be built from, and asking the human for it is never acceptable.
+        // When the platform could not resolve a name it hands back the id, and
+        // `U123<U123>` reads as a broken record rather than as an unknown name —
+        // so an unnamed speaker is just the id, once.
+        const id = sanitizeIdentity(sender.id);
+        const label = sanitizeIdentity(sender.name);
+        const who = newSpeaker ? (label === id ? `<${id}>` : `${label}<${id}>`) : "";
+        // The date only when it changed; inside one conversation-day it is noise.
+        const when = gap || newDay ? `${newDay ? `${day(now)} ` : ""}${hhmm(now)}` : "";
+        return `[${[who, when].filter(Boolean).join(" ")}]`;
+    }
+}
+/** Put the prefix above the message, or hand the message back untouched. */
+export const withPrefix = (prefix, text) => prefix ? `${prefix}\n${text}` : text;

package/dist/core/queue.js

@@ -0,0 +1,11 @@
+// The whole queue policy. Fixed by docs/architecture.md — do not add options.
+export function decide(msg, state) {
+    const steerPrefixed = msg.text.startsWith("!");
+    const text = steerPrefixed ? msg.text.slice(1).trimStart() : msg.text;
+    if (state === "idle")
+        return { action: "prompt", text };
+    if (msg.mode === "steer" || msg.mode === "followUp") {
+        return { action: msg.mode, text };
+    }
+    return { action: steerPrefixed ? "steer" : "followUp", text };
+}

package/dist/core/reply.js

@@ -0,0 +1,202 @@
+// Assistant-reply presentation, computed once for every surface: the next-step
+// block below, and a turn's completion stats. Both are rendered by the web
+// chat and by every IM adapter, so the wording and the units live here rather
+// than being re-derived per surface (they drifted once already).
+//
+// An agent may
+// end a turn with a "next step" block — a `---` rule followed by a row of
+// `[label]` tokens — and each surface renders those labels as buttons whose
+// click sends the label back as an ordinary user message. The syntax lives
+// here so web, IM adapters and Show pages never re-implement it.
+/**
+ * The surface contract handed to every agent Pier launches (main.ts wires it
+ * into the factory). Both halves of the feature live in this file: the syntax
+ * the agent is told to emit, and the parser that reads it back.
+ */
+export const REPLY_SURFACE_PROMPT = `## Pier chat surface
+
+Your replies render in a chat UI (web and IM). Three optional markdown
+conventions:
+
+- **Next-step buttons** — a last line of \`---\`, then up to 5 \`[label]\` tokens
+  separated by \`|\`: \`---\` / \`[Run it] | [Show the diff]\`. A click sends that
+  label as the user's next message. Only for short, obvious next moves, never
+  for anything destructive.
+- **Attachments** — link a file you produced by absolute \`file://\` URL:
+  \`[report.md](file:///abs/path/report.md)\`. Images render as thumbnails,
+  other files as a download card; only files inside the session's working
+  directory are readable.
+- **Staying silent** — \`<silent>why</silent>\` is stripped, and if nothing else
+  remains no message is sent. In a group chat you are handed every message,
+  including humans talking to each other: stay silent rather than acknowledge
+  what was not addressed to you.
+
+A message may start with \`[name<id> time]\` — the sender, added by Pier, not
+typed by them. It appears only when the speaker or the day changes, so the last
+one still applies. Use that \`id\` to mention someone; never ask for their own.
+`;
+/**
+ * The contract above plus the two facts about *this* deployment that an agent
+ * cannot work out for itself.
+ *
+ * Told, not discovered. Pier knows both — the home is its own startup argument
+ * and the address is a file it wrote — while an agent can only guess at a
+ * path and shell out to look. The guess is wrong on every instance that moves
+ * `PIER_HOME`, and it fails as "nothing is configured": indistinguishable from
+ * the truth, and reported to the user as such. Which is what happened.
+ */
+export function surfacePrompt(instance) {
+    const reach = instance.publicUrl
+        ? `Address: ${instance.publicUrl} — a board's link is that plus ` +
+            "`/boards/<slug>/`, or `/p/<slug>/` once published."
+        : "No public address is configured (the user sets one in Console → Settings), " +
+            "so give paths and never guess a host.";
+    return `${REPLY_SURFACE_PROMPT}
+## This Pier instance
+
+Boards: \`${instance.boardsDir}/<slug>/\` — this path, not \`~/.pier\`. ${reach}
+`;
+}
+/**
+ * Where a system input came from, in the fewest words that still say it.
+ *
+ * Lives here with `formatTurnMeta` for the same reason: it is *wording*, and
+ * every surface must spell it the same way. It was copied verbatim into the
+ * second adapter before landing here.
+ */
+export function originLabel(origin) {
+    if (origin.kind === "error")
+        return "\u26a0 failed";
+    if (origin.kind !== "task-message") {
+        return origin.kind === "task-delegation" ? "\u25b6 delegated task" : "\u21a9 task callback";
+    }
+    const kinds = {
+        steer: "\u270e steer",
+        follow_up: "\uff0b follow-up",
+        progress: "\u25c7 progress",
+        decision: "\u2753 decision needed",
+        reply: "\u21a9 reply",
+    };
+    return `from a subagent \u00b7 ${kinds[origin.messageKind] ?? origin.messageKind}`;
+}
+/**
+ * Quote and bracket characters that may be lifted out of a `**strong**` run.
+ * Moving them changes nothing a reader can see — the punctuation is simply no
+ * longer bold — while taking the delimiter off a character the parser refuses
+ * to close on.
+ */
+const LIFTABLE = /[\u201c\u201d"\u2018\u2019'()\uff08\uff09\u300c\u300d\u300e\u300f\u3010\u3011\u300a\u300b\u3008\u3009[\]]/;
+/**
+ * Repair emphasis that CommonMark refuses to close.
+ *
+ * A closing `**` must be *right-flanking*: preceded by non-whitespace, and
+ * either not preceded by punctuation or else followed by whitespace or
+ * punctuation. `**\u201c\u600e\u4e48\u505a\u201d**\uff1a` fails both halves \u2014 preceded by a quote,
+ * followed by a CJK colon the rule does not count \u2014 so the run never closes and
+ * the reader sees literal asterisks. `**\u95f2\u804a**\uff1a` is fine, because a letter
+ * precedes the delimiter. This is a known ten-year-old hole in the spec around
+ * CJK, not a Slack bug, and it shows up constantly in model output.
+ *
+ * The repair is to move the punctuation outside the delimiters, so the `**`
+ * lands against a letter: `\u201c**\u600e\u4e48\u505a**\u201d\uff1a`. Code is protected first \u2014 asterisks
+ * inside a fence or a code span are content, not markup.
+ */
+export function cjkFriendly(markdown) {
+    const stash = [];
+    const keep = (text) => `\uE010${stash.push(text) - 1}\uE011`;
+    let out = markdown
+        .replace(/```[\s\S]*?```/g, (m) => keep(m))
+        .replace(/`[^`\n]+`/g, (m) => keep(m));
+    out = out.replace(/\*\*(\S|\S[\s\S]*?\S)\*\*/g, (whole, inner) => {
+        let lead = "";
+        let trail = "";
+        let body = inner;
+        while (body.length > 1 && LIFTABLE.test(body[0])) {
+            lead += body[0];
+            body = body.slice(1);
+        }
+        while (body.length > 1 && LIFTABLE.test(body.at(-1))) {
+            trail = body.at(-1) + trail;
+            body = body.slice(0, -1);
+        }
+        // Nothing was on the edges, or the run is only punctuation: leave it be.
+        return lead || trail ? `${lead}**${body}**${trail}` : whole;
+    });
+    return out.replace(/\uE010(\d+)\uE011/g, (_m, i) => stash[Number(i)] ?? "");
+}
+/** How a reasoning level is spelled wherever a human reads it. */
+export const thinkingLabel = (level) => level === "xhigh" ? "Extra high" : level[0].toUpperCase() + level.slice(1);
+/** 1200 → "1.2K", 12_000 → "12K" — absolute token counts read badly inline. */
+export const compact = (n) => {
+    if (n < 1000)
+        return String(n);
+    const k = n / 1000;
+    // Precision comes from the *rounded* value, so 9_990 reads "10K" instead of
+    // a "10.0K" that claims a decimal it does not have.
+    return k >= 9.95 ? `${Math.round(k)}K` : `${k.toFixed(1)}K`;
+};
+/** "45s" / "1m14s". Floored at one second: sub-second precision is noise. */
+function formatDuration(ms) {
+    const secs = Math.max(1, Math.round(ms / 1000));
+    return secs < 60 ? `${secs}s` : `${Math.floor(secs / 60)}m${secs % 60}s`;
+}
+/**
+ * A turn's cost, in the one wording every surface uses: how long it took and
+ * how big the context is now. `tokens` is the context size at completion, not
+ * a per-turn sum (see TurnMeta) — the label stays "tok" because that is what
+ * the number is counted in.
+ */
+export const formatTurnMeta = (meta) => `${formatDuration(meta.durationMs)} · ${compact(meta.tokens)} tok`;
+/**
+ * Trailing `---` line + a row of bracket tokens, optionally `|`-separated.
+ * A markdown link (`[label](url)`) leaves `(url)` unmatched, so reference-link
+ * blocks stay message content instead of turning into buttons.
+ *
+ * `(?:^|\n)` because a turn is allowed to be nothing but its options: anchoring
+ * on a preceding newline left that whole block sitting in the message as raw
+ * text, with no buttons anywhere.
+ */
+const BLOCK = /(?:^|\n)[ \t]*-{3,}[ \t]*\r?\n((?:[ \t]*\[[^\]\r\n]+\][ \t]*(?:[|｜][ \t]*)?)+)\s*$/;
+const TOKEN = /\[([^\]\r\n]+)\]/g;
+const MAX_SUGGESTIONS = 5;
+/** Split an assistant turn's markdown into renderable text + next-step labels. */
+/**
+ * A deliberate non-answer. In a group thread the agent is handed every message,
+ * and most of them are two humans talking; a bot that replies to each one is
+ * unusable. Stripping the block here means an adapter needs no new concept: a
+ * turn whose text is empty already posts nothing and still retires its per-turn
+ * UI, which is exactly "listened, said nothing".
+ *
+ * The reason inside stays in the Pi transcript, so the choice is auditable
+ * without being broadcast to the chat.
+ */
+const SILENT = /<silent>([\s\S]*?)<\/silent>/gi;
+/**
+ * Why the agent stayed quiet. Stripped from anything sent to a chat, but the
+ * workbench is the operator's own view of the run — "it said nothing and here
+ * is why" is observability, and hiding it there would just make a silent turn
+ * look like a broken one.
+ */
+export function silentReason(markdown) {
+    const reasons = [...markdown.matchAll(SILENT)]
+        .map((m) => (m[1] ?? "").trim())
+        .filter(Boolean);
+    return reasons.length ? reasons.join(" · ") : undefined;
+}
+export function splitReply(rawMarkdown, meta) {
+    // Every surface that renders this goes through here, and every CommonMark
+    // parser has some version of the CJK emphasis hole — so the repair belongs
+    // once, at the seam, not per adapter.
+    const markdown = cjkFriendly(rawMarkdown.replace(SILENT, "").trim());
+    const silence = silentReason(rawMarkdown);
+    const m = BLOCK.exec(markdown);
+    if (!m?.[1])
+        return { text: markdown, suggestions: [], meta, silence };
+    const suggestions = [...m[1].matchAll(TOKEN)]
+        .map((t) => (t[1] ?? "").trim())
+        .filter(Boolean)
+        .slice(0, MAX_SUGGESTIONS);
+    if (!suggestions.length)
+        return { text: markdown, suggestions: [], meta, silence };
+    return { text: markdown.slice(0, m.index).trimEnd(), suggestions, meta, silence };
+}

package/dist/core/router.js

@@ -0,0 +1,189 @@
+// Conversation → session routing plus event wiring. In-memory for v1;
+// persistence arrives with task storage (docs/plans/bootstrap.md step 4).
+import { logger } from "../log.js";
+import { EventHub } from "./hub.js";
+import { SenderPrefix, withPrefix } from "./identity.js";
+import { decide } from "./queue.js";
+import { splitReply } from "./reply.js";
+const log = logger("core");
+/** An error goes into a chat window, so it is trimmed to something readable. */
+const truncate = (message) => message.length > 600 ? `${message.slice(0, 600)}…` : message;
+function keyOf(key) {
+    return `${key.channelId}:${key.conversationId}`;
+}
+export class Router {
+    hub;
+    resolve;
+    byKey = new Map();
+    bySession = new Map();
+    channels = new Map();
+    /** Who each session last heard from, so a header costs tokens only on news. */
+    senders = new SenderPrefix();
+    constructor(hub, 
+    /** Create or resume the session owning a conversation (wired in main.ts). */
+    resolve) {
+        this.hub = hub;
+        this.resolve = resolve;
+    }
+    registerChannel(channel) {
+        this.channels.set(channel.id, channel);
+    }
+    /**
+     * Tell the conversation something went wrong, then the event stream.
+     *
+     * Applies to every channel, because the failure mode is the same everywhere:
+     * an IM user watching the eyes come off with no reply cannot tell a crash
+     * from a deliberate silence, and the operator cannot debug what they never
+     * saw. The web reads errors off the hub already, so only a registered channel
+     * gets a note; `notify` is used rather than `send` so it is never mistaken
+     * for an assistant turn.
+     */
+    report(sessionId, key, message) {
+        // Three surfaces, one failure: the chat that is waiting, the web timeline,
+        // and the log the operator greps once it is reported to them.
+        log.error(`${keyOf(key)} session ${sessionId}: ${message}`);
+        this.hub.emit(sessionId, { type: "error", message });
+        const channel = this.channels.get(key.channelId);
+        // Best-effort and never recursive: if telling the chat also fails, the hub
+        // already has the original.
+        channel?.notify(key.conversationId, { text: truncate(message), origin: { kind: "error" } })
+            .catch((err) => {
+            log.error(`could not report the failure to ${key.channelId}`, err);
+            this.hub.emit(sessionId, {
+                type: "error",
+                message: `could not report the failure to ${key.channelId}: ${String(err)}`,
+            });
+        });
+    }
+    stateOf(sessionId) {
+        return this.bySession.get(sessionId)?.session.state;
+    }
+    stateSinceOf(sessionId) {
+        return this.bySession.get(sessionId)?.stateSince;
+    }
+    /** Current in-memory model of a live session (undefined when not attached). */
+    modelOf(sessionId) {
+        return this.bySession.get(sessionId)?.session.model;
+    }
+    /**
+     * Which conversation a session is answering, if any. The inverse of
+     * `sessionOf`, and what lets a tool act on "here" — an agent reached through
+     * a Slack thread otherwise has no way to name the thread it is replying in.
+     * A task or subagent session is attached to nothing and answers undefined.
+     */
+    conversationOf(sessionId) {
+        return this.bySession.get(sessionId)?.key;
+    }
+    /** Attach an existing session to a conversation and wire its events. */
+    attach(key, session) {
+        this.byKey.set(keyOf(key), session);
+        const existing = this.bySession.get(session.id);
+        if (existing?.session === session)
+            return;
+        this.bySession.set(session.id, { session, key, stateSince: Date.now() });
+        log.info(`attached ${keyOf(key)} → session ${session.id}`);
+        session.subscribe((payload) => {
+            this.hub.emit(session.id, payload);
+            // Run state is workspace-visible: every client's session list shows it.
+            if (payload.type === "state") {
+                const attached = this.bySession.get(session.id);
+                if (attached)
+                    attached.stateSince = Date.now();
+                this.hub.emitWorkspace({
+                    type: "session-state",
+                    sessionId: session.id,
+                    state: payload.state,
+                });
+            }
+            // An error the session itself reported (a tool that threw, a model
+            // refusal, a lost connection). Without this it lands only in the web
+            // timeline and the IM side goes quiet for no visible reason.
+            if (payload.type === "error") {
+                log.error(`${keyOf(key)} session ${session.id} reported: ${payload.message}`);
+                const channel = this.channels.get(key.channelId);
+                channel?.notify(key.conversationId, {
+                    text: truncate(payload.message),
+                    origin: { kind: "error" },
+                }).catch((err) => log.error(`notify ${key.channelId} failed`, err));
+            }
+            // A system input is context the chat did not see being typed. It goes
+            // out before the turn it triggers, so the answer has a visible cause.
+            if (payload.type === "system-input") {
+                const channel = this.channels.get(key.channelId);
+                channel?.notify(key.conversationId, { text: payload.text, origin: payload.origin })
+                    .catch((err) => {
+                    log.error(`notify ${key.channelId} failed`, err);
+                    this.hub.emit(session.id, {
+                        type: "error",
+                        message: `notify ${key.channelId} failed: ${String(err)}`,
+                    });
+                });
+            }
+            // Every turn-end reaches the channel, empty text included: an adapter's
+            // per-turn UI (Telegram's 👀 receipts) is retired here, and a turn that
+            // settled with nothing to say still has to settle.
+            if (payload.type === "turn-end") {
+                log.info(`turn end ${keyOf(key)} session ${session.id}: ${String(payload.text.length)} chars`);
+                const channel = this.channels.get(key.channelId);
+                if (channel) {
+                    channel.send(key.conversationId, splitReply(payload.text, payload.meta)).catch((err) => {
+                        this.report(session.id, key, `outbound to ${key.channelId} failed: ${String(err)}`);
+                    });
+                }
+            }
+        });
+    }
+    async abort(sessionId) {
+        await this.bySession.get(sessionId)?.session.abort();
+    }
+    /**
+     * The session already attached to a conversation, if any. Never creates one:
+     * a channel's stop or settings command must not be what opens a session.
+     */
+    sessionOf(key) {
+        return this.byKey.get(keyOf(key));
+    }
+    async abortConversation(key) {
+        await this.sessionOf(key)?.abort();
+    }
+    /** Session owning a conversation, resolving and attaching it on first use. */
+    async ensure(key) {
+        let session = this.byKey.get(keyOf(key));
+        // Web and task conversation ids are session ids. Reuse an attached
+        // instance so two surfaces never open the same Pi transcript twice.
+        if (!session && (key.channelId === "web" || key.channelId === "task")) {
+            session = this.bySession.get(key.conversationId)?.session;
+            if (session)
+                this.byKey.set(keyOf(key), session);
+        }
+        if (!session) {
+            try {
+                session = await this.resolve(key);
+            }
+            catch (err) {
+                // The one failure with nowhere to report itself: there is no session id
+                // to emit under yet, and every caller only sees a rejected promise.
+                log.error(`could not open a session for ${keyOf(key)}`, err);
+                throw err;
+            }
+            this.attach(key, session);
+        }
+        return session;
+    }
+    async dispatch(msg) {
+        const session = await this.ensure(msg.key);
+        const { action, text } = decide(msg, session.state);
+        // A group chat is many people talking into one session; without a speaker
+        // line the agent cannot tell them apart or mention anyone back. Emitted
+        // only when the speaker or the clock says something new.
+        const prompt = withPrefix(this.senders.next(session.id, msg.sender), text);
+        log.debug(`${action} ${keyOf(msg.key)} → session ${session.id}` +
+            ` (${String(prompt.length)} chars, ${String(msg.images?.length ?? 0)} images)`);
+        // Turn outcomes flow through the event stream; a rejected call surfaces
+        // there too, never as a thrown exception across the seam.
+        session[action](prompt, msg.images).catch((err) => {
+            this.report(session.id, msg.key, String(err));
+        });
+        return { sessionId: session.id };
+    }
+}

package/dist/core/types.js

@@ -0,0 +1,7 @@
+// Normative seam types — THIS FILE is the system contract (docs/architecture.md
+// documents the rules around it). Changing a seam is a design decision, not a
+// refactor; keep it implementable over RPC (no Pi types may appear here).
+/** Every level Pi accepts, in order. The union is derived so the two cannot
+ *  drift, and boundary validators use isThinkingLevel instead of their own copy. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export const isThinkingLevel = (v) => typeof v === "string" && THINKING_LEVELS.includes(v);