@timqi/pier 0.0.1

package/dist/channels/config.js

@@ -0,0 +1,172 @@
+// Channel config persistence and the permission gate every adapter shares.
+// One JSON document per platform holds credentials, defaults, bound users and
+// the discovered chats — token, groups and permissions in one place, so a
+// surface configuring a platform reads and writes exactly one row.
+// The shapes live in types.ts; this file is the store and the policy.
+import { pierDb } from "../db.js";
+import { defaultChannelConfig, } from "./types.js";
+const BIND_CODE_TTL_MS = 10 * 60_000;
+/** Envelope from secrets.ts. A token that matches was sealed by us; anything
+ *  else is legacy plaintext, still honored and re-sealed on the next save. */
+const SEALED = /^v1:[0-9a-f]{8}:/;
+export class ChannelStore {
+    secrets;
+    db;
+    cache = new Map();
+    /** Without `secrets`, tokens persist as given — tests and one-off tools.
+     *  With it, tokens are sealed at rest; a locked store throws on both paths
+     *  rather than serving a token it cannot read. */
+    constructor(db = pierDb(), secrets) {
+        this.secrets = secrets;
+        this.db = db;
+    }
+    /**
+     * The live cached document. Private on purpose: handing it out let a caller
+     * mutate config without saving, so memory and disk could disagree with no
+     * way to tell which was right. Internal readers use this; everyone outside
+     * gets a copy from get().
+     */
+    cached(platform) {
+        const hit = this.cache.get(platform);
+        if (hit)
+            return hit;
+        const row = this.db.prepare("SELECT json FROM channels WHERE platform = ?").get(platform);
+        const config = row
+            ? { ...defaultChannelConfig(), ...JSON.parse(row.json) }
+            : defaultChannelConfig();
+        if (this.secrets) {
+            for (const key of ["token", "appToken"]) {
+                if (SEALED.test(config[key]))
+                    config[key] = this.secrets.decrypt(config[key]);
+            }
+        }
+        this.cache.set(platform, config);
+        return config;
+    }
+    /** A detached copy: edit it freely, then hand it back to save(). */
+    get(platform) {
+        return structuredClone(this.cached(platform));
+    }
+    save(platform, config) {
+        // Clone on the way in too, so the caller keeping its object and mutating
+        // it later cannot reach into the cache behind save()'s back.
+        this.cache.set(platform, structuredClone(config));
+        // The cache holds plaintext (it is what adapters connect with); only the
+        // row is sealed.
+        const stored = this.secrets ? structuredClone(config) : config;
+        if (this.secrets) {
+            for (const key of ["token", "appToken"]) {
+                if (stored[key])
+                    stored[key] = this.secrets.encrypt(stored[key]);
+            }
+        }
+        this.db.prepare(`
+      INSERT INTO channels(platform, json) VALUES (?, ?)
+      ON CONFLICT(platform) DO UPDATE SET json = excluded.json
+    `).run(platform, JSON.stringify(stored));
+    }
+    chat(platform, chatId) {
+        return this.get(platform).chats.find((c) => c.id === chatId);
+    }
+    /**
+     * Record a chat the bot just met. Telegram has no "list my chats" API, so
+     * discovery is passive. A new chat copies the platform defaults and owns
+     * them from then on — the mention and bind gates are what keep it harmless
+     * until an operator configures it.
+     */
+    discoverChat(platform, chat) {
+        const config = this.get(platform);
+        const known = config.chats.find((c) => c.id === chat.id);
+        if (known) {
+            if (known.name === chat.name && known.kind === chat.kind)
+                return;
+            known.name = chat.name || known.name;
+            known.kind = chat.kind;
+        }
+        else {
+            config.chats.push({
+                id: chat.id,
+                name: chat.name,
+                kind: chat.kind,
+                enabled: true,
+                requireMention: config.requireMention,
+                requireBind: config.requireBind,
+                topicMode: config.topicMode,
+                cwd: config.cwd,
+                model: config.model,
+                thinking: config.thinking,
+            });
+        }
+        this.save(platform, config);
+    }
+    // Read-only and on the per-message path: no clone, nothing here escapes.
+    // An undiscovered chat falls back to the platform seed; in practice the
+    // adapter discovers before it asks.
+    policy(platform, chatId) {
+        const config = this.cached(platform);
+        const chat = config.chats.find((c) => c.id === chatId);
+        if (chat)
+            return chat;
+        return {
+            enabled: true,
+            requireMention: config.requireMention,
+            requireBind: config.requireBind,
+            topicMode: config.topicMode,
+            cwd: config.cwd,
+            model: config.model,
+            thinking: config.thinking,
+        };
+    }
+    isBound(platform, userId) {
+        return this.cached(platform).users.some((u) => u.id === userId);
+    }
+    /** Single-use, short-lived code an operator reads off the Console. */
+    issueBindCode(platform) {
+        const config = this.get(platform);
+        const code = Math.random().toString(36).slice(2, 8).toUpperCase();
+        config.bindCode = { code, expiresAt: Date.now() + BIND_CODE_TTL_MS };
+        this.save(platform, config);
+        return config.bindCode;
+    }
+    redeemBindCode(platform, code, user) {
+        const config = this.get(platform);
+        const pending = config.bindCode;
+        if (!pending || pending.expiresAt < Date.now())
+            return false;
+        if (pending.code !== code.trim().toUpperCase())
+            return false;
+        config.bindCode = null;
+        if (!config.users.some((u) => u.id === user.id)) {
+            config.users.push({ id: user.id, name: user.name, boundAt: Date.now() });
+        }
+        this.save(platform, config);
+        return true;
+    }
+    unbind(platform, userId) {
+        const config = this.get(platform);
+        config.users = config.users.filter((u) => u.id !== userId);
+        this.save(platform, config);
+    }
+}
+/**
+ * The whole inbound permission policy, platform-blind and total.
+ *
+ * A group denial is silent by contract: a group where the bot answers "you are
+ * not allowed" to every passing message is worse than one that stays quiet.
+ * A DM is the exception — two parties, so silence is just confusing — and the
+ * adapter answers `not-bound` there.
+ */
+export function gate({ policy, isDm, addressed, bound, bindRequest }) {
+    if (!policy.enabled)
+        return "chat-disabled";
+    // A DM has exactly two parties: mention is meaningless, and bind is not
+    // optional there — it is the only thing between a stranger and an agent with
+    // a shell. `requireMention`/`requireBind` are group settings by construction.
+    if (isDm)
+        return bound || bindRequest ? "allow" : "not-bound";
+    if (policy.requireMention && !addressed)
+        return "not-addressed";
+    if (policy.requireBind && !bound && !bindRequest)
+        return "not-bound";
+    return "allow";
+}

