charness 0.0.0-stage → 3.1.0

package/dist/platform/inbound.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @description The inbound half of the platform seam: what the core consumes
+ * from ANY surface.
+ *
+ * The core must not know that a message arrived as a Telegram update, a tracker
+ * comment or a Teams activity. It consumes {@link InboundEvent} — already
+ * normalized, already addressed by a {@link SessionKey}, already parsed into a
+ * platform-neutral command when the text carried one. The connector owns every
+ * step of that translation, plus the membership lookup that access control
+ * depends on.
+ *
+ * Deliberately NOT here: rendering, message limits, markup dialects, and any
+ * notion of what an update "is" on the wire. Those are outbound / connector
+ * concerns.
+ */
+import type { SessionKey } from '../sessionKey';
+/**
+ * @description Who sent an inbound event, reduced to what the core can use on
+ * ANY surface.
+ *
+ * `id` is a string because only Telegram's user ids happen to be numeric — a
+ * tracker account id or a Teams AAD object id is not. The core only ever
+ * compares and displays it.
+ *
+ * **There is deliberately no `isAdmin` flag.** `AdminCache` already owns that
+ * answer behind a TTL with failure backoff; a per-event snapshot would disagree
+ * with the cache after a demotion and leave the access policy with two sources
+ * of truth. The policy keeps asking the cache.
+ */
+export interface InboundAuthor {
+    id: string;
+    displayName: string;
+}
+/**
+ * @name AttachmentKind
+ * @description The media families the core can reason about, independent of
+ * what any one platform calls them. A connector maps its own richer taxonomy
+ * (Telegram splits `video` / `video_note` / `animation`) onto these.
+ */
+export type AttachmentKind = 'photo' | 'document' | 'video' | 'audio' | 'voice';
+/**
+ * @description One attachment on an inbound event, normalized.
+ *
+ * `handle` is opaque to the core: it is whatever the ORIGINATING connector
+ * needs to fetch the bytes later (a Telegram `file_id`, a tracker attachment
+ * URL). The core stores and passes it back; it never interprets it.
+ */
+export interface NormalizedAttachment {
+    kind: AttachmentKind;
+    handle: string;
+    /** Stable, non-reusable id for naming the saved copy, when the platform has one. */
+    uniqueId: string | null;
+    fileName: string | null;
+    sizeBytes: number | null;
+    /** Text accompanying the attachment, when the platform carries one. */
+    caption: string | null;
+}
+/**
+ * @description A command parsed out of the inbound text by the connector, in a
+ * form the neutral router can dispatch.
+ *
+ * - `name` — verbatim, without the platform's trigger syntax (`/` on Telegram,
+ *   an `@mention` on a tracker). Case is NOT folded here: the router matches
+ *   exactly, and a surface whose commands are case-insensitive normalises in
+ *   its own recogniser.
+ * - `args` — whitespace-split remainder, empties dropped.
+ * - `argsText` — the remainder verbatim (trimmed at the ends only). Kept
+ *   alongside `args` because commands that take free-form prose (a session
+ *   title, a schedule description) must preserve the user's inner spacing,
+ *   which `args.join(' ')` would not.
+ */
+export interface InboundCommand {
+    name: string;
+    args: string[];
+    argsText: string;
+}
+/**
+ * @description The message an inbound event replies to, reduced to what the
+ * core renders into the agent prompt.
+ *
+ * `isFromAssistant` is carried explicitly rather than left for the core to
+ * derive: only the connector knows which account is the integration's own, and
+ * the rendered quote attributes the text to `assistant` or `user` from it.
+ */
+export interface InboundReplyTo {
+    text: string;
+    author: InboundAuthor | null;
+    isFromAssistant: boolean;
+}
+/**
+ * @description One normalized inbound message from any surface.
+ *
+ * `raw` is the connector-private escape hatch — the original platform payload,
+ * opaque to the core. It exists so a connector's own handlers can recover full
+ * fidelity without the core growing platform fields; core code reading `raw` is
+ * a seam violation.
+ */
+export interface InboundEvent {
+    key: SessionKey;
+    author: InboundAuthor;
+    text: string;
+    attachments: NormalizedAttachment[];
+    replyTo?: InboundReplyTo;
+    command?: InboundCommand;
+    raw: unknown;
+}
+/** What the core hands a connector to receive normalized events. */
+export type InboundEventHandler = (event: InboundEvent) => Promise<void> | void;
+/**
+ * @description A member of a space, reduced to what access control needs.
+ *
+ * Replaces the telegraf `ChatMember` that `accessControl.ts` used to import:
+ * the policy cares only about "is this a real person with elevated rights",
+ * never about Telegram's nine membership statuses. Mapping a platform's status
+ * vocabulary onto `hasElevatedRights` is the connector's job.
+ */
+export interface PlatformMember {
+    id: string;
+    displayName: string;
+    isBot: boolean;
+    hasElevatedRights: boolean;
+}
+/**
+ * @description The inbound side of a connector.
+ *
+ * `listMembersWithElevatedRights` is part of the interface rather than a
+ * separate service because membership is inherently platform knowledge: only
+ * the connector knows which of its status values count as elevated. It returns
+ * ids (not members) because that is all the access policy compares against.
+ */
+export interface ConnectorInbound {
+    /** Begin delivering normalized events to `onEvent`. Idempotent. */
+    start(onEvent: InboundEventHandler): Promise<void>;
+    /** Stop delivering events and release the transport. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * Ids of the members of `space` who hold elevated rights there.
+     *
+     * A lookup that cannot be answered must REJECT. Resolving `[]` is a valid
+     * answer meaning "this space has no elevated members", and `AdminCache` caches
+     * it as a successful fetch — so a failure disguised as `[]` locks every
+     * operator out for the full TTL, with no retry and nothing logged. Only a
+     * rejection keeps the last-known set and re-tries on the failure backoff.
+     */
+    listMembersWithElevatedRights(space: string): Promise<string[]>;
+}
+//# sourceMappingURL=inbound.d.ts.map

