@songsid/agend 2.1.12 → 2.2.0-alpha.2

package/dist/needs-you-live.d.ts

@@ -0,0 +1,116 @@
+/**
+ * #1386 §5.1–5.4: one world's live "Needs you" message in its General — kept current, without flooding, and never
+ * left holding a capability it should not.
+ *
+ * - **Generations (§5.2a).** Every render is a generation. Its Acknowledge capabilities are minted for it, and the
+ *   previous generation's are revoked *before the render's first await* — an old button is stale from that moment,
+ *   whether or not the edit lands. Expiry never edits the message: the message is renewed at least every
+ *   RENEW_MS.
+ * - **Single flight with fences (§5.3a).** One render at a time; a change meanwhile schedules exactly one more. After
+ *   every await (post/edit/delete ACK) the render continues only if its generation is current, the feature is on,
+ *   the world exists, the target is the one it started with, and the fleet is not stopping. Otherwise nothing is
+ *   persisted, its capabilities are revoked, and a late post is deleted.
+ * - **Edit vs new post (§5.3).** Changes edit in place (debounced, at most one edit per EDIT_MIN_MS). A new item
+ *   replaces the message with a new post — at the bottom, so people are notified — at most once per POST_MIN_MS;
+ *   one inside that window is shown by an edit and posted when the window opens.
+ * - **The pointer (§5.4).** Reused only at the same canonical place; a moved target never receives this world's list
+ *   at its former destination (the old message is deleted best effort, without new content).
+ *
+ * Every effect is injected; times come from a monotonic clock.
+ */
+import type { NeedsYouItem } from "./needs-you.js";
+export interface LiveTarget {
+    chatId: string;
+    threadId?: string;
+}
+export interface LivePointer extends LiveTarget {
+    messageId: string;
+}
+export interface LiveChoice {
+    id: string;
+    label: string;
+}
+export interface LiveContent {
+    /** Nothing waits on this world: no message is posted for it if none exists yet. */
+    empty: boolean;
+    text: string;
+    /** Delivery items that get an Acknowledge button on this render. */
+    ackable: NeedsYouItem[];
+}
+/** Capabilities minted for one render; `bind` fixes the message id once a post returns it. */
+export interface LiveAcks {
+    choices: LiveChoice[];
+    bind(pointer: LivePointer): void;
+}
+export interface LiveDeps {
+    world: string;
+    now(): number;
+    setTimer(fn: () => void, ms: number): unknown;
+    clearTimer(handle: unknown): void;
+    /** The current canonical General target, or null when this world has none. */
+    target(): LiveTarget | null;
+    enabled(): boolean;
+    stopping(): boolean;
+    worldExists(): boolean;
+    /** This world's current content. */
+    content(): LiveContent;
+    post(target: LiveTarget, text: string, choices: LiveChoice[]): Promise<LivePointer>;
+    edit(pointer: LivePointer, text: string, choices: LiveChoice[]): Promise<void>;
+    remove(pointer: LivePointer): Promise<void>;
+    loadPointer(): LivePointer | null;
+    savePointer(pointer: LivePointer | null): void;
+    /** Mint Acknowledge capabilities for `generation`, bound to `place` (the message id may follow via bind). */
+    mintAcks(generation: number, place: LiveTarget & {
+        messageId?: string;
+    }, items: NeedsYouItem[]): LiveAcks;
+    /** Revoke every Acknowledge capability this world holds (all generations). */
+    revokeAcks(): void;
+    log(message: string, extra?: Record<string, unknown>): void;
+    text: {
+        stopped: string;
+        off: string;
+    };
+}
+export declare const DEBOUNCE_MS = 3000;
+export declare const EDIT_MIN_MS = 10000;
+export declare const POST_MIN_MS = 60000;
+export declare const RENEW_MS: number;
+/** A failed post backs off from POST_MIN_MS, doubling, up to this (#1398 review: never a tight retry loop). */
+export declare const POST_BACKOFF_MAX_MS: number;
+/** Telegram General is topic "1" on input and no thread on the wire: both are the same place. */
+export declare function canonicalTarget(target: LiveTarget): LiveTarget;
+export declare function samePlace(a: LiveTarget, b: LiveTarget): boolean;
+export declare class NeedsYouLiveMessage {
+    private readonly deps;
+    private generation;
+    private pointer;
+    private inFlight;
+    private rerun;
+    private timer;
+    private dueAt;
+    private lastEditAt;
+    /** No post (of any kind: first, moved, new item, edit fallback) before this monotonic time. */
+    private nextPostAt;
+    private postFailures;
+    private postWanted;
+    private retired;
+    constructor(deps: LiveDeps);
+    /** The list changed. `newIds`: an item appeared that this world has not shown before (→ a new post, rate-limited). */
+    changed(newIds: boolean): void;
+    /** Current generation (tests and the ack handler's generation check). */
+    get currentGeneration(): number;
+    get currentPointer(): LivePointer | null;
+    private requestAt;
+    private scheduleRenewal;
+    /** One render. Public for tests; normal use goes through changed(). */
+    render(): Promise<void>;
+    private fenced;
+    private renderOnce;
+    private postNew;
+    /** Shutdown: revoke first, then say so on the message, without buttons. No further renders. */
+    retire(): Promise<void>;
+    /** Replaced by another renderer (a new adapter under this world's id): stop and revoke, touching nothing remote. */
+    abandon(): void;
+    /** live_message turned off (or the world removed): revoke, mark the message, forget it. */
+    disable(): Promise<void>;
+}

