/**
 * `totem mail` — canonical cross-repo outbox poll (ADR-106 § 3 / ADR-107).
 *
 * Senders write to their own `<repoRoot>/.totem/orchestration/<sender-agent>/outbox/*.md`
 * with `to: <recipient-agent>` (or `to: broadcast`) in the frontmatter.
 * Recipients invoke this command at session-start (typically via a
 * vendor-specific hook in `.claude/hooks/` or `.gemini/hooks/`) to surface
 * unread mail addressed to themselves.
 *
 * SELF_AGENTS resolution flows through `resolveSelfAgents` from
 * `@mmnto/totem` (env > config.json > seat dirs ∪ basename map — the dirs ARE
 * the registration, mmnto-ai/totem#2141). Workspace defaults to the parent
 * directory of the calling repo, overridable via the `TOTEM_WORKSPACE` env
 * var or `--workspace` flag.
 *
 * Ports the strategy-side reference implementation
 * (`mmnto-ai/totem-strategy:.claude/hooks/SessionStart.cjs:pollInboundOutboxes`,
 * merged via mmnto-ai/totem-strategy#373) into a cohort-portable command
 * surface per the ADR-107 § Consequences direction.
 */
import { type SelfAgentResolution } from '@mmnto/totem';
/** A single piece of mail surfaced by the poll. */
export interface MailEntry {
    /** Outbox-relative filename (e.g. `2026-05-18T1734Z-strategy-claude.md`). */
    file: string;
    /** Repo basename where the outbox lives. */
    repo: string;
    /** Sender agent-id (from frontmatter `from:` or outbox-dir name as fallback). */
    from: string;
    /** Recipient (from frontmatter `to:`, preserved verbatim). */
    to: string;
    /** ISO timestamp from frontmatter `timestamp:` (ADR-098 v0.4 canonical), falling back to legacy `date:`; null if absent. */
    date: string | null;
    /** Subject line from frontmatter, or `(no subject)` if absent. */
    subject: string;
    /** Absolute path to the outbox file (useful for `--json` consumers). */
    filePath: string;
}
/** Aggregate result of a single poll. */
export interface MailPollResult {
    /** Resolution metadata describing how SELF_AGENTS was determined. `source`
     * is single-sourced from core's `SelfAgentResolution` (Greptile P2 on
     * mmnto-ai/totem#2160 — a manual copy would compile-error in the wrong
     * place if core ever narrowed a literal). */
    selfAgents: {
        agents: string[];
        source: SelfAgentResolution['source'];
    };
    /** Mail addressed to any SELF_AGENT or to `broadcast`, sorted newest-first. */
    mail: MailEntry[];
    /** Total files actually opened during the scan (≤ `MAX_SCAN`). */
    scanned: number;
    /** True iff the scan hit `MAX_SCAN` before exhausting the workspace. */
    truncated: boolean;
    /** Workspace directory walked (absolute). */
    workspace: string;
    /** Per-source repo failure messages — never throws, surfaces via this. */
    warnings: string[];
}
export interface MailCommandOptions {
    /** Emit JSON instead of human-readable text. */
    json?: boolean;
    /** Use the recursive variant of the ADR-106 § 3 glob (default: single-level). */
    recursive?: boolean;
    /** Workspace override (default: `TOTEM_WORKSPACE` env, else parent-of-cwd). */
    workspace?: string;
    /** Repo root override (default: `process.cwd()`). Test injection point. */
    repoRoot?: string;
    /** Env override (default: `process.env`). Test injection point. */
    env?: Record<string, string | undefined>;
    /** Scan cap override (default: `MAX_SCAN`). Test injection point — cap
     * MECHANICS are exercised with small fixtures instead of 5000-file trees. */
    maxScan?: number;
}
/**
 * Programmatic entry point. Returns a structured `MailPollResult` for
 * consumers that want to render their own output (hooks, MCP audits,
 * future surfaces). The CLI wrapper calls this then formats the result
 * for human consumption.
 *
 * Never throws — filesystem failures degrade to warnings on the result.
 */
export declare function pollMail(opts?: MailCommandOptions): MailPollResult;
export declare function mailCommand(opts?: MailCommandOptions): Promise<MailPollResult>;
/**
 * Structurally-complete dispatch header. ADR-098 v0.4 compliance is enforced
 * *by construction*: you cannot build this object without `schema` / `from` /
 * `to` / `timestamp` / `subject` / `expectedAction`, so a structurally invalid
 * dispatch is unrepresentable rather than rejected after the fact — the
 * strongest form of "enforce via substrate" (inv2 realized). The content
 * predicates that CANNOT be guaranteed at construction time (is the recipient
 * a known agent? do refs resolve?) are the validator's job, and warn rather
 * than block (inv6).
 */
