agent-nuvira 3.3.1 → 3.3.4

package/dist/findings/verdicts.d.ts

@@ -0,0 +1,241 @@
+/**
+ * WS1 (#23) — a finding, its verdict, and the gate that keeps the two honest.
+ *
+ * WHY THIS EXISTS. This repository has already paid for the bug this closes: a
+ * claim that was true-looking and unverified reached a user as fact. The tool
+ * descriptions reported success for work that had not happened
+ * (`docs/TOOL_TRUTHFULNESS_TRACKER.md`), the dashboard shipped a bundle that did
+ * not contain a tab that had been written and reviewed, and a WhatsApp task
+ * reported completion while the deliverable was never authored
+ * (`docs/rca_false_success_and_no_resume.md`). Every one of those is the same
+ * defect in a different costume: something was ASSERTED, nothing was CHECKED,
+ * and the assertion travelled as if it had been.
+ *
+ * The codebase already knows the right shape for this and uses it in one place.
+ * `src/nlu/learnings.ts` documents that "a learning is written ONLY when a
+ * misreading has been CONFIRMED by the model", and `src/nlu/intent-confirm.ts`
+ * is the probe that produces that confirmation. But the confirmation it produced
+ * was the model saying so — an assertion about an assertion, with no evidence
+ * attached. That is the gap: a verdict two-valued enough to be checked, and an
+ * evidence requirement strong enough that "CONFIRMED" cannot be typed in.
+ *
+ * THE MODEL. A finding is a CLAIM plus a VERDICT plus an OUTCOME plus EVIDENCE:
+ *
+ *   claim    — what is being asserted, in the words the reader will see.
+ *   verdict  — CONFIRMED (something was produced that a second party could
+ *              check) or PLAUSIBLE (a reasoned guess). Binary on purpose: a
+ *              0.7 confidence invites arithmetic on a number nobody calibrated,
+ *              and the interesting question is only ever "can this be checked".
+ *   outcome  — what became of it (kept, corrected, dropped, not persisted). A
+ *              finding with no outcome is a status report, not a finding.
+ *   evidence — the concrete things that were checked: a verbatim line, a command
+ *              and its real output, a path. Never a restatement of the claim.
+ *
+ * THE GATE, and why it is enforced in code rather than by convention. A rule
+ * that lives in a comment is a rule the next contributor is free to be
+ * enthusiastic about. `confirmFinding` refuses a promotion with no usable
+ * evidence and returns the finding STILL PLAUSIBLE with the reason attached —
+ * a refusal, not a throw, because "we could not verify this" is a normal outcome
+ * of a probe and must not take down the turn that asked. `enforceVerdicts` then
+ * applies the same rule to a whole batch on the way OUT, so no code path —
+ * including one written later by someone who never read this file — can emit a
+ * CONFIRMED finding that carries nothing.
+ *
+ * TWO DELIBERATE LIMITS.
+ *  1. This module does not decide what a finding MEANS or who may produce one.
+ *     It is the vocabulary and the gate, so every surface can report the same
+ *     shape and a reader can compare them (that is the parity requirement WS0
+ *     exists to measure).
+ *  2. It never invents evidence, and never treats its absence as failure of the
+ *     finding: a PLAUSIBLE finding is a legitimate, useful, honest object. The
+ *     only thing this module refuses is the promotion.
+ */
+/**
+ * What a finding is worth, in the only two amounts that matter.
+ *
+ * - `CONFIRMED` — something was produced that a second party could check.
+ * - `PLAUSIBLE` — reasoned, not verified. The default, and never a failure.
+ */
+export type Verdict = 'CONFIRMED' | 'PLAUSIBLE';
+/**
+ * The kinds of check that can produce evidence.
+ *
+ * `quote` is a verbatim span of the input (the part of a request a reading
+ * depends on); `command` is a command line and its REAL output; `file` is a path
+ * that was read; `observation` is a value a probe actually returned. Kept as a
+ * closed set so a reader can tell how strong a piece of evidence is without
+ * parsing prose — and so `describeFinding` can render it uniformly.
+ */
+export type EvidenceKind = 'quote' | 'command' | 'file' | 'observation';
+/**
+ * One check that was actually performed.
+ *
+ * `ref` is the evidence itself — the line, the command, the path — never a
+ * summary of it. A blank `ref` is not evidence: it is the type satisfied and the
+ * work skipped, which is precisely the defect this module exists to refuse.
+ */
+export interface Evidence {
+    kind: EvidenceKind;
+    ref: string;
+    /** Optional context: the output, the surrounding line, the reason. */
+    detail?: string;
+}
+/** A claim, its verdict, what became of it, and what was checked. */
+export interface Finding {
+    /** What is asserted, in the words the reader will see. */
+    claim: string;
+    verdict: Verdict;
+    /** What became of the finding. Required: a finding with no outcome is a status report. */
+    outcome: string;
+    /** The checks behind a CONFIRMED verdict. Empty is legal — for a PLAUSIBLE one. */
+    evidence: readonly Evidence[];
+    /** Where the finding came from, so a reader can weigh it (`intent-confirm`, `review`, …). */
+    source: string;
+    /** When it was recorded. Volatile: never part of a comparison between surfaces. */
+    at?: number;
+}
+/** The result of asking for a promotion, including the refusal. */
+export interface Promotion {
+    /** The finding AFTER the attempt — PLAUSIBLE and unchanged when refused. */
+    finding: Finding;
+    promoted: boolean;
+    /** Why it was refused. Present exactly when `promoted` is false. */
+    reason?: string;
+}
+/** What `plausibleFinding` needs. Everything else has a defensible default. */
+export interface FindingInput {
+    claim: string;
+    outcome: string;
+    source: string;
+    evidence?: readonly Evidence[];
+    at?: number;
+}
+/**
+ * True when this finding carries anything that was actually checked.
+ *
+ * Exported because the question "is this checkable" is asked in more places than
+ * the gate: a report renderer may want to group a batch by it, and a caller
+ * deciding whether to spend a model call on verification wants it before, not
+ * after.
+ */
+export declare function hasEvidence(finding: Finding): boolean;
+/**
+ * The usable evidence on a finding, in order.
+ *
+ * A finding is normalised on the way in, so this is not a filter a caller must
+ * remember to apply — it exists so a renderer can show the evidence and never
+ * the blanks.
+ */
+export declare function evidenceOf(finding: Finding): Evidence[];
+/**
+ * Record a claim that has NOT been checked.
+ *
+ * Deliberately the constructor: a finding cannot be BORN confirmed. Evidence can
+ * only arrive through `confirmFinding`, so the gate cannot be bypassed by a
+ * caller that helpfully knew the answer all along — the only way to a CONFIRMED
+ * verdict is the function that requires the evidence.
+ *
+ * Evidence passed here is KEPT (a caller that did check something should not lose
+ * it) but does not by itself promote the verdict; promotion is a separate,
+ * explicit act. That keeps "what we know" and "what we decided" from collapsing
+ * into one step that no one can audit.
+ */
+export declare function plausibleFinding(input: FindingInput): Finding;
+/**
+ * Promote a PLAUSIBLE finding to CONFIRMED — or refuse, and say why.
+ *
+ * The refusal is the point of the module. It returns the finding UNCHANGED and
+ * PLAUSIBLE rather than throwing, because "we could not check this" is the
+ * ordinary outcome of a probe against a world that may be offline, and a probe
+ * must never be able to take down the turn that asked it. Callers that need to
+ * branch on the answer read `promoted`.
+ *
+ * A CONFIRMED finding cannot be promoted again (nothing to do), and a CONFIRMED
+ * finding whose evidence is IMPOSSIBLE cannot exist: `enforceVerdicts` demotes
+ * it. Both cases are reported rather than silently accepted.
+ */
+export declare function confirmFinding(finding: Finding, evidence?: readonly Evidence[], options?: {
+    outcome?: string;
+    at?: number;
+}): Promotion;
+/** Force a finding back to PLAUSIBLE, keeping why. The inverse of a promotion. */
+export declare function demoteFinding(finding: Finding, why: string): Finding;
+/**
+ * The gate applied to a batch, on the way out.
+ *
+ * This is what makes the rule unfalsifiable-by-accident: ANY batch of findings
+ * about to be reported, logged or persisted can be passed through here, and a
+ * CONFIRMED verdict that carries nothing is demoted with the reason recorded in
+ * its own outcome. `confirmFinding` protects the direct path; this protects the
+ * paths nobody has written yet, including a finding assembled by hand in a
+ * module that never imported `confirmFinding`.
+ *
+ * Returns the repaired findings AND the claims that were demoted, because a
+ * silent repair would hide the wiring bug that produced the claim — the demotion
+ * is correct behaviour, and its CAUSE is still something a caller should see.
+ */
+export declare function enforceVerdicts(findings: readonly Finding[], why?: string): {
+    findings: Finding[];
+    demoted: string[];
+};
+/**
+ * Claims carrying a CONFIRMED verdict and no usable evidence.
+ *
+ * The assertion form of `enforceVerdicts`, for a caller that would rather fail
+ * than repair — a test, or a check that is about the producing code rather than
+ * the report.
+ */
+export declare function unsupportedConfirmations(findings: readonly Finding[]): string[];
+/**
+ * The wire form: plain JSON a surface can log, return over IPC or write to a
+ * report.
+ *
+ * Present so the five surfaces report a finding IDENTICALLY (the WS0 requirement)
+ * rather than each inventing a shape — a gateway log line and a child's IPC frame
+ * that disagree about a verdict are a parity failure nobody would notice until a
+ * user compared two outputs. `at` is deliberately excluded: it differs on every
+ * invocation, so comparing it would fail for surfaces that behave identically,
+ * the same reason `observation.ts` keeps timing out of the compared projection.
+ */
+export interface WireFinding {
+    claim: string;
+    verdict: Verdict;
+    outcome: string;
+    evidence: Array<{
+        kind: EvidenceKind;
+        ref: string;
+        detail?: string;
+    }>;
+    source: string;
+}
+/** One finding, reduced to the comparable wire form. */
+export declare function toWire(finding: Finding): WireFinding;
+/**
+ * Read a finding back off the wire, defensively.
+ *
+ * Returns `undefined` for anything malformed rather than guessing, and — the
+ * part that matters — a payload claiming CONFIRMED with no usable evidence comes
+ * back PLAUSIBLE. A reader on the other side of an IPC boundary or a log file
+ * cannot trust the producer, so the gate is re-applied on the way in rather than
+ * assumed to have been applied on the way out.
+ */
+export declare function fromWire(value: unknown): Finding | undefined;
+/**
+ * One line a person reads, used everywhere so two surfaces cannot render the
+ * same finding two ways.
+ *
+ * The evidence is shown for a CONFIRMED verdict and the reason for a PLAUSIBLE
+ * one, because those are the two things a reader needs to decide whether to
+ * trust the line — and printing a confidence number neither of them can act on
+ * is how a report starts lying politely.
+ */
+export declare function describeFinding(finding: Finding): string;
+/**
+ * A batch, summarised: how many are confirmed, and how many are still guesses.
+ *
+ * Exists so a caller cannot report a total without also having to look at the
+ * split. "12 findings" reads as twelve facts; "12 findings (3 confirmed, 9
+ * plausible)" cannot.
+ */
+export declare function summarizeVerdicts(findings: readonly Finding[]): string;
+//# sourceMappingURL=verdicts.d.ts.map