package/dist/channels/control.js

@@ -0,0 +1,71 @@
+// What an adapter is allowed to do to a session, beyond handing it a prompt.
+//
+// `Channel` has exactly one inbound path (`onMessage`) and keeps it: an in-chat
+// settings panel needs to read a session's model and change it, which is not a
+// prompt and must not become a second seam. So the channel layer — which owns
+// the router already — hands adapters this narrow, platform-blind interface.
+// Everything here is a thin wrapper over core; no policy lives in it.
+import { parseConversation as parseSlack } from "./slack.js";
+import { parseConversation as parseTelegram } from "./telegram.js";
+export function createControl({ router, factory, conversations, store }) {
+    const launchFor = (key) => {
+        const platform = key.channelId;
+        // Decoding a conversation id back to a chat id is the adapter layer's
+        // business, never core's — so each platform's own parser is used here.
+        const chatId = platform === "telegram"
+            ? parseTelegram(key.conversationId).chatId
+            : platform === "slack"
+                ? parseSlack(key.conversationId).channel
+                : undefined;
+        if (chatId === undefined)
+            return {};
+        const policy = store.policy(platform, chatId);
+        return {
+            cwd: policy.cwd || undefined,
+            model: policy.model ?? undefined,
+            thinking: policy.thinking ?? undefined,
+        };
+    };
+    return {
+        launchFor,
+        knows: (key) => conversations.get(key) !== undefined,
+        abort: (key) => router.abortConversation(key),
+        async status(key) {
+            const session = router.sessionOf(key);
+            if (!session)
+                return null;
+            // AgentSession has no cwd; the factory's listing is where it lives.
+            const listed = await factory.list();
+            const usage = session.contextUsage;
+            return {
+                sessionId: session.id,
+                cwd: listed.find((s) => s.id === session.id)?.cwd ?? "",
+                state: session.state,
+                model: session.model,
+                thinking: session.thinkingLevel,
+                thinkingLevels: session.availableThinkingLevels(),
+                tokens: usage?.tokens ?? null,
+                contextWindow: usage?.contextWindow ?? null,
+            };
+        },
+        models: () => factory.availableModels(),
+        async setModel(key, model) {
+            await router.sessionOf(key)?.setModel(model);
+        },
+        async setThinking(key, level) {
+            router.sessionOf(key)?.setThinkingLevel(level);
+        },
+        async newSession(key, cwd) {
+            const launch = launchFor(key);
+            const session = await factory.create({
+                ...launch,
+                cwd: cwd || launch.cwd || process.cwd(),
+            });
+            // Persist before attaching: a crash in between must not leave the chat
+            // pointing at a session nobody recorded.
+            conversations.set(key, session.id);
+            router.attach(key, session);
+            return session.id;
+        },
+    };
+}

