@timqi/pier 0.1.14 → 0.3.0

package/dist/core/router.js

@@ -1,46 +1,23 @@
 // Conversation → session routing plus event wiring. In-memory on purpose:
 // the durable chat → session map lives in channels/conversations.ts.
-import { randomUUID } from "node:crypto";
 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";
+import { cut, splitReply } from "./reply.js";
+import { isChatCommand } from "./types.js";
 const log = logger("core");
 /** Generous: eviction is a memory measure, and re-opening costs a Pi resume
  *  plus a transcript read. */
 const IDLE_TTL_MS = 30 * 60_000;
 const SWEEP_MS = 5 * 60_000;
-/** 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;
-/** What a chat window gets of a system input; a task callback carries up to
- *  8000 characters of result text (tasks/callbacks.ts). */
-const NOTE_CHARS = 200;
-const NOTE_LINES = 4;
-/** A note is context for the turn it precedes, not the message: pasted whole,
- *  a run result buries the chat on IM, which cannot collapse it. The hub and
- *  the transcript keep every character. */
-function digest(text) {
-    const body = text.trimEnd();
-    let head = body.split("\n").slice(0, NOTE_LINES).join("\n");
-    if (head.length > NOTE_CHARS) {
-        const capped = head.slice(0, NOTE_CHARS);
-        // A boundary before the midpoint loses more than the ragged edge costs.
-        const boundary = Math.max(capped.lastIndexOf("\n"), capped.lastIndexOf(" "));
-        head = capped.slice(0, boundary > NOTE_CHARS / 2 ? boundary : NOTE_CHARS);
-    }
-    const rest = body.slice(head.length).trim();
-    if (!rest)
-        return body;
-    const dropped = rest.split("\n").length;
-    return `${head.trimEnd()}\n… +${String(dropped)} more line${dropped === 1 ? "" : "s"}`;
-}
 function keyOf(key) {
     return `${key.channelId}:${key.conversationId}`;
 }
 /** `web:<id>` and `task:<id>` name one session id and neither is a chat — no
  *  Channel is registered under them — so they share a lock in `ensure`. */
 const isAlias = (key) => key.channelId === "web" || key.channelId === "task";