package/dist/platform/inbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../../src/platform/inbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uEAAuE;IACvE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEhF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,oEAAoE;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;;;;;OAQG;IACH,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACjE"}

package/dist/platform/inbound.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * @description The inbound half of the platform seam: what the core consumes
+ * from ANY surface.
+ *
+ * The core must not know that a message arrived as a Telegram update, a tracker
+ * comment or a Teams activity. It consumes {@link InboundEvent} — already
+ * normalized, already addressed by a {@link SessionKey}, already parsed into a
+ * platform-neutral command when the text carried one. The connector owns every
+ * step of that translation, plus the membership lookup that access control
+ * depends on.
+ *
+ * Deliberately NOT here: rendering, message limits, markup dialects, and any
+ * notion of what an update "is" on the wire. Those are outbound / connector
+ * concerns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=inbound.js.map

package/dist/platform/inbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.js","sourceRoot":"","sources":["../../src/platform/inbound.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/platform/outbound.d.ts

@@ -0,0 +1,225 @@
+/**
+ * @description The outbound half of the platform seam: what the core hands ANY
+ * surface, and what it may assume that surface can do.
+ *
+ * The core emits SEMANTIC content — text plus the structure it means (a set of
+ * options the user should pick from, a request to keep the message visible) —
+ * and never a rendered message. Telegram's HTML subset, a tracker's document
+ * format and Teams' cards are mutually incompatible, and so are their length
+ * limits, so rendering and splitting belong to the connector on the far side of
+ * this file.
+ *
+ * Deliberately NOT here: markup dialects, message limits, keyboards, pins,
+ * edit-in-place vs draft-cursor streaming. Those are connector-internal.
+ */
+import type { PlatformId, SessionKey } from '../sessionKey';
+import type { SendFilesToThreadOptions, SendFilesToThreadResult } from '../utils/fileSendService';
+/**
+ * @name MarkupDialect
+ * @description How a connector wants the semantic text spelled. Advertised
+ * rather than assumed, because a renderer that guesses wrong produces visible
+ * garbage (raw `<b>` tags) instead of failing.
+ *
+ * - `telegramHtml` — Telegram's small HTML subset.
+ * - `markdown` — CommonMark-ish, what most trackers accept.
+ * - `plain` — no markup at all; a renderer must strip rather than escape.
+ */
+export type MarkupDialect = 'telegramHtml' | 'markdown' | 'plain';
+/**
+ * @description What a surface can actually do, so the core can degrade instead
+ * of assuming. Every flag has a defined fallback the core must take when it is
+ * `false`; a connector never silently no-ops a capability it lacks.
+ */
+export interface ConnectorCapabilities {
+    /** Can an already-sent message be rewritten? False → send a new message instead. */
+    editMessages: boolean;
+    /** Can a message be kept visible at the top of the conversation? False → skip pinning. */
+    pinMessages: boolean;
+    /**
+     * Can options be offered as tappable controls? False → the enumerated text
+     * list stays (it is rendered either way) and the user answers by index.
+     */
+    tappableOptions: boolean;
+    /** Can files be delivered into the conversation? False → say so instead of sending. */
+    attachments: boolean;
+    /** Does the surface have threads of its own, or is a conversation flat? */
+    threadedReplies: boolean;
+    /** Is there a "the other side is working" affordance? False → `setActivity` is a no-op. */
+    activityIndicator: boolean;
+    /** Hard per-message character cap the connector's own splitter honours. */
+    maxMessageChars: number;
+    /** The dialect {@link OutboundContent.text} should be written in. */
+    markupDialect: MarkupDialect;
+}
+/**
+ * @description One choice the core is offering the user.
+ *
+ * `id` is what comes back on selection; `label` is what is shown. A connector
+ * with {@link ConnectorCapabilities.tappableOptions} renders these as controls,
+ * one without renders nothing extra — the enumerated list is already part of
+ * {@link OutboundContent.text}.
+ */
+export interface OutboundOption {
+    id: string;
+    label: string;
+    description?: string;
+}
+/**
+ * @description One piece of outbound content: semantic text plus the optional
+ * structure that goes with it.
+ *
+ * `text` is NOT pre-rendered for any surface — it is written in the dialect the
+ * connector advertised, and the connector escapes, renders and splits it.
+ */
+export interface OutboundContent {
+    text: string;
+    /**
+     * Choices the user may pick from. Always ALSO enumerated inside `text`, so a
+     * surface without tappable controls loses nothing but the tap.
+     */
+    options?: OutboundOption[];
+    /**
+     * Ask the surface to keep this message prominent (Telegram: pin, so a muted
+     * topic still notifies). Advisory — ignored where
+     * {@link ConnectorCapabilities.pinMessages} is false.
+     */
+    keepVisible?: boolean;
+}
+/**
+ * @description Advisory delivery hints riding one piece of content.
+ *
+ * Every flag describes the content's RELATIONSHIP to the turn around it, never
+ * a rendering instruction: a connector honours what its surface can express and
+ * ignores the rest without the core noticing. They are the agent adapters'
+ * `output` event metadata, which is why the vocabulary is streaming-shaped.
+ */
+export interface OutboundHints {
+    /**
+     * True when this text directly continues the previous emit of the same
+     * in-flight response (a streaming tail cut mid-sentence, possibly mid-word).
+     * A surface that can edit appends it to the message it is already rendering —
+     * concatenated as-is, no separator — instead of starting a new message.
+     * Absent/false = a standalone emit (new logical message).
+     */
+    isContinuation?: boolean;
+    /**
+     * True when this is the LAST frame of a turn (emitted as the session goes
+     * idle). The connector flushes it promptly instead of waiting out the
+     * possibly-429-stretched debounce, so the final message never lingers behind
+     * a cooldown. Only affects flush TIMING — append/continuation semantics are
+     * unchanged.
+     */
+    isFinal?: boolean;
+    /**
+     * True when this is a COMPLETE one-shot block, whole at emit time (e.g. the
+     * "↩️ Resumed — last N messages" context block) rather than a live streaming
+     * tail. The connector posts it instantly as a single message: Telegram's DM
+     * path SKIPS the native draft channel (whose typing animation would otherwise
+     * "draw" already-ready text progressively), and flushes the persist
+     * immediately (like {@link OutboundHints.isFinal}) instead of waiting out the
+     * debounce.
+     */
+    isComplete?: boolean;
+    /**
+     * True when this text comes from a SUB-AGENT (OpenCode: child session SSE;
+     * Claude: on-disk transcript tail), only emitted in `/subagent full` mode.
+     * The connector renders the chunk visibly marked ("🤖 ⤷ …") and OUTSIDE the
+     * parent reply's continuation chain — a child transcript must never become
+     * the base the parent's next continuation is appended to (it would corrupt
+     * the answer's accounting).
+     */
+    isSubagent?: boolean;
+    /**
+     * True when this text is the agent's OWN compaction summary streaming as
+     * ordinary output (OpenCode's summary message, `streamsCompactionSummary`).
+     * The core drops it unless `/compact_summary` is on for the topic — the same
+     * switch that gates the summary the bot posts for the other backends — so a
+     * connector only ever sees it when it is meant to be shown.
+     */
+    isCompactionSummary?: boolean;
+    /**
+     * True when this content is an interactive question the user is expected to
+     * answer. The connector gives it its own prominent message rather than
+     * appending it to the streaming cursor. (Claude scrapes questions out of its
+     * TUI and marks them here; OpenCode has a discrete question event with its
+     * own path.)
+     */
+    isQuestion?: boolean;
+    /**
+     * True when the source had a paragraph break immediately before this chunk's
+     * first new line (carried out-of-band because the relay pipeline's `.trim()`s
+     * would strip a leading blank). The connector inserts a blank-line (`\n\n`)
+     * separator when APPENDING this chunk to a pending buffer / live draft, so
+     * multi-paragraph answers keep their structure; IGNORED when the chunk starts
+     * a fresh message (a message must never start blank). OpenCode never sets it —
+     * it re-renders the full accumulated text, so blanks already survive.
+     */
+    startsNewParagraph?: boolean;
+}
+/**
+ * @name ActivityState
+ * @description What the conversation should look like it is doing.
+ * `working` while the agent is producing an answer, `idle` once the turn is
+ * drained. `starting` is a session booting that will say nothing until the
+ * user's next prompt (so no sustained indicator to stop later): a ONE-SHOT cue.
+ * A surface without an activity affordance ignores all three.
+ */
+export type ActivityState = 'working' | 'idle' | 'starting';
+/**
+ * @description A request to deliver files from the thread's bound folder.
+ *
+ * Reuses the file service's options verbatim: path safety, type classification
+ * and the album/size decision are already platform-neutral and live in
+ * `utils/fileSendService.ts`; only the transmission is connector work.
+ */
+export type OutboundFileRequest = SendFilesToThreadOptions;
+/** Outcome of {@link ConnectorOutbound.deliverFile}, relayed to the agent verbatim. */
+export type OutboundFileResult = SendFilesToThreadResult;
+/**
+ * @description The outbound side of a connector — the ONLY way the core reaches
+ * a user.
+ *
+ * `deliverFile` and `setActivity` are part of the contract rather than optional
+ * extras: the agent-facing MCP surface sends files, images and video, and the
+ * "the agent is working" affordance is one of the three jobs this seam exists to
+ * own (reply / stream / typing). A connector whose surface lacks either still
+ * implements it — declaring the capability `false` and degrading — so the core
+ * never needs a per-platform branch.
+ */
+export interface ConnectorOutbound {
+    /** Send one piece of semantic content into the conversation. */
+    deliver(key: SessionKey, content: OutboundContent, hints?: OutboundHints): Promise<void>;
+    /** Send files from the thread's bound folder into the conversation. */
+    deliverFile(key: SessionKey, request: OutboundFileRequest): Promise<OutboundFileResult>;
+    /** Show or clear the "working" affordance, or give the one-shot `starting` cue. Fire-and-forget by design. */
+    setActivity(key: SessionKey, activity: ActivityState): void;
+    /**
+     * Land anything still in flight for the conversation as permanent content, so
+     * a teardown can never discard the agent's final answer. Idempotent.
+     */
+    finalize(key: SessionKey): Promise<void>;
+    /** Drop per-conversation delivery state on a full teardown. Called AFTER {@link finalize}. */
+    dispose(key: SessionKey): void;
+    /**
+     * True while in-flight content still "owns" the live message. The core reads
+     * it to avoid interleaving a status frame into a half-written answer.
+     */
+    checkIsDelivering(key: SessionKey): boolean;
+    /**
+     * Conversations holding content that {@link finalize} would still land. The
+     * graceful-shutdown flush drains these before the process exits.
+     */
+    listUnfinalizedKeys(): SessionKey[];
+    /** What this surface can do. Read by the core to pick the rich or degraded path. */
+    readonly capabilities: ConnectorCapabilities;
+}
+/** @description The outbound of each platform this process serves. */
+export type ConnectorOutbounds = ReadonlyMap<PlatformId, ConnectorOutbound>;
+/**
+ * @description The outbound of a conversation's platform — the one lookup every
+ * core site goes through, so a conversation of another platform never reaches a
+ * Telegram send. Throws for a platform with no outbound here: a conversation
+ * this process holds always belongs to a platform it wired, so that is a bug.
+ */
+export declare function getConnectorOutbound(outbounds: ConnectorOutbounds, key: SessionKey): ConnectorOutbound;
+//# sourceMappingURL=outbound.d.ts.map