package/dist/needs-you-live.js

@@ -0,0 +1,228 @@
+export const DEBOUNCE_MS = 3_000;
+export const EDIT_MIN_MS = 10_000;
+export const POST_MIN_MS = 60_000;
+export const RENEW_MS = 10 * 60_000;
+/** A failed post backs off from POST_MIN_MS, doubling, up to this (#1398 review: never a tight retry loop). */
+export const POST_BACKOFF_MAX_MS = 15 * 60_000;
+/** Telegram General is topic "1" on input and no thread on the wire: both are the same place. */
+export function canonicalTarget(target) {
+    const thread = target.threadId === undefined || target.threadId === "" || target.threadId === "1" ? undefined : String(target.threadId);
+    return thread === undefined ? { chatId: String(target.chatId) } : { chatId: String(target.chatId), threadId: thread };
+}
+export function samePlace(a, b) {
+    const x = canonicalTarget(a), y = canonicalTarget(b);
+    return x.chatId === y.chatId && x.threadId === y.threadId;
+}
+export class NeedsYouLiveMessage {
+    deps;
+    generation = 0;
+    pointer;
+    inFlight = false;
+    rerun = false;
+    timer = null;
+    dueAt = Infinity;
+    lastEditAt = -Infinity;
+    /** No post (of any kind: first, moved, new item, edit fallback) before this monotonic time. */
+    nextPostAt = -Infinity;
+    postFailures = 0;
+    postWanted = false;
+    retired = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.pointer = deps.loadPointer();
+        // A restart has no capabilities: render at once so the message gets fresh ones (pre-restart buttons are stale).
+        this.requestAt(deps.now());
+    }
+    /** The list changed. `newIds`: an item appeared that this world has not shown before (→ a new post, rate-limited). */
+    changed(newIds) {
+        if (this.retired)
+            return;
+        if (newIds)
+            this.postWanted = true;
+        const now = this.deps.now();
+        let at = now + DEBOUNCE_MS;
+        if (this.postWanted)
+            at = Math.max(at, Math.min(this.nextPostAt, this.lastEditAt + EDIT_MIN_MS));
+        else
+            at = Math.max(at, this.lastEditAt + EDIT_MIN_MS);
+        this.requestAt(at);
+    }
+    /** Current generation (tests and the ack handler's generation check). */
+    get currentGeneration() { return this.generation; }
+    get currentPointer() { return this.pointer; }
+    requestAt(at) {
+        if (this.retired || at >= this.dueAt)
+            return;
+        if (this.timer !== null)
+            this.deps.clearTimer(this.timer);
+        this.dueAt = at;
+        this.timer = this.deps.setTimer(() => { this.timer = null; this.dueAt = Infinity; void this.render(); }, Math.max(0, at - this.deps.now()));
+    }
+    scheduleRenewal() {
+        this.requestAt(this.deps.now() + RENEW_MS);
+    }
+    /** One render. Public for tests; normal use goes through changed(). */
+    async render() {
+        if (this.retired)
+            return;
+        if (this.inFlight) {
+            this.rerun = true;
+            return;
+        }
+        this.inFlight = true;
+        try {
+            await this.renderOnce();
+        }
+        finally {
+            this.inFlight = false;
+            if (this.rerun && !this.retired) {
+                this.rerun = false;
+                this.requestAt(this.deps.now());
+            }
+            else if (!this.retired) {
+                // A new item shown by an edit inside the post window is posted when the window opens.
+                if (this.postWanted)
+                    this.requestAt(Math.max(this.deps.now(), this.nextPostAt));
+                if (this.timer === null)
+                    this.scheduleRenewal();
+            }
+        }
+    }
+    fenced(generation, target) {
+        const now = this.deps.target();
+        return generation === this.generation && !this.retired && this.deps.enabled() && !this.deps.stopping()
+            && this.deps.worldExists() && now !== null && samePlace(now, target);
+    }
+    async renderOnce() {
+        const target = this.deps.target();
+        if (!this.deps.enabled() || this.deps.stopping() || !this.deps.worldExists() || target === null)
+            return;
+        const generation = ++this.generation;
+        // Revoke before await: every earlier generation's buttons are stale from here on, whatever happens below.
+        this.deps.revokeAcks();
+        const content = this.deps.content();
+        const now = this.deps.now();
+        // Nothing to say and nothing said yet: a fleet that never needed anyone posts nothing.
+        if (this.pointer === null && content.empty) {
+            this.postWanted = false;
+            return;
+        }
+        const moved = this.pointer !== null && !samePlace(this.pointer, target);
+        const mayPost = now >= this.nextPostAt;
+        if (this.pointer === null || moved) {
+            // Only a post will do. Not yet allowed (a failed one is backing off): try again when it is.
+            if (!mayPost) {
+                this.postWanted = true;
+                return;
+            }
+            await this.postNew(generation, target, content, moved);
+            return;
+        }
+        if (this.postWanted && mayPost) {
+            await this.postNew(generation, target, content, false);
+            return;
+        }
+        const pointer = this.pointer;
+        const acks = this.deps.mintAcks(generation, pointer, content.ackable);
+        try {
+            await this.deps.edit(pointer, content.text, acks.choices);
+        }
+        catch (err) {
+            if (!this.fenced(generation, target)) {
+                this.deps.revokeAcks();
+                return;
+            }
+            this.deps.revokeAcks();
+            if (this.deps.now() < this.nextPostAt) {
+                // The fallback post is rate-limited like any other: try again when it may.
+                this.deps.log("live message edit failed; will post when allowed", { world: this.deps.world, err: String(err?.message ?? err) });
+                this.postWanted = true;
+                return;
+            }
+            this.deps.log("live message edit failed; posting a new one", { world: this.deps.world, err: String(err?.message ?? err) });
+            const next = ++this.generation;
+            await this.postNew(next, target, this.deps.content(), false);
+            return;
+        }
+        if (!this.fenced(generation, target)) {
+            this.deps.revokeAcks();
+            return;
+        }
+        this.lastEditAt = this.deps.now();
+    }
+    async postNew(generation, target, content, moved) {
+        const old = this.pointer;
+        const acks = this.deps.mintAcks(generation, canonicalTarget(target), content.ackable);
+        let sent;
+        try {
+            sent = await this.deps.post(target, content.text, acks.choices);
+        }
+        catch (err) {
+            this.deps.revokeAcks();
+            this.postFailures++;
+            const backoff = Math.min(POST_MIN_MS * 2 ** (this.postFailures - 1), POST_BACKOFF_MAX_MS);
+            this.nextPostAt = this.deps.now() + backoff;
+            this.postWanted = true; // retried — no sooner than nextPostAt
+            this.deps.log("live message post failed", { world: this.deps.world, err: String(err?.message ?? err), retryInMs: backoff });
+            return;
+        }
+        if (!this.fenced(generation, target)) {
+            // A late ACK: disabled, rebound, superseded or stopping meanwhile. Publish nothing current.
+            this.deps.revokeAcks();
+            void this.deps.remove(sent).catch(() => { });
+            return;
+        }
+        acks.bind(sent);
+        this.pointer = sent;
+        this.deps.savePointer(sent);
+        const at = this.deps.now();
+        this.nextPostAt = at + POST_MIN_MS;
+        this.postFailures = 0;
+        this.lastEditAt = at;
+        this.postWanted = false;
+        // The previous message goes — without new content, so a moved target's former destination never gets this list.
+        if (old !== null && !(old.messageId === sent.messageId && samePlace(old, sent))) {
+            void this.deps.remove(old).catch(err => this.deps.log(moved ? "could not remove the live message at its former target" : "could not remove the previous live message", { world: this.deps.world, err: String(err?.message ?? err) }));
+        }
+    }
+    /** Shutdown: revoke first, then say so on the message, without buttons. No further renders. */
+    async retire() {
+        if (this.retired)
+            return;
+        this.retired = true;
+        if (this.timer !== null) {
+            this.deps.clearTimer(this.timer);
+            this.timer = null;
+        }
+        this.deps.revokeAcks();
+        this.generation++;
+        if (this.pointer)
+            await this.deps.edit(this.pointer, this.deps.text.stopped, []).catch(() => { });
+    }
+    /** Replaced by another renderer (a new adapter under this world's id): stop and revoke, touching nothing remote. */
+    abandon() {
+        if (this.timer !== null) {
+            this.deps.clearTimer(this.timer);
+            this.timer = null;
+        }
+        this.retired = true;
+        this.deps.revokeAcks();
+        this.generation++;
+    }
+    /** live_message turned off (or the world removed): revoke, mark the message, forget it. */
+    async disable() {
+        if (this.timer !== null) {
+            this.deps.clearTimer(this.timer);
+            this.timer = null;
+        }
+        this.retired = true;
+        this.deps.revokeAcks();
+        this.generation++;
+        const pointer = this.pointer;
+        this.pointer = null;
+        this.deps.savePointer(null);
+        if (pointer)
+            await this.deps.edit(pointer, this.deps.text.off, []).catch(() => { });
+    }
+}
+//# sourceMappingURL=needs-you-live.js.map

