@timqi/pier 0.0.29 → 0.1.1

package/dist/config-sync.js

@@ -1,11 +1,93 @@
 // One serialized configuration subscriber, shared by Settings and the hourly
 // task. Only a successfully applied response advances its persistent ETag.
+// The source is fetched over HTTPS only, redirects followed while they stay
+// HTTPS, JSON capped at 1 MiB so a hostile or broken source cannot exhaust memory.
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
-import { configSourceUrl, CONFIG_SYNC_BYTES, downloadConfig } from "./config-sync-fetch.js";
 import { transact } from "./db.js";
 import { logger } from "./log.js";
 import { normalizeModelMenu } from "./settings.js";
 const log = logger("config-sync");
+export const CONFIG_SYNC_BYTES = 1024 * 1024;
+const MAX_REDIRECTS = 5;
+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 async function downloadConfig(raw, etag, signal) {
+    let url = configSourceUrl(raw);
+    for (let hop = 0;; hop++) {
+        signal.throwIfAborted();
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "GET", redirect: "manual", signal,
+                headers: { accept: "application/json", ...(etag ? { "if-none-match": etag } : {}) },
+            });
+        }
+        catch {
+            throw new Error(signal.aborted ? "Configuration download timed out or was cancelled" : "Could not connect to source");
+        }
+        const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
+        if (location) {
+            await res.body?.cancel().catch(() => { });
+            if (hop >= MAX_REDIRECTS)
+                throw new Error("Source redirected too many times");
+            try {
+                url = configSourceUrl(new URL(location, url).href);
+            }
+            catch {
+                throw new Error("Source redirected to a location that is not HTTPS");
+            }
+            continue;
+        }
+        if (res.status !== 200 && res.status !== 304) {
+            await res.body?.cancel().catch(() => { });
+            throw new Error(res.status === 404 || res.status === 410
+                ? "Source link was revoked or does not exist"
+                : `Source returned HTTP ${String(res.status)}`);
+        }
+        const status = res.status === 304 ? 304 : 200;
+        if (status === 200 && !/^application\/json(?:\s*;|$)/i.test(res.headers.get("content-type") ?? "")) {
+            await res.body?.cancel().catch(() => { });
+            throw new Error("Source did not return JSON");
+        }
+        return { status, etag: res.headers.get("etag"), body: await read(res, signal) };
+    }
+}
+async function read(res, signal) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return "";
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > CONFIG_SYNC_BYTES)
+                throw new Error("Configuration exceeds 1 MiB");
+            chunks.push(Buffer.from(value));
+        }
+    }
+    catch (err) {
+        await reader.cancel().catch(() => { });
+        if (err instanceof Error && err.message === "Configuration exceeds 1 MiB")
+            throw err;
+        throw new Error(signal.aborted ? "Configuration download timed out or was cancelled" : "Configuration download failed");
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
 const KEY = "configSync";
 // Object order is not a change; array order (model menu priority) is.
 export function configJson(value) {
@@ -162,8 +244,8 @@ export class ConfigSync {
                 try {
                     await this.deps.reload();
                 }
-                catch {
-                    throw new Error("Configuration saved, but reload failed; retry synchronization");
+                catch (cause) {
+                    throw new Error("Configuration saved, but reload failed; retry synchronization", { cause });
                 }
                 this.#save({ needsReload: false });
             }
@@ -171,7 +253,8 @@ export class ConfigSync {
         }
         catch (err) {
             const error = err instanceof Error ? err.message : "Configuration sync failed";
-            log.error(error);
+            // The message is the operator's; the cause, when there is one, is the log's.
+            log.error(error, err instanceof Error ? err.cause : err);
             this.#save({ lastChecked: Date.now(), error });
             throw new Error(error);
         }

package/dist/core/hub.js

@@ -3,8 +3,7 @@
 import { logger } from "../log.js";
 const log = logger("core");
 const RING_SIZE = 1000;
-/** A throwing subscriber costs only itself — emit() runs on the emitter's
- *  stack (Pi's dispatch path, for session events), which must not unwind. */
+/** emit() runs on the emitter's stack (Pi's dispatch path), which must not unwind. */
 function fanOut(subscribers, event) {
     for (const fn of subscribers) {
         try {
@@ -17,8 +16,7 @@ function fanOut(subscribers, event) {
 }
 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.
+    // No seq, no replay: a client that missed events re-lists on reconnect.
     workspace = new Set();
     bus(sessionId) {
         let b = this.buses.get(sessionId);
@@ -36,13 +34,9 @@ export class EventHub {
             sessionId,
             ...payload,
         };
-        // Text deltas fan out live but never enter the ring: one long reply emits
-        // thousands of them, so a ring that held them would hold *only* them and
-        // would have evicted the turn-start, tool and turn-end events a
-        // reconnecting client replays for. The text is not lost — `turn-end`
-        // carries the full reply (web/ui/chat.ts treats it as authoritative).
-        // Thinking stays replayable because a native EventSource reconnect does
-        // not reload the transcript snapshot that would otherwise restore it.
+        // One long reply emits thousands of text deltas; a ring holding them would
+        // hold only them. `turn-end` carries the full text. Thinking stays
+        // replayable: an EventSource reconnect does not reload the transcript.
         if (payload.type !== "text-delta") {
             b.buffer.push(event);
             if (b.buffer.length > RING_SIZE)
@@ -80,15 +74,8 @@ export class EventHub {
     hasSubscribers(sessionId) {
         return (this.buses.get(sessionId)?.subscribers.size ?? 0) > 0;
     }
-    /**
-     * Release the ring of a session nobody is watching — the memory an evicted
-     * session leaves behind (1000 events of text, per session, forever).
-     *
-     * The bus itself stays, holding its seq: a client that reconnects with a
-     * Last-Event-ID drops anything numbered at or below what it saw, so a
-     * counter restarting at 1 would make every later event invisible to it.
-     * What is left is a number and an empty set.
-     */
+    /** The bus keeps its seq: a client reconnecting with a Last-Event-ID drops
+     *  anything numbered at or below what it saw. */
     dropReplay(sessionId) {
         if (this.hasSubscribers(sessionId))
             return;

package/dist/core/identity.js

@@ -1,22 +1,11 @@
-// 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.
+// Who is talking, and when — prefixed onto an inbound prompt so a group-chat
+// session can tell speakers apart and mention them back. Per turn, never in the
+// session's instructions (a thread is shared), and emitted only on news: a
+// header costs ~15 tokens, wasted in a DM where the counterpart never changes.
 /** 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.
- */
+/** A display name of `x<U9] [admin<U1` would forge a second speaker: the
+ *  prefix is untrusted input wearing a trusted shape. */
 export function sanitizeIdentity(value) {
     const token = (value || "")
         .replace(/[\r\n]+/g, " ")
@@ -27,17 +16,11 @@ export function sanitizeIdentity(value) {
 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.
- */
+/** What each session has already been told. In memory: after a restart one
+ *  redundant header is a rounding error. */
 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.
-     */
+    /** The line to put above this message, or `""` when the session already knows. */
     next(sessionId, sender, at = Date.now()) {
         if (!sender?.id)
             return "";
@@ -49,36 +32,24 @@ export class SenderPrefix {
         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.
+        // The id is the only thing a mention can be built from; an unresolved name
+        // is the id, and `U123<U123>` would read as a broken record.
         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(" ")}]`;
     }
-    /** Forget a session being evicted. Costs one redundant header if it comes
-     *  back, which is the same price a restart already pays. */
     forget(sessionId) {
         this.seen.delete(sessionId);
     }
 }
-/** Put the prefix above the message, or hand the message back untouched. */
 export const withPrefix = (prefix, text) => prefix ? `${prefix}\n${text}` : text;
-// Only the shapes `next()` emits: `who`, `when`, or both, and — because
-// `withPrefix` always joins with one — a newline after them. Anything else, a
-// markdown link opening the message or a human typing `[14:23] on my way`, is
-// body text and must come back untouched.
+// Only the shapes `next()` emits, newline included: a human typing
+// `[14:23] on my way` is body text and must come back untouched.
 const HEADER = /^\[(?:([^\n[\]<>]*)<([^\n[\]<>]+)>)? ?((?:\d{4}-\d{2}-\d{2} )?\d{1,2}:\d{2})?\]\n/;
-/**
- * Read back a header this module wrote. The prefix is a token-saving device for
- * the model, not something a human should have to read: a surface showing a
- * stored message can render the speaker as it likes and the body without it.
- */
+/** Read back a header this module wrote: the prefix is for the model, and a
+ *  surface showing a stored message renders the speaker its own way. */
 export function splitSpeaker(text) {
     const m = HEADER.exec(text);
     if (!m?.[2] && !m?.[3])
@@ -96,25 +67,15 @@ const ATTACHMENT_LINES = /(?:\n\[[^\]\n]*(?:\]\(\s*<?file:\/\/[^\n]*|$))+$/;
 /** A long code span that opens the message, when something else follows it.
  *  Long, because `npm test` before "fails" is the subject, not a paste. */
 const LEADING_CODE_SPAN = /^\s*`[^`\n]{40,}`\s+(\S[\s\S]*)$/;
-/**
- * A session titled by its first prompt inherits that prompt's header, and the
- * header is for the model: anything a person reads — a list row, a session
- * header, a notification on a phone — would say "operator: …" on every session
- * the workbench ever opened. So the speaker comes off and what they said is
- * the title. Here rather than in a UI module because the push notification
- * needs the same answer and a second copy of this would drift (AGENTS.md §3).
- *
- * Two more things a first prompt carries that a title should not: the
- * attachment lines a channel appended (`[name](file:///…)`, often cut mid-name
- * by the title clip), and a pasted log line in backticks ahead of the actual
- * question — dropped only when a question follows; a paste alone stays.
- */
+/** A title derived from a first prompt drops what was for the model, not the
+ *  reader: the speaker header, the attachment lines a channel appended, and a
+ *  pasted code span ahead of the actual question. Shared by list rows and push
+ *  notifications, hence core. */
 export function readableTitle(title) {
     if (!title)
         return title;
     const { text } = splitSpeaker(title);
-    // No header — the title is what the person typed, and reflowing it would
-    // change what the sidebar's search is matching against for nothing.
+    // No header: reflowing what the person typed would change what search matches.
     if (text === title)
         return title;
     const said = text

package/dist/core/inbound-file.js

@@ -1,11 +1,5 @@
-// The file-link convention, browser-safe: what a user's attachment may be
-// called, the marker line that tells the agent about it, the parser that
-// splits it back out of a message, the size cap both ends enforce, and where a
-// `file://` link does not count as one at all (inside code).
-// Producers are node code (channels/, web/server.ts) but the web composer
-// builds markers and the web chat parses them in the browser, so the grammar
-// lives in a module with no node imports that either side can load. The
-// filesystem half (saving the bytes) is core/inbox.ts.
+// The inbound file-link grammar. No node imports: the browser composer builds
+// markers and the web chat parses them. Saving the bytes is core/inbox.ts.
 /** One cap for every inbound path: composer, upload route, Slack metadata. */
 export const MAX_INBOUND_BYTES = 32 * 1024 * 1024;
 /** Extension for a name-less upload (a pasted screenshot has no filename). */
@@ -17,11 +11,7 @@ const MIME_EXT = {
     "application/pdf": ".pdf",
     "text/plain": ".txt",
 };
-/**
- * A filename that is safe as a path segment and inside a markdown link:
- * basename only (no traversal), whitespace and link-breaking characters
- * folded to `-`, length capped.
- */
+/** Safe as a path segment (no traversal) and inside a markdown link. */
 export function safeName(name, mimeType) {
     const base = (name ?? "").split("/").pop().replace(/[\s\\()[\]<>%#?]/g, "-");
     if (!base || base === "." || base === "..")
@@ -32,29 +22,16 @@ export function safeName(name, mimeType) {
     const ext = dot > 0 ? base.slice(dot, dot + 16) : "";
     return base.slice(0, 64 - ext.length) + ext;
 }
-/**
- * The prompt line for a saved file — the attachment convention, inbound. The
- * path is percent-encoded (parentheses included, which encodeURI leaves
- * alone) so the link survives markdown and the marker regex even when
- * `PIER_HOME` contains spaces or parens; splitInboundFiles decodes.
- */
+/** Percent-encoded, parentheses included (encodeURI leaves them), so the link
+ *  survives markdown when `PIER_HOME` contains spaces or parens. */
 export const fileMarker = (path) => `[${path.split("/").pop() ?? "file"}](file://${encodeURI(path).replace(/\(/g, "%28").replace(/\)/g, "%29")})`;
-/**
- * The conversation-visible line for an attachment that never made it (5b: a
- * failed download must not look like no attachment). Plain text on purpose —
- * not a link — so every surface renders it as the words it is. Both
- * directions: an inbound file Pier could not fetch and an outbound one it
- * could not upload (channels/attach.ts) are the same fact to the reader.
- */
+/** A failed download must not look like no attachment (§5). Plain text, not a
+ *  link, so every surface renders the words; used in both directions. */
 export const lostMarker = (name, reason) => `[attachment lost: ${name} — ${reason}]`;
 /** A fenced block's opening or closing line. */
 const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
-/**
- * The character ranges of `text` that are code: fenced blocks (fence lines
- * included) and inline spans. Inline spans are paired within a line — one that
- * wraps across a newline is legal markdown and not how anyone writes an
- * example link, and per-line pairing keeps this a scan instead of a parser.
- */
+/** Code ranges: fenced blocks and inline spans. Spans are paired within a line,
+ *  which keeps this a scan instead of a parser. */
 function codeRanges(text) {
     const ranges = [];
     let fence;
@@ -71,8 +48,8 @@ function codeRanges(text) {
             ranges.push([at, at + line.length]);
         }
         else {
-            // A span closes on the next backtick run of the same length; runs in
-            // between are content, so an unpaired opener leaves the rest as prose.
+            // A span closes on the next run of the same length; an unpaired opener
+            // leaves the rest as prose.
             const runs = [...line.matchAll(/`+/g)];
             for (let i = 0; i < runs.length; i++) {
                 const open = runs[i];
@@ -89,13 +66,8 @@ function codeRanges(text) {
     }
     return ranges;
 }
-/**
- * `text.replace(pattern, …)` for every match that is not inside code. An agent
- * that documents this convention writes an example link in backticks, and a
- * scanner that cannot tell an example from a link turned that example into a
- * real attachment — a dead card in the chat, a lost-attachment line in Slack.
- * Matches inside code are left byte-identical: the reader asked to see them.
- */
+/** `text.replace(pattern, …)` outside code only: an example link in backticks
+ *  is not an attachment, and the reader asked to see it byte-identical. */
 export function replaceOutsideCode(text, pattern, replace) {
     const skip = codeRanges(text);
     let out = "";
@@ -112,14 +84,8 @@ export function replaceOutsideCode(text, pattern, replace) {
 }
 // A whole line that is one `[name](file:///…)` link — what fileMarker emits.
 const MARKER_RE = /^\[[^\]\n]*\]\(\s*<?file:\/\/(\/[^)>\s]*)>?\s*\)$/;
-/**
- * Split a user message into its typed text and the attached files' paths.
- * Only the contiguous *trailing* block of marker lines is an attachment —
- * that is where every producer puts them — so a `file://` link the user
- * wrote mid-message stays message text. No code scan needed for the same
- * reason: an example in a fence sits under its closing line, which is not a
- * marker line, so the walk stops there before ever reaching it.
- */
+/** Only the contiguous trailing block of marker lines is an attachment, so a
+ *  `file://` link mid-message stays text and a fenced example is never reached. */
 export function splitInboundFiles(raw) {
     const lines = raw.split("\n");
     let start = lines.length;

package/dist/core/inbox.js

@@ -1,42 +1,27 @@
-// Inbound user files: bytes land on disk exactly once.
-//
-// A photo pasted on the web, dropped in Telegram or uploaded to Slack used to
-// travel as base64 through the seam into the transcript, where it was re-sent
-// with every provider request until compaction. Now the adapter (or the web
-// upload route) saves the bytes under `$PIER_HOME/inbox/<channel>/` and the
-// prompt carries only a marker line (core/inbound-file.ts owns that grammar),
-// so the agent reads a file only when it decides the file is worth looking at.
+// Inbound user files: bytes land on disk once under `$PIER_HOME/inbox/<channel>/`
+// and the prompt carries only a marker line, so a file is never re-sent with
+// every provider request and the agent reads it only when it chooses to.
 import { mkdir, writeFile } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { basename, join } from "node:path";
 import { pierPath } from "../paths.js";
 import { fileMarker, lostMarker, MAX_INBOUND_BYTES, safeName } from "./inbound-file.js";
 /** Where every inbound file lives; the attachment route allowlists this root. */
-export const INBOX_DIR = pierPath("inbox");
-/**
- * Write one inbound file and return its absolute path. The timestamp-random
- * prefix keeps concurrent saves collision-free (`wx` turns the impossible
- * collision into an error instead of an overwrite) and makes `ls` read as a
- * timeline. Owner-only modes: uploads are private conversation content on a
- * possibly shared machine. Nothing is ever deleted here — pruning the inbox
- * is the operator's call (docs/deploy.md).
- */
+const INBOX_DIR = pierPath("inbox");
+/** `wx` turns a prefix collision into an error, not an overwrite. Owner-only
+ *  modes: uploads are private content on a possibly shared machine. Nothing is
+ *  deleted here; pruning is the operator's call (docs/deploy.md). */
 export async function saveInbound(channelId, name, mimeType, bytes) {
-    // The channel id is ours ("web" | "telegram" | "slack"), not user input,
-    // but basename() keeps a future id honest.
+    // The channel id is ours, not user input; basename() keeps a future id honest.
     const dir = join(INBOX_DIR, basename(channelId));
     await mkdir(dir, { recursive: true, mode: 0o700 });
     const path = join(dir, `${String(Date.now())}-${randomBytes(3).toString("hex")}-${safeName(name, mimeType)}`);
     await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
     return path;
 }
-/**
- * Collect a fetch response's body, refusing past `maxBytes` mid-stream. The
- * metadata size gate in saveInboundAll is only as honest as the platform's
- * metadata — absent or wrong, `arrayBuffer()` buffers whatever arrives — so
- * the read itself is bounded too. Throws with "too large" in the message,
- * which the loop below translates into the honest lost-marker reason.
- */
+/** The metadata size gate is only as honest as the platform's metadata, so the
+ *  read itself is bounded too. Throws with "too large" in the message, which
+ *  saveInboundAll translates into the lost-marker reason. */
 export async function readCapped(body, maxBytes) {
     if (!body)
         return new Uint8Array(0);
@@ -67,14 +52,8 @@ export async function readCapped(body, maxBytes) {
     }
     return bytes;
 }
-/**
- * Save a message's attachments; each becomes a marker line for the prompt —
- * and a failed or oversized one becomes a lost-marker line, never silence
- * (5b). Written three times, once per adapter, before landing here: the
- * size gate before the fetch (an unauthorized sender is already filtered by
- * then, but a movie must not be buffered whole either) and the never-silent
- * failure path are invariants, and invariants drift when copied.
- */
+/** Each attachment becomes a marker line; a failed or oversized one becomes a
+ *  lost-marker line, never silence (§5). The size gate runs before the fetch. */
 export async function saveInboundAll(channelId, files, log) {
     const markers = [];
     for (const file of files) {
@@ -89,7 +68,6 @@ export async function saveInboundAll(channelId, files, log) {
         }
         catch (err) {
             log(`attachment download failed: ${String(err)}`);
-            // A fetch that refused mid-stream names its reason; keep it honest.
             const why = String(err).includes("too large") ? "too large" : "download failed";
             markers.push(lostMarker(file.label, why));
         }

package/dist/core/queue.js

@@ -1,14 +1,12 @@
 // The whole queue policy. Fixed by docs/architecture.md — do not add options.
 export function decide(msg, state) {
     // An explicit mode takes the text verbatim: IM sends steer for every
-    // message, so a leading "!" there is content, not a control prefix —
-    // consuming it silently rewrote what the person typed.
+    // message, so a leading "!" there is content, not a control prefix.
     if (msg.mode === "steer" || msg.mode === "followUp") {
         return { action: state === "idle" ? "prompt" : msg.mode, text: msg.text };
     }
-    // On auto the "!" is a control prefix and always consumed — whether the
-    // turn happened to end first must not decide if it was content. Idle just
-    // means there is nothing to steer, so it degenerates to a prompt.
+    // On auto the "!" is always consumed: whether the turn happened to end
+    // first must not decide if it was content.
     const steerPrefixed = msg.text.startsWith("!");
     const text = steerPrefixed ? msg.text.slice(1).trimStart() : msg.text;
     if (state === "idle")