package/dist/platform/outbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.d.ts","sourceRoot":"","sources":["../../src/platform/outbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAElG;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,UAAU,GAAG,OAAO,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,YAAY,EAAE,OAAO,CAAC;IACtB,0FAA0F;IAC1F,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,uFAAuF;IACvF,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,eAAe,EAAE,OAAO,CAAC;IACzB,2FAA2F;IAC3F,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAE3D,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,uEAAuE;IACvE,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACxF,8GAA8G;IAC9G,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5D;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,8FAA8F;IAC9F,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5C;;;OAGG;IACH,mBAAmB,IAAI,UAAU,EAAE,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;CAC9C;AAED,sEAAsE;AACtE,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,kBAAkB,EAAE,GAAG,EAAE,UAAU,GAAG,iBAAiB,CAItG"}

package/dist/platform/outbound.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * @description The outbound half of the platform seam: what the core hands ANY
+ * surface, and what it may assume that surface can do.
+ *
+ * The core emits SEMANTIC content — text plus the structure it means (a set of
+ * options the user should pick from, a request to keep the message visible) —
+ * and never a rendered message. Telegram's HTML subset, a tracker's document
+ * format and Teams' cards are mutually incompatible, and so are their length
+ * limits, so rendering and splitting belong to the connector on the far side of
+ * this file.
+ *
+ * Deliberately NOT here: markup dialects, message limits, keyboards, pins,
+ * edit-in-place vs draft-cursor streaming. Those are connector-internal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConnectorOutbound = getConnectorOutbound;
+/**
+ * @description The outbound of a conversation's platform — the one lookup every
+ * core site goes through, so a conversation of another platform never reaches a
+ * Telegram send. Throws for a platform with no outbound here: a conversation
+ * this process holds always belongs to a platform it wired, so that is a bug.
+ */
+function getConnectorOutbound(outbounds, key) {
+    const outbound = outbounds.get(key.platform);
+    if (!outbound)
+        throw new Error(`No connector outbound for platform "${key.platform}"`);
+    return outbound;
+}
+//# sourceMappingURL=outbound.js.map