package/dist/channels/conversations.js

@@ -0,0 +1,65 @@
+// Durable conversation → session routing for IM channels.
+//
+// core/router.ts keeps its map in memory, which is enough for the surfaces
+// whose conversation id already IS a session id (web) or that persist their
+// target themselves (tasks). An IM conversation id is a chat or a topic, so
+// without this table a restart would silently hand every group a brand-new
+// session: the chat history stays on screen while the agent forgets all of
+// it, and the old transcript becomes unreachable.
+//
+// Owned by channels/ rather than core/ so core stays storage-agnostic — the
+// same split tasks/ already uses for its target session ids.
+import { pierDb } from "../db.js";
+export class ConversationStore {
+    db;
+    constructor(db = pierDb()) {
+        this.db = db;
+    }
+    get(key) {
+        const row = this.db.prepare(`
+      SELECT session_id FROM conversations WHERE channel_id = ? AND conversation_id = ?
+    `).get(key.channelId, key.conversationId);
+        return row?.session_id;
+    }
+    set(key, sessionId) {
+        this.db.prepare(`
+      INSERT INTO conversations(channel_id, conversation_id, session_id, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(channel_id, conversation_id) DO UPDATE SET
+        session_id = excluded.session_id, updated_at = excluded.updated_at
+    `).run(key.channelId, key.conversationId, sessionId, Date.now());
+    }
+    /** Drop a mapping whose session Pi no longer has, so the next message
+     * starts a fresh one instead of failing forever. */
+    forget(key) {
+        this.db.prepare(`
+      DELETE FROM conversations WHERE channel_id = ? AND conversation_id = ?
+    `).run(key.channelId, key.conversationId);
+    }
+}
+/**
+ * The IM half of the router's session factory: reuse this conversation's
+ * session across restarts, and only create when there is nothing to resume.
+ * Wired in main.ts, so neither core nor an adapter learns where the mapping
+ * lives.
+ */
+export function resolveConversation(store, factory, launchFor, onStale) {
+    return async (key) => {
+        const known = store.get(key);
+        if (known) {
+            try {
+                return await factory.resume(known);
+            }
+            catch (err) {
+                // Pi never persisted it (a first turn that never landed) or the
+                // transcript was deleted. Re-route rather than fail every message.
+                onStale?.(`${key.channelId}:${key.conversationId} lost session ${known}: ${String(err)}`);
+                store.forget(key);
+            }
+        }
+        const launch = launchFor(key);
+        const session = await factory.create({ ...launch, cwd: launch.cwd ?? process.cwd() });
+        store.set(key, session.id);
+        return session;
+    };
+}

