@timqi/pier 0.0.1 → 0.0.3

package/dist/agent/models.js

@@ -1,6 +1,18 @@
 // Pure model-list curation, unit-testable without Pi. The raw registry
 // returns every catalog entry per authed provider (legacy generations, dated
 // aliases, -latest aliases); the picker wants the common working set.
+/** Operator-pinned models first, menu order, without inventing entries: a
+ * pin that is not in the list (stale menu, logged-out provider) is skipped
+ * rather than offered as a model that would only fail on selection. */
+export function pinFirst(models, pins) {
+    if (!pins.length)
+        return models;
+    const key = (m) => `${m.provider}/${m.id}`;
+    const listed = new Map(models.map((m) => [key(m), m]));
+    const pinned = pins.map((p) => listed.get(key(p))).filter((m) => !!m);
+    const picked = new Set(pinned.map(key));
+    return [...pinned, ...models.filter((m) => !picked.has(key(m)))];
+}
 export function curateModels(models) {
     const ids = new Set(models.map((m) => `${m.provider}/${m.id}`));
     return models

package/dist/agent/pi.js

@@ -1,19 +1,31 @@
 // The ONLY file allowed to import @earendil-works/pi-*. Implements the
 // AgentFactory/AgentSession seam from src/core/types.ts on the Pi SDK.
 // No Pi type may appear in an exported signature.
-import { createAgentSession, DefaultResourceLoader, defineTool, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, CredentialSynchronizationError, DefaultResourceLoader, defineTool, ModelRuntime, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { logger } from "../log.js";
-import { imageAt, toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
-import { defaultAgentDir } from "./config.js";
-import { curateModels } from "./models.js";
+import { toChatTurns, toSessionEvents, turnMetaAt, } from "./events.js";
+import { defaultAgentDir, PiConfigStore } from "./config.js";
+import { curateModels, pinFirst } from "./models.js";
 const log = logger("agent");
-const toImageContent = (images) => images?.map((i) => ({ type: "image", data: i.data, mimeType: i.mimeType }));
 /** Pi's bash tool has no default timeout, so a hung command holds the turn
  * until someone aborts it — nobody is watching in a scheduled task. Kept below
- * the task-run timeout (tasks/definitions.ts) so a stuck command comes back as
+ * the default task-run timeout so a stuck command comes back as
  * a tool error the agent can retry with an explicit longer timeout, instead of
  * killing the whole run. */
 const BASH_DEFAULT_TIMEOUT_SECONDS = 600;
+/** 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.
+
+# 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: 100 words (or 100 Chinese chars), max 3 bullets; 300 when explicitly asked why or how. Code blocks, diffs and commands don't count.
+- 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\`.
+- 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.`;
+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. */
 const bashTimeoutDefault = (pi) => {
@@ -23,10 +35,24 @@ const bashTimeoutDefault = (pi) => {
         }
     });
 };
-class PiSession {
+export class PiSession {
     pi;
-    constructor(pi) {
+    pinned;
+    constructor(pi, 
+    /** Operator pins, read per call — the menu can change while we run. */
+    pinned = () => []) {
         this.pi = pi;
+        this.pinned = pinned;
+    }
+    /** Pi's dispose unhooks the one listener that persists and emits, so a turn
+     *  started after it runs for real — model call, tools and all — and lands
+     *  nowhere: no transcript entry, no event, and a promise that resolves as if
+     *  it worked. Refusing is what turns that silence into the failure it is;
+     *  callers already report or retry a rejection (§5b). */
+    disposed = false;
+    live() {
+        if (this.disposed)
+            throw new Error(`session ${this.pi.sessionId} is closed`);
     }
     get id() {
         return this.pi.sessionId;
@@ -57,7 +83,7 @@ class PiSession {
     }
     async availableModels() {
         const available = await this.pi.modelRuntime.getAvailable();
-        const curated = curateModels(available.map((m) => ({ provider: m.provider, id: m.id, reasoning: m.reasoning })));
+        const curated = pinFirst(curateModels(available.map((m) => ({ provider: m.provider, id: m.id, reasoning: m.reasoning }))), this.pinned());
         // The session's active model must stay selectable even when curation
         // (or an older catalog) would hide it.
         const current = this.model;
@@ -82,11 +108,9 @@ class PiSession {
         return this.pi.clearQueue();
     }
     async history() {
+        this.live();
         return toChatTurns(this.pi.messages);
     }
-    async image(ordinal) {
-        return imageAt(this.pi.messages, ordinal);
-    }
     async rewindToUserTurn(index) {
         const total = (await this.history()).filter((t) => t.role === "user").length;
         // Anchor at the tail: branch entries keep compacted-away history that
@@ -104,16 +128,22 @@ class PiSession {
         if (cancelled)
             throw new Error("rewind cancelled");
     }
-    prompt(text, images) {
-        return this.pi.prompt(text, { images: toImageContent(images) });
+    // Async, so a refusal is a rejected promise: the seam promises callers they
+    // may only `.catch()` (core/types.ts), and dispatch does exactly that.
+    async prompt(text) {
+        this.live();
+        return this.pi.prompt(text);
     }
-    steer(text, images) {
-        return this.pi.steer(text, toImageContent(images));
+    async steer(text) {
+        this.live();
+        return this.pi.steer(text);
     }
-    followUp(text, images) {
-        return this.pi.followUp(text, toImageContent(images));
+    async followUp(text) {
+        this.live();
+        return this.pi.followUp(text);
     }
-    systemInput(text, origin, mode) {
+    async systemInput(text, origin, mode) {
+        this.live();
         return this.pi.sendCustomMessage({ customType: "pier.system-input", content: text, display: true, details: origin }, { triggerTurn: true, deliverAs: mode === "prompt" ? undefined : mode });
     }
     abort() {
@@ -136,6 +166,7 @@ class PiSession {
         return undefined;
     }
     async dispose() {
+        this.disposed = true;
         this.pi.dispose();
     }
 }
@@ -144,6 +175,8 @@ export class PiAgentFactory {
     instructions;
     skillPaths;
     credentials;
+    providerConfig;
+    pinned;
     constructor(extraTools = [], 
     /** Appended as a virtual context file, so Pi's own prompt stays intact.
      * Read per session, not captured once: it carries settings a user can
@@ -157,23 +190,141 @@ export class PiAgentFactory {
      * Optional only for bare test factories; main.ts always passes one, and
      * every runtime built here reads and writes through it — an OAuth refresh
      * persists to the database, never to a plaintext file. */
-    credentials) {
+    credentials, providerConfig = new PiConfigStore(), 
+    /** Operator-pinned models (Console → Settings → Models), surfaced first in
+     * every picker. A getter for the same reason `instructions` is one. */
+    pinned = () => []) {
         this.extraTools = extraTools;
         this.instructions = instructions;
         this.skillPaths = skillPaths;
         this.credentials = credentials;
+        this.providerConfig = providerConfig;
+        this.pinned = pinned;
     }
     /** One runtime for the whole process; catalogs are global, not per session. */
     catalog;
+    refreshQueue = Promise.resolve();
+    builtinProviderIds;
     /** Structural fit: CredentialStore mirrors pi-ai's interface of the same
      * name, so the SDK accepts it without this file exporting any SDK type. */
     createRuntime() {
         return ModelRuntime.create(this.credentials ? { credentials: this.credentials } : {});
     }
+    authRuntime() {
+        return (this.catalog ??= this.createRuntime());
+    }
+    refreshedRuntime() {
+        const result = this.refreshQueue.then(async () => {
+            const runtime = await this.authRuntime();
+            await runtime.refresh({ allowNetwork: false });
+            return runtime;
+        });
+        this.refreshQueue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    builtinIds() {
+        return (this.builtinProviderIds ??= ModelRuntime.create({
+            ...(this.credentials ? { credentials: this.credentials } : {}),
+            modelsPath: null,
+            refreshOnCreate: false,
+        }).then((runtime) => new Set(runtime.getProviders().map((provider) => provider.id))));
+    }
     async availableModels() {
-        this.catalog ??= this.createRuntime();
-        const available = await (await this.catalog).getAvailable();
-        return curateModels(available.map((m) => ({ provider: m.provider, id: m.id, reasoning: m.reasoning })));
+        const available = await (await this.refreshedRuntime()).getAvailable();
+        return pinFirst(curateModels(available.map((m) => ({ provider: m.provider, id: m.id, reasoning: m.reasoning }))), this.pinned());
+    }
+    async providers() {
+        const [builtinIds, structures] = await Promise.all([
+            this.builtinIds(),
+            this.providerConfig.providerStructures(),
+        ]);
+        // Refresh after queued config writes settle, so runtime and structure never
+        // combine an older catalog with a newer models.json snapshot.
+        const runtime = await this.refreshedRuntime();
+        const stored = new Map((await runtime.listCredentials()).map((c) => [c.providerId, c.type]));
+        return runtime.getProviders().map((provider) => {
+            const status = runtime.getProviderAuthStatus(provider.id);
+            const methods = [];
+            if (provider.auth.apiKey?.login) {
+                methods.push({ type: "api_key", name: provider.auth.apiKey.name });
+            }
+            if (provider.auth.oauth) {
+                methods.push({
+                    type: "oauth",
+                    name: provider.auth.oauth.loginLabel ?? provider.auth.oauth.name,
+                    ...(provider.auth.oauth.isSubscription ? { subscription: true } : {}),
+                });
+            }
+            const credential = stored.get(provider.id);
+            const structure = structures[provider.id];
+            return {
+                id: provider.id,
+                name: structure?.name ?? provider.name,
+                builtin: builtinIds.has(provider.id),
+                methods,
+                configured: status.configured,
+                ...(status.label ? { source: status.label } : status.source ? { source: status.source } : {}),
+                ...(credential ? { stored: credential } : {}),
+                ...(structure?.endpoint ? { endpoint: structure.endpoint } : {}),
+                ...(structure?.api ? { api: structure.api } : {}),
+                ...(structure?.models ? { models: structure.models } : {}),
+            };
+        });
+    }
+    async setup(input) {
+        const builtins = await this.builtinIds();
+        if (input.kind === "builtin" && !builtins.has(input.id)) {
+            throw new Error(`not a built-in provider: ${input.id}`);
+        }
+        if (input.kind === "custom" && builtins.has(input.id)) {
+            throw new Error(`built-in provider must use built-in setup: ${input.id}`);
+        }
+        try {
+            await this.providerConfig.setupProvider(input, async () => {
+                const runtime = await this.refreshedRuntime();
+                const error = runtime.getError();
+                if (error)
+                    throw new Error(error);
+                if (!runtime.getProvider(input.id))
+                    throw new Error(`provider did not load: ${input.id}`);
+            });
+        }
+        catch (err) {
+            try {
+                await this.refreshedRuntime();
+            }
+            catch (refreshErr) {
+                log.warn("provider runtime refresh failed after config rollback", refreshErr);
+            }
+            throw err;
+        }
+    }
+    async login(providerId, type, interaction) {
+        const store = this.credentials;
+        const previous = await store?.read(providerId);
+        const restore = async (committed) => {
+            if (store && await store.replaceIfCurrent(providerId, committed, previous)) {
+                await this.refreshedRuntime();
+            }
+        };
+        try {
+            const committed = await (await this.authRuntime()).login(providerId, type, interaction);
+            return () => restore(committed);
+        }
+        catch (err) {
+            if (err instanceof CredentialSynchronizationError && err.credential) {
+                try {
+                    await restore(err.credential);
+                }
+                catch (rollback) {
+                    throw new AggregateError([err, rollback], `failed to restore credential for ${providerId}`);
+                }
+            }
+            throw err;
+        }
+    }
+    async logout(providerId) {
+        await (await this.authRuntime()).logout(providerId, { signal: AbortSignal.timeout(15_000) });
     }
     /**
      * Pi discovers AGENTS.md itself; we append one more, in memory, telling the
@@ -184,6 +335,9 @@ export class PiAgentFactory {
         const loader = new DefaultResourceLoader({
             cwd,
             agentDir: defaultAgentDir(), // same discovery Pi would have done itself
+            // SYSTEM.md remains user-owned: append it after Pier's replacement for
+            // Pi's generic default, preserving the user's later instruction layer.
+            systemPromptOverride: pierSystemPrompt,
             additionalSkillPaths: this.skillPaths,
             extensionFactories: [{ name: "pier-bash-timeout", factory: bashTimeoutDefault, hidden: true }],
             agentsFilesOverride: (current) => {
@@ -230,11 +384,12 @@ export class PiAgentFactory {
                 }
             },
         }));
-        if (opts.name)
-            sessionManager.appendSessionInfo(opts.name);
         // Locked Secrets is a refusal with a reason, here — not "provider is not
-        // configured" three calls later, and never a fall back to auth.json.
+        // configured" three calls later, and never a fall back to auth.json. Before
+        // appendSessionInfo, so the refused open writes nothing to disk.
         this.credentials?.assertUnlocked();
+        if (opts.name)
+            sessionManager.appendSessionInfo(opts.name);
         const tools = opts.capabilities === "read"
             ? ["read", "grep", "find", "ls", ...this.extraTools.map((tool) => tool.name)]
             : undefined;
@@ -247,7 +402,7 @@ export class PiAgentFactory {
             resourceLoader: await this.resourceLoader(cwd),
         });
         live = created.session;
-        const session = new PiSession(live);
+        const session = new PiSession(live, this.pinned);
         if (opts.model)
             await session.setModel(opts.model);
         if (opts.thinking)

package/dist/boards/boards.js

@@ -4,8 +4,8 @@
 //
 // Only <board>/site is reachable over HTTP: sources, README and the manifest
 // itself stay off the wire, so a public board leaks nothing about how it was
-// made. `public` is a data state, not yet a security boundary — nothing in
-// Pier authenticates today (docs/architecture.md, Open Questions).
+// made. `/boards/*` is authenticated; `/p/*` additionally requires the
+// manifest's `public` flag and runs as sandboxed active content.
 import { readdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
 import { extname, join, resolve, sep } from "node:path";
 import { logger } from "../log.js";
@@ -33,11 +33,16 @@ const TYPES = {
     ".txt": "text/plain; charset=utf-8",
     ".csv": "text/plain; charset=utf-8",
 };
-// A published board must not be able to phone home: no third-party fetches, no
-// framing, no beacons. Inline style/script stay allowed — a single-file board
-// is the normal shape.
+// Board HTML is active content on the workbench origin. Scripts stay available
+// for self-contained pages, but the response sandbox removes forms, frames,
+// popups and network access. Public pages omit same-origin too, so their scripts
+// receive an opaque origin and cannot inherit an operator's authority.
 const CSP = "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; " +
-    "script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-ancestors 'none'";
+    "script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-src 'none'; " +
+    "worker-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; " +
+    "frame-ancestors 'none'";
+const PRIVATE_CSP = `sandbox allow-scripts allow-same-origin; ${CSP}`;
+const PUBLIC_CSP = `sandbox allow-scripts; ${CSP}`;
 /** Malformed boards are reported once, not on every scan. */
 const warned = new Set();
 /** The one choke point where a slug becomes a path, so the slug is validated
@@ -148,12 +153,17 @@ async function serveFile(c, dir, slug, rest, publicOnly) {
     const headers = {
         "content-type": type,
         "x-content-type-options": "nosniff",
-        // HTML is the page an agent keeps rewriting; assets are fingerprinted or
-        // rare enough that five minutes is safe.
-        "cache-control": type.startsWith("text/html") ? "no-store" : "max-age=300",
+        // Every public request rechecks the manifest, so unpublishing cannot leave
+        // a shared-cache copy reachable. Private assets may stay in one browser.
+        "cache-control": publicOnly || type.startsWith("text/html")
+            ? "no-store"
+            : "private, max-age=300",
+        "content-security-policy": publicOnly ? PUBLIC_CSP : PRIVATE_CSP,
     };
+    // Public sandboxed pages have an opaque origin. Fonts and module scripts need
+    // CORS even when their URLs are under the same published board.
     if (publicOnly)
-        headers["content-security-policy"] = CSP;
+        headers["access-control-allow-origin"] = "*";
     return c.body(await readFile(file), 200, headers);
 }
 export function registerBoardRoutes(app, dir = defaultBoardsDir()) {

package/dist/channels/routes.js

@@ -1,4 +1,4 @@
-// Console → Channels HTTP surface. One document per platform: credentials,
+// Settings → Channels HTTP surface. One document per platform: credentials,
 // global defaults, bound users and discovered chats travel together, so the
 // UI never has to stitch two half-configs.
 import { isThinkingLevel } from "../core/types.js";

package/dist/channels/runtime.js

@@ -12,22 +12,39 @@ const ADAPTERS = [
 // Lifecycle news, which is not what the injected sink below is for: that one
 // is a warning sink the adapters share, and "slack started" is not a warning.
 const log = logger("channels");
+// The parameter below shadows `log` inside its own default expression.
+const warn = (m) => log.warn(m);
 export class ChannelRuntime {
     store;
     router;
     control;
     log;
     live = new Map();
-    constructor(store, router, control, log = (m) => logger("channels").warn(m)) {
+    reloading = Promise.resolve();
+    stopped = false;
+    constructor(store, router, control, log = warn) {
         this.store = store;
         this.router = router;
         this.control = control;
         this.log = log;
     }
-    /** (Re)start every platform whose config says it should run. Idempotent. */
-    async reload() {
-        for (const adapter of ADAPTERS)
-            await this.restart(adapter);
+    /** (Re)start every platform whose config says it should run. Idempotent.
+     *  Serialized — two concurrent Console saves raced into duplicate live
+     *  adapters; platforms restart in parallel so a hung start on one cannot
+     *  stall the other, and a failure is logged, never swallowed. */
+    reload() {
+        const run = this.reloading.catch(() => { }).then(async () => {
+            if (this.stopped)
+                return;
+            const results = await Promise.allSettled(ADAPTERS.map((a) => this.restart(a)));
+            results.forEach((result, i) => {
+                if (result.status === "rejected") {
+                    this.log(`${ADAPTERS[i].platform} reload failed: ${String(result.reason)}`);
+                }
+            });
+        });
+        this.reloading = run;
+        return run;
     }
     async restart(adapter) {
         const { platform, needsAppToken, build } = adapter;
@@ -67,7 +84,21 @@ export class ChannelRuntime {
         this.live.set(platform, channel);
         log.info(`${platform} started`);
     }
+    /** Post a note into a conversation on a live adapter. Boot-time restart-note
+     *  delivery (src/drain.ts) has no session to report through; false means the
+     *  platform is not running, so the caller can say so instead of dropping it. */
+    async notify(platform, conversationId, text) {
+        const channel = this.live.get(platform);
+        if (!channel)
+            return false;
+        await channel.notify(conversationId, { text, origin: { kind: "error" } });
+        return true;
+    }
     async stop() {
+        // Join the reload queue first: an in-flight restart could otherwise
+        // register an adapter after `live` was cleared — running, unstoppable.
+        this.stopped = true;
+        await this.reloading.catch(() => { });
         for (const channel of this.live.values()) {
             await channel.stop().catch((err) => this.log(`${channel.id} did not stop cleanly: ${String(err)}`));
         }

package/dist/channels/slack-api.js

@@ -288,9 +288,7 @@ export class SlackApi {
         });
         if (!res.ok)
             throw new Error(`slack file download: ${res.status}`);
-        const mimeType = res.headers.get("content-type")?.split(";")[0] ?? file.mimetype ?? "image/png";
-        if (!mimeType.startsWith("image/"))
-            throw new Error(`slack file is ${mimeType}, not an image`);
-        return { data: Buffer.from(await res.arrayBuffer()).toString("base64"), mimeType };
+        const mimeType = res.headers.get("content-type")?.split(";")[0] ?? file.mimetype ?? "application/octet-stream";
+        return { bytes: new Uint8Array(await res.arrayBuffer()), mimeType };
     }
 }

package/dist/channels/slack-outbound.js

@@ -4,7 +4,7 @@
 // inbound traffic: which renderer to use, how to chunk against that renderer's
 // limit, and what an empty turn still has to say. The adapter keeps the 👀
 // receipts, because those are about the turn ending, not about what was said.
-import { formatTurnMeta, originLabel } from "../core/reply.js";
+import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
 import { isBlockRejection } from "./slack-api.js";
 import { actions, chunk, context, escapeMrkdwn, markdown, MARKDOWN_MAX, MRKDWN_MAX, sections, toMrkdwn, } from "./slack-render.js";
 /**
@@ -38,13 +38,9 @@ export class SlackOutbound {
         // indistinguishable from a crash, a dropped connection or a bug, and the
         // person waiting has no way to tell. A muted one-liner is the cheapest
         // honest answer.
-        // Options count as a reply: the buttons are the answer, so a turn that is
-        // only its options is not "nothing".
-        const quiet = text || row
-            ? ""
-            : reply.silence
-                ? `_stayed silent — ${escapeMrkdwn(reply.silence)}_`
-                : "_no reply_";
+        const quiet = isSilentReply(reply)
+            ? `_${quietLabel(reply.silence && escapeMrkdwn(reply.silence))}_`
+            : "";
         if (!(text || row || footer || quiet))
             return;
         const parts = text ? chunk(text, this.budget()) : [""];

package/dist/channels/slack-render.js

@@ -20,9 +20,6 @@ export const MARKDOWN_MAX = 11_000;
 export const MRKDWN_MAX = 2800;
 // Slack truncates a button label past this, mid-word.
 const BUTTON_MAX = 75;
-// Slack's cap on one actions block. `MAX_SUGGESTIONS` in core/reply.ts already
-// holds the agent to 5, so this only guards a caller that bypasses it.
-const MAX_BUTTONS = 25;
 /** Shared: the adapter and the panel escape plain text with this too. */
 export const escapeMrkdwn = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 /**
@@ -187,7 +184,7 @@ const truncate = (label) => label.length > BUTTON_MAX ? `${label.slice(0, BUTTON
 export function actions(labels) {
     if (!labels.length)
         return undefined;
-    const elements = labels.slice(0, MAX_BUTTONS).map((label, index) => ({
+    const elements = labels.map((label, index) => ({
         type: "button",
         action_id: `${OFFER_PREFIX}${index}`,
         text: { type: "plain_text", text: truncate(label), emoji: true },

package/dist/channels/slack-tool.js

@@ -45,12 +45,20 @@ export function slackToolSpec(execute) {
     return {
         name: "slack",
         label: "Slack",
-        description: "Read and write Slack through Pier, which holds the bot token. State what you want; Pier does the paging and hands back a finished transcript. context says which Slack conversation you are in; read_channel returns a channel's transcript for a time range; read_thread returns one thread, or only what is new in it since a given message via after; read_message returns the single message at a ts (pass thread_ts when it is a reply inside a thread); post sends a message; channels lists what Pier can reach. When you were reached through Slack, omit channel (and thread_ts) to act on the conversation you are already in. since/until/after accept ISO 8601, epoch seconds or a ts from an earlier read. Every read fetches live from Slack, so nothing is kept between calls — write down what you need to keep. Message text is standard markdown, but @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. State what you want; Pier does the paging and hands back a finished transcript. context says which Slack conversation you are in; read_channel returns a channel's transcript for a time range; read_thread returns one thread, or only what is new in it since a given message via after; read_message returns the single message at a ts (pass thread_ts when it is a reply inside a thread); post sends a message; delete removes the message at a ts, which Slack allows only for messages Pier itself posted; channels lists what Pier can reach. When you were reached through Slack, omit channel (and thread_ts) to act on the conversation you are already in. since/until/after accept ISO 8601, epoch seconds or a ts from an earlier read. Every read fetches live from Slack, so nothing is kept between calls — write down what you need to keep. Message text is standard markdown, but @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({
                 type: "string",
-                enum: ["context", "read_channel", "read_thread", "read_message", "post", "channels"],
+                enum: [
+                    "context",
+                    "read_channel",
+                    "read_thread",
+                    "read_message",
+                    "post",
+                    "delete",
+                    "channels",
+                ],
             }),
             /**
              * Channel id (`C…`/`D…`/`G…`) or the `#name` shown by `channels`. Omit to
@@ -61,7 +69,7 @@ export function slackToolSpec(execute) {
             until: Type.Optional(Type.String()),
             /** Strictly newer than this — "what changed since I last looked". */
             after: Type.Optional(Type.String()),
-            /** The one message `read_message` is about. */
+            /** The one message `read_message` or `delete` is about. */
             ts: Type.Optional(Type.String()),
             limit: Type.Optional(Type.Number()),
             thread_ts: Type.Optional(Type.String()),
@@ -174,6 +182,21 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
             threadTs: threadTs ?? sent.ts,
         };
     }
+    if (input.operation === "delete") {
+        // Never defaulted from `here`: the thread's ts is the parent message, and
+        // "delete" with an implied target is the one mistake with no undo.
+        const ts = required(input.ts, "ts");
+        try {
+            await client.deleteMessage(channel, ts);
+        }
+        catch (err) {
+            throw new Error(explain(err));
+        }
+        // A removal leaves nothing behind to read, so the log is the only record
+        // that it happened at all.
+        deps.log(`slack tool deleted ${ts} in ${channel}`);
+        return { channel, ts, deleted: true };
+    }
     throw new Error(`unknown slack operation: ${String(input.operation)}`);
 }
 /** Accept a `#name` or a bare name as well as an id — models prefer names. */
@@ -285,6 +308,8 @@ function explain(err) {
         missing_scope: "Pier's Slack app lacks the scope for this read; the operator must reinstall it",
         ratelimited: "Slack rate-limited this read; wait a minute or ask for a narrower range",
         thread_not_found: "no thread with that ts in this channel",
+        cant_delete_message: "Slack only lets Pier delete what its own bot posted; a person's message has to be deleted by them",
+        message_not_found: "no message with that ts in this channel — a ts only means anything in the conversation it came from",
     }[code] ?? String(err);
 }
 /** Strictly newer, so `after: <last ts I saw>` never repeats that message. */