+const webKey = (sessionId) => ({ channelId: "web", conversationId: sessionId });
 export class QueueOperationError extends Error {
     reason;
     constructor(reason, message) {
@@ -48,6 +25,28 @@ export class QueueOperationError extends Error {
         this.reason = reason;
     }
 }
+/** A message the router did not take and has already told the chat about
+ *  (`refuse`): a caller that reports its own failures skips these. */
+export class Refused extends Error {
+}
+/** A short skill spelling that names more than one skill: not sent, the chat told. */
+export class SkillAmbiguous extends Refused {
+}
+/** `/<word> <rest>` or `%<word> <rest>` (also `/skill:<word>`) resolved to the
+ *  one skill `word` is a prefix of — of the name, or of the name after any `-`;
+ *  the text unchanged when it names none (docs/design/11-im-conversation.md). */
+function skillText(text, skills) {
+    // Two characters at least: `/s <text>` is the settings draft's spelling (channels/commands.ts).
+    const [, kept, spelled, rest] = /^[/%](skill:)?([^\s/%]{2,})(?:[ \t]+([\s\S]*))?$/i.exec(text.trim()) ?? [];
+    const word = spelled?.toLowerCase();
+    if (!word || (!kept && isChatCommand(word)))
+        return text;
+    const names = skills.map((s) => s.name);
+    const found = names.includes(word) ? [word] : names.filter((name) => name.split("-").some((_, i, parts) => parts.slice(i).join("-").startsWith(word)));
+    if (found.length > 1)
+        return new SkillAmbiguous(`/${word} matches ${found.join(", ")} — say more`);
+    return found[0] ? `/skill:${found[0]}${rest ? ` ${rest}` : ""}` : text;
+}
 export class Router {
     hub;
     resolve;
@@ -64,7 +63,7 @@ export class Router {
     /** Set by a graceful restart (src/drain.ts); `endDrain` is for the caller
      *  that drains speculatively and may not get to exit. */
     draining = false;
-    spokenTo;
+    turnEnded;
     constructor(hub, 
     /** Create or resume the session owning a conversation (wired in main.ts). */
     resolve, 
@@ -80,14 +79,46 @@ export class Router {
         this.sessionIdOf = sessionIdOf;
         this.chatKeyOf = chatKeyOf;
     }
+    /** A session its adapter's stop sent back to its own stream takes its chat again. */
     registerChannel(channel) {
         this.channels.set(channel.id, channel);
+        for (const attached of this.bySession.values())
+            this.toChat(attached);
+    }
+    /** A stopped adapter's sessions answer on their own stream until it is back:
+     *  a key on a dead channel delivers nowhere, and Web Push reads it as a chat's. */
+    unregisterChannel(channelId) {
+        this.channels.delete(channelId);
+        for (const key of this.byKey.keys())
+            if (key.startsWith(`${channelId}:`))
+                this.byKey.delete(key);
+        for (const attached of this.bySession.values()) {
+            if (attached.key.channelId === channelId)
+                attached.key = webKey(attached.session.id);
+        }
     }
-    /** Fires for humans only: chats and the workbench pass through `dispatch`,
-     *  tasks and subagents do not. Registered late because the listener
-     *  (web/session-state.ts) is built with the web surface. */
-    onSpokenTo(listener) {
-        this.spokenTo = listener;
+    /** The durable chat outranks the alias that happened to open the session
+     *  first (a restart, the web speaking first), same rule as `reached`. */
+    toChat(attached) {
+        const chat = isAlias(attached.key) ? this.chatKeyOf(attached.session.id) : undefined;
+        if (!chat || !this.channels.has(chat.channelId))
+            return;
+        this.hold(chat, attached.session);
+        attached.key = chat;
+    }
+    /** A chat key taken from another session (the chain's rotation) leaves it,
+     *  or two sessions would answer one chat. */
+    hold(key, session) {
+        const previous = this.byKey.get(keyOf(key));
+        const left = previous && previous !== session ? this.bySession.get(previous.id) : undefined;
+        if (left && keyOf(left.key) === keyOf(key))
+            left.key = webKey(left.session.id);
+        this.byKey.set(keyOf(key), session);
+    }
+    /** Every attached session's answered turn, runs' and humans' alike; a failed
+     *  turn is not one. Registered by the task service (tasks/service.ts). */
+    onTurnEnd(listener) {
+        this.turnEnded = listener;
     }
     /** A failure reaches the chat as well as the hub (§5): on IM, silence is
      *  indistinguishable from a crash. `notify`, not `send`, so it is never
@@ -97,7 +128,7 @@ export class Router {
         this.hub.emit(sessionId, { type: "error", message });
         const channel = this.channels.get(key.channelId);
         // Never recursive: if telling the chat also fails, the hub has the original.
-        channel?.notify(key.conversationId, { text: truncate(message), origin: { kind: "error" } })
+        channel?.notify(key.conversationId, { text: cut(message, 600), origin: { kind: "error" } })
             .catch((err) => {
             log.error(`could not report the failure to ${key.channelId}`, err);
             this.hub.emit(sessionId, {
@@ -126,7 +157,7 @@ export class Router {
         // Snapshot: the loop awaits dispose(), and the map may change meanwhile.
         // oxlint-disable-next-line unicorn/no-useless-spread
         for (const [id, attached] of [...this.bySession]) {
-            if (this.queueOperations.has(id) || this.recoveries.get(id)?.some((b) => b.status === "submitting"))
+            if (this.queueOperations.has(id) || this.submitting.has(id))
                 continue;
             if (!includeWatched && this.hub.hasSubscribers(id))
                 continue;
@@ -165,9 +196,6 @@ export class Router {
     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;
@@ -187,7 +215,7 @@ export class Router {
     attach(key, session) {
         const existing = this.bySession.get(session.id);
         if (existing?.session === session) {
-            this.byKey.set(keyOf(key), session);
+            this.hold(key, session);
             this.reached(session, key);
             return;
         }
@@ -199,14 +227,13 @@ export class Router {
             this.forgetKeys(existing.session);
             void existing.session.dispose().catch((err) => log.error(`disposing replaced session ${session.id} failed`, err));
         }
-        this.byKey.set(keyOf(key), session);
+        this.hold(key, session);
         log.info(`attached ${keyOf(key)} → session ${session.id}`);
         // Delivery reads `attached.key` live: a chat attaching after the workbench
         // opened the session takes over (`reached`), and the closure must follow.
         const attached = {
             session,
             key,
-            stateSince: Date.now(),
             activeAt: Date.now(),
             touched: 0,
             unsubscribe: session.subscribe((payload) => {
@@ -214,7 +241,7 @@ export class Router {
                 this.hub.emit(session.id, payload);
                 if (payload.type === "state") {
                     // Every turn passes here, so it also proves liveness to the sweeper.
-                    attached.stateSince = attached.activeAt = Date.now();
+                    attached.activeAt = Date.now();
                     attached.touched += 1;
                     this.hub.emitWorkspace({
                         type: "session-state",
@@ -230,7 +257,7 @@ export class Router {
                     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),
+                        text: cut(payload.message, 600),
                         origin: { kind: "error" },
                     }).catch((err) => log.error(`notify ${key.channelId} failed`, err));
                 }
@@ -239,7 +266,7 @@ export class Router {
                 if (payload.type === "system-input") {
                     const channel = this.channels.get(key.channelId);
                     channel?.notify(key.conversationId, {
-                        text: digest(payload.text),
+                        text: payload.text,
                         origin: payload.origin,
                         at: payload.at,
                     })
@@ -260,6 +287,8 @@ export class Router {
                 // Empty text included: adapters retire per-turn UI (👀 receipts) on it.
                 if (payload.type === "turn-end") {
                     log.info(`turn end ${keyOf(key)} session ${session.id}: ${String(payload.text.length)} chars`);
+                    if (!payload.error)
+                        this.turnEnded?.(session.id, payload.text);
                     const channel = this.channels.get(key.channelId);
                     if (channel) {
                         const reply = splitReply(payload.text, payload.meta);
@@ -272,13 +301,7 @@ export class Router {
             }),
         };
         this.bySession.set(session.id, attached);
-        // The durable chat outranks the alias that happened to open the session
-        // first (a restart, the web speaking first), same rule as `reached`.
-        const chat = isAlias(key) ? this.chatKeyOf(session.id) : undefined;
-        if (chat) {
-            this.byKey.set(keyOf(chat), session);
-            attached.key = chat;
-        }
+        this.toChat(attached);
     }
     /** An adapter's send is several platform calls (chunks, then attachments),
      *  so two answers left to overlap interleave in the chat. Per conversation:
@@ -303,37 +326,12 @@ export class Router {
     }
     queueOperations = new Set();
     promotionRequested = new Set();
-    recoveries = new Map();
-    // Latest failed batch id, so a clear cannot erase a newer rejection that
-    // arrived while it awaited the backend.
-    uncertaintyHeld = new Map();
-    queueUncertain(sessionId) {
-        return this.uncertaintyHeld.has(sessionId);
-    }
-    recoveryOf(sessionId) {
-        return structuredClone(this.recoveries.get(sessionId) ?? []);
-    }
-    recoveryChanged(sessionId) {
-        if (!this.recoveries.get(sessionId)?.length)
-            this.recoveries.delete(sessionId);
-        this.hub.emit(sessionId, {
-            type: "queue-recovery", batches: this.recoveryOf(sessionId), uncertain: this.queueUncertain(sessionId),
-        });
-    }
-    acknowledgeRecovery(sessionId, batchId) {
-        const batches = this.recoveries.get(sessionId);
-        const batch = batches?.find((b) => b.id === batchId);
-        if (!batch)
-            throw new QueueOperationError("missing", "No such recovery batch");
-        if (batch.status === "submitting")
-            throw new QueueOperationError("busy", "Submission has not settled");
-        this.recoveries.set(sessionId, batches.filter((b) => b !== batch));
-        this.promotionRequested.delete(sessionId);
-        this.recoveryChanged(sessionId);
-    }
+    // Promotions launched but not settled, per session: automatic promotion
+    // waits for them, and eviction must not dispose a preflight.
+    submitting = new Map();
     /** Only queue mutation holds this lock; a running turn does not, so manual
      *  controls stay available while it runs. */
-    async useQueue(sessionId, action, key = { channelId: "web", conversationId: sessionId }) {
+    async useQueue(sessionId, action, key = webKey(sessionId)) {
         if (this.queueOperations.has(sessionId))
             throw new QueueOperationError("busy", "Queue operation in progress");
         this.queueOperations.add(sessionId);
@@ -347,10 +345,7 @@ export class Router {
     }
     async recallQueue(sessionId) {
         return this.useQueue(sessionId, async (session) => {
-            const held = this.uncertaintyHeld.get(sessionId);
             const queue = await session.clearQueue();
-            if (this.uncertaintyHeld.get(sessionId) === held && this.uncertaintyHeld.delete(sessionId))
-                this.recoveryChanged(sessionId);
             if (queue.steering.length || queue.followUp.length)
                 this.forgetSender(sessionId);
             return queue;
@@ -360,35 +355,25 @@ export class Router {
         if (this.draining)
             throw new QueueOperationError("draining", "Pier is restarting; queued messages were not submitted");
     }
+    /** Once cleared, the originals exist only here: a failure hands them back
+     *  to the conversation with the error, and nothing is kept for a resend. */
     async deliverQueue(sessionId, mode) {
-        let retained = false;
+        let cleared = false;
         try {
             this.checkQueueDrain();
             return await this.useQueue(sessionId, async (session) => {
                 this.checkQueueDrain();
-                if (mode === "auto" && (session.state !== "idle" || this.queueUncertain(sessionId) || this.recoveries.get(sessionId)?.length))
+                if (mode === "auto" && session.state !== "idle")
                     return "";
-                const held = this.uncertaintyHeld.get(sessionId);
                 const queue = await session.clearQueue();
-                if (mode !== "auto" && this.uncertaintyHeld.get(sessionId) === held && this.uncertaintyHeld.delete(sessionId))
-                    this.recoveryChanged(sessionId);
                 if (!queue.steering.length && !queue.followUp.length)
                     throw new QueueOperationError("empty", "Queue is empty");
-                const batch = { id: randomUUID(), ...queue, status: "submitting" };
-                this.recoveries.set(sessionId, [...(this.recoveries.get(sessionId) ?? []), batch]);
-                retained = true;
-                this.recoveryChanged(sessionId);
-                const text = [...batch.steering, ...batch.followUp].join("\n");
-                let invoked = false;
+                cleared = true;
+                const text = [...queue.steering, ...queue.followUp].join("\n");
                 const failed = (err) => {
                     this.forgetSender(sessionId);
                     this.promotionRequested.delete(sessionId);
-                    batch.status = invoked ? "uncertain" : "not-submitted";
-                    if (invoked)
-                        this.uncertaintyHeld.set(sessionId, batch.id);
-                    batch.error = String(err);
-                    this.recoveryChanged(sessionId);
-                    this.reportTo(sessionId, `Queue promotion failed (${batch.status}); automatic queue paused, originals remain available in queue recovery: ${String(err)}`);
+                    this.reportTo(sessionId, `Queued messages were not delivered — send them again: ${String(err)}\n\n${text}`);
                 };
                 try {
                     this.checkQueueDrain();
@@ -397,13 +382,17 @@ export class Router {
                     this.checkQueueDrain();
                     // Not via dispatch: the text was headed at original dispatch, and a
                     // second pass could attribute these words to the operator.
-                    invoked = true;
                     const submitted = mode === "steer" && session.state === "streaming"
                         ? session.steer(text) : session.prompt(text);
-                    void submitted.then(() => {
-                        this.recoveries.set(sessionId, (this.recoveries.get(sessionId) ?? []).filter((b) => b !== batch));
-                        this.recoveryChanged(sessionId);
-                    }, failed).finally(() => this.resumePromotion(sessionId));
+                    this.submitting.set(sessionId, (this.submitting.get(sessionId) ?? 0) + 1);
+                    void submitted.catch(failed).finally(() => {
+                        const left = this.submitting.get(sessionId) - 1;
+                        if (left)
+                            this.submitting.set(sessionId, left);
+                        else
+                            this.submitting.delete(sessionId);
+                        this.resumePromotion(sessionId);
+                    });
                     return text;
                 }
                 catch (err) {
@@ -413,7 +402,7 @@ export class Router {
             }, mode === "auto" ? this.conversationOf(sessionId) : undefined);
         }
         catch (err) {
-            if (!retained && !(err instanceof QueueOperationError && (err.reason === "busy" || err.reason === "empty"))) {
+            if (!cleared && !(err instanceof QueueOperationError && (err.reason === "busy" || err.reason === "empty"))) {
                 this.reportTo(sessionId, `Could not promote queued messages: ${String(err)}`);
             }
             throw err;
@@ -431,10 +420,7 @@ export class Router {
     resumePromotion(sessionId) {
         // queue_update precedes the backend's enqueue. Never clear it reentrantly.
         queueMicrotask(() => {
-            if (!this.promotionRequested.has(sessionId) || this.queueOperations.has(sessionId))
-                return;
-            // Retained failures require a human decision, not an automatic resend.
-            if (this.queueUncertain(sessionId) || this.recoveries.get(sessionId)?.length)
+            if (!this.promotionRequested.has(sessionId) || this.queueOperations.has(sessionId) || this.submitting.has(sessionId))
                 return;
             this.promotionRequested.delete(sessionId);
             const attached = this.bySession.get(sessionId);
@@ -476,12 +462,14 @@ export class Router {
         return this.draining;
     }
     /** Told to the chat directly (§5): an adapter's dispatch catch only logs. */
-    refuseDraining(key) {
-        const message = "Pier is restarting — this message was not taken; send it again in a moment.";
+    refuse(key, err) {
         this.channels.get(key.channelId)
-            ?.notify(key.conversationId, { text: message, origin: { kind: "error" } })
-            .catch((err) => log.error(`could not report the drain to ${key.channelId}`, err));
-        throw new Error(message);
+            ?.notify(key.conversationId, { text: err.message, origin: { kind: "error" } })
+            .catch((e) => log.error(`could not report the refusal to ${key.channelId}`, e));
+        throw err;
+    }
+    refuseDraining(key) {
+        this.refuse(key, new Refused("Pier is restarting — this message was not taken; send it again in a moment."));
     }
     /** Attached sessions still mid-turn, and conversations whose answer is still
      *  going out (`sending`) — what the drain waits on, and what its deadline
@@ -549,7 +537,7 @@ export class Router {
      *  that is waiting. Either way the waiting side is not left with nothing. */
     unopened(key, err) {
         log.error(`could not open a session for ${keyOf(key)}`, err);
-        const message = truncate(`could not open a session: ${String(err)}`);
+        const message = cut(`could not open a session: ${String(err)}`, 600);
         if (key.channelId === "web" || key.channelId === "task") {
             this.reportTo(key.conversationId, message);
             return;
@@ -581,13 +569,18 @@ export class Router {
         const session = await this.ensure(msg.key);
         if (this.draining)
             this.refuseDraining(msg.key);
-        this.spokenTo?.(session.id);
-        const { action, text } = decide(msg, session.state);
+        const skilled = skillText(msg.text, session.skills());
+        if (skilled instanceof SkillAmbiguous)
+            this.refuse(msg.key, skilled);
+        const { action, text } = decide({ ...msg, text: skilled }, session.state);
         // A chat is named so the agent can hand it to a script (skills/pier-slack);
         // an alias names nothing a shell could reach.
         const where = isAlias(msg.key) ? undefined : keyOf(msg.key);
         const opaque = this.channels.get(msg.key.channelId)?.opaqueIds;
-        const prompt = withPrefix(this.senders.next(session.id, msg.sender, Date.now(), where, opaque), text);
+        const header = this.senders.next(session.id, msg.sender, Date.now(), where, opaque, text);
+        // Pi expands `/skill:<name>` only at the very start, so a header rides in its args.
+        const skill = header ? /^\/skill:\S+/.exec(text)?.[0] : undefined;
+        const prompt = skill ? `${skill} ${withPrefix(header, text.slice(skill.length).trimStart())}` : withPrefix(header, text);
         log.debug(`${action} ${keyOf(msg.key)} → session ${session.id} (${String(prompt.length)} chars)`);
         // A rejected call surfaces on the event stream, never as a throw across the seam.
         session[action](prompt).catch((err) => {

package/dist/core/search.js

@@ -0,0 +1,65 @@
+// `pier search`: the `/search` route's host and the verb's argv, on the search
+// seam core declares (`AgentFactory.search`); root keeps only the dispatch, as
+// for `pier task` and `pier web`. Argv shape is checked here, the host validates
+// the params, and its text reaches the shell verbatim (08 §Failure lines).
+import { parseArgs } from "node:util";
+import { readableTitle } from "./identity.js";
+const USAGE = "usage: pier search <q...> [--limit N] [--json]";
+// The match marks are the palette's to paint; a line is one line.
+const flat = (text) => text.replaceAll("\u0001", "").replaceAll("\u0002", "").replace(/\s+/g, " ").trim();
+// A title may be a whole first message; the snippet is what the line is for.
+const TITLE_CHARS = 30;
+const clip = (text) => {
+    const chars = [...text];
+    return chars.length > TITLE_CHARS ? `${chars.slice(0, TITLE_CHARS - 1).join("").trimEnd()}…` : text;
+};
+// sv-SE spells local time as YYYY-MM-DD HH:MM.
+const when = (at) => new Date(at).toLocaleString("sv-SE", { dateStyle: "short", timeStyle: "short" });
+const processIo = {
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+};
+/** `/search`'s params to hits, each titled with its session's name as it is
+ *  now; a session gone from disk is named by its id. */
+export const searchSessions = (factory) => async (params) => {
+    const { q, limit = 20 } = (params ?? {});
+    const query = typeof q === "string" ? q.trim() : "";
+    if (!query)
+        throw new Error("q must be non-empty words to search for");
+    if (!Number.isInteger(limit))
+        throw new Error("limit must be an integer");
+    const hits = await factory.search(query, Math.min(50, Math.max(1, limit)));
+    return {
+        hits: await Promise.all(hits.map(async (hit) => ({ ...hit, title: readableTitle((await factory.find(hit.sessionId))?.title) ?? hit.sessionId }))),
+    };
+};
+/** One line per hit, or the answer's object with `--json`. */
+export async function runSearchCli(argv, post, io = processIo) {
+    let v = {};
+    let words = [];
+    try {
+        ({ values: v, positionals: words } = parseArgs({ args: argv, allowPositionals: true, strict: true, options: { limit: { type: "string" }, json: { type: "boolean" } } }));
+    }
+    catch (err) {
+        io.stderr(`search: ${err instanceof Error ? err.message : String(err)}\n${USAGE}`);
+        return 2;
+    }
+    if (!words.length) {
+        io.stderr(`search: say what to search for\n${USAGE}`);
+        return 2;
+    }
+    const { status, body } = await post({ q: words.join(" "), ...(v.limit === undefined ? {} : { limit: Number(v.limit) }) });
+    if (status !== 200 || !body.result) {
+        io.stderr(`search: ${body.error ?? `socket answered ${String(status)}`}`);
+        return 1;
+    }
+    const { hits } = body.result;
+    if (v.json)
+        io.stdout(JSON.stringify(body.result));
+    else if (!hits.length)
+        io.stdout("no hits");
+    else
+        for (const hit of hits)
+            io.stdout(`${hit.sessionId} · ${clip(flat(hit.title))} · ${hit.role} · ${when(hit.at)}: ${flat(hit.snippet)}`);
+    return 0;
+}

package/dist/core/types.js

@@ -1,87 +1,48 @@
-// 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).
+// Normative seam types of the conversation — Channel, AgentSession, its events,
+// the chain — 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).
+/** The chat commands, each with the one line the composer's completion shows:
+ *  a message to the continuous conversation that is exactly `/<word>` or `%<word>` is a
+ *  command, never a message (core/chain.ts). Browser-safe: the composer
+ *  lists this table. */
+export const CHAT_COMMANDS = {
+    status: "what is open — in flight, or waiting on you",
+    new: "start a new session now",
+    stop: "stop the reply in progress",
+    skills: "the skills this session can run, by name",
+};
+export const isChatCommand = (v) => typeof v === "string" && Object.hasOwn(CHAT_COMMANDS, v);
+/** How long the continuous conversation's head may go without a user message
+ *  before the next one starts a new session: the "long" prompt-cache TTL
+ *  interactive sessions request, past which the cache is cold anyway. */
+export const CHAIN_IDLE_MS = 60 * 60_000;
+/** The run ledger's recent window: what `pier task runs` lists and the open items join against. */
+export const LEDGER_WINDOW_MS = 24 * 60 * 60_000;
+/** How large the continuous conversation's head's context may grow before the
+ *  next user message starts a new session: past it, a turn costs more than the
+ *  rotation's one cache write pays back. */
+export const CHAIN_FULL_TOKENS = 60_000;
+/** Declared here, not in tasks/, because `BackgroundRun`, the `task-status` event core carries, names it.
+ *  In order: the Console lists them so, and a worker count reads so. */
+export const TASK_RUN_STATES = ["queued", "running", "succeeded", "failed", "cancelled", "interrupted", "skipped"];
+/** The `state` of a run an open item names that the ledger no longer holds; its `name` is the id. */
+export const NOT_IN_LEDGER = "not in the ledger";
 /** How much of a tool result any surface ever shows. A transcript replay
  *  carries no more than that: a session's tool output is most of its history
  *  payload, and the bytes past this point were downloaded to be sliced off. */
 export const MAX_STEP_OUTPUT = 8_000;
 /** How much of a message becomes a title, wherever one is derived: the listing
- *  reading a transcript (agent/listing.ts), a rename's fallback (agent/pi.ts),
- *  the fill at first prompt and the rename boundary (web/). */
+ *  reading a transcript (agent/listing.ts), the title model's answer
+ *  (agent/pi.ts), the fill at first prompt (web/). */
 export const SESSION_TITLE_MAX = 80;
+/** The one spelling a model is compared and printed by. */
+export const modelKey = (m) => `${m.provider}/${m.id}`;
 /** 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);
-export class PackageError extends Error {
-    reason;
-    constructor(reason, message) {
-        super(message);
-        this.reason = reason;
-    }
-}
-// Wire-protocol names, not SDK types — but they are pi-ai's spellings, and a
-// non-Pi backend is bound to them by this seam.
-const PROVIDER_APIS = [
-    "openai-completions",
-    "openai-responses",
-    "anthropic-messages",
-    "google-generative-ai",
-];
-export const isProviderApi = (value) => typeof value === "string" && PROVIDER_APIS.includes(value);
-/** How far a model's reasoning goes. Every reasoning model offers up to
- *  "high"; the two levels above it exist only for a model whose catalog entry
- *  says so, which is the one thing a Console-defined model could not say. */
-export const MODEL_EFFORTS = ["high", "xhigh", "max"];
-/** The rules of the ProviderSetup seam, in one place: agent/ enforces them on
- *  write and web/ pre-checks them at its HTTP boundary, and neither may import
- *  the other. Throws the message the surface shows. */
-export function validateProviderSetup(input) {
-    if (input.id.length > 100 || !/^[a-z0-9][a-z0-9._-]*$/.test(input.id)) {
-        throw new Error("invalid provider id");
-    }
-    if (input.endpoint) {
-        if (input.endpoint.length > 2048 || input.endpoint !== input.endpoint.trim()) {
-            throw new Error("invalid endpoint");
-        }
-        validateEndpoint(input.endpoint);
-    }
-    if (input.kind === "builtin")
-        return;
-    if (!input.endpoint)
-        throw new Error("custom provider endpoint required");
-    if (input.name && (input.name.length > 200 || input.name !== input.name.trim())) {
-        throw new Error("invalid provider name");
-    }
-    if (!isProviderApi(input.api))
-        throw new Error("unsupported provider API");
-    if (!input.models.length || input.models.length > 100)
-        throw new Error("1-100 models required");
-    const ids = input.models.map((model) => model.id);
-    if (ids.some((id) => !id || id.length > 200 || id !== id.trim()) || new Set(ids).size !== ids.length) {
-        throw new Error("model ids must be non-empty, trimmed and unique");
-    }
-    // An effort ceiling on a model that does not reason would be written into
-    // the catalog and never offered — a setting that lies about itself.
-    if (input.models.some((model) => model.effort !== undefined && !model.reasoning)) {
-        throw new Error("effort requires reasoning");
-    }
-    if (input.models.some((model) => model.effort !== undefined && !MODEL_EFFORTS.includes(model.effort))) {
-        throw new Error("unsupported model effort");
-    }
-}
-export function validateEndpoint(endpoint) {
-    let url;
-    try {
-        url = new URL(endpoint);
-    }
-    catch {
-        throw new Error("endpoint must be an http(s) URL");
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new Error("endpoint must be an http(s) URL");
-    }
-    if (url.username || url.password || url.search || url.hash) {
-        throw new Error("endpoint must not contain credentials, query or fragment");
-    }
-}
+/** The work classes a dispatcher names instead of a model; a tier's menu
+ *  entries are tried in order. Here, not in settings.ts, so the browser shares it. */
+export const MODEL_TIERS = ["hardest", "balanced", "cheap"];
+export const isModelTier = (v) => typeof v === "string" && MODEL_TIERS.includes(v);