package/dist/needs-you-live.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"needs-you-live.js","sourceRoot":"","sources":["../src/needs-you-live.ts"],"names":[],"mappings":"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"}

package/dist/needs-you.d.ts

@@ -0,0 +1,132 @@
+/**
+ * #1386 "Needs you": one list of everything currently waiting on the person, derived — on demand, never stored —
+ * from state the fleet already holds. Design: docs/design/1386-needs-you-inbox.md (§3 sources, §4 derivation).
+ *
+ * This module is pure: the fleet collects the inputs, this decides the items, which world owns each, what the
+ * rendered list is (its signature), and the live chat message's text and links. Nothing here touches a socket,
+ * a file or a clock of its own.
+ */
+export type NeedsYouType = "prompt" | "awaiting_input" | "instance" | "delivery";
+export interface NeedsYouItem {
+    /** Stable per occurrence: a new episode, crash or delivery is a new id (§3). */
+    id: string;
+    type: NeedsYouType;
+    /** The instance to open; a delivery's is its target. */
+    instance: string;
+    /** The world (adapter id) that owns the instance, or undefined: listed only in /ui (§5.0). */
+    owner?: string;
+    /** Which kind of wait, for the title (localized by the renderer, not here). */
+    reason: NeedsYouReason;
+    /** One line, may be "": a prompt's text, an interaction summary, "source → target · kind". */
+    detail: string;
+    /** Epoch ms when it started waiting. */
+    since: number;
+    /** prompt: the nonce the web answers through POST /ui/prompt, its buttons, and where the buttons are. */
+    nonce?: string;
+    actions?: Array<{
+        id: string;
+        label: string;
+    }>;
+    promptAt?: {
+        adapterId: string;
+        chatId: string;
+        threadId?: string;
+        messageId?: string;
+    };
+    /** delivery: the outbox row; Acknowledge offered. */
+    deliveryId?: string;
+}
+export type NeedsYouReason = "hang" | "exited" | "assist" | "permission" | "dangerous_command" | "login" | "dialog" | "terminal_input" | "auth_paused" | "crashed" | "delivery_uncertain" | "delivery_failed";
+/** A fleet prompt offered on the dashboard (hang / exit-restart / interactive-assist), as the fleet holds it. */
+export interface PromptInput {
+    nonce: string;
+    prefix: string;
+    instance: string;
+    text: string;
+    actions: Array<{
+        id: string;
+        label: string;
+    }>;
+    createdAt: number;
+    adapterId: string;
+    chatId: string;
+    threadId?: string;
+    messageId?: string;
+    /** interactive-assist only: the interaction wait it was raised for (§3.2). */
+    assistFor?: {
+        owner: string | null;
+        episode: number | null;
+    };
+}
+export interface InstanceInput {
+    name: string;
+    /** presentation state: "awaiting_input" when the CLI waits at its terminal and that is not stale/suspected. */
+    state?: string;
+    interaction?: {
+        kind?: string | null;
+        owner?: string | null;
+        episode?: number | null;
+        since?: number | null;
+    } | null;
+    interactionSummary?: string | null;
+    /** The pause marker's reason, for a paused instance; and when it was paused. */
+    pauseReason?: string | null;
+    pausedAt?: number | null;
+    /** "crashed" with the time the fleet first saw it so (§3.3). */
+    crashedAt?: number | null;
+}
+export interface DeliveryInput {
+    deliveryId: string;
+    state: "uncertain" | "failed";
+    source: string;
+    target: string;
+    kind: string;
+    finishedAt: number;
+}
+export interface NeedsYouInputs {
+    prompts: PromptInput[];
+    instances: InstanceInput[];
+    deliveries: DeliveryInput[];
+    /** The live world that owns an instance, or undefined (no channel, or its world is gone). */
+    ownerOf: (instance: string) => string | undefined;
+}
+/** §3: every item, from the inputs only. Ordered by instance (the one with the oldest item first), then oldest first. */
+export declare function deriveNeedsYou(inputs: NeedsYouInputs): NeedsYouItem[];
+/** §5.0: the items a world's chat surfaces show — only those whose instance it owns. */
+export declare function itemsForWorld(items: readonly NeedsYouItem[], world: string): NeedsYouItem[];
+/** The age bucket shown next to an item: changes of it re-render, nothing finer does. */
+export declare function ageLabel(sinceMs: number, nowMs: number): string;
+/**
+ * §4.2: what a surface shows, as a string — ids in order, each item's displayed text and age bucket, and its action
+ * coordinates (the prompt message it links to, its owning world). Two lists with the same signature render the same.
+ * New-item notification is keyed on ids, separately; a re-render never notifies.
+ */
+export declare function renderSignature(items: readonly NeedsYouItem[], nowMs: number): string;
+export interface WorldPlace {
+    type: "discord" | "telegram" | string;
+    /** Discord: the guild id. Telegram: the supergroup id (-100…). */
+    groupId?: string;
+}
+/** A link to a message (a prompt's own buttons), or undefined when none can be built for this platform/place. */
+export declare function messageLink(place: WorldPlace, at: {
+    chatId: string;
+    threadId?: string;
+    messageId?: string;
+}): string | undefined;
+/** A way to the instance's own thread: Discord's channel mention (clickable in place), Telegram's topic link. */
+export declare function instanceLink(place: WorldPlace, topicId: string | undefined): string | undefined;
+export interface LiveLine {
+    item: NeedsYouItem;
+    title: string;
+    link?: string;
+}
+export declare const LIVE_MAX_LINES = 10;
+export declare const LIVE_MAX_ACKS = 5;
+/**
+ * The live message for one world: header, at most LIVE_MAX_LINES lines (then "… and N more"), and which delivery
+ * items get an Acknowledge button (the newest LIVE_MAX_ACKS of those shown). `t` localizes.
+ */
+export declare function renderLiveMessage(lines: readonly LiveLine[], nowMs: number, t: (key: string, ...args: Array<string | number>) => string): {
+    text: string;
+    ackable: NeedsYouItem[];
+};