package/dist/platform/outbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.js","sourceRoot":"","sources":["../../src/platform/outbound.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AA8NH,oDAIC;AAVD;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,SAA6B,EAAE,GAAe;IACjF,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/platform/unservedStateGuard.d.ts

@@ -0,0 +1,27 @@
+import type { PlatformId, SessionKey } from '../sessionKey';
+import type { StateStore } from '../state';
+/**
+ * @description R13 (Jira connector plan J4b): an instance never boots on another
+ * platform's state. Every boot scan already skips a conversation it does not
+ * serve, but the state is shared: a Telegram instance's save, unbind or sweep
+ * rewrites the file another platform's conversations live in, and two instances
+ * on one `DATA_DIR` would fight over it. So a `DATA_DIR` that holds bindings,
+ * open requests, schedules or armed retries of a platform outside `CONNECTORS`
+ * stops the start instead.
+ */
+/** What a conversation left in the state, named for the start-up message. */
+export type PersistedConversationKind = 'bindings' | 'open requests' | 'schedules' | 'armed retries';
+export interface PersistedConversation {
+    kind: PersistedConversationKind;
+    key: SessionKey;
+}
+/** The part of the store the guard reads. */
+export type PersistedConversationSource = Pick<StateStore, 'listBindings' | 'getOpenRequests' | 'getSchedules' | 'getApiRetries'>;
+export declare function getPersistedConversations(source: PersistedConversationSource): PersistedConversation[];
+/**
+ * @description The start-up error for conversations outside `platforms`, counted
+ * per platform and kind (no keys: they name chats and issues); `null` when
+ * every conversation is served.
+ */
+export declare function getUnservedStateError(conversations: readonly PersistedConversation[], platforms: ReadonlySet<PlatformId>): string | null;
+//# sourceMappingURL=unservedStateGuard.d.ts.map

