@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/helpers/streaming.js

@@ -0,0 +1,209 @@
+/** Streams agent deltas + tool calls to chat via debounced edits; splits past MAX_BODY_LEN. */
+import { errMsg, log } from '../log.js';
+/** 1500ms keeps us under Discord's ~5/5s per-channel edit cap; leading-edge 500ms for first delta. */
+const DEFAULT_DEBOUNCE_MS = 1500;
+const LEADING_MS = 500;
+/** Discord cap is 2000; 1900 leaves headroom for status suffix. */
+const MAX_BODY_LEN = 1900;
+const STATUS_RESERVE = 80;
+/** Cap result so a 1000-line file dump doesn't blow the per-message char budget. */
+const MAX_RESULT_LINES = 50;
+const MAX_RESULT_CHARS = 1500;
+/** One per bot. Coalesces edits so concurrent threads don't compound rate limits. */
+export class StreamScheduler {
+    debounceMs;
+    leadingMs;
+    dirty = new Set();
+    timer = null;
+    lastFlushAt = 0;
+    constructor(debounceMs = DEFAULT_DEBOUNCE_MS, leadingMs = LEADING_MS) {
+        this.debounceMs = debounceMs;
+        this.leadingMs = leadingMs;
+    }
+    request(stream) {
+        this.dirty.add(stream);
+        if (this.timer)
+            return;
+        const sinceLast = Date.now() - this.lastFlushAt;
+        const delay = sinceLast >= this.debounceMs ? this.leadingMs : this.debounceMs - sinceLast;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.lastFlushAt = Date.now();
+            const batch = [...this.dirty];
+            this.dirty.clear();
+            for (const s of batch)
+                void s._flushFromScheduler();
+        }, delay);
+    }
+    forget(stream) { this.dirty.delete(stream); }
+}
+/** Break embedded triple backticks so they can't close our fenced block early. */
+const escapeFence = (s) => s.replace(/```/g, '`​`​`');
+/** Cap output by lines + chars; return `body` to embed and a `_(N more …)_` overflow note (or ''). */
+function truncateResult(s) {
+    const lines = s.split('\n');
+    let body = lines.slice(0, MAX_RESULT_LINES).join('\n');
+    const droppedLines = Math.max(0, lines.length - MAX_RESULT_LINES);
+    if (body.length > MAX_RESULT_CHARS)
+        body = body.slice(0, MAX_RESULT_CHARS) + '…';
+    if (droppedLines === 0 && body === s)
+        return { body: s, overflow: '' };
+    const noun = droppedLines > 0 ? `${droppedLines} more line${droppedLines === 1 ? '' : 's'}` : 'output truncated';
+    return { body, overflow: `_(${noun})_` };
+}
+export class StreamingMessage {
+    adapter;
+    scheduler;
+    blocks = [];
+    segments = [{ id: null, text: '', dirty: false }];
+    statusLine = null;
+    flushing = false;
+    flushAgain = false;
+    finalized = false;
+    constructor(adapter, scheduler) {
+        this.adapter = adapter;
+        this.scheduler = scheduler;
+    }
+    appendDelta(delta) {
+        if (this.finalized || !delta)
+            return;
+        const last = this.blocks.at(-1);
+        if (last?.kind === 'text')
+            last.text += delta;
+        else
+            this.blocks.push({ kind: 'text', text: delta });
+        this.scheduler.request(this);
+    }
+    setStatus(status) {
+        if (this.finalized)
+            return;
+        this.statusLine = status;
+        this.scheduler.request(this);
+    }
+    /** Add a tool block keyed by `id`; rendered immediately as a header, output filled in via appendToolResult. */
+    appendToolCall(id, name, detail) {
+        if (this.finalized)
+            return;
+        this.blocks.push({ kind: 'tool', id, name, detail });
+        this.scheduler.request(this);
+    }
+    /** Set the matching tool block's result; renders truncated output under the header. */
+    appendToolResult(id, result) {
+        if (this.finalized || !result)
+            return;
+        const tool = this.blocks.find((b) => b.kind === 'tool' && b.id === id);
+        if (tool)
+            tool.result = result;
+        this.scheduler.request(this);
+    }
+    appendError(message) {
+        if (this.finalized)
+            return;
+        this.statusLine = null;
+        this.blocks.push({ kind: 'text', text: `⚠️ ${message}` });
+        this.scheduler.request(this);
+    }
+    async finalize() {
+        if (this.finalized)
+            return;
+        this.finalized = true;
+        this.scheduler.forget(this);
+        this.statusLine = null;
+        await this.flush();
+    }
+    async _flushFromScheduler() { await this.flush(); }
+    /** Render the block list into a single markdown body. */
+    renderBody() {
+        return this.blocks.map(b => b.kind === 'text' ? b.text : this.renderToolBlock(b)).join('\n\n').trim();
+    }
+    /** Plain header + fenced input block + fenced output block. Each fence is fully visible (no collapse). */
+    renderToolBlock(b) {
+        const parts = [`🛠 **${b.name}**`];
+        if (b.detail)
+            parts.push('```\n' + escapeFence(b.detail) + '\n```');
+        if (b.result) {
+            const { body, overflow } = truncateResult(b.result);
+            parts.push('```\n' + escapeFence(body) + '\n```');
+            if (overflow)
+                parts.push(overflow);
+        }
+        return parts.join('\n');
+    }
+    /** Redistribute the rendered body across segments, keeping existing segment ids stable. */
+    redistribute() {
+        const fullBody = this.renderBody();
+        const chunks = this.chunkify(fullBody, MAX_BODY_LEN - STATUS_RESERVE);
+        if (!chunks.length)
+            chunks.push('');
+        for (let i = 0; i < chunks.length; i++) {
+            if (i >= this.segments.length) {
+                this.segments.push({ id: null, text: chunks[i], dirty: true });
+            }
+            else if (this.segments[i].text !== chunks[i]) {
+                this.segments[i].text = chunks[i];
+                this.segments[i].dirty = true;
+            }
+        }
+    }
+    chunkify(s, cap) {
+        if (s.length <= cap)
+            return [s];
+        const out = [];
+        for (let r = s; r.length > 0;) {
+            const take = r.length > cap ? this.sliceAtBoundary(r, cap) : r;
+            out.push(take);
+            r = r.slice(take.length);
+        }
+        return out;
+    }
+    /** Split at the last paragraph/line/sentence/word break in range; hard slice otherwise. */
+    sliceAtBoundary(s, room) {
+        if (s.length <= room)
+            return s;
+        const candidate = s.slice(0, room);
+        for (const b of ['\n\n', '\n', '. ', ' ']) {
+            const i = candidate.lastIndexOf(b);
+            if (i > room * 0.5)
+                return candidate.slice(0, i + b.length);
+        }
+        return candidate;
+    }
+    async flush() {
+        if (this.flushing) {
+            this.flushAgain = true;
+            return;
+        }
+        this.flushing = true;
+        try {
+            do {
+                this.flushAgain = false;
+                this.redistribute();
+                for (let i = 0; i < this.segments.length; i++) {
+                    const s = this.segments[i];
+                    const body = this.render(s, i === this.segments.length - 1);
+                    if (!body)
+                        continue;
+                    try {
+                        if (s.id === null)
+                            s.id = await this.adapter.send(body);
+                        else if (s.dirty)
+                            await this.adapter.edit(s.id, body);
+                        s.dirty = false;
+                    }
+                    catch (err) {
+                        log.warn({ err: errMsg(err) }, 'streaming edit failed');
+                    }
+                }
+            } while (this.flushAgain);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    render(s, isLast) {
+        const showStatus = isLast && !!this.statusLine;
+        if (!s.text)
+            return showStatus ? this.statusLine : '';
+        return showStatus ? `${s.text}\n\n${this.statusLine}` : s.text;
+    }
+}

package/dist/helpers/telegram-format.js

@@ -0,0 +1,39 @@
+/** Convert markdown → Telegram HTML. Stream-safe: unmatched markers fall through as literal text. */
+const ENTITY_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
+const esc = (s) => s.replace(/[&<>]/g, c => ENTITY_MAP[c]);
+/** SOH — invalid in Telegram text + never in agent output, so collisions are impossible. */
+const SENT = '\x01';
+export function mdToTelegramHtml(md) {
+    const slots = [];
+    const stash = (html) => {
+        slots.push(html);
+        return `${SENT}${slots.length - 1}${SENT}`;
+    };
+    /** Fenced code first so its contents aren't touched by other rules. */
+    let work = md.replace(/```([A-Za-z0-9_+\-.]*)\n?([\s\S]*?)```/g, (_m, lang, code) => {
+        const inner = lang
+            ? `<pre><code class="language-${esc(lang)}">${esc(code)}</code></pre>`
+            : `<pre>${esc(code)}</pre>`;
+        return stash(inner);
+    });
+    /** Inline code; skip multi-line spans (likely an unclosed mid-stream fence). */
+    work = work.replace(/`([^`\n]+)`/g, (_m, code) => stash(`<code>${esc(code)}</code>`));
+    /** Escape outside stashes before running tag-emitting rules. */
+    work = esc(work);
+    work = work.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/g, (_m, text, url) => stash(`<a href="${url.replace(/"/g, '%22')}">${text}</a>`));
+    /** Bold before italic so single-`*` rule doesn't eat half of `**bold**`. */
+    work = work.replace(/\*\*([^*\n]+?)\*\*/g, '<b>$1</b>').replace(/__([^_\n]+?)__/g, '<b>$1</b>');
+    /** Italic: \S guards prevent matching `2 * 3` arithmetic or `foo_bar` identifiers. */
+    work = work
+        .replace(/(^|[^*\w])\*(\S[^*\n]*?\S|\S)\*(?!\w)/g, '$1<i>$2</i>')
+        .replace(/(^|[^_\w])_(\S[^_\n]*?\S|\S)_(?!\w)/g, '$1<i>$2</i>');
+    work = work.replace(/~~([^~\n]+?)~~/g, '<s>$1</s>');
+    /** Headings → bold (Telegram has no heading element). */
+    work = work.replace(/^#{1,6}\s+(.+?)\s*$/gm, '<b>$1</b>');
+    /** Collapse consecutive `> ` lines into one <blockquote> for prose-level quotes. */
+    work = work.replace(/(^|\n)((?:&gt;\s?[^\n]*\n?)+)/g, (_m, lead, block) => {
+        const inner = block.replace(/^&gt;\s?/gm, '').replace(/\n+$/, '');
+        return `${lead}<blockquote>${inner}</blockquote>${block.endsWith('\n') ? '\n' : ''}`;
+    });
+    return work.replace(new RegExp(`${SENT}(\\d+)${SENT}`, 'g'), (_m, idx) => slots[Number(idx)]);
+}

package/dist/helpers/turn.js

@@ -0,0 +1,40 @@
+/** Run a turn; stream response via adapter. In-flight follow-ups queue and drain as one combined turn. */
+import { errMsg, log } from '../log.js';
+import { StreamingMessage } from './streaming.js';
+const inFlight = new Set();
+const queued = new Map();
+export async function runTurn(agent, threadId, text, adapter, scheduler) {
+    const dispatch = (t) => runTurn(agent, threadId, t, adapter, scheduler);
+    if (inFlight.has(threadId)) {
+        const q = queued.get(threadId);
+        if (q)
+            q.texts.push(text);
+        else
+            queued.set(threadId, { texts: [text], dispatch });
+        return;
+    }
+    inFlight.add(threadId);
+    const stream = new StreamingMessage(adapter, scheduler);
+    const finishAndDrain = async () => {
+        await stream.finalize();
+        inFlight.delete(threadId);
+        const q = queued.get(threadId);
+        if (!q?.texts.length)
+            return;
+        queued.delete(threadId);
+        await q.dispatch(q.texts.join('\n\n')).catch(err => log.warn({ err: errMsg(err) }, 'queued turn failed'));
+    };
+    const callbacks = {
+        onDelta: d => stream.appendDelta(d),
+        onToolStart: a => a.transient ? stream.setStatus(a.name) : stream.appendToolCall(a.id, a.name, a.detail),
+        onToolEnd: (id, result) => { if (result)
+            stream.appendToolResult(id, result); stream.setStatus(null); },
+        onComplete: () => { void finishAndDrain(); },
+        onError: err => {
+            log.warn({ err: errMsg(err) }, 'agent turn failed');
+            stream.appendError(errMsg(err) || 'agent turn failed');
+            void finishAndDrain();
+        },
+    };
+    await agent.sendTurn(threadId, text, callbacks);
+}

package/dist/log.js

@@ -1,6 +1,4 @@
-// Pino → stderr. Stdout is reserved for command output (`metro`'s inbound
-// JSON lines, subcommand results, --json) — any stray write there breaks
-// parsing. Override level with METRO_LOG_LEVEL.
+/** Pino → stderr. Stdout reserved for command output / --json. */
 import pino from 'pino';
 export const log = pino({ name: 'metro', level: process.env.METRO_LOG_LEVEL || 'info' }, pino.destination(2));
 export const errMsg = (err) => {