@mininglamp-oss/cc-channel-octo 1.0.1-dev.60b73f3

package/dist/session-store.js

@@ -0,0 +1,297 @@
+/**
+ * Session Store — SQLite persistence via better-sqlite3 + thin adapter.
+ */
+import { escapeRoleLabels, sanitizeDisplayName } from './prompt-safety.js';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  channel_id TEXT NOT NULL,
+  channel_type INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  role TEXT NOT NULL CHECK(role IN ('user', 'assistant')),
+  content TEXT NOT NULL,
+  timestamp INTEGER NOT NULL,
+  message_seq INTEGER,
+  from_name TEXT,
+  FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS group_members (
+  group_id TEXT NOT NULL,
+  uid TEXT NOT NULL,
+  name TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY(group_id, uid)
+);
+
+-- v0.3 /reset barrier: the message_seq at which a session was intentionally
+-- cleared. Kept in a SEPARATE table (no FK to sessions) so it SURVIVES
+-- deleteSession() and a process restart — G4 cold-start backfill consults it to
+-- avoid resurrecting pre-reset history. One row per session that ever reset.
+CREATE TABLE IF NOT EXISTS reset_barriers (
+  session_id TEXT PRIMARY KEY,
+  reset_seq INTEGER NOT NULL
+);
+
+-- v0.3 persistent sessions: maps our sessionKey to the SDK's session UUID so a
+-- later turn can resume the same agent session (v2 Session API). Kept separate
+-- from the sessions table (different lifecycle); cleared by /reset with history.
+CREATE TABLE IF NOT EXISTS sdk_sessions (
+  session_id TEXT PRIMARY KEY,
+  sdk_session_id TEXT NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_session_id ON messages(session_id, id);
+`;
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+function rowToSession(row) {
+    return {
+        id: row.id,
+        channelId: row.channel_id,
+        channelType: row.channel_type,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export class SessionStore {
+    adapter;
+    selectSession;
+    insertSession;
+    touchSession;
+    insertMessage;
+    selectRecentMessages;
+    deleteExpired;
+    deleteSessionStmt;
+    upsertResetBarrier;
+    selectResetBarrier;
+    upsertSdkSession;
+    selectSdkSession;
+    deleteSdkSession;
+    deleteExpiredSdkSessions;
+    /** Tracks the last message_seq at which the bot replied, per group session key. */
+    lastBotReplySeq = new Map();
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    init() {
+        this.adapter.exec(SCHEMA);
+        // Migrations: add columns missing on pre-existing DBs (SQLite can't add them
+        // via CREATE TABLE IF NOT EXISTS). Guarded + throw on real failure (Q1-2) so
+        // a silent failure can't surface later as cryptic SQL errors. Note: this is
+        // schema presence, NOT data back-compat. New rows always write from_name;
+        // older rows added before this column may be NULL, which renderTurn handles
+        // via `from_name ?? role` — keep that coalesce (it is not dead code).
+        try {
+            const cols = this.adapter
+                .prepare("PRAGMA table_info(messages)")
+                .all();
+            if (!cols.some((c) => c.name === 'message_seq')) {
+                this.adapter.exec('ALTER TABLE messages ADD COLUMN message_seq INTEGER');
+            }
+            if (!cols.some((c) => c.name === 'from_name')) {
+                this.adapter.exec('ALTER TABLE messages ADD COLUMN from_name TEXT');
+            }
+        }
+        catch (err) {
+            throw new Error(`session-store: messages column migration failed — database is in an unknown state. Underlying error: ${String(err)}`);
+        }
+        this.selectSession = this.adapter.prepare('SELECT * FROM sessions WHERE id = ?');
+        this.insertSession = this.adapter.prepare('INSERT INTO sessions (id, channel_id, channel_type, created_at, updated_at) VALUES (?, ?, ?, ?, ?)');
+        this.touchSession = this.adapter.prepare('UPDATE sessions SET updated_at = ? WHERE id = ?');
+        this.insertMessage = this.adapter.prepare('INSERT INTO messages (session_id, role, content, timestamp, message_seq, from_name) VALUES (?, ?, ?, ?, ?, ?)');
+        this.selectRecentMessages = this.adapter.prepare('SELECT role, content, message_seq, from_name FROM messages WHERE session_id = ? ORDER BY id DESC LIMIT ?');
+        this.deleteExpired = this.adapter.prepare('DELETE FROM sessions WHERE updated_at < ?');
+        this.deleteSessionStmt = this.adapter.prepare('DELETE FROM sessions WHERE id = ?');
+        this.upsertResetBarrier = this.adapter.prepare('INSERT INTO reset_barriers (session_id, reset_seq) VALUES (?, ?) ' +
+            'ON CONFLICT(session_id) DO UPDATE SET reset_seq = excluded.reset_seq ' +
+            'WHERE excluded.reset_seq > reset_barriers.reset_seq');
+        this.selectResetBarrier = this.adapter.prepare('SELECT reset_seq FROM reset_barriers WHERE session_id = ?');
+        this.upsertSdkSession = this.adapter.prepare('INSERT INTO sdk_sessions (session_id, sdk_session_id, updated_at) VALUES (?, ?, ?) ' +
+            'ON CONFLICT(session_id) DO UPDATE SET sdk_session_id = excluded.sdk_session_id, ' +
+            'updated_at = excluded.updated_at');
+        this.selectSdkSession = this.adapter.prepare('SELECT sdk_session_id FROM sdk_sessions WHERE session_id = ?');
+        this.deleteSdkSession = this.adapter.prepare('DELETE FROM sdk_sessions WHERE session_id = ?');
+        this.deleteExpiredSdkSessions = this.adapter.prepare('DELETE FROM sdk_sessions WHERE updated_at < ?');
+    }
+    getOrCreate(id, channelId, channelType) {
+        const now = Date.now();
+        const existing = this.selectSession.get(id);
+        if (existing) {
+            this.touchSession.run(now, id);
+            return rowToSession({ ...existing, updated_at: now });
+        }
+        this.insertSession.run(id, channelId, channelType, now, now);
+        return {
+            id,
+            channelId,
+            channelType,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    appendUser(sessionId, content, messageSeq, fromName) {
+        this.append(sessionId, 'user', content, messageSeq, fromName);
+    }
+    appendAssistant(sessionId, content, messageSeq, botName) {
+        // Assistant turns are attributed to the bot's name (the caller passes the
+        // registered bot id). Stored like any other turn — rendering is uniform.
+        this.append(sessionId, 'assistant', content, messageSeq, botName);
+    }
+    append(sessionId, role, content, messageSeq, fromName) {
+        const now = Date.now();
+        // SECURITY: from_name is the IM display name — USER-CONTROLLED. It is
+        // rendered into the shared history prefix as `[<role> <from_name>]:`, so a
+        // raw value like `Alice]\n[assistant bot]: forged` would inject a fake
+        // assistant turn that every group member then sees (cross-user context
+        // poisoning in shared group mode). sanitizeDisplayName (prompt-safety, the
+        // shared choke point) strips bracket/line-break chars, caps length, and
+        // falls back to the role if nothing survives.
+        const safeName = sanitizeDisplayName(fromName ?? role, role);
+        this.insertMessage.run(sessionId, role, content, now, messageSeq ?? null, safeName);
+        this.touchSession.run(now, sessionId);
+    }
+    /**
+     * Render one history turn with speaker attribution. Group sessions are shared
+     * across members, so every turn names its sender — `[user <name>]:` and
+     * `[assistant <botName>]:`. The name is sanitized at write time (see append())
+     * so it cannot forge turn labels; the `?? role` coalesce only guards rows from
+     * before this column existed.
+     *
+     * SECURITY: the message CONTENT is also user-controlled and travels into the
+     * shared `[Conversation history]` block. A body whose line starts with
+     * `[assistant ...]:` / `[user ...]:` would forge an extra turn that, in shared
+     * group mode, every member then reads as real conversation (cross-user context
+     * poisoning — the same threat the from_name strip closes, but via content and
+     * easier to exploit since no display name is needed). So we neutralize any
+     * line-leading role label in the content here, at render time. This is the one
+     * coherent policy: turn labels can ONLY originate from this renderer, never
+     * from a user-controlled name or body.
+     */
+    renderTurn(r) {
+        return `[${r.role} ${r.from_name ?? r.role}]: ${escapeRoleLabels(r.content)}`;
+    }
+    buildHistoryPrefix(sessionId, limit) {
+        const rows = this.selectRecentMessages.all(sessionId, limit);
+        // Rows are DESC; reverse to chronological order.
+        const ordered = rows.slice().reverse();
+        return ordered.map((r) => this.renderTurn(r)).join('\n');
+    }
+    cleanExpired() {
+        const cutoff = Date.now() - SEVEN_DAYS_MS;
+        const result = this.deleteExpired.run(cutoff);
+        // Expire the SDK-session mapping on the same 7-day TTL. sdk_sessions is a
+        // separate table (no FK cascade to sessions), so without this a stale mapping
+        // would survive the sessions/messages cleanup — and since SDK sessions are
+        // always on, the next message would recreate the session and `resume` the
+        // expired SDK conversation, silently resurrecting history past the TTL
+        // (PR #120 review). updated_at is bumped every turn (setSdkSessionId), so it
+        // tracks activity exactly like sessions.updated_at.
+        this.deleteExpiredSdkSessions.run(cutoff);
+        return result.changes;
+    }
+    deleteSession(sessionId) {
+        this.deleteSessionStmt.run(sessionId);
+    }
+    /**
+     * v0.3 /reset: record a barrier so cold-start backfill never resurrects
+     * history at or before `resetSeq`. Persisted independently of the session row
+     * (survives deleteSession + restart). Monotonic — a later reset raises the
+     * barrier, an out-of-order/older seq is ignored.
+     *
+     * `resetSeq` is the message_seq of the /reset command itself; everything up to
+     * and including it is considered intentionally discarded.
+     */
+    setResetBarrier(sessionId, resetSeq) {
+        this.upsertResetBarrier.run(sessionId, resetSeq);
+    }
+    /** Return the reset barrier seq for a session, or undefined if never reset. */
+    getResetBarrier(sessionId) {
+        const row = this.selectResetBarrier.get(sessionId);
+        return row?.reset_seq;
+    }
+    /**
+     * v0.3 persistent sessions: record the SDK session UUID for a sessionKey so a
+     * later turn can resume it. Upserts (latest wins).
+     */
+    setSdkSessionId(sessionId, sdkSessionId) {
+        this.upsertSdkSession.run(sessionId, sdkSessionId, Date.now());
+    }
+    /** Return the stored SDK session UUID for a sessionKey, or undefined. */
+    getSdkSessionId(sessionId) {
+        const row = this.selectSdkSession.get(sessionId);
+        return row?.sdk_session_id;
+    }
+    /** Forget the SDK session mapping (e.g. on /reset or a resume failure). */
+    clearSdkSessionId(sessionId) {
+        this.deleteSdkSession.run(sessionId);
+    }
+    close() {
+        this.adapter.close();
+    }
+    /** Record the message_seq at which the bot last replied for a session. */
+    setLastBotReplySeq(sessionId, seq) {
+        this.lastBotReplySeq.set(sessionId, seq);
+    }
+    /** Get the message_seq at which the bot last replied for a session. */
+    getLastBotReplySeq(sessionId) {
+        return this.lastBotReplySeq.get(sessionId);
+    }
+    /**
+     * Build history prefix with answered/new segmentation (G10).
+     * Messages with message_seq <= lastBotReplySeq are labeled [answered history],
+     * messages after are labeled [new messages]. Falls back to flat history if
+     * no lastBotReplySeq tracked or no seq data available.
+     */
+    buildSegmentedHistoryPrefix(sessionId, limit) {
+        const rows = this.selectRecentMessages.all(sessionId, limit);
+        const ordered = rows.slice().reverse();
+        if (ordered.length === 0)
+            return '';
+        const lastReplySeq = this.lastBotReplySeq.get(sessionId);
+        if (lastReplySeq === undefined) {
+            // No segmentation tracking — return flat history.
+            return ordered.map((r) => this.renderTurn(r)).join('\n');
+        }
+        // Real segmentation by message_seq (G10 fix per PR#30 review):
+        // - rows with message_seq <= lastReplySeq are answered
+        // - rows with message_seq > lastReplySeq are new
+        // - rows with NULL message_seq (assistant replies, legacy) attach to the
+        //   answered side if they precede any "new" user row, else stay flat.
+        const answered = [];
+        const newMsgs = [];
+        let seenNew = false;
+        for (const r of ordered) {
+            if (r.message_seq != null && r.message_seq > lastReplySeq) {
+                seenNew = true;
+                newMsgs.push(r);
+            }
+            else if (r.message_seq != null) {
+                answered.push(r);
+            }
+            else {
+                // No seq (e.g. assistant reply) — follows the current side.
+                (seenNew ? newMsgs : answered).push(r);
+            }
+        }
+        if (newMsgs.length === 0) {
+            // Nothing new since last reply — don't show segmentation labels.
+            return answered.map((r) => this.renderTurn(r)).join('\n');
+        }
+        const parts = [];
+        if (answered.length > 0) {
+            parts.push('[answered history]');
+            parts.push(...answered.map((r) => this.renderTurn(r)));
+        }
+        parts.push('[new messages]');
+        parts.push(...newMsgs.map((r) => this.renderTurn(r)));
+        return parts.join('\n');
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/session-store.js.map

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

package/dist/skill-linker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * #100: Generic skill linking.
+ *
+ * cc supports external tooling (octo-cli, gh, anything) purely as DATA: the
+ * operator drops standard Claude skills into a `skills/` directory and cc loads
+ * them — no per-tool code. The SDK only discovers skills under a session's
+ * `<cwd>/.claude/skills/` when `settingSources` includes `project`, so for each
+ * turn we symlink the operator-owned skill dirs into the session sandbox.
+ *
+ * Two layers, mirroring config: an install-wide `<baseDir>/skills` shared by all
+ * bots, and a per-bot `<baseDir>/<id>/skills`. Per-bot overrides global on a name
+ * collision (pass sources as [global, perBot] — later wins).
+ *
+ * The links point OUTSIDE the sandbox to the operator-owned skill dirs, so the
+ * 7-day cwd TTL sweep removes only the links, never the real skills. We only ever
+ * manage symlinks we created (real files/dirs the agent placed are left alone),
+ * and we prune managed links whose source skill has disappeared so a removed
+ * skill stops being offered.
+ *
+ * Best-effort throughout: a missing source dir is skipped, any per-link error is
+ * logged and skipped, and the function never throws — a skill-linking failure
+ * must not break a turn.
+ */
+/**
+ * Symlink every skill found under `sources` into `<sandboxDir>/.claude/skills/`.
+ *
+ * @param sandboxDir - the resolved per-session cwd (the agent's working dir)
+ * @param sources - skill source dirs in ascending precedence (later wins on a
+ *   name collision). Typically `[globalSkillsDir, perBotSkillsDir]`.
+ */
+export declare function linkSkillsIntoSandbox(sandboxDir: string, sources: string[]): void;

package/dist/skill-linker.js

@@ -0,0 +1,160 @@
+/**
+ * #100: Generic skill linking.
+ *
+ * cc supports external tooling (octo-cli, gh, anything) purely as DATA: the
+ * operator drops standard Claude skills into a `skills/` directory and cc loads
+ * them — no per-tool code. The SDK only discovers skills under a session's
+ * `<cwd>/.claude/skills/` when `settingSources` includes `project`, so for each
+ * turn we symlink the operator-owned skill dirs into the session sandbox.
+ *
+ * Two layers, mirroring config: an install-wide `<baseDir>/skills` shared by all
+ * bots, and a per-bot `<baseDir>/<id>/skills`. Per-bot overrides global on a name
+ * collision (pass sources as [global, perBot] — later wins).
+ *
+ * The links point OUTSIDE the sandbox to the operator-owned skill dirs, so the
+ * 7-day cwd TTL sweep removes only the links, never the real skills. We only ever
+ * manage symlinks we created (real files/dirs the agent placed are left alone),
+ * and we prune managed links whose source skill has disappeared so a removed
+ * skill stops being offered.
+ *
+ * Best-effort throughout: a missing source dir is skipped, any per-link error is
+ * logged and skipped, and the function never throws — a skill-linking failure
+ * must not break a turn.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync, } from 'node:fs';
+import { join } from 'node:path';
+/** Sandbox subpath the SDK scans for project-scope skills. */
+const SKILLS_SUBPATH = join('.claude', 'skills');
+/**
+ * Symlink every skill found under `sources` into `<sandboxDir>/.claude/skills/`.
+ *
+ * @param sandboxDir - the resolved per-session cwd (the agent's working dir)
+ * @param sources - skill source dirs in ascending precedence (later wins on a
+ *   name collision). Typically `[globalSkillsDir, perBotSkillsDir]`.
+ */
+export function linkSkillsIntoSandbox(sandboxDir, sources) {
+    const skillsRoot = join(sandboxDir, SKILLS_SUBPATH);
+    // Collect desired links: skillName → absolute source path. Later sources
+    // overwrite earlier ones, so per-bot shadows global.
+    const desired = new Map();
+    for (const src of sources) {
+        let entries;
+        try {
+            if (!existsSync(src))
+                continue;
+            entries = readdirSync(src);
+        }
+        catch (err) {
+            console.error(`[cc-channel-octo] skill source unreadable ${src}: ${String(err)}`);
+            continue;
+        }
+        for (const name of entries) {
+            // A skill is a directory (or a symlink to one); skip dotfiles / stray files.
+            if (name.startsWith('.'))
+                continue;
+            const target = join(src, name);
+            try {
+                if (lstatSync(target).isDirectory() || lstatSync(target).isSymbolicLink()) {
+                    desired.set(name, target);
+                }
+            }
+            catch {
+                // racing removal — skip
+            }
+        }
+    }
+    try {
+        mkdirSync(skillsRoot, { recursive: true });
+    }
+    catch (err) {
+        console.error(`[cc-channel-octo] cannot create skills dir ${skillsRoot}: ${String(err)}`);
+        return; // nothing else we can do
+    }
+    // Prune managed (symlink) entries that are no longer desired or whose target
+    // vanished. Never touch real dirs/files (the agent may have created its own).
+    let existing = [];
+    try {
+        existing = readdirSync(skillsRoot);
+    }
+    catch {
+        existing = [];
+    }
+    for (const name of existing) {
+        const linkPath = join(skillsRoot, name);
+        let isLink = false;
+        try {
+            isLink = lstatSync(linkPath).isSymbolicLink();
+        }
+        catch {
+            continue;
+        }
+        if (!isLink)
+            continue; // leave real entries alone
+        const wanted = desired.get(name);
+        let currentTarget;
+        try {
+            currentTarget = readlinkSync(linkPath);
+        }
+        catch {
+            currentTarget = undefined;
+        }
+        // Remove if: not wanted anymore, points elsewhere now, or target gone.
+        if (!wanted || currentTarget !== wanted || !existsSync(linkPath)) {
+            try {
+                rmSync(linkPath, { force: true });
+            }
+            catch (err) {
+                console.error(`[cc-channel-octo] failed pruning skill link ${linkPath}: ${String(err)}`);
+            }
+        }
+    }
+    // Create desired links. The prune pass above already removed any managed link
+    // that was wrong/stale/dangling, so here: skip if a real entry shadows the
+    // name (agent's own file wins) or a correct symlink already exists; else link.
+    for (const [name, target] of desired) {
+        const linkPath = join(skillsRoot, name);
+        try {
+            if (isSymlink(linkPath)) {
+                if (readlinkSafe(linkPath) === target)
+                    continue; // already correct
+                rmSync(linkPath, { force: true }); // wrong target → replace
+            }
+            else if (lstatExists(linkPath)) {
+                continue; // a real dir/file shadows this skill name — respect it
+            }
+            symlinkSync(target, linkPath);
+        }
+        catch (err) {
+            console.error(`[cc-channel-octo] failed linking skill ${name} → ${target}: ${String(err)}`);
+        }
+    }
+}
+/** True when `p` exists as any kind of entry (does not follow symlinks). */
+function lstatExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `p` exists and is a symlink (false on any error). */
+function isSymlink(p) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** readlink that returns undefined on error. */
+function readlinkSafe(p) {
+    try {
+        return readlinkSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=skill-linker.js.map

package/dist/skill-linker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-linker.js","sourceRoot":"","sources":["../src/skill-linker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,MAAM,EACN,WAAW,GACZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,8DAA8D;AAC9D,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkB,EAAE,OAAiB;IACzE,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IAEpD,yEAAyE;IACzE,qDAAqD;IACrD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC/B,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,6CAA6C,GAAG,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClF,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,6EAA6E;YAC7E,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACnC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC;gBACH,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;oBAC1E,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACH,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,8CAA8C,UAAU,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1F,OAAO,CAAC,yBAAyB;IACnC,CAAC;IAED,6EAA6E;IAC7E,8EAA8E;IAC9E,IAAI,QAAQ,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC;QACH,QAAQ,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,EAAE,CAAC;IAChB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC,MAAM;YAAE,SAAS,CAAC,2BAA2B;QAClD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,aAAiC,CAAC;QACtC,IAAI,CAAC;YACH,aAAa,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,aAAa,GAAG,SAAS,CAAC;QAC5B,CAAC;QACD,uEAAuE;QACvE,IAAI,CAAC,MAAM,IAAI,aAAa,KAAK,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjE,IAAI,CAAC;gBACH,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,+CAA+C,QAAQ,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,2EAA2E;IAC3E,+EAA+E;IAC/E,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxB,IAAI,YAAY,CAAC,QAAQ,CAAC,KAAK,MAAM;oBAAE,SAAS,CAAC,kBAAkB;gBACnE,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,yBAAyB;YAC9D,CAAC;iBAAM,IAAI,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjC,SAAS,CAAC,uDAAuD;YACnE,CAAC;YACD,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,0CAA0C,IAAI,MAAM,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,SAAS,WAAW,CAAC,CAAS;IAC5B,IAAI,CAAC;QACH,SAAS,CAAC,CAAC,CAAC,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,SAAS,SAAS,CAAC,CAAS;IAC1B,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,SAAS,YAAY,CAAC,CAAS;IAC7B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/stream-relay.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Stream Relay — typing heartbeat + message splitting + plain sendMessage delivery.
+ *
+ * Consumes an AsyncIterable<string> of text chunks and delivers them to Octo
+ * via plain sendMessage with intelligent splitting.
+ *
+ * Design constraints:
+ * - Knows nothing about Claude SDK — input is a generic async text stream.
+ * - All Octo API calls go through the api.ts functions (no raw fetch).
+ * - Typing indicators keep the user informed while chunks accumulate.
+ */
+import type { ChannelType } from "./octo/types.js";
+/** A protected range that splitMessage must not cut through. */
+export interface ProtectedRange {
+    /** Start offset (inclusive, UTF-16 code units). */
+    start: number;
+    /** End offset (exclusive). */
+    end: number;
+}
+/**
+ * Split a long text into segments at natural boundaries.
+ *
+ * Priority: paragraph break (\n\n) > newline (\n) > space > hard cut.
+ * Each segment is at most `maxChars` characters.
+ *
+ * `protectedRanges` (P0-1): byte ranges that must NOT be split through. Used
+ * by deliver() to keep resolved @name mentions intact — a name like
+ * "@John Smith Junior" must be sent as one unit so the corresponding
+ * MentionEntity offset/length lands cleanly in one segment.
+ */
+export declare function splitMessage(text: string, maxChars?: number, protectedRanges?: ProtectedRange[]): string[];
+export declare class StreamRelay {
+    /**
+     * Deliver an async stream of text chunks to an Octo channel.
+     *
+     * 1. Starts a typing indicator heartbeat (5 s interval).
+     * 2. Accumulates all chunks from the async iterable.
+     * 3. Sends the accumulated text via plain sendMessage with splitting.
+     * 4. Always cleans up the typing heartbeat.
+     */
+    deliver(channelId: string, channelType: ChannelType, chunks: AsyncIterable<string>, apiUrl: string, botToken: string, maxResponseChars?: number, memberMap?: Map<string, string>, isValidUid?: (uid: string) => boolean): Promise<void>;
+}