package/dist/channels/gatekeeper.js

@@ -0,0 +1,63 @@
+// The two inbound decisions every adapter makes identically: may this message
+// through, and may this stranger be told how to bind.
+//
+// Both were written twice before landing here, and both have a rule that is
+// easy to get subtly wrong on the second copy — a drop must always name its
+// verdict, and the throttle map must prune rather than grow. Keeping them in
+// one place is what makes "log every drop" and "bound every map fed by
+// strangers" true of every platform instead of one.
+import { gate } from "./config.js";
+/** How often one unbound DM sender may be told how to bind. */
+const BIND_HINT_EVERY_MS = 10 * 60_000;
+export class Gatekeeper {
+    store;
+    platform;
+    log;
+    noun;
+    /** Last time each unbound DM sender was told how to bind. */
+    hints = new Map();
+    constructor(store, platform, log, 
+    /** What the platform calls a conversation, for the drop log. */
+    noun = "chat") {
+        this.store = store;
+        this.platform = platform;
+        this.log = log;
+        this.noun = noun;
+    }
+    /**
+     * The whole inbound permission decision, plus the log line every drop owes.
+     * A silently skipped branch is indistinguishable from a bug, so the verdict
+     * is always named.
+     */
+    admit(what, chatId, req) {
+        const verdict = gate({
+            policy: this.store.policy(this.platform, chatId),
+            isDm: req.isDm,
+            addressed: req.addressed,
+            bound: this.store.isBound(this.platform, req.userId),
+            bindRequest: req.bindRequest ?? false,
+        });
+        if (verdict === "allow")
+            return true;
+        this.log(`dropped ${what} in ${this.noun} ${chatId}: ${verdict}`);
+        return false;
+    }
+    /**
+     * May this sender be told how to bind? Groups stay silent by contract, but a
+     * DM that swallows every message looks broken rather than locked — and a bot
+     * that answers every one is an echo amplifier.
+     *
+     * Anyone can DM a bot, so this map is fed by strangers: expired entries are
+     * dropped on the way past instead of keeping one per sender forever.
+     */
+    mayHint(userId, now = Date.now()) {
+        if (now - (this.hints.get(userId) ?? 0) < BIND_HINT_EVERY_MS)
+            return false;
+        for (const [id, at] of this.hints) {
+            if (now - at >= BIND_HINT_EVERY_MS)
+                this.hints.delete(id);
+        }
+        this.hints.set(userId, now);
+        return true;
+    }
+}

package/dist/channels/panel.js

