@open-everywhere/provider-slack 0.1.0

package/dist/agent/channels/slack-wake-backscroll.d.ts

@@ -0,0 +1,188 @@
+import { WAKE_BACKSCROLL_MAX, type ContextLine, type NormalizedMessage, type BackscrollTrustFor, type SeatAdmissionFn, type SeatCatchUpFetch, type SeatCatchUpRequest, type WakeMessageInput } from "@open-everywhere/core/agent/adapter-api.js";
+export { WAKE_BACKSCROLL_MAX };
+/**
+ * The widest THREAD slice this module hands a caller that ADMITS BEFORE IT CAPS (OPE-1744,
+ * {@link WakeBackscrollInput.threadAdmissionSlice}). Five times {@link WAKE_BACKSCROLL_MAX}, so the
+ * policy can look past a long run of refused replies and still fill the ten-line slot; half the page
+ * the thread fetch buys, so the slice stays bounded.
+ * 🔴 IT IS A COST BOUND, AND THE COST IS THE CALLER'S PER-AUTHOR PROBE. Slack's hydration regrades
+ * every returned line before it admits, and that regrade runs one TTL-cached `users.info` per
+ * DISTINCT vouchable author. Handing back the whole 100-reply page would put that fan-out on a busy
+ * thread; the probe fails OPEN, so an exhausted burst demotes nobody and a guest keeps the tier a
+ * confirmed-internal channel gives. The slice is bounded here to keep that burst small.
+ */
+export declare const THREAD_ADMISSION_MAX: number;
+/** The Slack bot's resolved identity — used to label the agent's own prior posts as `agent`. */
+export interface WakeBotIdentity {
+    readonly userId?: string;
+    readonly botId?: string;
+}
+/** A Slack Web-API caller: POSTs `method` with url-encoded `params`, returns parsed JSON or
+ *  undefined on any failure (fail-soft). Injected so the fetcher is unit-testable offline. */
+export type SlackRequester = (method: string, params: Record<string, string>) => Promise<Record<string, unknown> | undefined>;
+/** The triggering event, narrowed to what the backscroll needs. */
+export interface WakeBackscrollInput {
+    readonly channelId: string;
+    /** The triggering message's ts. */
+    readonly ts: string;
+    /** Thread root ts — present ⇒ in-thread wake (conversations.replies); absent ⇒ top-level. */
+    readonly threadTs?: string;
+    /**
+     * THREAD LEG ONLY (OPE-1744): hand back the ADMISSION slice — up to {@link THREAD_ADMISSION_MAX}
+     * replies rather than the render cap's {@link WAKE_BACKSCROLL_MAX} — so the caller filters first
+     * and caps after. That is the order channels/seat-admission.ts {@link admitToSeat} states ("filter,
+     * then let the caller cap — never the reverse, or a refused bot's bytes would eat a person's
+     * message out of the cap"). A caller that applies an admission policy asks for it and caps with
+     * `capLines` once the policy has run; every other caller leaves it absent and gets the render-cap
+     * slice it always got.
+     * 🔴 IT MOVES THE CAP, NEVER THE POLICY. The admission stays ABOVE this seam, in the caller, so a
+     * wiring that supplies its own `backscroll` still cannot bypass it — a cap is a budget, not a
+     * security control, which is why this is the half that may cross.
+     * The CHANNEL leg ignores it: its raw fetch asks Slack for {@link WAKE_BACKSCROLL_MAX} messages, so
+     * there is no wider slice to hand back and backfilling would mean buying a bigger page.
+     */
+    readonly threadAdmissionSlice?: boolean;
+}
+/** Injected seams so the fetcher runs without a network (tests) but defaults to live Slack. */
+export interface WakeBackscrollDeps {
+    readonly request: SlackRequester;
+    readonly identity: () => Promise<WakeBotIdentity>;
+}
+/** Reset the cached wake bot identity (tests only). */
+export declare function _resetWakeBotIdentity(): void;
+/** The RAW-lines result of a name-drop backscroll fetch (W3): the oldest-first
+ *  {@link ContextLine}s — capped at {@link WAKE_BACKSCROLL_MAX}, or at the wider
+ *  {@link THREAD_ADMISSION_MAX} where the caller asked for the thread leg's admission slice
+ *  ({@link WakeBackscrollInput.threadAdmissionSlice}) and caps itself — plus the renderContext
+ *  `source` label and the Slack read-more hint. The renderer
+ *  ({@link renderContext}, called inside renderWake) turns these into the untrusted-wrapped context
+ *  block — so no pre-rendered string ever flows through the wake plumbing. `null` = nothing to add
+ *  OR any failure (always non-fatal). */
+export interface WakeBackscrollLines {
+    readonly lines: readonly ContextLine[];
+    readonly source: string;
+    /** Slack HAS read tools, so the hint names them; renderContext appends it OUTSIDE the untrusted
+     *  block only when the slice actually hit the cap. */
+    readonly readMoreHint: string;
+}
+/**
+ * Fetch recent conversation history for a name-drop wake as RAW ContextLines + source + hint (W3) —
+ * the renderer wraps them (renderContext, inside renderWake). `null` = nothing to add OR any
+ * failure (always non-fatal).
+ *
+ * - IN-THREAD wake (`threadTs`): `conversations.replies`, sliced to "since the agent's last reply"
+ *   (see {@link sinceLastAgentReply}); the triggering message itself is excluded (the wake message
+ *   already carries its text). Capped at {@link WAKE_BACKSCROLL_MAX}, or at the wider
+ *   {@link THREAD_ADMISSION_MAX} when the caller asks for the admission slice
+ *   ({@link WakeBackscrollInput.threadAdmissionSlice}).
+ * - TOP-LEVEL wake (no `threadTs`): `conversations.history` with `latest = ts`, `inclusive: false`
+ *   → strictly-older messages only, most recent N.
+ */
+export declare function fetchWakeBackscrollLines(input: WakeBackscrollInput, deps?: WakeBackscrollDeps): Promise<WakeBackscrollLines | null>;
+/**
+ * Fetch recent conversation history for a name-drop wake, rendered as `context` strings
+ * (untrusted-wrapped, oldest-first, capped at {@link WAKE_BACKSCROLL_MAX}). Empty array = nothing to
+ * add OR any failure. Thin wrapper over {@link fetchWakeBackscrollLines} + the shared renderContext,
+ * so its output stays byte-identical to before the W3 refactor (retained for its existing callers
+ * and byte-identity tests; the live name-drop path now uses the lines variant directly).
+ */
+export declare function fetchWakeBackscroll(input: WakeBackscrollInput, deps?: WakeBackscrollDeps): Promise<string[]>;
+/** Reachback (hours) for the raw Slack window: how far back from the trigger conversations.history
+ *  is paginated. Generous enough that the SPINE (the most-recent cluster, exempt from the 36h
+ *  enrichment cap) can still reach across a weekend/overnight gap (~66h Fri-4pm→Mon-10am), yet a
+ *  hard floor that bounds the fetch. 7d default; overridable for ops/testing. */
+export declare const RAW_FETCH_REACHBACK_HOURS: number;
+/**
+ * The VISIBILITY / TRUST GATE (spec §Bounds — the load-bearing SECURITY filter): backscroll must
+ * never surface a message it can't ATTRIBUTE. The channel-internal confirmation
+ * (confirmChannelInternalWithMeta) fail-closes the restricted-area / at-rest-isolation dimension
+ * BEFORE this fetcher is ever called. So the per-message gate here KEEPS:
+ *   - the bot's OWN prior posts (`agent` → `self`);
+ *   - identifiable humans (`user` → `human`);
+ *   - ATTRIBUTABLE foreign bots (`bot` WITH a bot id → `bot`) — INCLUDED as MARKED AWARENESS
+ *     (clearly bot-flagged, CONTEXT-ONLY, never a wake trigger). Design intent: the supervisor
+ *     SHOULD see foreign-bot posts, and dropping them breaks CONVERSATIONAL COHERENCE — a human
+ *     replying to a bot's message would otherwise arrive with the bot message missing, so the agent
+ *     couldn't tell what the human is responding to.
+ * and DROPS ONLY:
+ *   - unattributable senders (`unknown`, or a `bot` with no id) — no auth'd author ⇒ fail closed.
+ * (System-subtype noise is already dropped upstream by linesFromMessages.) Foreign-bot messages are
+ * CONTEXT-ONLY on this path: the neutral core never sets `trigger` on backscroll, and the LIVE
+ * trigger gate (slack-events.ts shouldSupervisorWake) still drops bot-authored messages as triggers,
+ * so a bot post is awareness, never a response obligation. Wired explicitly + unit-tested
+ * (slack-wake-backscroll-test.ts) so it can't be forgotten.
+ */
+export declare function isBackscrollVisible(line: ContextLine): boolean;
+export interface WakeEnvelopeBackscrollInput {
+    readonly channelId: string;
+    /** The triggering message's ts — the window's upper (exclusive) bound and the reachback origin. */
+    readonly ts: string;
+    /** Known thread root for a thread-bound catch-up. Present ⇒ read that thread directly; a root
+     * older than `sinceMs` is absent from `conversations.history` but its newer replies are not. */
+    readonly threadRoot?: string;
+    /** Hours to look back from `ts` for the raw fetch. Defaults to {@link RAW_FETCH_REACHBACK_HOURS}. */
+    readonly reachbackHours?: number;
+    /**
+     * THE CATCH-UP BOUND (OPE-1695 (b)): epoch milliseconds of the seat's own LAST WAKE, so this read
+     * returns what the room said since the seat last looked. It only ever NARROWS the window — the
+     * reachback floor above still applies — so a seat quiet for a month reads the recent tail, and a
+     * seat with no recorded wake reads the bootstrap window exactly as a first wake always did.
+     */
+    readonly sinceMs?: number;
+}
+/**
+ * SLACK FETCH SEAM: fetch a bounded, visibility-GATED, NORMALIZED backscroll window (channel history
+ * + in-window thread replies) for a supervisor first wake. This is the platform boundary — the
+ * neutral core ({@link fetchedBackscroll}) consumes its output. FAIL-SOFT: any error/failure yields
+ * `[]`. Deduped by message id (a thread root appears in both history and its replies[0]).
+ */
+export declare function fetchSlackBackscrollWindow(input: WakeEnvelopeBackscrollInput, deps?: WakeBackscrollDeps, failureMode?: "soft" | "throw"): Promise<NormalizedMessage[]>;
+/**
+ * SLACK'S REGISTERED CATCH-UP FETCH (OPE-1726) — the one thing this surface contributes to the shared
+ * since-last-wake path (core channels/seat-catch-up.ts). It is the SAME window fetch the bootstrap
+ * arm takes ({@link fetchSlackBackscrollWindow}), addressed by the neutral request shape: the seat's
+ * container, bounded below by its last wake and above by the trigger.
+ * 🔴 THE UPPER BOUND IS RE-EXPRESSED AS A SLACK `ts`, because `conversations.history` takes `latest`
+ * in Slack's own seconds-with-fraction form and not epoch ms. `excludeId` IS that ts on this surface
+ * (a Slack ts is both a time and an id), so it is preferred over the derived string — a derived one
+ * can lose the trailing digits Slack's ordering depends on. With neither, the read falls back to
+ * `now`, which is the honest upper bound for a catch-up with no stated trigger.
+ * A transport/read failure propagates to core's shared boundary, which keeps the wake alive and
+ * records `failed` instead of reporting a quiet channel (OPE-1842). Bootstrap callers keep the
+ * window fetch's default fail-soft mode.
+ */
+export declare function fetchSlackSeatCatchUp(req: SeatCatchUpRequest, deps?: WakeBackscrollDeps): Promise<readonly NormalizedMessage[]>;
+/**
+ * A Slack `ts` is a second with a six-digit fraction, so it carries MILLISECOND grain (OPE-1847,
+ * `core/agent/channels/seat-catch-up.ts` {@link SeatCatchUpDeclaration.timestampPrecisionMs}).
+ * 🔴 ONE MILLISECOND IS NOT ZERO WIDENING. The road widens the LOWER bound by nothing here and the
+ * UPPER bound by exactly one millisecond, so a message stamped at the trigger's own instant is
+ * INSIDE the window and `excludeId` is the only thing that removes the trigger. That holds on this
+ * surface twice over: `conversations.history` is called with `inclusive: "false"`, so the trigger
+ * never reaches the fetch, and a message that did would carry its `ts` as its id — the same value
+ * the wake path passes as `excludeId`.
+ * 🔴 THE DECLARATION CANNOT EXPRESS THIS SURFACE'S SUB-MILLISECOND `ts`. The unit is a whole number
+ * of milliseconds, so the road's floor rounds Slack's fraction away. It costs nothing today: the
+ * bound is a bound, not an ordering, and the fetch orders by `ts` itself.
+ * 🔴 IT IS STILL DECLARED, and the parity test requires it. The declaration is what makes "this
+ * surface needs the finest unit" a CHECKED claim rather than an omission, and an omission is
+ * indistinguishable from the GitHub and Notion defect this whole mechanism exists to close.
+ */
+export declare const SLACK_TIMESTAMP_PRECISION_MS = 1;
+/** The registered form — the transport seam is fixed to the live one, so a caller cannot inject past
+ *  the bot token. Tests drive {@link fetchSlackSeatCatchUp} with a canned requester instead. */
+export declare const slackSeatCatchUpFetch: SeatCatchUpFetch;
+/**
+ * Fetch + cluster a standing seat's channel backscroll into session-tagged
+ * {@link WakeMessageInput} entries (oldest-first, no `trigger`; per-message trust via
+ * `trustFor` when the caller supplies the resolver, the fail-closed per-sender default otherwise).
+ * Thin orchestration over the Slack fetch seam ({@link fetchSlackBackscrollWindow}) + the neutral
+ * capped core ({@link fetchedBackscroll}), which applies the domain's `admit` policy. Serves the
+ * BOOTSTRAP window ONLY — a fresh generation's first wake, the one read with no cross-surface twin.
+ * Since OPE-1726 the since-last-wake CATCH-UP is not this function's job: it runs through
+ * {@link fetchSlackSeatCatchUp}, registered into the shared core path (core channels/seat-catch-up.ts
+ * `seatCatchUp`), which owns the bounds, the admission policy and the cap for every surface. This
+ * function still ACCEPTS `input.sinceMs`, but no caller sets it. FAIL-SOFT ABSOLUTELY.
+ */
+export declare function fetchWakeEnvelopeBackscroll(input: WakeEnvelopeBackscrollInput, deps?: WakeBackscrollDeps, trustFor?: BackscrollTrustFor, admit?: SeatAdmissionFn): Promise<WakeMessageInput[]>;
+//# sourceMappingURL=slack-wake-backscroll.d.ts.map

package/dist/agent/channels/slack-wake-backscroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack-wake-backscroll.d.ts","sourceRoot":"","sources":["../../../agent/channels/slack-wake-backscroll.ts"],"names":[],"mappings":"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"}