package/dist/platform/unservedStateGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unservedStateGuard.d.ts","sourceRoot":"","sources":["../../src/platform/unservedStateGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C;;;;;;;;GAQG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,eAAe,GAAG,WAAW,GAAG,eAAe,CAAC;AAErG,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,yBAAyB,CAAC;IAChC,GAAG,EAAE,UAAU,CAAC;CACjB;AAED,6CAA6C;AAC7C,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,GAAG,iBAAiB,GAAG,cAAc,GAAG,eAAe,CAAC,CAAC;AAUlI,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,2BAA2B,GAAG,qBAAqB,EAAE,CAOtG;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,SAAS,qBAAqB,EAAE,EAC/C,SAAS,EAAE,WAAW,CAAC,UAAU,CAAC,GACjC,MAAM,GAAG,IAAI,CAaf"}

package/dist/platform/unservedStateGuard.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPersistedConversations = getPersistedConversations;
+exports.getUnservedStateError = getUnservedStateError;
+const sessionKey_1 = require("../sessionKey");
+const connectorSet_1 = require("./connectorSet");
+/** Keys that do not parse are skipped, as every boot scan skips them. */
+function getParsedKeys(kind, keyStrings) {
+    return keyStrings.flatMap((keyString) => {
+        const key = (0, sessionKey_1.tryKeyFromString)(keyString);
+        return key ? [{ kind, key }] : [];
+    });
+}
+function getPersistedConversations(source) {
+    return [
+        ...source.listBindings().map(({ key }) => ({ kind: 'bindings', key })),
+        ...getParsedKeys('open requests', Object.keys(source.getOpenRequests())),
+        ...getParsedKeys('schedules', Object.values(source.getSchedules()).map((schedule) => schedule.threadKey)),
+        ...getParsedKeys('armed retries', Object.keys(source.getApiRetries())),
+    ];
+}
+/**
+ * @description The start-up error for conversations outside `platforms`, counted
+ * per platform and kind (no keys: they name chats and issues); `null` when
+ * every conversation is served.
+ */
+function getUnservedStateError(conversations, platforms) {
+    const countsByPlatform = new Map();
+    for (const { kind, key } of conversations) {
+        if ((0, connectorSet_1.checkIsServedConversation)(key, platforms))
+            continue;
+        const counts = countsByPlatform.get(key.platform) ?? new Map();
+        counts.set(kind, (counts.get(kind) ?? 0) + 1);
+        countsByPlatform.set(key.platform, counts);
+    }
+    if (countsByPlatform.size === 0)
+        return null;
+    const details = [...countsByPlatform].map(([platform, counts]) => `${platform} (${[...counts].map(([kind, count]) => `${kind}: ${count}`).join(', ')})`);
+    return `DATA_DIR holds conversations of a platform this instance does not serve — ${details.join('; ')}. ` +
+        'Start the instance that serves them on this DATA_DIR, or give this one a DATA_DIR of its own.';
+}
+//# sourceMappingURL=unservedStateGuard.js.map