package/dist/findings/verdicts.d.ts.map

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

package/dist/findings/verdicts.js

@@ -0,0 +1,284 @@
+/**
+ * WS1 (#23) — a finding, its verdict, and the gate that keeps the two honest.
+ *
+ * WHY THIS EXISTS. This repository has already paid for the bug this closes: a
+ * claim that was true-looking and unverified reached a user as fact. The tool
+ * descriptions reported success for work that had not happened
+ * (`docs/TOOL_TRUTHFULNESS_TRACKER.md`), the dashboard shipped a bundle that did
+ * not contain a tab that had been written and reviewed, and a WhatsApp task
+ * reported completion while the deliverable was never authored
+ * (`docs/rca_false_success_and_no_resume.md`). Every one of those is the same
+ * defect in a different costume: something was ASSERTED, nothing was CHECKED,
+ * and the assertion travelled as if it had been.
+ *
+ * The codebase already knows the right shape for this and uses it in one place.
+ * `src/nlu/learnings.ts` documents that "a learning is written ONLY when a
+ * misreading has been CONFIRMED by the model", and `src/nlu/intent-confirm.ts`
+ * is the probe that produces that confirmation. But the confirmation it produced
+ * was the model saying so — an assertion about an assertion, with no evidence
+ * attached. That is the gap: a verdict two-valued enough to be checked, and an
+ * evidence requirement strong enough that "CONFIRMED" cannot be typed in.
+ *
+ * THE MODEL. A finding is a CLAIM plus a VERDICT plus an OUTCOME plus EVIDENCE:
+ *
+ *   claim    — what is being asserted, in the words the reader will see.
+ *   verdict  — CONFIRMED (something was produced that a second party could
+ *              check) or PLAUSIBLE (a reasoned guess). Binary on purpose: a
+ *              0.7 confidence invites arithmetic on a number nobody calibrated,
+ *              and the interesting question is only ever "can this be checked".
+ *   outcome  — what became of it (kept, corrected, dropped, not persisted). A
+ *              finding with no outcome is a status report, not a finding.
+ *   evidence — the concrete things that were checked: a verbatim line, a command
+ *              and its real output, a path. Never a restatement of the claim.
+ *
+ * THE GATE, and why it is enforced in code rather than by convention. A rule
+ * that lives in a comment is a rule the next contributor is free to be
+ * enthusiastic about. `confirmFinding` refuses a promotion with no usable
+ * evidence and returns the finding STILL PLAUSIBLE with the reason attached —
+ * a refusal, not a throw, because "we could not verify this" is a normal outcome
+ * of a probe and must not take down the turn that asked. `enforceVerdicts` then
+ * applies the same rule to a whole batch on the way OUT, so no code path —
+ * including one written later by someone who never read this file — can emit a
+ * CONFIRMED finding that carries nothing.
+ *
+ * TWO DELIBERATE LIMITS.
+ *  1. This module does not decide what a finding MEANS or who may produce one.
+ *     It is the vocabulary and the gate, so every surface can report the same
+ *     shape and a reader can compare them (that is the parity requirement WS0
+ *     exists to measure).
+ *  2. It never invents evidence, and never treats its absence as failure of the
+ *     finding: a PLAUSIBLE finding is a legitimate, useful, honest object. The
+ *     only thing this module refuses is the promotion.
+ */
+/**
+ * A usable piece of evidence: a non-blank `ref`.
+ *
+ * Whitespace-only is rejected rather than trimmed to "": a caller that passed
+ * `' '` passed nothing, and accepting it would make the gate trivially avoidable.
+ */
+function isUsable(evidence) {
+    return Boolean(evidence) && typeof evidence.ref === 'string' && evidence.ref.trim().length > 0;
+}
+/**
+ * True when this finding carries anything that was actually checked.
+ *
+ * Exported because the question "is this checkable" is asked in more places than
+ * the gate: a report renderer may want to group a batch by it, and a caller
+ * deciding whether to spend a model call on verification wants it before, not
+ * after.
+ */
+export function hasEvidence(finding) {
+    return finding.evidence.some(isUsable);
+}
+/**
+ * The usable evidence on a finding, in order.
+ *
+ * A finding is normalised on the way in, so this is not a filter a caller must
+ * remember to apply — it exists so a renderer can show the evidence and never
+ * the blanks.
+ */
+export function evidenceOf(finding) {
+    return finding.evidence.filter(isUsable);
+}
+/**
+ * Record a claim that has NOT been checked.
+ *
+ * Deliberately the constructor: a finding cannot be BORN confirmed. Evidence can
+ * only arrive through `confirmFinding`, so the gate cannot be bypassed by a
+ * caller that helpfully knew the answer all along — the only way to a CONFIRMED
+ * verdict is the function that requires the evidence.
+ *
+ * Evidence passed here is KEPT (a caller that did check something should not lose
+ * it) but does not by itself promote the verdict; promotion is a separate,
+ * explicit act. That keeps "what we know" and "what we decided" from collapsing
+ * into one step that no one can audit.
+ */
+export function plausibleFinding(input) {
+    return {
+        claim: input.claim,
+        verdict: 'PLAUSIBLE',
+        outcome: input.outcome,
+        evidence: [...(input.evidence ?? [])],
+        source: input.source,
+        ...(input.at !== undefined ? { at: input.at } : {}),
+    };
+}
+/**
+ * Promote a PLAUSIBLE finding to CONFIRMED — or refuse, and say why.
+ *
+ * The refusal is the point of the module. It returns the finding UNCHANGED and
+ * PLAUSIBLE rather than throwing, because "we could not check this" is the
+ * ordinary outcome of a probe against a world that may be offline, and a probe
+ * must never be able to take down the turn that asked it. Callers that need to
+ * branch on the answer read `promoted`.
+ *
+ * A CONFIRMED finding cannot be promoted again (nothing to do), and a CONFIRMED
+ * finding whose evidence is IMPOSSIBLE cannot exist: `enforceVerdicts` demotes
+ * it. Both cases are reported rather than silently accepted.
+ */
+export function confirmFinding(finding, evidence = [], options = {}) {
+    const combined = [...finding.evidence, ...evidence];
+    const outcome = options.outcome ?? finding.outcome;
+    if (finding.verdict === 'CONFIRMED' && hasEvidence(finding)) {
+        return {
+            finding: { ...finding, outcome, ...(options.at !== undefined ? { at: options.at } : {}) },
+            promoted: false,
+            reason: 'already CONFIRMED — a verdict is recorded once, and the evidence that earned it is on the finding',
+        };
+    }
+    if (!combined.some(isUsable)) {
+        return {
+            finding: { ...finding, outcome, evidence: combined, ...(options.at !== undefined ? { at: options.at } : {}) },
+            promoted: false,
+            reason: 'no usable evidence — a CONFIRMED verdict means something was CHECKED, so it needs a command ' +
+                'and its output, a path that was read, a quote from the input, or a value a probe returned. ' +
+                'A restatement of the claim is not evidence, and a blank reference is not a check.',
+        };
+    }
+    return {
+        finding: {
+            ...finding,
+            verdict: 'CONFIRMED',
+            outcome,
+            evidence: combined,
+            ...(options.at !== undefined ? { at: options.at } : {}),
+        },
+        promoted: true,
+    };
+}
+/** Force a finding back to PLAUSIBLE, keeping why. The inverse of a promotion. */
+export function demoteFinding(finding, why) {
+    if (finding.verdict === 'PLAUSIBLE')
+        return finding;
+    const note = finding.outcome.includes(why) ? finding.outcome : `${finding.outcome} — ${why}`;
+    return { ...finding, verdict: 'PLAUSIBLE', outcome: note };
+}
+/**
+ * The gate applied to a batch, on the way out.
+ *
+ * This is what makes the rule unfalsifiable-by-accident: ANY batch of findings
+ * about to be reported, logged or persisted can be passed through here, and a
+ * CONFIRMED verdict that carries nothing is demoted with the reason recorded in
+ * its own outcome. `confirmFinding` protects the direct path; this protects the
+ * paths nobody has written yet, including a finding assembled by hand in a
+ * module that never imported `confirmFinding`.
+ *
+ * Returns the repaired findings AND the claims that were demoted, because a
+ * silent repair would hide the wiring bug that produced the claim — the demotion
+ * is correct behaviour, and its CAUSE is still something a caller should see.
+ */
+export function enforceVerdicts(findings, why = 'not promoted: no usable evidence') {
+    const demoted = [];
+    const repaired = findings.map((finding) => {
+        if (finding.verdict !== 'CONFIRMED' || hasEvidence(finding))
+            return finding;
+        demoted.push(finding.claim);
+        return demoteFinding(finding, why);
+    });
+    return { findings: repaired, demoted };
+}
+/**
+ * Claims carrying a CONFIRMED verdict and no usable evidence.
+ *
+ * The assertion form of `enforceVerdicts`, for a caller that would rather fail
+ * than repair — a test, or a check that is about the producing code rather than
+ * the report.
+ */
+export function unsupportedConfirmations(findings) {
+    return findings
+        .filter((finding) => finding.verdict === 'CONFIRMED' && !hasEvidence(finding))
+        .map((finding) => finding.claim);
+}
+/** One finding, reduced to the comparable wire form. */
+export function toWire(finding) {
+    return {
+        claim: finding.claim,
+        verdict: finding.verdict,
+        outcome: finding.outcome,
+        evidence: evidenceOf(finding).map((e) => ({
+            kind: e.kind,
+            ref: e.ref,
+            ...(e.detail ? { detail: e.detail } : {}),
+        })),
+        source: finding.source,
+    };
+}
+const EVIDENCE_KINDS = ['quote', 'command', 'file', 'observation'];
+/**
+ * Read a finding back off the wire, defensively.
+ *
+ * Returns `undefined` for anything malformed rather than guessing, and — the
+ * part that matters — a payload claiming CONFIRMED with no usable evidence comes
+ * back PLAUSIBLE. A reader on the other side of an IPC boundary or a log file
+ * cannot trust the producer, so the gate is re-applied on the way in rather than
+ * assumed to have been applied on the way out.
+ */
+export function fromWire(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    if (typeof raw.claim !== 'string' || !raw.claim.trim())
+        return undefined;
+    if (typeof raw.outcome !== 'string')
+        return undefined;
+    if (typeof raw.source !== 'string')
+        return undefined;
+    if (raw.verdict !== 'CONFIRMED' && raw.verdict !== 'PLAUSIBLE')
+        return undefined;
+    const evidence = Array.isArray(raw.evidence)
+        ? raw.evidence
+            .filter((e) => Boolean(e) &&
+            typeof e === 'object' &&
+            EVIDENCE_KINDS.includes(e.kind) &&
+            typeof e.ref === 'string')
+            .map((e) => ({
+            kind: e.kind,
+            ref: e.ref,
+            ...(typeof e.detail === 'string' && e.detail ? { detail: e.detail } : {}),
+        }))
+        : [];
+    const finding = {
+        claim: raw.claim,
+        verdict: raw.verdict,
+        outcome: raw.outcome,
+        evidence,
+        source: raw.source,
+    };
+    // Re-applied, not trusted: see the docstring.
+    return enforceVerdicts([finding]).findings[0];
+}
+/** How one piece of evidence reads. */
+function describeEvidence(evidence) {
+    const label = evidence.kind === 'command' ? 'ran' : evidence.kind === 'file' ? 'read' : evidence.kind;
+    return `${label} ${evidence.kind === 'quote' ? `"${evidence.ref}"` : evidence.ref}${evidence.detail ? ` (${evidence.detail})` : ''}`;
+}
+/**
+ * One line a person reads, used everywhere so two surfaces cannot render the
+ * same finding two ways.
+ *
+ * The evidence is shown for a CONFIRMED verdict and the reason for a PLAUSIBLE
+ * one, because those are the two things a reader needs to decide whether to
+ * trust the line — and printing a confidence number neither of them can act on
+ * is how a report starts lying politely.
+ */
+export function describeFinding(finding) {
+    const head = `${finding.verdict === 'CONFIRMED' ? '✅' : '🔎'} ${finding.claim} — ${finding.outcome}`;
+    const evidence = evidenceOf(finding);
+    if (finding.verdict === 'CONFIRMED' && evidence.length > 0) {
+        return `${head}\n  evidence: ${evidence.map(describeEvidence).join('; ')}`;
+    }
+    return `${head}\n  no evidence — reported as PLAUSIBLE, not verified.`;
+}
+/**
+ * A batch, summarised: how many are confirmed, and how many are still guesses.
+ *
+ * Exists so a caller cannot report a total without also having to look at the
+ * split. "12 findings" reads as twelve facts; "12 findings (3 confirmed, 9
+ * plausible)" cannot.
+ */
+export function summarizeVerdicts(findings) {
+    const confirmed = findings.filter((f) => f.verdict === 'CONFIRMED' && hasEvidence(f)).length;
+    const plausible = findings.length - confirmed;
+    return `${findings.length} finding(s): ${confirmed} confirmed, ${plausible} plausible`;
+}
+//# sourceMappingURL=verdicts.js.map