export interface DispatchHeader {
    schema: string;
    from: string;
    to: string;
    /** Full RFC3339 UTC, e.g. `2026-06-09T17:34:37.127Z` (ADR-098 v0.4). */
    timestamp: string;
    subject: string;
    /** ADR-098 v0.4 mandatory; the `none` literal for informational dispatches. */
    expectedAction: string;
    inReplyTo?: string;
    priority?: string;
    related?: string[];
}
export interface MailSendOptions {
    /** Recipient agent-id (or `broadcast`). */
    to: string;
    /** Subject line (the cohort convention carries the gist here). */
    subject: string;
    /** Sender agent-id; default resolves from self, erroring if ambiguous. */
    from?: string;
    /** Read the dispatch body from this file (hard error if unreadable). */
    bodyFile?: string;
    /** Direct body text (test/stdin seam); `bodyFile` overrides when both set. */
    body?: string;
    /** `in-reply-to:` frontmatter — the source dispatch path. */
    inReplyTo?: string;
    /** `priority:` frontmatter. */
    priority?: string;
    /** `related-issues:` frontmatter list. */
    related?: string[];
    /** `expected-action:` frontmatter; defaults to the `none` literal. */
    expectedAction?: string;
    /** Filename slug override; default derived from the subject. */
    slug?: string;
    /**
     * Workspace for dir-derived known-recipient validation (default:
     * `TOTEM_WORKSPACE` env, else parent of repoRoot — the same resolution as
     * `pollMail`). Advisory only (inv6): widens the known set so a
     * dir-registered seat is not warned as unknown (mmnto-ai/totem#2141).
     */
    workspace?: string;
    /** Repo root (default: cwd). Test injection point. */
    repoRoot?: string;
    /** Env override (default: process.env). Test injection point. */
    env?: Record<string, string | undefined>;
    /** Clock injection for deterministic timestamps/filenames in tests. */
    now?: () => Date;
    /** Known-recipient set override (default: `knownCohortAgents()`). */
    knownAgents?: readonly string[];
}
export interface MailSendResult {
    /** Absolute path of the written dispatch. */
    filePath: string;
    /** Basename of the written dispatch. */
    fileName: string;
    /** The composed (structurally-valid-by-construction) header. */
    header: DispatchHeader;
    /** Content-class warnings surfaced at emit-time; dispatch still written. */
    warnings: string[];
}
/**
 * Serialize a dispatch header + body to ADR-098 v0.4 markdown. Pure +
 * deterministic — the round-trip anchor: its output MUST parse back through
 * `parseHeader` (the sensor↔actuator "one enumeration, two readers" pairing).
 * Frontmatter keys are kebab-case wire form, the surface the reader greps.
 */
export declare function composeDispatch(header: DispatchHeader, body: string): string;
/**
 * Content-class validation (inv1: exact predicates only — set membership and
 * non-emptiness, never judgment). NEVER throws, NEVER blocks: returns warnings
 * the caller surfaces at emit-time and writes anyway (inv6). The headline check
 * is the unknown-recipient typo class (strategy-claude 2026-06-09): a typo'd
 * recipient writes under a wrong name and is undelivered-but-not-errored unless
 * the sender is told loudly.
 */
export declare function validateDispatchContent(header: {
    to: string;
    related?: string[];
}, knownAgents: readonly string[]): string[];
/**
 * Resolve the single sender identity for an outbound dispatch. Unlike the
 * reader (which resolves a SET of self-agents to filter by), send must pick
 * ONE. Precedence: explicit `--from` > unambiguous `resolveSelfAgents` > error.
 * A >1 ambiguous map (e.g. totem hosts both totem-claude + totem-gemini) is a
 * hard usage error — never silently pick one (it would mis-attribute the
 * dispatch). Zero is a hard error too — never write to `.../undefined/outbox`.
 */
export declare function resolveSelfSender(repoRoot: string, env: Record<string, string | undefined>, explicitFrom?: string): string;
/**
 * Compose + validate + write an outbound dispatch to the sender's own outbox.
 * Structural validity is by construction; content warnings are returned (the
 * CLI wrapper surfaces them loudly) and never block the write. The only HARD
 * failures are usage errors (missing to/subject, unresolvable/ambiguous self,
 * unreadable body-file) and actuation failure (a write that didn't land —
 * fail-loud, Tenet 4, the opposite of the inv6 content case).
 */
export declare function mailSend(opts: MailSendOptions): MailSendResult;
/**
 * `totem mail reply <source>` — syntactic sugar over `mailSend`. Reads the
 * source dispatch (HARD error if missing/unparseable — reply structurally needs
 * it to infer the recipient + subject), then sends with `to = source.from`
 * (falling back to the source's outbox-dir agent, reader parity),
 * `subject = "Re: <source.subject>"`, and `in-reply-to` set to the source's
 * repo-relative wire form. Any field can still be overridden via opts.
 */
export declare function mailReply(source: string, opts?: Omit<MailSendOptions, 'to' | 'subject' | 'inReplyTo'> & {
    to?: string;
    subject?: string;
}): MailSendResult;
/**
 * CLI wrapper for `mail send` / `mail reply`. Surfaces content warnings LOUDLY
 * on stderr at emit-time (inv6: the dispatch still wrote — this is the typo
 * backstop, not a block), then confirms the written path.
 */
export declare function mailSendCommand(result: MailSendResult): Promise<MailSendResult>;
//# sourceMappingURL=mail.d.ts.map