package/dist/platform/unservedStateGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unservedStateGuard.js","sourceRoot":"","sources":["../../src/platform/unservedStateGuard.ts"],"names":[],"mappings":";;AAkCA,8DAOC;AAOD,sDAgBC;AA/DD,8CAAiD;AAEjD,iDAA2D;AAuB3D,yEAAyE;AACzE,SAAS,aAAa,CAAC,IAA+B,EAAE,UAA6B;IACnF,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE;QACtC,MAAM,GAAG,GAAG,IAAA,6BAAgB,EAAC,SAAS,CAAC,CAAC;QACxC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAgB,yBAAyB,CAAC,MAAmC;IAC3E,OAAO;QACL,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,EAAyB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7F,GAAG,aAAa,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;QACxE,GAAG,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACzG,GAAG,aAAa,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;KACvE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CACnC,aAA+C,EAC/C,SAAkC;IAElC,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAsD,CAAC;IACvF,KAAK,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,aAAa,EAAE,CAAC;QAC1C,IAAI,IAAA,wCAAyB,EAAC,GAAG,EAAE,SAAS,CAAC;YAAE,SAAS;QACxD,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,GAAG,EAAqC,CAAC;QAClG,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9C,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,gBAAgB,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,OAAO,GAAG,CAAC,GAAG,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,CAC/D,GAAG,QAAQ,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzF,OAAO,6EAA6E,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACxG,+FAA+F,CAAC;AACpG,CAAC"}