@@ -0,0 +1,233 @@
+// The in-chat settings panel, minus the platform.
+//
+// One message edited in place — a new message per tap would bury the chat.
+// Every payload is namespaced `cfg:` and consumed here, so a panel tap can
+// never be mistaken for one of the agent's next-step buttons (whose payload is
+// the label itself) and never reaches the agent. Choices travel as an index
+// rather than a name: Telegram's callback data caps at 64 bytes, and an index
+// cannot be invalidated by a label someone rewrote.
+//
+// What is left to a platform is markup, how its one message is sent, edited
+// and deleted, and how it asks for a single typed answer — Slack has modals,
+// Telegram has a forced reply. Everything above that is the same panel, so it
+// is written once here.
+import { compact, thinkingLabel } from "../core/reply.js";
+export const PANEL_PREFIX = "cfg:";
+const MODELS_PER_PAGE = 8;
+const onOff = (v) => (v ? "on" : "off");
+const btn = (label, action) => ({ label, action });
+export class ChatPanel {
+    deps;
+    panels = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Gates this platform has and the other does not. */
+    gateExtras(_chat, _policy) {
+        return "";
+    }
+    code(text) {
+        return `${this.fence[0]}${this.esc(text)}${this.fence[1]}`;
+    }
+    remember(key, state) {
+        this.panels.set(key.conversationId, state);
+    }
+    state(key) {
+        return this.panels.get(key.conversationId);
+    }
+    // --- rendering ---------------------------------------------------------------
+    /** The panel proper: this session, this chat, and what can be done to them. */
+    async view(key, chatId) {
+        const status = await this.deps.control.status(key);
+        return {
+            groups: [
+                {
+                    title: "Session",
+                    lines: status
+                        ? this.sessionLines(status)
+                        : ["None yet — send a message to start one."],
+                },
+                // Slack calls it a channel, Telegram a chat; the panel says what the
+                // person reading it says.
+                {
+                    title: this.platform === "slack" ? "Channel" : "Chat",
+                    lines: this.chatLines(chatId),
+                },
+            ],
+            rows: [
+                [btn("Model", "models:0"), btn("Reasoning", "think")],
+                [btn("New session", "new"), btn("New session in…", "cwd")],
+                [
+                    ...(status?.state === "streaming" ? [btn("⏹ Stop", "stop")] : []),
+                    btn("Close", "close"),
+                ],
+            ],
+        };
+    }
+    sessionLines(status) {
+        const usage = status.tokens !== null && status.contextWindow
+            ? `${compact(status.tokens)}/${compact(status.contextWindow)} tok`
+            : "not measured yet";
+        return [
+            `${this.code(status.sessionId.slice(0, 8))} · ${status.state}`,
+            `Directory: ${this.code(status.cwd || "?")}`,
+            `Model: ${status.model ? this.esc(status.model.id) : "Pi default"} · ${thinkingLabel(status.thinking)}`,
+            `Context: ${usage}`,
+        ];
+    }
+    chatLines(chatId) {
+        const chat = this.deps.store.chat(this.platform, chatId);
+        if (!chat)
+            return [this.code(chatId)];
+        const policy = this.deps.store.policy(this.platform, chatId);
+        // A DM is bind-only by construction, so the group knobs would be a lie.
+        const gates = chat.kind === "dm"
+            ? "bound users only"
+            : `mention ${onOff(policy.requireMention)} · bind ${onOff(policy.requireBind)}${this.gateExtras(chat, policy)}`;
+        return [`${this.esc(chat.name || chatId)} · ${chat.kind} · ${this.code(chatId)}`, gates];
+    }
+    /** Redraw the panel this conversation owns. */
+    async refresh(key, note) {
+        const state = this.state(key);
+        if (!state)
+            return;
+        await this.draw(state, await this.view(key, state.chatId), note);
+    }
+    // --- actions -----------------------------------------------------------------
+    /**
+     * Handle a `cfg:` payload. Returns false when it is not ours, so the caller
+     * can treat it as one of the agent's next-step labels instead.
+     *
+     * `reopen` is how a panel left behind by a previous process recovers: its
+     * state died with that process, and redrawing from the platform's own copy
+     * of the message is the only honest answer. It costs one tap.
+     */
+    async dispatch(key, payload, ctx, reopen) {
+        if (!payload.startsWith(PANEL_PREFIX))
+            return false;
+        const [action = "", arg = ""] = payload.slice(PANEL_PREFIX.length).split(":");
+        const state = this.state(key);
+        if (!state && action !== "close") {
+            await reopen();
+            return true;
+        }
+        switch (action) {
+            case "close":
+                this.panels.delete(key.conversationId);
+                if (state)
+                    await this.erase(state);
+                return true;
+            case "panel":
+                await this.refresh(key);
+                return true;
+            case "models":
+                await this.showModels(key, Number(arg) || 0);
+                return true;
+            case "model":
+                await this.pickModel(key, Number(arg));
+                return true;
+            case "think":
+                if (arg)
+                    await this.pickThinking(key, arg);
+                else
+                    await this.showThinking(key);
+                return true;
+            case "new": {
+                const id = await this.deps.control.newSession(key);
+                await this.refresh(key, `Started session ${id.slice(0, 8)}.`);
+                return true;
+            }
+            case "cwd":
+                await this.promptCwd(key, state, ctx);
+                return true;
+            case "stop":
+                await this.deps.control.abort(key);
+                await this.refresh(key, "Stop requested.");
+                return true;
+            default:
+                this.deps.log(`unknown panel action: ${action}`);
+                return true;
+        }
+    }
+    async showModels(key, page) {
+        const state = this.state(key);
+        if (!state)
+            return;
+        state.models = await this.deps.control.models().catch(() => []);
+        const status = await this.deps.control.status(key);
+        const pages = Math.max(1, Math.ceil(state.models.length / MODELS_PER_PAGE));
+        const at = Math.min(Math.max(page, 0), pages - 1);
+        const slice = state.models.slice(at * MODELS_PER_PAGE, (at + 1) * MODELS_PER_PAGE);
+        await this.draw(state, {
+            groups: [{
+                    title: "Model",
+                    suffix: ` · page ${at + 1}/${pages}`,
+                    lines: state.models.length ? [] : ["No models with configured auth."],
+                }],
+            picks: slice.map((model, i) => {
+                const current = status?.model?.provider === model.provider && status.model.id === model.id;
+                return btn(`${current ? "✓ " : ""}${model.id}`, `model:${at * MODELS_PER_PAGE + i}`);
+            }),
+            rows: [[
+                    ...(at > 0 ? [btn("‹ Prev", `models:${at - 1}`)] : []),
+                    ...(at < pages - 1 ? [btn("Next ›", `models:${at + 1}`)] : []),
+                    btn("‹ Back", "panel"),
+                ]],
+        });
+    }
+    async pickModel(key, index) {
+        const model = this.state(key)?.models[index];
+        if (!model)
+            return this.refresh(key, "That model is no longer listed.");
+        try {
+            await this.deps.control.setModel(key, model);
+            await this.refresh(key, `Model set to ${model.id}.`);
+        }
+        catch (err) {
+            await this.refresh(key, `Could not set that model: ${String(err)}`);
+        }
+    }
+    async showThinking(key) {
+        const state = this.state(key);
+        if (!state)
+            return;
+        const status = await this.deps.control.status(key);
+        const levels = status?.thinkingLevels ?? [];
+        await this.draw(state, {
+            groups: [{
+                    title: "Reasoning",
+                    lines: levels.length ? [] : ["This model has no levels."],
+                }],
+            picks: levels.map((level) => btn(`${status?.thinking === level ? "✓ " : ""}${thinkingLabel(level)}`, `think:${level}`)),
+            rows: [[btn("‹ Back", "panel")]],
+        });
+    }
+    async pickThinking(key, level) {
+        await this.deps.control.setThinking(key, level);
+        await this.refresh(key, `Reasoning set to ${thinkingLabel(level)}.`);
+    }
+    /**
+     * The one action that is not reversible in place: Pi fixes cwd at session
+     * creation, so "change the working directory" *is* "start a new session
+     * there". Shared because both platforms have to say so and handle the same
+     * two failures.
+     */
+    async startSessionIn(key, path) {
+        if (!path.startsWith("/")) {
+            // A silent no-op here reads as "the button is broken".
+            const error = "That is not an absolute path — nothing changed.";
+            await this.refresh(key, error);
+            return { error };
+        }
+        try {
+            const id = await this.deps.control.newSession(key, path);
+            await this.refresh(key, `Started session ${id.slice(0, 8)} in ${path}.`);
+            return { id };
+        }
+        catch (err) {
+            const error = `Could not start a session there: ${String(err)}`;
+            await this.refresh(key, error);
+            return { error };
+        }
+    }
+}