instar 1.3.595 → 1.3.596

package/dist/core/TelegramLiveSender.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TelegramLiveSender — the real Telegram `SurfaceSender` for the live-test harness
+ * (docs/specs/live-user-channel-proof-standard.md §5.4). It posts a message into a
+ * Telegram forum topic AS A NON-AGENT IDENTITY (a DEMO bot / second account in a demo
+ * group — NOT the agent's own bot, which the agent would not treat as inbound), then
+ * waits for the AGENT's reply by polling the topic history for the next agent-authored
+ * message.
+ *
+ * Same shape as SlackLiveSender: the send transport (the demo-bot post) and the
+ * history read are INJECTED, so the CODE is complete + unit-testable here and the only
+ * wiring-time dependency is the demo-bot CREDENTIAL + a demo group/topic (provisioning).
+ *
+ * The agent's reply is identified DETERMINISTICALLY: the earliest history entry with
+ * `fromUser === false` (an agent outbound) whose messageId is strictly after the one we
+ * sent. Null on timeout. The responder-MACHINE attribution (the cross-machine proof) is
+ * the RealChannelDriver's injected placement reader, not this sender.
+ */
+import type { SurfaceSender } from './RealChannelDriver.js';
+import type { SendResult, ReplyResult } from './LiveTestHarness.js';
+/** The subset of TelegramAdapter.getTopicHistory's LogEntry this sender reads. */
+export interface TelegramHistoryEntry {
+    messageId: number;
+    text: string;
+    /** true = inbound user message; false = an agent (bot) outbound — the reply we wait for. */
+    fromUser: boolean;
+}
+export interface TelegramLiveSenderDeps {
+    /** Post a message into the topic AS THE DEMO identity (demo-bot token). Returns the new message id. */
+    postAsDemoUser: (topicId: number, text: string) => Promise<{
+        messageId: number;
+    }>;
+    /** Read recent topic history (Echo's getTopicHistory), newest-or-oldest order tolerated. */
+    getHistory: (topicId: number, limit?: number) => TelegramHistoryEntry[] | Promise<TelegramHistoryEntry[]>;
+    pollIntervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    logger?: (m: string) => void;
+}
+export declare class TelegramLiveSender implements SurfaceSender {
+    private readonly d;
+    constructor(deps: TelegramLiveSenderDeps);
+    private now;
+    private sleep;
+    private log;
+    private topicNum;
+    send(channelId: string, text: string): Promise<SendResult>;
+    awaitReply(channelId: string, opts: {
+        timeoutMs: number;
+        afterMessageId?: string;
+    }): Promise<Omit<ReplyResult, 'responderMachineId'> | null>;
+    private findAgentReply;
+}
+//# sourceMappingURL=TelegramLiveSender.d.ts.map

package/dist/core/TelegramLiveSender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TelegramLiveSender.d.ts","sourceRoot":"","sources":["../../src/core/TelegramLiveSender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEpE,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,uGAAuG;IACvG,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,4FAA4F;IAC5F,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,oBAAoB,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC1G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAyB;gBAC/B,IAAI,EAAE,sBAAsB;IAExC,OAAO,CAAC,GAAG;YACG,KAAK;IAGnB,OAAO,CAAC,GAAG;IAEX,OAAO,CAAC,QAAQ;IAMV,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ1D,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,oBAAoB,CAAC,GAAG,IAAI,CAAC;YAepI,cAAc;CAW7B"}

package/dist/core/TelegramLiveSender.js

@@ -0,0 +1,69 @@
+/**
+ * TelegramLiveSender — the real Telegram `SurfaceSender` for the live-test harness
+ * (docs/specs/live-user-channel-proof-standard.md §5.4). It posts a message into a
+ * Telegram forum topic AS A NON-AGENT IDENTITY (a DEMO bot / second account in a demo
+ * group — NOT the agent's own bot, which the agent would not treat as inbound), then
+ * waits for the AGENT's reply by polling the topic history for the next agent-authored
+ * message.
+ *
+ * Same shape as SlackLiveSender: the send transport (the demo-bot post) and the
+ * history read are INJECTED, so the CODE is complete + unit-testable here and the only
+ * wiring-time dependency is the demo-bot CREDENTIAL + a demo group/topic (provisioning).
+ *
+ * The agent's reply is identified DETERMINISTICALLY: the earliest history entry with
+ * `fromUser === false` (an agent outbound) whose messageId is strictly after the one we
+ * sent. Null on timeout. The responder-MACHINE attribution (the cross-machine proof) is
+ * the RealChannelDriver's injected placement reader, not this sender.
+ */
+export class TelegramLiveSender {
+    d;
+    constructor(deps) { this.d = deps; }
+    now() { return (this.d.now ?? Date.now)(); }
+    async sleep(ms) {
+        return (this.d.sleep ?? ((m) => new Promise((r) => setTimeout(r, m))))(ms);
+    }
+    log(m) { this.d.logger?.(`[telegram-live-sender] ${m}`); }
+    topicNum(channelId) {
+        const n = Number(channelId);
+        if (!Number.isFinite(n))
+            throw new Error(`telegram channelId "${channelId}" is not a numeric topic id`);
+        return n;
+    }
+    async send(channelId, text) {
+        const res = await this.d.postAsDemoUser(this.topicNum(channelId), text);
+        if (!Number.isFinite(res?.messageId)) {
+            throw new Error(`postAsDemoUser returned no messageId — message not posted`);
+        }
+        return { messageId: String(res.messageId) };
+    }
+    async awaitReply(channelId, opts) {
+        const topic = this.topicNum(channelId);
+        const afterId = opts.afterMessageId != null ? Number(opts.afterMessageId) : -Infinity;
+        const deadline = this.now() + opts.timeoutMs;
+        const pollMs = this.d.pollIntervalMs ?? 2000;
+        for (let first = true; first || this.now() < deadline; first = false) {
+            const reply = await this.findAgentReply(topic, afterId);
+            if (reply)
+                return reply;
+            if (this.now() >= deadline)
+                break;
+            await this.sleep(pollMs);
+        }
+        this.log(`no agent reply in topic ${topic} within ${opts.timeoutMs}ms`);
+        return null;
+    }
+    async findAgentReply(topicId, afterId) {
+        const entries = await this.d.getHistory(topicId, 100);
+        // Oldest-first by messageId so we return the EARLIEST agent reply after the prompt.
+        const oldestFirst = [...entries].sort((a, b) => a.messageId - b.messageId);
+        for (const e of oldestFirst) {
+            if (e.messageId <= afterId)
+                continue; // strictly after the prompt
+            if (e.fromUser)
+                continue; // skip inbound user messages (incl. our own demo post)
+            return { text: e.text ?? '', messageId: String(e.messageId) };
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=TelegramLiveSender.js.map

package/dist/core/TelegramLiveSender.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.595",
+  "version": "1.3.596",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-16T10:03:21.927Z",
-  "instarVersion": "1.3.595",
+  "generatedAt": "2026-06-16T10:35:02.431Z",
+  "instarVersion": "1.3.596",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.596.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`TelegramLiveSender` — a real Telegram `SurfaceSender` for the live-test harness (spec §5.4), ships DARK (not wired). Posts into a forum topic as a non-agent demo identity (injected post fn), awaits the agent's reply by polling topic history for the earliest `fromUser===false` entry strictly after the sent messageId. Parameterized on the demo-bot post fn + history reader, so only the demo-bot credential + demo group need provisioning.
+
+## What to Tell Your User
+
+Nothing yet — internal harness infrastructure, ships dark (no runtime surface, no behavior change).
+
+## Summary of New Capabilities
+
+None user-facing. Internally: the real Telegram drive for the live-test harness (Telegram half of the Telegram-AND-Slack bar). No new routes, config, or flags.
+
+## Evidence
+
+- `tests/unit/TelegramLiveSender.test.ts` — 8 tests: post→id, non-numeric-topic throw, no-id throw, earliest-agent-reply-after-prompt, ignores inbound, poll-until-lands, timeout→null, async getHistory.
+- `tsc --noEmit` clean. instar-dev gate green.

package/upgrades/side-effects/live-test-telegram-sender.md

@@ -0,0 +1,28 @@
+# Side-Effects Review — Live-test Telegram sender
+
+**Slug:** live-test-telegram-sender
+**Spec:** docs/specs/live-user-channel-proof-standard.md §5.4 (Platform-Sanctioned Automation)
+**Files:** src/core/TelegramLiveSender.ts, tests/unit/TelegramLiveSender.test.ts
+**Posture:** ships DARK — one pure/injectable SurfaceSender, NOT wired into server.ts.
+
+## What it is
+TelegramLiveSender — the real Telegram `SurfaceSender`: posts into a forum topic AS A NON-AGENT identity (an injected demo-bot post fn), then `awaitReply` polls the topic history for the AGENT's reply (the earliest entry with `fromUser === false` strictly after the sent messageId). Same proven shape as SlackLiveSender; parameterized on the demo-bot post fn + the history reader, so only the demo-bot CREDENTIAL + a demo group/topic need provisioning.
+
+## Phase 1 — Principle check (signal vs authority)
+Not a decision point — transport (post + poll). No block/filter/gate. Compliant.
+
+## Phase 4 — Side-effects answers
+1. **Over-block** — n/a. Worst case: the reply match misses a genuine agent reply → scenario records no-reply FAIL. Mitigated by the deterministic `fromUser===false` + strictly-after-messageId match over the full poll window.
+2. **Under-block** — n/a. Risk of matching a STALE agent message mitigated by the `messageId > afterId` strictly-after guard + oldest-first scan (earliest reply after the prompt).
+3. **Level-of-abstraction fit** — correct: the concrete Telegram adapter for the harness's `SurfaceSender` seam. Wraps the demo-bot post + getTopicHistory rather than reinventing them.
+4. **Signal vs authority** — compliant (transport, no authority).
+5. **Interactions** — none yet (dark, unwired). The demo-bot identity is SEPARATE from Echo's own bot, so a demo post can't be confused with Echo's outbound; history read is read-only.
+6. **External surfaces** — when wired, it WILL post a real message into a demo Telegram group via the demo-bot token. THIS increment: no wiring, no external surface. The demo-bot token + demo group is the provisioning dependency; the code is parameterized on it.
+7. **Multi-machine posture** — machine-agnostic (talks to the Telegram Bot API + reads topic history). The cross-machine attribution is the RealChannelDriver's PlacementResponderReader, not this sender. No single-machine assumption.
+8. **Rollback cost** — trivial: dark, unwired. Revert the commit.
+
+## No-deferrals
+The runner route (wires both senders + RealChannelDriver + harness + the multi-machine matrix) is the NEXT tracked increment (CMT-1568, `.instar/plans/live-test-harness-drivers-BUILD.md`), not a deferral. This sender is complete + fully unit-tested (8 tests). The demo-bot/group provisioning is an external-credential dependency tracked in the plan, not a code deferral — the code is parameterized so only the credential is missing.
+
+## Phase 5 — Second-pass review
+Not required: transport adapter, no block/allow/lifecycle/sentinel/gate surface (the Phase-5 triggers).