package/dist/postToSession.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @description Post a prompt into a conversation's agent session (Jira connector
+ * plan J5, D21): make sure a session is ready — the ensure resumes the
+ * conversation's own sleeping session, else starts one if needed — let a
+ * BUSY session finish its turn (up to {@link waitIdleTimeoutMs} — live work is
+ * never interrupted on purpose; after the bound the forward takes the normal
+ * interrupt path), then forward — unless an armed usage-limit wait holds the
+ * prompt, checked before the session is touched and again right before the
+ * forward (R23). The scheduler's fire (steps 3–4) and the Jira
+ * connector's requests share it. Every side effect is injected, so the wait
+ * loop runs on a fake clock in tests.
+ */
+/** Poll cadence for the wait-for-idle loop: re-check the busy probe every 5s. */
+export declare const busyPollIntervalMs = 5000;
+/**
+ * Upper bound on waiting for a busy session to go idle before forwarding anyway
+ * (10 min). The forward then takes the normal interrupt path, so a wedged turn
+ * never blocks a post forever.
+ */
+export declare const waitIdleTimeoutMs: number;
+/**
+ * @name EnsureSessionResult
+ * @description What {@link PostToSessionDeps.ensureSession} reports back. It
+ * mirrors bot.ts's `ensureAgentSession` outcome without importing it: `ok` means
+ * a session is ready (active, mid-startup, or just started — a prompt forwarded
+ * now is delivered or buffered-then-replayed); `unbound`/`no-adapter`/
+ * `start-failed` are the three failure reasons (`no-adapter` = a bound
+ * conversation that never picked an agent, with no fallback adapter given).
+ */
+export type EnsureSessionFailureReason = 'unbound' | 'no-adapter' | 'start-failed';
+/** `isFresh` — the ensure started a NEW conversation (a start, or a resume that failed and fell back to one). */
+export type EnsureSessionResult = {
+    ok: true;
+    isFresh: boolean;
+} | {
+    ok: false;
+    reason: EnsureSessionFailureReason;
+};
+/**
+ * @name SessionPromptText
+ * @description A prompt whose text depends on the session it lands in (Jira prompt
+ * context C5): `buildText` runs right before the forward — after the ensure, the
+ * wait for idle and the second limit check — and is told whether the session is
+ * fresh; `fullText` is what stands on its own (a hold keeps it, a re-post sends it).
+ */
+export interface SessionPromptText {
+    fullText: string;
+    buildText: (context: {
+        isFresh: boolean;
+    }) => string;
+}
+/**
+ * @name PostToSessionDeps
+ * @description `conversationKey` is the serialized `SessionKey`; the bot's
+ * lambdas parse it back where needed.
+ */
+export interface PostToSessionDeps {
+    /**
+     * Optional: hold the prompt while the conversation waits out an armed usage
+     * limit (Jira plan R23) — posting it would only hit the limit again; it reaches
+     * the session once the wait ends. `true` = held, nothing else to do now.
+     * `heldText` — what it says when it arrives late (R27); the run is `text`.
+     */
+    holdForLimitResume?: (conversationKey: string, text: string, heldText?: string) => boolean;
+    /** Whether the conversation's agent is mid-turn right now (sync, in-memory probe). */
+    checkBusy: (conversationKey: string) => boolean;
+    /** Ensure a session is ready: a sleeping one is resumed by its id (a tracker issue keeps one conversation for
+     *  good, Jira plan D5); one with nothing to resume is started with `fallbackAdapterName`. */
+    ensureSession: (conversationKey: string, fallbackAdapterName?: string) => Promise<EnsureSessionResult>;
+    /** Forward the prompt to the conversation's agent. */
+    forwardPrompt: (conversationKey: string, text: string) => Promise<void>;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * @name PostToSessionResult
+ * @description `isHeld` — an armed usage-limit wait held the prompt; it reaches the
+ * session once the wait ends. `forward-failed` carries the forward's own error message.
+ */
+export type PostToSessionResult = {
+    ok: true;
+    isHeld: boolean;
+} | {
+    ok: false;
+    reason: EnsureSessionFailureReason;
+} | {
+    ok: false;
+    reason: 'forward-failed';
+    error: string;
+};
+export declare function postToSession(deps: PostToSessionDeps, conversationKey: string, prompt: string | SessionPromptText, fallbackAdapterName?: string, options?: {
+    heldText?: string;
+}): Promise<PostToSessionResult>;
+//# sourceMappingURL=postToSession.d.ts.map

package/dist/postToSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postToSession.d.ts","sourceRoot":"","sources":["../src/postToSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAiB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,YAAY,GAAG,cAAc,CAAC;AAEnF,iHAAiH;AACjH,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,CAAC;AAErH;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,CAAC;CACtD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3F,sFAAsF;IACtF,SAAS,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD;iGAC6F;IAC7F,aAAa,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,mBAAmB,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvG,sDAAsD;IACtD,aAAa,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAU3D,wBAAsB,aAAa,CACjC,IAAI,EAAE,iBAAiB,EACvB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAClC,mBAAmB,CAAC,EAAE,MAAM,EAC5B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,mBAAmB,CAAC,CAiB9B"}