package/dist/needs-you.js

@@ -0,0 +1,164 @@
+/**
+ * #1386 "Needs you": one list of everything currently waiting on the person, derived — on demand, never stored —
+ * from state the fleet already holds. Design: docs/design/1386-needs-you-inbox.md (§3 sources, §4 derivation).
+ *
+ * This module is pure: the fleet collects the inputs, this decides the items, which world owns each, what the
+ * rendered list is (its signature), and the live chat message's text and links. Nothing here touches a socket,
+ * a file or a clock of its own.
+ */
+const PROMPT_REASON = {
+    "hang:": "hang",
+    "exit-restart:": "exited",
+    "interactive-assist:": "assist",
+};
+const INTERACTION_REASON = {
+    permission: "permission",
+    dangerous_command: "dangerous_command",
+    login: "login",
+    dialog: "dialog",
+    suspected_terminal_input: "terminal_input",
+};
+const oneLine = (text, max = 160) => {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+/** §3: every item, from the inputs only. Ordered by instance (the one with the oldest item first), then oldest first. */
+export function deriveNeedsYou(inputs) {
+    const items = [];
+    // §3.1 prompts.
+    for (const p of inputs.prompts) {
+        const reason = PROMPT_REASON[p.prefix];
+        if (!reason)
+            continue;
+        items.push({
+            id: `prompt:${p.nonce}`, type: "prompt", instance: p.instance, reason,
+            detail: oneLine(p.text), since: p.createdAt, nonce: p.nonce, actions: p.actions,
+            promptAt: { adapterId: p.adapterId, chatId: p.chatId, ...(p.threadId !== undefined ? { threadId: p.threadId } : {}), ...(p.messageId ? { messageId: p.messageId } : {}) },
+        });
+    }
+    for (const inst of inputs.instances) {
+        // §3.2 awaiting_input — folded into an interactive-assist prompt only when it was raised for this same wait.
+        if (inst.state === "awaiting_input" && inst.interaction) {
+            const episode = inst.interaction.episode ?? null;
+            const owner = inst.interaction.owner ?? null;
+            const folded = inputs.prompts.some(p => p.prefix === "interactive-assist:" && p.instance === inst.name
+                && p.assistFor !== undefined && p.assistFor.episode === episode && p.assistFor.owner === owner);
+            if (!folded) {
+                items.push({
+                    id: `awaiting:${inst.name}:${owner ?? "-"}:${episode ?? "-"}`, type: "awaiting_input", instance: inst.name,
+                    reason: INTERACTION_REASON[inst.interaction.kind ?? ""] ?? "dialog",
+                    detail: oneLine(inst.interactionSummary ?? ""), since: inst.interaction.since ?? 0,
+                });
+            }
+        }
+        // §3.3 instance: paused for sign-in, or crashed.
+        if (inst.pauseReason === "auth") {
+            items.push({ id: `auth:${inst.name}:${inst.pausedAt ?? 0}`, type: "instance", instance: inst.name, reason: "auth_paused", detail: "", since: inst.pausedAt ?? 0 });
+        }
+        if (inst.crashedAt != null) {
+            items.push({ id: `crashed:${inst.name}:${inst.crashedAt}`, type: "instance", instance: inst.name, reason: "crashed", detail: "", since: inst.crashedAt });
+        }
+    }
+    // §3.4 deliveries (already filtered by the outbox: unacknowledged, last 24 h, newest 50).
+    for (const d of inputs.deliveries) {
+        items.push({
+            id: `delivery:${d.deliveryId}`, type: "delivery", instance: d.target,
+            reason: d.state === "uncertain" ? "delivery_uncertain" : "delivery_failed",
+            detail: oneLine(`${d.source} → ${d.target} · ${d.kind}`), since: d.finishedAt, deliveryId: d.deliveryId,
+        });
+    }
+    for (const item of items) {
+        const owner = inputs.ownerOf(item.instance);
+        if (owner !== undefined)
+            item.owner = owner;
+    }
+    // Group by instance; instances ordered by their oldest item, items oldest first.
+    const oldest = new Map();
+    for (const item of items)
+        oldest.set(item.instance, Math.min(oldest.get(item.instance) ?? Infinity, item.since));
+    return items.sort((a, b) => (oldest.get(a.instance) - oldest.get(b.instance)) || a.instance.localeCompare(b.instance) || (a.since - b.since) || a.id.localeCompare(b.id));
+}
+/** §5.0: the items a world's chat surfaces show — only those whose instance it owns. */
+export function itemsForWorld(items, world) {
+    return items.filter(item => item.owner === world);
+}
+/** The age bucket shown next to an item: changes of it re-render, nothing finer does. */
+export function ageLabel(sinceMs, nowMs) {
+    const minutes = Math.max(0, Math.floor((nowMs - sinceMs) / 60_000));
+    if (minutes < 1)
+        return "<1m";
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}
+/**
+ * §4.2: what a surface shows, as a string — ids in order, each item's displayed text and age bucket, and its action
+ * coordinates (the prompt message it links to, its owning world). Two lists with the same signature render the same.
+ * New-item notification is keyed on ids, separately; a re-render never notifies.
+ */
+export function renderSignature(items, nowMs) {
+    return JSON.stringify(items.map(i => [
+        i.id, i.reason, i.detail, ageLabel(i.since, nowMs), i.owner ?? null,
+        i.promptAt ? [i.promptAt.adapterId, i.promptAt.chatId, i.promptAt.threadId ?? null, i.promptAt.messageId ?? null] : null,
+    ]));
+}
+const SNOWFLAKE = /^\d{5,25}$/;
+/** A link to a message (a prompt's own buttons), or undefined when none can be built for this platform/place. */
+export function messageLink(place, at) {
+    if (!at.messageId)
+        return undefined;
+    if (place.type === "discord") {
+        const channel = at.threadId ?? at.chatId;
+        if (!place.groupId || !SNOWFLAKE.test(place.groupId) || !SNOWFLAKE.test(channel) || !SNOWFLAKE.test(at.messageId))
+            return undefined;
+        return `https://discord.com/channels/${place.groupId}/${channel}/${at.messageId}`;
+    }
+    if (place.type === "telegram") {
+        const internal = telegramInternalId(at.chatId);
+        if (!internal || !/^\d+$/.test(at.messageId))
+            return undefined;
+        const topic = at.threadId && at.threadId !== "1" && /^\d+$/.test(at.threadId) ? `${at.threadId}/` : "";
+        return `https://t.me/c/${internal}/${topic}${at.messageId}`;
+    }
+    return undefined;
+}
+/** A way to the instance's own thread: Discord's channel mention (clickable in place), Telegram's topic link. */
+export function instanceLink(place, topicId) {
+    if (!topicId)
+        return undefined;
+    if (place.type === "discord")
+        return SNOWFLAKE.test(topicId) ? `<#${topicId}>` : undefined;
+    if (place.type === "telegram") {
+        const internal = telegramInternalId(place.groupId ?? "");
+        return internal && /^\d+$/.test(topicId) && topicId !== "1" ? `https://t.me/c/${internal}/${topicId}` : undefined;
+    }
+    return undefined;
+}
+/** t.me/c/ links take a supergroup's id without its -100 prefix; anything else has no such link. */
+function telegramInternalId(chatId) {
+    const m = /^-100(\d+)$/.exec(chatId);
+    return m ? m[1] : undefined;
+}
+export const LIVE_MAX_LINES = 10;
+export const LIVE_MAX_ACKS = 5;
+/**
+ * The live message for one world: header, at most LIVE_MAX_LINES lines (then "… and N more"), and which delivery
+ * items get an Acknowledge button (the newest LIVE_MAX_ACKS of those shown). `t` localizes.
+ */
+export function renderLiveMessage(lines, nowMs, t) {
+    if (lines.length === 0)
+        return { text: t("needs.live_empty"), ackable: [] };
+    const shown = lines.slice(0, LIVE_MAX_LINES);
+    const body = shown.map(l => {
+        const age = ageLabel(l.item.since, nowMs);
+        const head = `• ${l.item.instance} — ${l.title} (${age})`;
+        return l.link ? `${head} · ${l.link}` : head;
+    });
+    if (lines.length > shown.length)
+        body.push(t("needs.live_more", lines.length - shown.length));
+    const ackable = shown.filter(l => l.item.type === "delivery").map(l => l.item)
+        .sort((a, b) => b.since - a.since).slice(0, LIVE_MAX_ACKS);
+    return { text: [t("needs.live_header", lines.length), ...body].join("\n"), ackable };
+}
+//# sourceMappingURL=needs-you.js.map