@timqi/pier 0.0.17 → 0.0.20

package/dist/channels/dedup.js

@@ -4,6 +4,9 @@
 // the second copy had already appeared and the map has an invariant that is
 // easy to lose on a rewrite: it is fed by every message in every chat the bot
 // is in, so it must be bounded and time-limited, never grow-only.
+/** Fraction of `max` a full map is cut back to, so the eviction walk is paid
+ *  once per that many messages instead of once per message. */
+const KEEP = 0.9;
 export class Dedup {
     log;
     ttlMs;
@@ -28,8 +31,13 @@ export class Dedup {
             // is a forgotten id under extreme load (a redelivery slips through,
             // which downstream handling tolerates); unbounded memory is worse.
             // Map iterates in insertion order, so the front is the oldest.
+            //
+            // Evicting down to `KEEP` rather than to exactly `max` is what makes
+            // the walk amortized: at the bound, freeing one slot per message meant
+            // re-walking the whole map on every message from then on.
+            const keep = Math.floor(this.max * KEEP);
             for (const [id] of this.seen) {
-                if (this.seen.size < this.max)
+                if (this.seen.size <= keep)
                     break;
                 this.seen.delete(id);
             }

package/dist/channels/lark.js

@@ -44,7 +44,6 @@ const DRAIN_TIMEOUT_MS = 5000;
 /** How long a delivered event id is remembered, against redelivery. */
 const DEDUP_TTL_MS = 5 * 60_000;
 const DEDUP_MAX = 2000;
-const SWEEP_EVERY_MS = 60_000;
 /**
  * A Lark conversation is always `<chatId>/<rootMessageId>` — the thread is
  * the session. This pair is the only definition of the format; control.ts
@@ -87,7 +86,6 @@ export class LarkChannel {
     out;
     socket;
     running = false;
-    sweptAt = 0;
     constructor(deps) {
         this.deps = deps;
         const config = deps.store.get("lark");
@@ -143,10 +141,8 @@ export class LarkChannel {
     onEvent(event, onMessage) {
         if (!this.running)
             return;
-        if (Date.now() - this.sweptAt > SWEEP_EVERY_MS) {
-            this.sweptAt = Date.now();
-            void this.receipts.sweep();
-        }
+        // Asked on every event, throttled inside receipts.ts.
+        void this.receipts.sweep();
         // Our own echo or another app's message.
         if (event.senderType === "app")
             return;

package/dist/channels/receipts.js

@@ -8,6 +8,14 @@
 // it finds at startup (nothing in memory can be its own yet), and sweeps its
 // own stragglers on a timer.
 import { pierDb } from "../db.js";
+/**
+ * How often the straggler sweep may really run. Adapters ask on the inbound
+ * path — per envelope, or per `getUpdates` round trip — and the books only
+ * change on the scale of `staleMs`, so a busy chat would otherwise run this
+ * query hundreds of times a minute. Throttled here rather than in each
+ * adapter, which is where the same timestamp had been copied twice already.
+ */
+const SWEEP_EVERY_MS = 60_000;
 const toReceipt = (row) => ({
     conversationId: row.conversation_id,
     chatId: row.chat_id,
@@ -68,6 +76,7 @@ export class Receipts {
     staleMs;
     /** In-flight `setReaction` per marked message. Only this process's own. */
     applying = new Map();
+    sweptAt = 0;
     constructor(api, ledger, log, emoji, 
     /** After this, a receipt's turn is assumed never to settle. */
     staleMs) {
@@ -106,14 +115,20 @@ export class Receipts {
      * ours yet — and past `staleMs` a receipt's turn is never going to settle.
      */
     sweep(all = false) {
+        const now = Date.now();
+        // `all` is the startup sweep: it takes everything, so it is never skipped.
+        if (!all && now - this.sweptAt < SWEEP_EVERY_MS)
+            return Promise.resolve();
+        this.sweptAt = now;
         return this.clear(this.ledger.takeStale(all ? 0 : this.staleMs));
     }
     async clear(receipts) {
-        for (const { chatId, messageId } of receipts) {
-            const key = `${chatId}:${messageId}`;
-            await this.applying.get(key);
-            this.applying.delete(key);
-            await this.api.setReaction(chatId, messageId, null).catch(() => { });
-        }
+        // Wait together, then launch clears in booking order: if one apply is slow,
+        // it must not let a later receipt clear first.
+        await Promise.all(receipts.map(({ chatId, messageId }) => this.applying.get(`${chatId}:${messageId}`)));
+        for (const { chatId, messageId } of receipts)
+            this.applying.delete(`${chatId}:${messageId}`);
+        await Promise.all(receipts.map(({ chatId, messageId }) => this.api.setReaction(chatId, messageId, null)
+            .catch((err) => this.log(`reaction clear failed: ${String(err)}`))));
     }
 }

package/dist/channels/slack-tool.js

@@ -27,19 +27,25 @@ const tsToNumber = (ts) => Number(ts);
 const tsToIso = (ts) => new Date(Math.floor(tsToNumber(ts) * 1000)).toISOString();
 /** Minute precision in the transcript: the exact time is in the `ts` beside it. */
 const tsToMinute = (ts) => `${tsToIso(ts).slice(0, 16)}Z`;
+/** Epoch seconds at the year 2100: past this, the caller meant milliseconds. */
+const MAX_SECONDS = 4_102_444_800;
 /** Accepts an ISO date, an epoch-seconds number, or a raw Slack ts. */
 export function toTs(value) {
     if (value === undefined || value === "")
         return undefined;
-    if (typeof value === "number")
-        return String(value);
-    const trimmed = value.trim();
-    if (/^\d+(\.\d+)?$/.test(trimmed))
-        return trimmed;
-    const parsed = Date.parse(trimmed);
-    if (Number.isNaN(parsed))
+    const raw = typeof value === "number" ? String(value) : value.trim();
+    // A ts is passed through untouched — it is an id, not a number to reformat.
+    const numeric = /^\d+(\.\d+)?$/.test(raw);
+    const seconds = numeric ? Number(raw) : Date.parse(raw) / 1000;
+    if (Number.isNaN(seconds))
         throw new Error(`not a time: ${value}`);
-    return String(parsed / 1000);
+    // Milliseconds are the mistake worth naming: Slack takes the window without
+    // complaint, finds nothing that far in the future, and answers with an empty
+    // read that is indistinguishable from a channel where nobody spoke.
+    if (seconds > MAX_SECONDS) {
+        throw new Error(`${value} is past the year 2100 — Slack times are epoch seconds, not milliseconds`);
+    }
+    return numeric ? raw : String(seconds);
 }
 /**
  * Whether a session opened now is given the tool at all: the same two switches
@@ -91,6 +97,8 @@ export function slackToolSpec(execute, available) {
             text: Type.Optional(Type.String()),
         }),
         available,
+        // Stands down with the tool: without Slack, its manual is a route to nowhere.
+        skill: "pier-slack",
         execute,
     };
 }
@@ -165,10 +173,12 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
     // own bounds are inclusive-ish, so the boundary message is dropped here
     // rather than trusted to the API.
     const after = toTs(input.after);
+    // Both reads take it, so it is read once: a cap that worked on a channel and
+    // was ignored on a thread would be the more expensive kind of surprise.
+    const limit = Math.min(Number(input.limit) || MAX_MESSAGES, MAX_MESSAGES);
     if (input.operation === "read_channel") {
         const since = after ?? toTs(input.since);
         const until = toTs(input.until);
-        const limit = Math.min(Number(input.limit) || MAX_MESSAGES, MAX_MESSAGES);
         return readChannel(deps, client, channel, since, until, after, limit);
     }
     if (input.operation === "read_thread") {
@@ -177,7 +187,7 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
             : at?.threadTs;
         if (!threadTs)
             throw new Error("thread_ts is required outside a Slack thread");
-        return readThread(deps, client, channel, threadTs, after);
+        return readThread(deps, client, channel, threadTs, after, limit);
     }
     if (input.operation === "read_message") {
         const asked = typeof input.thread_ts === "string" ? input.thread_ts.trim() : "";
@@ -204,6 +214,7 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
             at: sent.ts ? tsToIso(sent.ts) : null,
             // Returned so a follow-up can reply under what was just posted.
             threadTs: threadTs ?? sent.ts,
+            ...inertMention(text),
         };
     }
     if (input.operation === "edit") {
@@ -211,14 +222,23 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
         // and Slack keeps no visible record of what it said before.
         const ts = required(input.ts, "ts");
         const text = messageText(input.text);
+        // Defaulted from `here` as `post` is: a correction is nearly always to a
+        // reply the agent made in this thread, and `conversations.history` cannot
+        // see inside a thread — without this the read below always comes up empty.
+        const asked = typeof input.thread_ts === "string" ? input.thread_ts.trim() : "";
+        const inThread = asked || (channel === at?.channel ? at?.threadTs : undefined);
+        // Read before the write, because after it the old wording exists nowhere:
+        // Slack keeps no version, so this log is the only record of what was
+        // replaced. Best-effort — a failed read must not block the correction.
+        const was = await previousText(client, channel, ts, inThread);
         try {
             await client.updateMessage({ channel, ts, text, blocks: [{ type: "markdown", text }] });
         }
         catch (err) {
             throw new Error(explain(err));
         }
-        deps.log(`slack tool edited ${ts} in ${channel}`);
-        return { channel, ts, edited: true };
+        deps.log(`slack tool edited ${ts} in ${channel}; was: ${was ?? "(not captured)"}`);
+        return { channel, ts, edited: true, ...inertMention(text) };
     }
     if (input.operation === "delete") {
         // Never defaulted from `here`: the thread's ts is the parent message, and
@@ -237,6 +257,50 @@ export async function handleSlackTool(deps, raw, callerSessionId = "") {
     }
     throw new Error(`unknown slack operation: ${String(input.operation)}`);
 }
+/**
+ * The one message at `ts`. A `ts` is unique only within its conversation, and
+ * `conversations.history` never returns what was posted inside a thread — so a
+ * reply has to be asked for through its thread, and only the caller knows.
+ */
+async function oneMessage(client, channel, ts, threadTs) {
+    const page = threadTs
+        ? await client.replies(channel, threadTs, { oldest: ts, limit: 20 })
+        : await client.history(channel, { oldest: ts, latest: ts, limit: 1 });
+    return page.messages.find((msg) => msg.ts === ts);
+}
+/** One line of what a message said, for the log an edit leaves behind. */
+async function previousText(client, channel, ts, threadTs) {
+    try {
+        const text = (await oneMessage(client, channel, ts, threadTs))?.text;
+        return text === undefined ? undefined : text.slice(0, 200).replace(/\s+/g, " ");
+    }
+    catch {
+        // Not swallowed: the caller logs that the old wording was not captured,
+        // which is the fact that matters. Refusing the edit over it would be worse.
+        return undefined;
+    }
+}
+/**
+ * A plain `@alice` is the one Slack mistake that looks like it worked: the
+ * message goes up, renders as text, and notifies nobody. Reported after the
+ * fact rather than refused — a name in prose is legitimate, an unping is not
+ * worth losing the message over.
+ */
+function inertMention(text) {
+    const prose = text
+        .replace(/```[\s\S]*?```|`[^`]*`/g, "") // code says @ and # for other reasons
+        .replace(/<[^>]*>/g, ""); // already Slack syntax
+    const hit = /(?:^|\s)([@#][A-Za-z][\w.-]*)/.exec(prose)?.[1];
+    if (!hit)
+        return {};
+    const as = hit.startsWith("@")
+        ? /^@(here|channel|everyone)$/.test(hit) ? `<!${hit.slice(1)}>` : "<@U…>"
+        : "<#C…>";
+    return {
+        hint: `${hit} is plain text and notified nobody — Slack needs ${as}. ` +
+            `Edit this ts if it was meant to reach someone.`,
+    };
+}
 /** Accept a `#name` or a bare name as well as an id — models prefer names. */
 function resolveChannel(deps, given) {
     if (/^[CDG][A-Z0-9]+$/.test(given))
@@ -265,30 +329,27 @@ async function readChannel(deps, client, channel, since, until, after, limit) {
         messages: await lines(deps, client, window),
     };
 }
-async function readThread(deps, client, channel, threadTs, after) {
+async function readThread(deps, client, channel, threadTs, after, limit) {
     const fetched = await fetchPages(deps, (cursor) => client.replies(channel, threadTs, { oldest: after, cursor }), `thread ${threadTs} in ${channel}`);
-    const messages = newerThan(transcript(fetched.messages), after);
+    const all = newerThan(transcript(fetched.messages), after);
+    // Oldest first, as in a channel read: a thread cut at its newest end still
+    // reads as a thread, and the cut has to be said either way — a long thread
+    // that answers as if it were complete is the read nobody double-checks.
+    const messages = all.slice(0, limit);
     return {
         channel,
         // Hoisted: every line in a thread carries the same one.
         threadTs,
         count: messages.length,
+        ...(fetched.truncated || all.length > messages.length ? { truncated: true } : {}),
         ...(fetched.incomplete ? { incomplete: fetched.incomplete } : {}),
         format: LINE_FORMAT,
         messages: await lines(deps, client, messages),
     };
 }
-/**
- * One message, because that is sometimes the whole question. A `ts` is unique
- * only within its conversation, and `conversations.history` never returns what
- * was posted inside a thread — so a reply has to be asked for through its
- * thread, and saying which one is the caller's job.
- */
+/** One message, because that is sometimes the whole question. */
 async function readMessage(deps, client, channel, ts, threadTs) {
-    const page = threadTs
-        ? await client.replies(channel, threadTs, { oldest: ts, limit: 20 })
-        : await client.history(channel, { oldest: ts, latest: ts, limit: 1 });
-    const found = page.messages.find((msg) => msg.ts === ts);
+    const found = await oneMessage(client, channel, ts, threadTs);
     if (!found) {
         throw new Error(threadTs
             ? `no message ${ts} in thread ${threadTs}`
@@ -342,7 +403,7 @@ function explain(err) {
     const code = /slack [\w.]+: (\w+)/.exec(String(err))?.[1] ?? "";
     return {
         channel_not_found: "no such channel, or Pier's bot cannot see it — check the channels operation",
-        not_in_channel: "Pier's bot is not in that channel; someone has to invite it before it can read",
+        not_in_channel: "Pier's bot is not in that channel; someone has to run `/invite @Pier` there before it can read",
         missing_scope: "Pier's Slack app lacks the scope for this call; the operator must reinstall it",
         ratelimited: "Slack rate-limited Pier; wait a minute, and narrow the range if this was a read",
         thread_not_found: "no thread with that ts in this channel",

package/dist/channels/slack.js

@@ -52,8 +52,6 @@ const DRAIN_TIMEOUT_MS = 5000;
  */
 const DEDUP_TTL_MS = 5 * 60_000;
 const DEDUP_MAX = 2000;
-/** How often the straggler sweep may run; see onEnvelope. */
-const SWEEP_EVERY_MS = 60_000;
 /**
  * Commands that may appear as a bare word, and exactly how many arguments each
  * takes. Both halves are load-bearing, because Slack gives us no leading `/` to
@@ -132,7 +130,6 @@ export class SlackChannel {
     out;
     socket;
     running = false;
-    sweptAt = 0;
     constructor(deps) {
         this.deps = deps;
         const config = deps.store.get("slack");
@@ -195,13 +192,8 @@ export class SlackChannel {
     onEnvelope(env, onMessage) {
         if (!this.running)
             return;
-        // Envelopes arrive pushed, not in polled batches, so the sweep is timed
-        // rather than per-envelope: a busy channel would otherwise run this query
-        // hundreds of times a minute for something that changes every 30.
-        if (Date.now() - this.sweptAt > SWEEP_EVERY_MS) {
-            this.sweptAt = Date.now();
-            void this.receipts.sweep();
-        }
+        // Asked on every envelope, throttled inside receipts.ts.
+        void this.receipts.sweep();
         if (env.type === "events_api") {
             const payload = env.payload;
             const event = payload?.event;

package/dist/channels/telegram.js

@@ -124,6 +124,7 @@ export class TelegramChannel {
                 const updates = await this.api.getUpdates(this.offset, POLL_SECONDS);
                 if (!this.running)
                     return;
+                // Asked on every round trip, throttled inside receipts.ts.
                 void this.receipts.sweep();
                 if (!updates.length && Date.now() - startedAt < 1000) {
                     await new Promise((r) => setTimeout(r, 1000));

package/dist/config-sync-fetch.js

@@ -0,0 +1,97 @@
+// Fetch one configuration document without turning an operator URL into an
+// arbitrary network proxy. DNS is checked once and the TLS request is pinned
+// to that address; redirects never inherit the token or bypass the check.
+import { lookup } from "node:dns/promises";
+import { request } from "node:https";
+import { BlockList, isIP } from "node:net";
+import { checkServerIdentity } from "node:tls";
+export const CONFIG_SYNC_BYTES = 1024 * 1024;
+const blockedV4 = new BlockList();
+const blockedV6 = new BlockList();
+for (const [address, prefix] of [
+    ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+    ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16],
+    ["198.18.0.0", 15], ["224.0.0.0", 4], ["240.0.0.0", 4],
+])
+    blockedV4.addSubnet(address, prefix, "ipv4");
+for (const [address, prefix] of [
+    ["::", 96], ["::ffff:0:0", 96], ["64:ff9b::", 96], ["64:ff9b:1::", 48],
+    ["100::", 64], ["2001::", 32], ["2002::", 16], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8],
+])
+    blockedV6.addSubnet(address, prefix, "ipv6");
+const globalV6 = new BlockList();
+globalV6.addSubnet("2000::", 3, "ipv6");
+export function configSourceUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new Error("A valid HTTPS source URL is required");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.hash || raw.length > 4096) {
+        throw new Error("Source must be HTTPS, without credentials or a fragment");
+    }
+    return url;
+}
+export function publicConfigAddress(address) {
+    const family = isIP(address);
+    return family !== 0 && (family !== 6 || globalV6.check(address, "ipv6")) &&
+        !(family === 4 ? blockedV4 : blockedV6).check(address, family === 4 ? "ipv4" : "ipv6");
+}
+export async function downloadConfig(raw, etag, signal) {
+    const url = configSourceUrl(raw);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    const addresses = isIP(hostname)
+        ? [{ address: hostname, family: isIP(hostname) }]
+        : await Promise.race([
+            lookup(hostname, { all: true }),
+            new Promise((_, reject) => {
+                if (signal.aborted)
+                    reject(new Error("Configuration download aborted"));
+                else
+                    signal.addEventListener("abort", () => reject(new Error("Configuration download aborted")), { once: true });
+            }),
+        ]);
+    if (!addresses.length || addresses.some(({ address }) => !publicConfigAddress(address))) {
+        throw new Error("Source must resolve to a public address");
+    }
+    signal.throwIfAborted();
+    const address = addresses[0];
+    return new Promise((resolve, reject) => {
+        const req = request({
+            hostname: address.address, family: address.family, port: url.port || 443,
+            servername: isIP(hostname) ? undefined : hostname,
+            checkServerIdentity: (_host, cert) => checkServerIdentity(hostname, cert),
+            path: `${url.pathname}${url.search}`, method: "GET", signal,
+            headers: { host: url.host, accept: "application/json", ...(etag ? { "if-none-match": etag } : {}) },
+        }, (res) => {
+            const status = res.statusCode;
+            if (status !== 200 && status !== 304) {
+                res.destroy();
+                reject(new Error(status === 404 || status === 410
+                    ? "Source link was revoked or does not exist"
+                    : `Source returned HTTP ${String(status)}`));
+                return;
+            }
+            if (status === 200 && !/^application\/json(?:\s*;|$)/i.test(res.headers["content-type"] ?? "")) {
+                res.destroy();
+                reject(new Error("Source did not return JSON"));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            res.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > CONFIG_SYNC_BYTES)
+                    res.destroy(new Error("Configuration exceeds 1 MiB"));
+                else
+                    chunks.push(chunk);
+            });
+            res.on("error", () => reject(new Error(size > CONFIG_SYNC_BYTES ? "Configuration exceeds 1 MiB" : "Configuration download failed")));
+            res.on("end", () => resolve({ status, etag: res.headers.etag ?? null, body: Buffer.concat(chunks).toString("utf8") }));
+        });
+        req.on("error", () => reject(new Error(signal.aborted ? "Configuration download timed out or was cancelled" : "Could not connect to source")));
+        req.end();
+    });
+}

package/dist/config-sync-task.js

@@ -0,0 +1,59 @@
+// The single hourly task owned by the configuration subscription. The task
+// history records manual and scheduled checks; its enabled bit follows the
+// subscription, never a second independently editable switch.
+const OWNER = "config-sync";
+export function configSyncTask(tasks, sync) {
+    let taskId = null;
+    let reconciliation = Promise.resolve();
+    const reconcile = () => {
+        const next = reconciliation.then(async () => {
+            const owned = tasks.list().filter((task) => task.creator === OWNER && !task.archived);
+            for (const extra of owned.slice(1))
+                tasks.archive(extra.id, OWNER);
+            const status = sync.status();
+            if (!owned.length && !status.sourceUrl)
+                return;
+            const draft = {
+                name: "Configuration sync",
+                description: "Checks the configuration source from Settings > Agent every hour.",
+                enabled: status.enabled,
+                trigger: { type: "cron", expression: "23 * * * *", timezone: "UTC" },
+                action: { type: "system", name: OWNER },
+                callback: { type: "none" },
+                timeoutSeconds: 30,
+            };
+            const task = owned[0];
+            if (!task)
+                taskId = (await tasks.create(draft, OWNER)).id;
+            else {
+                taskId = task.id;
+                if (Object.entries(draft).some(([key, value]) => JSON.stringify(task[key]) !== JSON.stringify(value))) {
+                    await tasks.update(task.id, draft, OWNER);
+                }
+            }
+        });
+        // A failed reconciliation must be retryable, but the caller still receives
+        // the original rejection and reports it on its originating surface.
+        reconciliation = next.then(() => undefined, () => undefined);
+        return next;
+    };
+    const run = async () => {
+        await reconcile();
+        if (!taskId || !sync.status().enabled)
+            throw new Error("Configuration subscription is paused");
+        const active = tasks.activeRun(taskId);
+        const started = active ?? tasks.run(taskId, null, "manual");
+        const done = await tasks.waitForRun(started.id);
+        if (done.state !== "succeeded")
+            throw new Error(done.error ?? `Configuration sync ${done.state}`);
+        return done.result?.type === "system" ? done.result.text : "Configuration sync finished";
+    };
+    return {
+        reconcile,
+        run,
+        status: () => ({
+            ...sync.status(), taskId,
+            nextRunAt: taskId ? tasks.get(taskId).nextRunAt : null,
+        }),
+    };
+}