package/dist/findings/verdicts.js.map

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

package/dist/gateway/adapters.d.ts

@@ -14,6 +14,7 @@
  */
 import type { Platform } from './channel-directory.js';
 import type { WhatsAppBridge } from './whatsapp/bridge.js';
+import { type InboundMedia } from './inbound-media.js';
 export interface InboundMessage {
     platform: Platform;
     /** Channel id (chat id / webhook channel id) to REPLY to. */
@@ -38,6 +39,13 @@ export interface InboundMessage {
      * every delivery is treated as new (content dedup is opt-in — see dedup.ts).
      */
     messageId?: string;
+    /**
+     * A document/image attachment that rode in on this message, already
+     * downloaded by the transport. `handleInbound` hydrates it through the same
+     * `read_extract` the agent uses, so a document is TEXT by the time routing
+     * happens instead of a message with empty text that gets dropped.
+     */
+    media?: InboundMedia;
 }
 /** The handler an adapter calls for every inbound message. */
 export type MessageHandler = (msg: InboundMessage) => void | Promise<void>;
@@ -100,6 +108,17 @@ export declare class TelegramAdapter implements ChannelAdapter {
     describe(): string;
     private api;
     start(onMessage: MessageHandler): Promise<void>;
+    /**
+     * Download an inbound attachment's bytes via `getFile` + the file endpoint.
+     * Never throws — returns null on any failure (or when the file is larger than
+     * the extraction cap), so the turn still runs with its caption text.
+     */
+    private downloadFile;
+    /**
+     * Build the inbound media payload from a Telegram message, or null when it
+     * carries none. Photos arrive as several sizes — the largest is used.
+     */
+    private inboundMedia;
     stop(): Promise<void>;
     send(channelId: string, text: string): Promise<boolean>;
     /**
@@ -138,7 +157,16 @@ export declare class DiscordAdapter extends WebhookChannelAdapter {
     readonly tokenEnvVar = "BUFF_DISCORD_BOT_TOKEN";
     readonly configured: boolean;
     constructor();
+    /** The real-time Gateway connection, when a bot token is configured. */
+    private gateway;
     describe(): string;
+    /**
+     * Inbound Discord messages arrive over the Gateway WebSocket (a bot cannot
+     * own the Discord webhook), so a bot token starts the real-time source. The
+     * shared webhook receiver still serves outbound-only webhook setups.
+     */
+    start(onMessage: MessageHandler): Promise<void>;
+    stop(): Promise<void>;
     protected sendUrl(channelId: string): string;
     protected payloadFor(_channelId: string, text: string): unknown;
     /**
@@ -156,7 +184,16 @@ export declare class SlackAdapter extends WebhookChannelAdapter {
     readonly tokenEnvVar = "BUFF_SLACK_BOT_TOKEN";
     readonly configured: boolean;
     constructor();
+    /** The Socket Mode connection, when an app-level token is configured. */
+    private socketMode;
     describe(): string;
+    /**
+     * Slack Events API inbound needs a public HTTPS endpoint; apps that cannot
+     * expose one use Socket Mode, which carries the same `event_callback`
+     * envelopes. Enabled by an app-level token (`SLACK_APP_TOKEN`, `xapp-…`).
+     */
+    start(onMessage: MessageHandler): Promise<void>;
+    stop(): Promise<void>;
     protected sendUrl(channelId: string): string;
     protected payloadFor(channelId: string, text: string): unknown;
 }
@@ -636,6 +673,15 @@ export declare class HomeAssistantAdapter implements ChannelAdapter {
     stop(): Promise<void>;
     send(channelId: string, text: string): Promise<boolean>;
 }
+/** An inbound webhook attachment that must be downloaded before extraction. */
+export interface WebhookAttachment {
+    url: string;
+    filename?: string;
+    mimetype?: string;
+    size?: number;
+    /** True when fetching the URL needs the platform bot token (Slack files). */
+    authenticated?: boolean;
+}
 /** Payload parsers: extract {channelId, text, from} from each platform's webhook body. */
 export interface WebhookPayload {
     channelId: string;
@@ -647,7 +693,20 @@ export interface WebhookPayload {
     isGroup?: boolean;
     /** The platform's message id, when the webhook body carries one (dedup). */
     messageId?: string;
+    /** An attachment that rode in on the message (Discord CDN / Slack file). */
+    media?: {
+        type: InboundMedia['type'];
+        attachment: WebhookAttachment;
+        caption?: string;
+    };
 }
+/**
+ * Classify an attachment by MIME type, falling back to its filename extension.
+ * Exported for the real-time transports (`realtime.ts`), which receive Discord
+ * `content_type` / Slack `mimetype` on a live gateway event rather than a
+ * webhook body.
+ */
+export declare function mediaKindFromMime(mimetype?: string, filename?: string): InboundMedia['type'];
 /**
  * Parse platform-specific webhook bodies into a normal InboundMessage.
  * Returns null when the payload isn't a user message (e.g. Slack challenge).
@@ -665,6 +724,12 @@ export declare class WebhookReceiver {
      * When the platform secret is set, unsigned POSTs are rejected (401).
      */
     start(onMessage: MessageHandler, port?: number, host?: string): Promise<void>;
+    /**
+     * Download a webhook attachment's bytes. Never throws — returns null on any
+     * failure, so the text turn still runs. Slack's `url_private*` endpoints need
+     * the bot token; Discord's CDN URL is public.
+     */
+    private downloadWebhookMedia;
     /**
      * Verify a webhook POST's platform signature. Returns true when the
      * platform has NO secret configured (local/trusted setup) or the signature