@open-everywhere/provider-github 0.0.0-stage → 0.1.0

package/dist/agent/channels/github-reaction-scope.js

@@ -0,0 +1,296 @@
+// THE GITHUB REACTION-POLL SCOPE (OPE-1540) — the two gates that decide whether one delivery is
+// allowed to spend REST calls looking for reactions, and the durable record the first gate reads.
+//
+// WHY A GATE EXISTS AT ALL. GitHub pushes no reaction webhook, so the feedback arm
+// (channels/github-reaction-feedback.ts) POLLS: every signature-verified `issue_comment`/`issues`
+// delivery made it read the issue and a comment page, and only then could it learn that the agent
+// has never commented in that conversation and there is nothing to look at. That is 2–3 installation
+// REST calls per delivery, on the SAME installation token the reply path mints. A repository taking
+// 400 deliveries an hour spent ~800–1200 GETs an hour learning nothing, and the 429 pressure landed
+// on the agent's own posts.
+//
+// ── GATE 1: THE CONVERSATION MUST BE ONE THE AGENT IS IN, AND IT READS TWO RECORDS
+//
+// A reaction the arm can record is a reaction on the AGENT's own comment, so a conversation the agent
+// has never commented in can hold none. Gate 1 answers "is the agent in this conversation" from two
+// durable records, and admits on EITHER. Both are keyed store reads; neither costs a REST call.
+//
+//  1. THE POST CLAIM, written by this bundle's own reply path (channels/github-post-arm.ts
+//     `liveGitHubPost`). That is the one place a GitHub comment leaves THIS BUNDLE — every `reply`
+//     tool call, every unified-window reply and every ambient-supervisor answer.
+//  2. THE ENGAGEMENT ROW, written by the §2.5 seam (channels/github-engagement.ts) when somebody
+//     @mentions the app in a container.
+//
+// 🔴 THE SECOND READ EXISTS BECAUSE THIS BUNDLE IS NOT THE ONLY POSTER. eve's default posts the
+// `input.requested` comment, which this bundle does not override, and it still posts a NATIVE
+// terminal completion on the paths that fall back to it — a review thread's inline reply, and a
+// state with no post anchor (`channels/github.ts`). (An ordinary native terminal completion claims
+// here now: it posts through `liveGitHubPost` since OPE-1681, so that example is no longer one.) Those comments carry the app's login and attract reactions exactly as a `reply`
+// does, and NOTHING in this bundle sees them go out — so a post-claim-only gate would refuse those
+// conversations forever, not merely until the next reply. The engagement row is what covers them: the
+// native leg wakes only on an @mention (which marks the row) or on a plain comment in a container
+// already marked, so every conversation eve can post in has one.
+//
+// 🔴 IT ADMITS A LITTLE MORE THAN "HAS POSTED", ON PURPOSE. A container somebody @mentioned the app
+// in where the app then said nothing is admitted and costs a poll. That is the safe direction — the
+// alternative is a reaction the deployment can never record — and gate 2 caps what it can cost.
+//
+// 🔴 THE POST CLAIM IS A `notice_claim`, AND THE LIFETIME IS THE POINT. "The agent has commented
+// here" never stops being true, so the record must never expire: a TTL would blind the poll to a
+// quiet conversation's reactions the moment the TTL lapsed, and re-writing the mark needs a post
+// nobody is going to make. `claimNotice`/`noticeClaimed` (operational/store.ts) is the tree's
+// at-most-once claim with no TTL and no prune, which is exactly this shape. Growth is one row per
+// conversation the agent has ever commented in — bounded by conversations, never by deliveries.
+//
+// 🔴 WHAT THE CUT-OVER COSTS, STATED. Both records start from what already exists: engagement rows
+// are already there for every container an @mention ever reached, and the post claim starts EMPTY. So
+// a conversation the agent only ever answered ambiently — no @mention, hence no engagement row — and
+// has not answered since this shipped is not polled until it answers there again. The reaction arm
+// landed one day before this gate (OPE-1502, PR #587), so the window of reactions that can fall into
+// that gap is one day wide. It is a real gap, not a theoretical one.
+//
+// FAIL-OPEN on a store error. An unreadable record answers "the agent is in this conversation", so a
+// store blip costs REST calls rather than silently stopping the feedback signal. It is the opposite
+// posture from the reaction DEDUPE next door (channels/github-reaction-feedback.ts), which fails
+// CLOSED — these two gates bound a COST, and that one bounds what the audit log claims happened.
+//
+// ── GATE 2: A PER-REPOSITORY HOURLY BUDGET
+//
+// Gate 1 bounds the poll to conversations the agent is in, which is the big cut. It does NOT bound
+// what one very busy conversation can spend: a hundred comments an hour in a pull request the agent
+// replied to is a hundred polls. So a second gate caps the polls one REPOSITORY may run in one clock
+// hour, and the trip is AUDITED — a silently capped feedback signal reads exactly like a feature that
+// stopped working.
+//
+// 🔴 THE COUNTER IS APPROXIMATE UNDER CONCURRENCY, AND THAT IS ACCEPTED. It is a read-then-write over
+// the opaque `task_result` KV, not an atomic increment, so two deliveries racing on the same repo can
+// both read N and write N+1 — the hour's true count can exceed the budget by roughly the number of
+// concurrent deliveries. A rate budget is a cost bound, not a security control: over-counting would
+// drop feedback that should have been recorded, under-counting costs a few extra GETs. The cheap,
+// non-atomic direction is the one whose failure mode is the harmless one.
+//
+// 🔴 THE TTL IS COUPLED, SO IT IS NOT A KNOB. `task_result`'s prune is ORG-WIDE and uses the CALLING
+// writer's own ttl (operational/store.ts, the task_result section), so every consumer must pass the
+// same six hours. {@link GITHUB_POLL_BUDGET_TTL_MS} exists to be that number and nothing else — a
+// shorter one here would start deleting `model/turn-state.ts`'s live rows on every delivery.
+import { appendAudit, deploymentOrg, getOperationalStore, } from "@open-everywhere/core/agent/adapter-api.js";
+import { githubConversationKey } from "./github-identity.js";
+/** How many reaction polls one repository may run in one clock hour. Sized so an ordinarily busy
+ *  repository never reaches it — the gate is a ceiling on a runaway conversation, not a throttle on
+ *  normal traffic. One ADMITTED poll costs up to 13 GETs (the issue read, one or two comment pages,
+ *  and up to `GITHUB_REACTION_POLL_COMMENT_BUDGET` reaction reads), so this bounds a repository's
+ *  worst hour to ~780 GETs on the installation token the reply path shares. The everyday cost is far
+ *  below that: most polls read three. */
+export const GITHUB_REACTION_POLL_HOURLY_BUDGET = 60;
+/** The `task_result` retention every consumer of that table shares. See the header: it is coupled,
+ *  not tunable. Six hours, the same window `model/turn-state.ts` and the three other consumers use. */
+const GITHUB_POLL_BUDGET_TTL_MS = 6 * 60 * 60 * 1000;
+/** The audit action a tripped budget writes. Queryable over the control plane's audit route, the
+ *  same way `github.ambient_skipped` answers "why did the ambient leg stay quiet". */
+export const GITHUB_REACTION_POLL_BUDGET_ACTION = "github.reaction_poll_budget";
+/** The audit action an UNREADABLE CLAIM STORE writes, once per poll. The dedupe next door fails
+ *  CLOSED, so a store that cannot answer "is this recorded" stops every feedback row for as long as
+ *  it stays down — and a silent zero reads exactly like a quiet week. This row is the signal. It
+ *  carries the same audit ACTION shape as the budget trip above, so an operator reads both off the
+ *  control plane's audit route; the GRAIN differs, and {@link auditGitHubReactionClaimUnreadable}
+ *  says how. */
+export const GITHUB_REACTION_CLAIM_UNREADABLE_ACTION = "github.reaction_claim_unreadable";
+/** How long a reply may wait on the best-effort post claim below.
+ *
+ * 🔴 THE CEILING IS THE POINT, NOT THE NUMBER. `liveGitHubPost` marks the conversation AFTER the
+ * comment has already landed, so this write can only ever delay the reply tool's RETURN — and with
+ * no ceiling a slow store held that return for as long as it liked, on the turn path. Two seconds is
+ * far more than a keyed claim needs and far less than a turn can notice. */
+export const GITHUB_POSTED_MARK_TIMEOUT_MS = 2000;
+/** How long the trip row's once-per-hour guard holds. It is the bucket width, not a dedupe window:
+ *  the key already carries the hour, so this only has to outlive the hour it names. */
+const BUDGET_AUDIT_TTL_MS = 2 * 60 * 60 * 1000;
+/** The claim key for "the agent has commented in this conversation". `githubConversationKey` is the
+ *  SAME `owner/repo#N` anchor the engagement registry and the stop registry address, so the mark and
+ *  every other per-conversation record in this bundle name the container the same way. */
+function githubPostedClaimKey(owner, repo, number) {
+    const anchor = githubConversationKey(owner, repo, number);
+    return anchor ? `github-posted:${anchor}` : undefined;
+}
+/** The hourly budget's key for one repository. The clock hour rides IN the key, so the counter needs
+ *  no reset and a stale bucket simply stops being read. */
+export function githubPollBudgetKey(owner, repo, atIso) {
+    return `github-reaction-poll-budget:${owner}/${repo}:${atIso.slice(0, 13)}`;
+}
+/**
+ * Record that the agent has commented in this conversation. Best-effort and idempotent — a second
+ * post in the same conversation re-claims a key that is already claimed, which the store answers
+ * false to and this function ignores. NEVER THROWS: a lost mark costs a later poll, never a reply.
+ *
+ * 🔴 IT IS ALSO BOUNDED, WHICH IS THE OTHER HALF OF THAT CONTRACT. The one caller is
+ * `liveGitHubPost`, on the reply tool's own path, and it calls this AFTER the comment has landed. An
+ * unbounded await therefore could not lose a reply but could hold the tool's return for as long as
+ * the store took — a real hazard on a tree that already stalls in its post-turn closeout. So the
+ * write RACES {@link GITHUB_POSTED_MARK_TIMEOUT_MS}: a store slower than that is treated exactly
+ * like the store that throws, and costs a later poll rather than the turn.
+ *
+ * The abandoned write is not cancelled — nothing here can cancel a store call — so it carries its
+ * own settled handler and may still land after this returns. That is the harmless direction: the
+ * claim is idempotent and its only reader is the next poll.
+ */
+export async function markGitHubConversationPosted(owner, repo, number, atIso) {
+    const key = githubPostedClaimKey(owner, repo, number);
+    if (!key)
+        return;
+    let write;
+    try {
+        // The `.then(_, _)` is what keeps an abandoned rejection from surfacing as an unhandled one:
+        // after the race gives up, nothing else is holding this promise.
+        write = getOperationalStore()
+            .claimNotice(deploymentOrg(), key, atIso)
+            .then(() => undefined, () => undefined);
+    }
+    catch {
+        // A store that cannot even be resolved. The reply already landed; there is nothing to wait on.
+        return;
+    }
+    // `unref` so the ceiling never keeps a host alive on its own, and `clearTimeout` so a write that
+    // beat it leaves no pending timer behind.
+    let timer;
+    const ceiling = new Promise((resolve) => {
+        timer = setTimeout(resolve, GITHUB_POSTED_MARK_TIMEOUT_MS);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([write, ceiling]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Is the agent IN this conversation — has this bundle's reply path posted here, or did an @mention
+ * engage the container? Either answers yes; see the header for why both reads are needed.
+ *
+ * FAIL-OPEN on a store error, and on a delivery that names no container: an unanswerable question
+ * admits the poll, whose own parse then refuses a delivery that names nothing.
+ */
+export async function githubConversationInScope(surfaceKey, owner, repo, number) {
+    const key = githubPostedClaimKey(owner, repo, number);
+    const anchor = githubConversationKey(owner, repo, number);
+    if (!key || !anchor)
+        return true;
+    const org = deploymentOrg();
+    try {
+        if (await getOperationalStore().noticeClaimed(org, key))
+            return true;
+        // 🔴 THE STORE, NOT `getThreadEngagement`. That helper swallows its own failure and answers
+        // null, so an unreadable registry would be indistinguishable from an un-engaged container and
+        // this gate would fail CLOSED on a store blip — the one direction the header forbids. Reading
+        // the store directly lets the catch below take the fail-open answer for BOTH records. The
+        // coordinates are the helper's own: `p.org` and `p.surfaceKey`, keyed by the container anchor.
+        return (await getOperationalStore().getEngagement(org, surfaceKey, anchor)) !== null;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Spend one poll from this repository's hourly budget.
+ *
+ * Admits and counts while the hour has room; refuses once the budget is spent, and writes ONE
+ * {@link GITHUB_REACTION_POLL_BUDGET_ACTION} row for that hour rather than one per refused delivery —
+ * the refusals are the loud part of a busy hour, and an unthrottled row per delivery would be the
+ * same flood in the audit log that the budget exists to stop in GitHub's API.
+ *
+ * FAIL-OPEN on a store error: an unreadable counter admits the poll. A budget is a cost bound, so a
+ * store blip must never silence the feedback signal.
+ */
+export async function spendGitHubPollBudget(owner, repo, atIso, budget = GITHUB_REACTION_POLL_HOURLY_BUDGET) {
+    const org = deploymentOrg();
+    const key = githubPollBudgetKey(owner, repo, atIso);
+    let used = 0;
+    try {
+        const raw = await getOperationalStore().getTaskResult(org, key);
+        const parsed = raw ? JSON.parse(raw) : undefined;
+        used = typeof parsed?.polls === "number" && Number.isFinite(parsed.polls) ? parsed.polls : 0;
+    }
+    catch {
+        return { admitted: true, polls: 0 };
+    }
+    if (used >= budget) {
+        await auditBudgetTrip(org, owner, repo, atIso, used, budget);
+        return { admitted: false, polls: used };
+    }
+    const polls = used + 1;
+    try {
+        await getOperationalStore().putTaskResult(org, key, JSON.stringify({ polls }), atIso, GITHUB_POLL_BUDGET_TTL_MS);
+    }
+    catch {
+        // The count is lost for this delivery; the poll still runs. Under-counting costs GETs, never a row.
+    }
+    return { admitted: true, polls };
+}
+/**
+ * Write the one row that says this poll's claim store could not be read.
+ *
+ * 🔴 WHY IT EXISTS. The reaction dedupe (channels/github-reaction-feedback.ts) fails CLOSED on an
+ * unreadable claim — an unknown answer counts as ALREADY RECORDED — which is the right posture for
+ * what the audit log claims happened, and a silent one. A store that stays unreadable therefore
+ * records nothing at all, forever, and the operator sees a feature that looks healthy and reports
+ * zero. This row is the difference between "nobody reacted" and "the store is down".
+ *
+ * ONE ROW PER POLL, never one per reaction: a busy comment page holds dozens of reactions and one
+ * broken store would write a row for each. `skipped` carries the count instead, so the row is as
+ * loud as the flood would have been. That is a DIFFERENT GRAIN from the budget trip below, which
+ * `markEventSeen` throttles to one row per repository per hour — this one has no throttle, because a
+ * poll that could not read the store is a distinct event and the count is the thing being reported.
+ *
+ * 🔴 WHAT BOUNDS THE VOLUME, HONESTLY. The poll reaches here only past gate 2, so an ordinary hour
+ * holds at most {@link GITHUB_REACTION_POLL_HOURLY_BUDGET} of these per repository — but only WHILE
+ * THE BUDGET COUNTER IS WRITABLE. Gate 2 fails open on a store error, so a fault that breaks the
+ * `task_result` write while `audit_log` inserts still land gives one row per delivery instead. That
+ * is the same trade the gate already made, and both directions of it are a cost, never a lost row.
+ *
+ * 🔴 AND IT IS NOT A SIGNAL FOR EVERY OUTAGE. `appendAudit` writes through the SAME operational
+ * store whose claim read just threw, so a whole-store outage loses this row too — best-effort, one
+ * retry, then a drop-counter tick and a `[open-everywhere:audit] dropped a …` warn (core
+ * agent/audit/audit.ts). This row is what makes a PARTIAL fault legible — a missing `notice_claim`
+ * table, a table-level grant — and the audit drop counter is what makes the total one legible. The
+ * operator doc states the same split.
+ *
+ * Best-effort, like every other write in this module: nothing here may cost the ingress its ack.
+ */
+export async function auditGitHubReactionClaimUnreadable(owner, repo, atIso, skipped) {
+    try {
+        await appendAudit({
+            ts: atIso,
+            org: deploymentOrg(),
+            platform: "github",
+            workspace: owner,
+            surface: `github/${owner}/${repo}`,
+            action: GITHUB_REACTION_CLAIM_UNREADABLE_ACTION,
+            detail: { skipped, hour: atIso.slice(0, 13) },
+        });
+    }
+    catch {
+        // Nothing here may cost the ingress its ack.
+    }
+}
+/** The trip row, at most once per repository per hour. Both the throttle and the write are
+ *  best-effort: a budget that cannot audit itself still refuses the poll. */
+async function auditBudgetTrip(org, owner, repo, atIso, used, budget) {
+    try {
+        const first = await getOperationalStore().markEventSeen(org, `${githubPollBudgetKey(owner, repo, atIso)}:tripped`, atIso, BUDGET_AUDIT_TTL_MS);
+        if (!first)
+            return;
+        await appendAudit({
+            ts: atIso,
+            org,
+            platform: "github",
+            workspace: owner,
+            surface: `github/${owner}/${repo}`,
+            action: GITHUB_REACTION_POLL_BUDGET_ACTION,
+            detail: { budget, polls: used, hour: atIso.slice(0, 13) },
+        });
+    }
+    catch {
+        // Nothing here may cost the ingress its ack.
+    }
+}
+//# sourceMappingURL=github-reaction-scope.js.map

package/dist/agent/channels/github-reaction-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-reaction-scope.js","sourceRoot":"","sources":["../../../agent/channels/github-reaction-scope.ts"],"names":[],"mappings":"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"}

package/dist/agent/channels/github-read.d.ts

@@ -0,0 +1,135 @@
+import { type AdapterReadFetch, type BindableContext, type PrFetchFn, type RenderedLine, type RetryPolicy, type WakeReadAddress } from "@open-everywhere/core/agent/adapter-api.js";
+/**
+ * The 429 budget ONE READ may spend, across every call it makes (OPE-1299).
+ *
+ * 🔴 THE DEFECT WAS MULTIPLICATION, NOT THE PER-CALL POLICY. `withRetryAfterLoose`'s budget is
+ * per call, and both reads here walk several: `readChannel` issues up to three (`issues.get`, then
+ * one or two `issues.comments.list` pages) and `readThread` up to {@link MAX_REVIEW_PAGES}
+ * `pulls.comments.list` pages (it fetches no issue object — the review-comment walk is the whole
+ * read). Under the shared 60 s default that is ~3 and ~5 minutes of waiting for ONE `read_channel` /
+ * `read_thread` tool call, and nothing bounded the sum.
+ *
+ * So the whole read shares ONE deadline, read fresh per call ({@link walkRetry}). The first call
+ * still gets the full budget — a single-call read is not tightened at all, which is why this costs
+ * no extra failures on the ordinary path — and each later call gets only what is left. The worst
+ * case for a whole read becomes this number instead of a multiple of it.
+ *
+ * 🔴 THIS IS THE SEAM'S OWN POLICY, NOT A CALLER'S. `ReadAdapter.readChannel`/`readThread`
+ * (core's channels/channel-read.ts) take no options object, and every one of the six adapters
+ * already spends the trailing parameter on its own transport seam — so widening the interface to
+ * carry a policy is a cross-provider change, and no production caller could pass one until it
+ * happened. Slack answered the same question the same way: `PROBE_OPERATIONS`
+ * (providers/slack/agent/channels/slack-web-api.ts) is a table the seam applies itself, with an
+ * explicit dependency still winning. `getJson`'s `retry` argument keeps that property here — a test
+ * passes its own policy and this default never reaches it.
+ *
+ * 60 s, matching `DEFAULT_TOTAL_BUDGET_MS`: a read that 429s out degrades the turn's context rather
+ * than losing an answer, so the budget buys latency back without making a first attempt any more
+ * likely to fail.
+ */
+export declare const READ_WALK_BUDGET_MS = 60000;
+/**
+ * The clock and sleep one walk runs on. Absent in production — the adapter takes the real ones.
+ *
+ * 🔴 IT IS HERE SO THE SHARED BUDGET IS TESTABLE AT ALL. The claim this seam makes is about the
+ * SECOND and later calls of a walk, and a walk under the real clock can only be observed by waiting
+ * out its real waits. `github-read-test.ts` § 8 drives a clock that advances on each recorded sleep,
+ * which is what lets one assertion separate "one deadline for the walk" from "one budget per call".
+ */
+export interface ReadWalkSeam {
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** The policy one call inside a walk takes: whatever is left of the walk's shared deadline. Zero is
+ *  a real value the primitive honours — at the deadline, a retry gives up instead of waiting. */
+export declare function walkRetry(deadlineMs: number, seam?: ReadWalkSeam): RetryPolicy;
+/** One GitHub conversation's address, parsed out of the container id. */
+export interface GitHubContainer {
+    /** The repo owner, as GitHub spells it — the API path segment, never a sanitized key segment. */
+    readonly owner: string;
+    readonly repo: string;
+    /** `owner/repo` — the form every core SCM helper takes. */
+    readonly repoFull: string;
+    /** The issue or PR number. */
+    readonly number: number;
+}
+/**
+ * Parse `owner/repo#number` — the container id {@link githubReadAdapter.wakeAddress} mints.
+ *
+ * Returns `undefined` on anything else rather than guessing a part. A partial address would fetch
+ * another repo's conversation of the same number, which is the silent mis-address the whole
+ * wake-container design refuses (core channels/wake-container.ts).
+ */
+export declare function parseGithubContainer(container: string): GitHubContainer | undefined;
+/** The live transport. Injected in every read below so the whole adapter drives offline — the same
+ *  DI shape slack-read / discord-read take. */
+/** THE package's ONE read transport. Exported so channels/github-reaction-feedback.ts borrows it
+ *  rather than reaching for `globalThis.fetch` itself — a second reach would be a second transport
+ *  outside this module's retry seam, which `test:github-write-seam` §4 exists to refuse. */
+export declare const liveGithubReadFetch: PrFetchFn;
+/**
+ * `operation` is the vendor route name (OPE-1255) `withRetryAfterLoose`'s `RateLimitExhaustedError`
+ * reports on exhaustion — this read-only transport was, until now, the ONE issue/PR reader in this
+ * package with no 429 backoff (`docs/extending/provider-rate-limits.md`).
+ *
+ * Exported so its retry behaviour is unit-tested directly (github-read-test.ts), the same way
+ * `github-rate-limit-test.ts` drives `githubWrite` directly rather than through a full reply.
+ *
+ * `retry` reaches no caller OUTSIDE this file — `ReadAdapter.readChannel`/`readThread`
+ * (channels/channel-read.ts) take no options object. Since OPE-1299 the adapter itself passes one:
+ * each read builds a shared deadline and hands every call what is left of it
+ * ({@link READ_WALK_BUDGET_MS}, {@link walkRetry}), so a multi-call read is bounded as a whole.
+ */
+export declare function getJson<T>(fetchFn: PrFetchFn, url: string, token: string, operation: string, retry?: RetryPolicy): Promise<T>;
+/** The raw shapes this adapter reads. Only the fields it renders are declared. */
+interface RawGitHubUser {
+    readonly login?: string;
+    readonly type?: string;
+}
+interface RawComment {
+    readonly id?: number;
+    readonly body?: string | null;
+    readonly user?: RawGitHubUser;
+    readonly created_at?: string;
+    readonly in_reply_to_id?: number | null;
+}
+/**
+ * The review comments belonging to ONE thread, oldest-first — the thread's own root plus every
+ * comment that replies into it. PURE, and exported for the render test.
+ *
+ * GitHub sets `in_reply_to_id` to the thread's ROOT on every reply, not to the comment being
+ * answered, so one equality covers a thread of any depth. The root itself carries no
+ * `in_reply_to_id`, which is why it is matched by id.
+ */
+export declare function reviewThreadLines(comments: readonly RawComment[], rootId: string): RenderedLine[];
+export declare const githubReadAdapter: {
+    platform: "github";
+    /**
+     * OPE-929 — GitHub's own spelling of "which container and which thread is this turn in".
+     *
+     * The CONTAINER is the conversation key `owner/repo#number`, read off the binding's
+     * `anchorChannelId`: `bindGitHub` already mints it there through `githubConversationKey`, so this
+     * adds no second derivation. A turn with no conversation anchor (a supervisor seed, a degraded
+     * binding) reports none, and the caller refuses loudly rather than reading the repo's newest
+     * issue.
+     *
+     * The THREAD ROOT is present only on a REVIEW-THREAD turn — an inline comment on a PR's diff.
+     * An issue comment and a PR TIMELINE comment are at the top level of their conversation, so they
+     * report no thread root and `read_thread` refuses them honestly. That is the same answer a
+     * base-channel Discord turn gets, and for the same reason.
+     */
+    wakeAddress(ctx: BindableContext): WakeReadAddress | undefined;
+    /**
+     * The issue-or-PR conversation: its opening post, then its newest timeline comments. `channel` is
+     * the container id — see {@link parseGithubContainer}.
+     */
+    readChannel(ctx: BindableContext, channel: string, limit?: number, fetchFn?: PrFetchFn, walk?: ReadWalkSeam): Promise<AdapterReadFetch>;
+    /**
+     * One REVIEW THREAD on a PR — the inline discussion `threadTs` roots. An issue has no review
+     * threads, so a read there comes back empty and the neutral render says so; it never invents a
+     * thread out of the timeline.
+     */
+    readThread(ctx: BindableContext, channel: string, threadTs: string, limit?: number, fetchFn?: PrFetchFn, walk?: ReadWalkSeam): Promise<AdapterReadFetch>;
+};
+export {};
+//# sourceMappingURL=github-read.d.ts.map

package/dist/agent/channels/github-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-read.d.ts","sourceRoot":"","sources":["../../../agent/channels/github-read.ts"],"names":[],"mappings":"AAmEA,OAAO,EAQL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,4CAA4C,CAAC;AAapD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED;iGACiG;AACjG,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,WAAW,CAOlF;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAWnF;AAED;+CAC+C;AAC/C;;4FAE4F;AAC5F,eAAO,MAAM,mBAAmB,EAAkC,SAAS,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAInI;AAED,kFAAkF;AAClF,UAAU,aAAa;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AASD,UAAU,UAAU;IAClB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAqJD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAGjG;AAED,eAAO,MAAM,iBAAiB;IAC5B,QAAQ,EAAE,QAAQ;IAClB;;;;;;;;;;;;;OAaG;IACH,WAAW,MAAM,eAAe,GAAG,eAAe,GAAG,SAAS;IAM9D;;;OAGG;IACG,WAAW,MACV,eAAe,WACX,MAAM,UACP,MAAM,YACL,SAAS,SACZ,YAAY,GACjB,OAAO,CAAC,gBAAgB,CAAC;IAqB5B;;;;OAIG;IACG,UAAU,MACT,eAAe,WACX,MAAM,YACL,MAAM,UACR,MAAM,YACL,SAAS,SACZ,YAAY,GACjB,OAAO,CAAC,gBAAgB,CAAC;CAmB7B,CAAC"}