@birdybeep/agent-core 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,852 @@
+import { z } from 'zod';
+
+/**
+ * Canonical agent event payload (§10.2) as zod schemas + inferred types — the typed
+ * contract every adapter, the normalizer, and the sender share.
+ *
+ * LOCKSTEP (§16.4): field-for-field identical to the product `packages/schemas`
+ * `event.ts` (same names, same optionality, same enums, same constraints). This is
+ * the SHAPE contract validated at ingestion (`POST /v1/agent-events`); any change
+ * to the product schema is a coordinated change here. This package validates SHAPE
+ * only — it never stores or logs payload content (§15.2). Redaction/truncation/path
+ * hashing is CORE-NORMALIZE's job, not this file's.
+ */
+
+/** Machine identity carried on each event (§10.2). `os` is free-form (the adapter reports it). */
+declare const machineSchema: z.ZodObject<{
+    label: z.ZodString;
+    os: z.ZodString;
+}, z.core.$strip>;
+/** Workspace context (§10.2). `repo_name`/`branch` are optional ("if available", §8.6). */
+declare const workspaceSchema: z.ZodObject<{
+    cwd: z.ZodString;
+    repo_name: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Open-ended event metadata (§10.2): known fields plus any adapter-specific extras. */
+declare const eventMetadataSchema: z.ZodObject<{
+    tool: z.ZodOptional<z.ZodString>;
+    command_summary: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodUnknown>>;
+/** The canonical agent event payload (§10.2). */
+declare const birdyBeepAgentEventSchema: z.ZodObject<{
+    event_id: z.ZodString;
+    event_type: z.ZodEnum<{
+        session_started: "session_started";
+        session_resumed: "session_resumed";
+        session_active: "session_active";
+        needs_input: "needs_input";
+        approval_required: "approval_required";
+        agent_idle: "agent_idle";
+        agent_completed: "agent_completed";
+        agent_failed: "agent_failed";
+        test_failed: "test_failed";
+        tool_started: "tool_started";
+        tool_finished: "tool_finished";
+        subagent_started: "subagent_started";
+        subagent_completed: "subagent_completed";
+        custom: "custom";
+        test: "test";
+    }>;
+    occurred_at: z.ZodISODateTime;
+    harness: z.ZodEnum<{
+        claude_code: "claude_code";
+        codex: "codex";
+        opencode: "opencode";
+    }>;
+    harness_version: z.ZodOptional<z.ZodString>;
+    source_session_id: z.ZodString;
+    machine: z.ZodObject<{
+        label: z.ZodString;
+        os: z.ZodString;
+    }, z.core.$strip>;
+    workspace: z.ZodObject<{
+        cwd: z.ZodString;
+        repo_name: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    status: z.ZodEnum<{
+        starting: "starting";
+        running: "running";
+        waiting_for_input: "waiting_for_input";
+        waiting_for_approval: "waiting_for_approval";
+        idle: "idle";
+        completed: "completed";
+        failed: "failed";
+        unknown: "unknown";
+    }>;
+    title: z.ZodString;
+    body: z.ZodString;
+    metadata: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodOptional<z.ZodString>;
+        command_summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+}, z.core.$strip>;
+type Machine = z.infer<typeof machineSchema>;
+type Workspace = z.infer<typeof workspaceSchema>;
+type EventMetadata = z.infer<typeof eventMetadataSchema>;
+type BirdyBeepAgentEvent = z.infer<typeof birdyBeepAgentEventSchema>;
+/**
+ * The request body for `POST /v1/agent-events` is exactly the canonical event
+ * payload (§13.4/§13.5). Aliased so the sender (CORE-SENDER) reads intent clearly.
+ */
+declare const agentEventsRequestSchema: z.ZodObject<{
+    event_id: z.ZodString;
+    event_type: z.ZodEnum<{
+        session_started: "session_started";
+        session_resumed: "session_resumed";
+        session_active: "session_active";
+        needs_input: "needs_input";
+        approval_required: "approval_required";
+        agent_idle: "agent_idle";
+        agent_completed: "agent_completed";
+        agent_failed: "agent_failed";
+        test_failed: "test_failed";
+        tool_started: "tool_started";
+        tool_finished: "tool_finished";
+        subagent_started: "subagent_started";
+        subagent_completed: "subagent_completed";
+        custom: "custom";
+        test: "test";
+    }>;
+    occurred_at: z.ZodISODateTime;
+    harness: z.ZodEnum<{
+        claude_code: "claude_code";
+        codex: "codex";
+        opencode: "opencode";
+    }>;
+    harness_version: z.ZodOptional<z.ZodString>;
+    source_session_id: z.ZodString;
+    machine: z.ZodObject<{
+        label: z.ZodString;
+        os: z.ZodString;
+    }, z.core.$strip>;
+    workspace: z.ZodObject<{
+        cwd: z.ZodString;
+        repo_name: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    status: z.ZodEnum<{
+        starting: "starting";
+        running: "running";
+        waiting_for_input: "waiting_for_input";
+        waiting_for_approval: "waiting_for_approval";
+        idle: "idle";
+        completed: "completed";
+        failed: "failed";
+        unknown: "unknown";
+    }>;
+    title: z.ZodString;
+    body: z.ZodString;
+    metadata: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodOptional<z.ZodString>;
+        command_summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+}, z.core.$strip>;
+type AgentEventsRequest = BirdyBeepAgentEvent;
+
+/**
+ * Primitive enums + guards for the canonical agent event (§10.1, §10.4, §13.5).
+ *
+ * LOCKSTEP (§16.4): these unions MIRROR the product repo's `@birdybeep/shared`
+ * (HARNESS_IDS / BIRDYBEEP_EVENT_TYPES / AGENT_SESSION_STATUSES) and the zod
+ * validators in its `packages/schemas`. The agent repo cannot import the private
+ * `@birdybeep/shared`, so the values are vendored here — any change there MUST be
+ * mirrored here (the schema parity test fails if the agent side drifts).
+ */
+
+/** Every agent event type, in PRD §10.1 order. Mirrors @birdybeep/shared BIRDYBEEP_EVENT_TYPES. */
+declare const BIRDYBEEP_EVENT_TYPES: readonly ["session_started", "session_resumed", "session_active", "needs_input", "approval_required", "agent_idle", "agent_completed", "agent_failed", "test_failed", "tool_started", "tool_finished", "subagent_started", "subagent_completed", "custom", "test"];
+type BirdyBeepEventType = (typeof BIRDYBEEP_EVENT_TYPES)[number];
+/** Every session status, in PRD §10.4 order. Mirrors @birdybeep/shared AGENT_SESSION_STATUSES. */
+declare const AGENT_SESSION_STATUSES: readonly ["starting", "running", "waiting_for_input", "waiting_for_approval", "idle", "completed", "failed", "unknown"];
+type AgentSessionStatus = (typeof AGENT_SESSION_STATUSES)[number];
+/** Supported harness ids (§9.5–9.7). Mirrors @birdybeep/shared HARNESS_IDS. */
+declare const HARNESS_IDS: readonly ["claude_code", "codex", "opencode"];
+type HarnessId = (typeof HARNESS_IDS)[number];
+/** Enum validators derived from the vendored tuples so the validator can't drift from the type. */
+declare const eventTypeSchema: z.ZodEnum<{
+    session_started: "session_started";
+    session_resumed: "session_resumed";
+    session_active: "session_active";
+    needs_input: "needs_input";
+    approval_required: "approval_required";
+    agent_idle: "agent_idle";
+    agent_completed: "agent_completed";
+    agent_failed: "agent_failed";
+    test_failed: "test_failed";
+    tool_started: "tool_started";
+    tool_finished: "tool_finished";
+    subagent_started: "subagent_started";
+    subagent_completed: "subagent_completed";
+    custom: "custom";
+    test: "test";
+}>;
+declare const sessionStatusSchema: z.ZodEnum<{
+    starting: "starting";
+    running: "running";
+    waiting_for_input: "waiting_for_input";
+    waiting_for_approval: "waiting_for_approval";
+    idle: "idle";
+    completed: "completed";
+    failed: "failed";
+    unknown: "unknown";
+}>;
+declare const harnessSchema: z.ZodEnum<{
+    claude_code: "claude_code";
+    codex: "codex";
+    opencode: "opencode";
+}>;
+/** ISO 8601 timestamp, e.g. "2026-06-11T12:34:56.000Z" (trailing Z or numeric offset). */
+declare const isoDateTimeSchema: z.ZodISODateTime;
+/** Max accepted agent-event request body, in bytes (§13.5). Mirrors the product MAX_AGENT_EVENT_BYTES. */
+declare const MAX_AGENT_EVENT_BYTES: number;
+/**
+ * Whether a raw agent-event body is within the size cap (§13.5). Platform-neutral
+ * (no TextEncoder / Buffer): pass the body's byte length, or the raw bytes.
+ */
+declare function isWithinMaxAgentEventSize(body: number | ArrayBuffer | ArrayBufferView): boolean;
+
+/**
+ * The `AgentAdapter` interface (§9.1): the one uniform contract the Claude Code,
+ * Codex, and OpenCode adapters all implement, so the CLI can detect/install/
+ * uninstall/check/doctor/normalize any harness without special-casing. New
+ * harnesses plug in by implementing this — nothing in the CLI changes.
+ *
+ * Contract every adapter MUST honor (§7.3), enforced by the shared E2E harness:
+ *   - install is IDEMPOTENT (a second install is a no-op);
+ *   - existing config is BACKED UP before modification;
+ *   - only BirdyBeep-MANAGED entries are added (existing config preserved);
+ *   - tokens are NEVER written into harness config or repo files;
+ *   - install/uninstall report changed files + any required user actions;
+ *   - uninstall removes exactly the managed entries (restores the original).
+ */
+
+/** Integration status values (§8.8). */
+declare const INTEGRATION_STATUSES: readonly ["installed", "not_detected", "needs_restart", "needs_trust", "error", "revoked", "unknown"];
+type IntegrationStatus = (typeof INTEGRATION_STATUSES)[number];
+/** Result of probing whether a harness is present on the machine. */
+interface DetectionResult {
+    detected: boolean;
+    version?: string;
+    /** Path to the harness config the adapter would manage, if found. */
+    configPath?: string;
+    detail?: string;
+}
+interface InstallOptions {
+    /** Compute + report changes without writing anything. */
+    dryRun?: boolean;
+}
+interface InstallResult {
+    /** False when the install was a no-op (already installed / idempotent re-run). */
+    changed: boolean;
+    /** Config files created or modified by this install. */
+    changedFiles: string[];
+    /** Backups written before modifying pre-existing config. */
+    backupFiles: string[];
+    /** Actions the user must still take (e.g. trust Codex hooks, restart OpenCode). */
+    requiredActions: string[];
+    /** Resulting integration status (e.g. installed / needs_trust / needs_restart). */
+    status: IntegrationStatus;
+}
+interface UninstallOptions {
+    dryRun?: boolean;
+}
+interface UninstallResult {
+    changed: boolean;
+    /** Files removed (created by BirdyBeep). */
+    removedFiles: string[];
+    /** Files restored from backup to their pre-install contents. */
+    restoredFiles: string[];
+}
+interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    status?: IntegrationStatus;
+    detail?: string;
+    /** Suggested fix when `ok` is false. */
+    remedy?: string;
+}
+interface DoctorResult {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+/** The contract implemented by every harness adapter (§9.1). */
+interface AgentAdapter {
+    /** Stable harness id (also the event `harness` value). */
+    readonly id: HarnessId;
+    /** Human-facing harness name, e.g. "Claude Code". */
+    readonly displayName: string;
+    /** Is this harness installed/usable on the machine? */
+    detect(): Promise<DetectionResult>;
+    /** Idempotently install BirdyBeep into the harness config (backs up first). */
+    install(options?: InstallOptions): Promise<InstallResult>;
+    /** Remove BirdyBeep's managed entries, restoring the original config. */
+    uninstall(options?: UninstallOptions): Promise<UninstallResult>;
+    /** Current integration status (§8.8). */
+    status(): Promise<IntegrationStatus>;
+    /** Diagnose integration health and suggest remedies. */
+    doctor(): Promise<DoctorResult>;
+    /** Map a raw harness payload to a redacted, validated canonical event. */
+    normalizeEvent(input: unknown): Promise<BirdyBeepAgentEvent>;
+}
+
+/**
+ * API error/response contract (§13.4) — MIRRORED from the product
+ * `packages/schemas/api.ts` (their ticket 95e). The single wire-facing error shape
+ * the Worker emits and this CLI parses; agent-core's sender keys retry-vs-terminal
+ * off these codes. LOCKSTEP (§16.4): keep ERROR_CODES / the envelope / ERROR_STATUS
+ * identical to the product. Additive to and independent of the §10.2 event payload.
+ *
+ * Messages are human-readable text only — never notification title/body or request
+ * content (§15.2); `details` is for safe structured hints (e.g. which field failed).
+ */
+
+/** Stable, machine-readable error codes the client keys off. */
+declare const ERROR_CODES: readonly ["validation_failed", "unauthorized", "forbidden", "token_revoked", "not_found", "payload_too_large", "rate_limited", "quota_exceeded", "internal_error"];
+declare const errorCodeSchema: z.ZodEnum<{
+    validation_failed: "validation_failed";
+    unauthorized: "unauthorized";
+    forbidden: "forbidden";
+    token_revoked: "token_revoked";
+    not_found: "not_found";
+    payload_too_large: "payload_too_large";
+    rate_limited: "rate_limited";
+    quota_exceeded: "quota_exceeded";
+    internal_error: "internal_error";
+}>;
+type ErrorCode = (typeof ERROR_CODES)[number];
+/** The error response envelope: `{ error: { code, message, details? }, requestId? }`. */
+declare const errorEnvelopeSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            validation_failed: "validation_failed";
+            unauthorized: "unauthorized";
+            forbidden: "forbidden";
+            token_revoked: "token_revoked";
+            not_found: "not_found";
+            payload_too_large: "payload_too_large";
+            rate_limited: "rate_limited";
+            quota_exceeded: "quota_exceeded";
+            internal_error: "internal_error";
+        }>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ErrorEnvelope = z.infer<typeof errorEnvelopeSchema>;
+/** Generic success envelope (`{ data }`) for endpoints that opt into wrapping. */
+declare const successEnvelopeSchema: <T extends z.ZodTypeAny>(data: T) => z.ZodObject<{
+    data: T;
+}, z.core.$strip>;
+type SuccessEnvelope<T> = {
+    data: T;
+};
+/**
+ * Canonical HTTP status per error code — part of the contract: a given code always
+ * maps to this status, so the client can branch on either.
+ */
+declare const ERROR_STATUS: {
+    readonly validation_failed: 400;
+    readonly unauthorized: 401;
+    readonly forbidden: 403;
+    readonly token_revoked: 403;
+    readonly not_found: 404;
+    readonly payload_too_large: 413;
+    readonly rate_limited: 429;
+    readonly quota_exceeded: 429;
+    readonly internal_error: 500;
+};
+
+/** Default dedup window: collapse identical events seen within 10s. */
+declare const DEFAULT_DEDUP_WINDOW_MS = 10000;
+/**
+ * Window for collapsing the SAME-approval double-fire (same session + type, different
+ * body — e.g. "Claude Code needs your permission…" vs "Approve Bash?"). DELIBERATE
+ * TRADEOFF: within this window a genuinely DISTINCT second approval is also collapsed
+ * (dropped!), inverting the module's better-double-beep-than-drop bias — so the window
+ * is as short as the double-fire allows. The double-fire is one harness action emitting
+ * two hooks back-to-back (typically <100ms apart); two REAL approvals are separated by
+ * the human answering the first, or by prompts that Claude Code serializes in its UI —
+ * sub-second spacing is not a realistic distinct-approval pattern. Keep this ≤ the
+ * ledger's default window (markAndCheck clamps a wider value down) and NEVER raise it
+ * casually: every added millisecond widens the drop window for real approvals.
+ * Best-effort under concurrency: two SIMULTANEOUS hook processes can both pass the
+ * read-check-write ledger race and double-beep — that direction is fail-open (annoying,
+ * not lossy) and accepted.
+ */
+declare const APPROVAL_COLLAPSE_WINDOW_MS = 1000;
+interface RecentEventLedgerOptions {
+    /** Ledger file path (default `<dataDir>/recent-events.json`). */
+    path?: string;
+    /** Dedup window in ms (default 10s). Also the retention horizon for pruning. */
+    windowMs?: number;
+    /** Injectable clock (ms) for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * A canonical identity for an event: same harness + session + type + CONTENT = the
+ * "same beep". Content rides as a truncated hash so the ledger file never stores
+ * notification text (§15.2).
+ */
+declare function eventIdentity(event: {
+    harness: string;
+    source_session_id: string;
+    event_type: string;
+    title: string;
+    body: string;
+}): string;
+/**
+ * The content-BLIND identity used ONLY for the approval double-fire collapse (see the
+ * module doc): one physical approval emits two payload shapes whose bodies differ, so
+ * the content-aware identity cannot pair them.
+ */
+declare function approvalCollapseIdentity(event: {
+    harness: string;
+    source_session_id: string;
+}): string;
+declare class RecentEventLedger {
+    #private;
+    readonly path: string;
+    constructor(options?: RecentEventLedgerOptions);
+    /**
+     * If `identity` was recorded within the window, return true (it's a duplicate —
+     * caller should skip). Otherwise record it (pruning expired entries) and return
+     * false. `windowMs` narrows the duplicate check for THIS identity (e.g. the short
+     * approval-collapse window) — pruning always uses the ledger's own (max) window so
+     * a narrower check never evicts entries other checks still need. Fail-open: any
+     * I/O error returns false (allow the send).
+     */
+    markAndCheck(identity: string, windowMs?: number): boolean;
+    clear(): void;
+    /** Whether the ledger file has secure (0600) perms. True on Windows (ACL-based). */
+    isSecure(): boolean;
+}
+
+/** Durable host signals combined into the fingerprint. Injectable for deterministic tests. */
+interface MachineSignals {
+    hostname: string;
+    platform: string;
+    arch: string;
+    cpuModel: string;
+    totalmem: number;
+    /** First stable non-internal MAC, or null. */
+    mac: string | null;
+}
+/** Gather durable signals from the host. */
+declare function collectMachineSignals(): MachineSignals;
+/** Derive the non-reversible fingerprint hash from signals (raw values never returned). */
+declare function fingerprintFromSignals(signals: MachineSignals): string;
+/** Stable, hashed machine fingerprint (`machine_installations.machine_fingerprint_hash`, §14.3). */
+declare function getMachineFingerprintHash(signals?: MachineSignals): string;
+/** Normalized OS value for `machine.os` (§10.2) / `machine_installations.os` (§14.3). */
+declare function getOS(platform?: NodeJS.Platform): string;
+/** Best-effort human label for `machine.label` (§10.2); auto-detected, editable in-app (§8.7). */
+declare function getMachineLabel(rawHostname?: string): string;
+/** Convenience: the full machine identity used by pairing + the event `machine` block. */
+interface MachineIdentity {
+    label: string;
+    os: string;
+    fingerprintHash: string;
+}
+declare function getMachineIdentity(): MachineIdentity;
+
+/** 24h default retention (§15.3). */
+declare const QUEUE_RETENTION_MS: number;
+/** Default max entries drained per call so a drain never blocks the harness (§9.3). */
+declare const DEFAULT_DRAIN_MAX = 50;
+/**
+ * Age after which a `.claim` file is considered ORPHANED and returned to the queue
+ * (erm): a drain claims an entry via rename before sending; if that process is killed
+ * mid-send the claim would otherwise strand the event forever (claims are invisible
+ * to normal reads). Far above any legitimate in-flight send (bounded to seconds).
+ */
+declare const CLAIM_RECLAIM_MS = 60000;
+/** What the sender decided for one queued event. delivered/drop → remove; retry → keep. */
+type DrainOutcome = "delivered" | "drop" | "retry";
+interface DrainResult {
+    delivered: number;
+    dropped: number;
+    kept: number;
+    pruned: number;
+}
+interface LocalEventQueueOptions {
+    /** Queue directory (default `<dataDir>/queue`). Tests pass a sandbox path. */
+    dir?: string;
+    /** Retention window in ms (default 24h). */
+    retentionMs?: number;
+    /** Injectable clock (ms since epoch) for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Best-effort on-disk queue. Every public method swallows I/O errors (returning a
+ * safe default) so a full/locked/corrupt queue degrades gracefully and never
+ * throws into the calling hook.
+ */
+declare class LocalEventQueue {
+    #private;
+    readonly dir: string;
+    constructor(options?: LocalEventQueueOptions);
+    /** Park a normalized event on disk (atomic write, 0600). Never throws. */
+    enqueue(event: BirdyBeepAgentEvent): boolean;
+    /** Count of fresh (non-expired) queued events. Prunes expired entries as a side effect. */
+    size(): number;
+    /**
+     * Drain up to `max` fresh entries through `send`. Each entry is CLAIMED via an
+     * atomic rename before sending, so two concurrent drains never double-send the
+     * same event. delivered/drop remove the entry; retry keeps it for next time.
+     * Bounded + best-effort: never throws into the caller.
+     */
+    drain(send: (event: BirdyBeepAgentEvent) => Promise<DrainOutcome> | DrainOutcome, options?: {
+        max?: number;
+        stopWhen?: () => boolean;
+    }): Promise<DrainResult>;
+    /** Remove every queued entry (used by `doctor` / debug tooling). Never throws. */
+    clear(): number;
+    /** Whether the queue dir has secure (0700) perms. Returns true on Windows (ACL-based). */
+    isSecure(): boolean;
+}
+
+type TokenStoreKind = "keychain" | "file";
+interface TokenStore {
+    readonly kind: TokenStoreKind;
+    get(): Promise<string | null>;
+    set(token: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Pluggable OS-keychain backend. Real impls shell out; tests inject a fake. */
+interface KeychainBackend {
+    /** Whether this backend can be used on the current machine. */
+    readonly available: boolean;
+    get(service: string, account: string): Promise<string | null>;
+    set(service: string, account: string, secret: string): Promise<void>;
+    delete(service: string, account: string): Promise<void>;
+}
+interface FileTokenStoreOptions {
+    /** Override the token file path (tests). Default `<dataDir>/token`. */
+    path?: string;
+}
+declare class FileTokenStore implements TokenStore {
+    #private;
+    readonly kind = "file";
+    readonly path: string;
+    constructor(options?: FileTokenStoreOptions);
+    get(): Promise<string | null>;
+    set(token: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class KeychainTokenStore implements TokenStore {
+    #private;
+    readonly kind = "keychain";
+    constructor(backend: KeychainBackend);
+    get(): Promise<string | null>;
+    set(token: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** A backend that reports itself unavailable (Linux without secret service / Windows fallback). */
+declare const unavailableKeychainBackend: KeychainBackend;
+/** macOS Keychain via the built-in `security` CLI. */
+declare function macosKeychainBackend(): KeychainBackend;
+/** The default keychain backend for the current OS (best-effort; file fallback otherwise). */
+declare function defaultKeychainBackend(): KeychainBackend;
+interface TokenStoreOptions {
+    /** Inject a keychain backend (tests / custom). Defaults to the OS backend. */
+    backend?: KeychainBackend;
+    /** Override the fallback file path (tests). */
+    filePath?: string;
+}
+/** Resolve the PRIMARY store: keychain when available, else the strict-perm file. */
+declare function resolveTokenStore(options?: TokenStoreOptions): TokenStore;
+/** Store the machine token in the primary store (keychain if available, else file). */
+declare function setToken(token: string, options?: TokenStoreOptions): Promise<TokenStoreKind>;
+/** Read the machine token: keychain first if available, then the file fallback. */
+declare function getToken(options?: TokenStoreOptions): Promise<string | null>;
+/** Remove the token from BOTH keychain and file fallback (logout / revoke). */
+declare function clearToken(options?: TokenStoreOptions): Promise<void>;
+
+/**
+ * Event sender (§9.2–9.3): POST a normalized event to `/v1/agent-events` with a
+ * SHORT hard timeout; on timeout/network/transient failure, queue it and return
+ * fast — never blocking or throwing into the harness. The retry-vs-terminal
+ * decision keys off the product error-envelope code (mirrored in `api.ts`), so the
+ * queue never fills with un-deliverable events. Each send also opportunistically
+ * drains the backlog (bounded by count AND by a TOTAL time budget — Claude Code
+ * installs its hooks with a 10s timeout, and an unbounded 50-entry drain at 3s per
+ * attempt could blow well past it, erm). The token is read from secure storage at
+ * send time and never logged; request bodies/title/body are never logged.
+ */
+
+declare const DEFAULT_SEND_TIMEOUT_MS = 3000;
+/**
+ * Total wall-clock budget for one send() (first attempt + opportunistic drain).
+ * Comfortably under the 10s hook timeout the adapters install, with headroom for
+ * process spawn + stdin read around it.
+ */
+declare const DEFAULT_TOTAL_BUDGET_MS = 5000;
+type SendOutcome = "delivered" | "queued" | "dropped";
+interface SendResult {
+    outcome: SendOutcome;
+    status?: number;
+    /** Error code from the response envelope, when the server returned one. */
+    code?: ErrorCode;
+    /**
+     * The backend's delivery decision from the 202 body (`notified` / `suppressed` /
+     * `deduped`), when parseable. Lets callers (CLI `test`, 9fh) report what actually
+     * happened instead of claiming a beep that the backend decided not to push.
+     */
+    decision?: string;
+    /** Result of the opportunistic queue drain performed on this send. */
+    drained?: DrainResult;
+}
+interface SenderConfig {
+    /** API base URL, e.g. `https://api.birdybeep.com` (or a `wrangler dev` URL). */
+    baseUrl: string;
+    /** Hard per-request timeout (default 3s) — the harness must not wait longer. */
+    timeoutMs?: number;
+    /** Total budget for one send()+drain (default 5s) — see module doc (erm). */
+    totalBudgetMs?: number;
+    /** Queue instance (default a LocalEventQueue at the user data dir). */
+    queue?: LocalEventQueue;
+    /** Token-store options (inject backend/path in tests). */
+    tokenOptions?: TokenStoreOptions;
+    /** fetch implementation (injected in tests). */
+    fetchImpl?: typeof fetch;
+    /** Max queued events drained per send (bounded so the hook returns fast). */
+    drainMax?: number;
+    /** Injectable clock (ms) for deterministic budget tests. */
+    now?: () => number;
+}
+interface Sender {
+    send(event: BirdyBeepAgentEvent): Promise<SendResult>;
+    drainNow(): Promise<DrainResult>;
+}
+declare function createSender(config: SenderConfig): Sender;
+
+/**
+ * The shared hook pipeline (§9.2–9.3): the core of `birdybeep hook <harness>`.
+ * A harness fires a hook → this runs adapter.normalizeEvent (redact/hash/validate)
+ * → dedup (collapse a repeat of the same beep) → sender.send (short timeout, queue
+ * on failure) → return fast. It must NEVER throw into or block the harness: an
+ * unmappable payload is skipped, a duplicate is dropped, and delivery failures queue.
+ * The CLI `hook` command (CLI-HOOK) wires stdin + adapter selection around this.
+ */
+
+type HookOutcome = "delivered" | "queued" | "dropped" | "deduped" | "skipped";
+interface HookResult {
+    outcome: HookOutcome;
+    /** The normalized event type, when the payload was mappable. */
+    eventType?: string;
+    /** The sender's result, when a send was attempted. */
+    send?: SendResult;
+}
+interface RunHookOptions {
+    sender: Sender;
+    /** Dedup ledger (default a RecentEventLedger at the user data dir). */
+    ledger?: RecentEventLedger;
+}
+/**
+ * Run one harness hook fire end-to-end. Returns a {@link HookResult}; never throws.
+ */
+declare function runAgentHook(adapter: AgentAdapter, rawInput: unknown, options: RunHookOptions): Promise<HookResult>;
+
+/**
+ * Integration-status report wire contract (§8.8/§13.4) — MIRRORED from the product
+ * `packages/schemas/integrations.ts`. `birdybeep agent install` / `doctor` report each
+ * harness's install/health state in ONE batched `POST /v1/integrations/status` call.
+ * LOCKSTEP (§16.4): additive to and independent of the §10.2 event payload.
+ *
+ * Identity (machine + user) is derived server-side from the machine token, never from this
+ * body. `last_status_payload` is diagnostic-only JSON (metadata only — never notification
+ * title/body or plaintext paths, §15.2), size-capped so an oversized blob fails validation.
+ */
+
+/** §8.8 integration status, as a validator (mirrors the product's `integrationStatusSchema`). */
+declare const integrationStatusSchema: z.ZodEnum<{
+    unknown: "unknown";
+    error: "error";
+    installed: "installed";
+    not_detected: "not_detected";
+    needs_restart: "needs_restart";
+    needs_trust: "needs_trust";
+    revoked: "revoked";
+}>;
+/** A machine reports a handful of harnesses per call (§8.8). */
+declare const STATUS_REPORT_MAX_ITEMS = 16;
+/** Diagnostic payload cap (§13.5): an oversized `last_status_payload` → 400. */
+declare const STATUS_REPORT_MAX_PAYLOAD_BYTES = 2048;
+/** One harness's reported install/health state. */
+declare const integrationStatusItemSchema: z.ZodObject<{
+    harness: z.ZodEnum<{
+        claude_code: "claude_code";
+        codex: "codex";
+        opencode: "opencode";
+    }>;
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        error: "error";
+        installed: "installed";
+        not_detected: "not_detected";
+        needs_restart: "needs_restart";
+        needs_trust: "needs_trust";
+        revoked: "revoked";
+    }>;
+    harness_version: z.ZodOptional<z.ZodString>;
+    adapter_version: z.ZodOptional<z.ZodString>;
+    last_status_payload: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** The batched `POST /v1/integrations/status` request body. */
+declare const integrationStatusReportSchema: z.ZodObject<{
+    integrations: z.ZodArray<z.ZodObject<{
+        harness: z.ZodEnum<{
+            claude_code: "claude_code";
+            codex: "codex";
+            opencode: "opencode";
+        }>;
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            error: "error";
+            installed: "installed";
+            not_detected: "not_detected";
+            needs_restart: "needs_restart";
+            needs_trust: "needs_trust";
+            revoked: "revoked";
+        }>;
+        harness_version: z.ZodOptional<z.ZodString>;
+        adapter_version: z.ZodOptional<z.ZodString>;
+        last_status_payload: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The response: the server echoes each harness's EFFECTIVE status (e.g. it forces
+ * Codex → `needs_trust` until the first event regardless of what the CLI reported).
+ * Tolerant of extra fields so a server addition won't break parsing.
+ */
+declare const integrationStatusResponseSchema: z.ZodObject<{
+    integrations: z.ZodArray<z.ZodObject<{
+        harness: z.ZodEnum<{
+            claude_code: "claude_code";
+            codex: "codex";
+            opencode: "opencode";
+        }>;
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            error: "error";
+            installed: "installed";
+            not_detected: "not_detected";
+            needs_restart: "needs_restart";
+            needs_trust: "needs_trust";
+            revoked: "revoked";
+        }>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+}, z.core.$strip>;
+type IntegrationStatusItem = z.infer<typeof integrationStatusItemSchema>;
+type IntegrationStatusReport = z.infer<typeof integrationStatusReportSchema>;
+type IntegrationStatusResponse = z.infer<typeof integrationStatusResponseSchema>;
+
+/** Per-field truncation caps (agent-local privacy choice; the 16 KB total is the lockstep cap). */
+declare const TITLE_MAX_CHARS = 200;
+declare const BODY_MAX_CHARS = 2000;
+declare const METADATA_VALUE_MAX_CHARS = 500;
+declare const METADATA_MAX_KEYS = 64;
+declare const METADATA_MAX_DEPTH = 4;
+declare const LABEL_MAX_CHARS = 120;
+/** Thrown when input cannot be coerced into a valid, under-cap event. */
+declare class NormalizeError extends Error {
+    readonly issues?: readonly unknown[] | undefined;
+    constructor(message: string, issues?: readonly unknown[] | undefined);
+}
+interface NormalizeOptions {
+    /** Injectable clock for deterministic tests. Default: real wall clock (ISO). */
+    now?: () => string;
+    /** Injectable id generator for deterministic tests. Default: `evt_local_<uuid>`. */
+    generateId?: () => string;
+}
+/** Replace every absolute path in a string with a stable hash (no raw path survives). */
+declare function scrubAbsolutePaths(text: string): string;
+/** Replace secret-looking substrings with a redaction marker. */
+declare function redactSecrets(text: string): string;
+/** Truncate to `max` chars with an ellipsis marker. */
+declare function truncate(text: string, max: number): string;
+/** Hash an absolute path so it never leaves the machine raw (§14.5). */
+declare function hashPath(path: string): string;
+/**
+ * Coerce raw adapter input into a privacy-safe, size-bounded, validated
+ * {@link BirdyBeepAgentEvent}. Fills `event_id`/`occurred_at` defaults, hashes
+ * absolute paths, redacts secrets, truncates strings, and enforces the size cap.
+ * Throws {@link NormalizeError} if the result cannot be made valid + under-cap.
+ */
+declare function normalizeEvent(input: unknown, opts?: NormalizeOptions): BirdyBeepAgentEvent;
+
+/**
+ * Pairing handshake wire contract (§7.2/§13.4) — MIRRORED from the product
+ * `packages/schemas/pairing.ts`. The CLI builds the `POST /v1/pair/start` + `/v1/pair/token`
+ * requests and parses these (BARE, not `{ data }`-wrapped) responses. LOCKSTEP (§16.4):
+ * additive to and independent of the §10.2 event payload — a change here is coordinated.
+ *
+ * Privacy (§15.1): codes are short-lived single-use, stored HASHED server-side; `qr_payload`
+ * carries only the short `user_code`, NEVER a durable token; the `machine_token` from
+ * `/pair/token` is shown once and only its peppered hash is persisted. Optional advisory
+ * fields use `.catch(undefined)` to match the routes' accept-and-ignore leniency.
+ *
+ * (`/v1/pair/approve` is the signed-in MOBILE side — not mirrored here; the CLI never calls it.)
+ */
+
+/** `POST /v1/pair/start` — UNAUTHENTICATED; the CLI opens a pairing session. */
+declare const pairStartRequestSchema: z.ZodObject<{
+    machine_label: z.ZodString;
+    os: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    cli_version: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    requested_scopes: z.ZodCatch<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+/** `POST /v1/pair/token` — UNAUTHENTICATED; the CLI exchanges its device code (polled). */
+declare const pairTokenRequestSchema: z.ZodObject<{
+    device_code: z.ZodString;
+    machine_fingerprint: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+/** `POST /v1/pair/start` response (bare). `qr_payload` encodes only the short `user_code`. */
+declare const pairStartResponseSchema: z.ZodObject<{
+    device_code: z.ZodString;
+    user_code: z.ZodString;
+    qr_payload: z.ZodString;
+    expires_at: z.ZodISODateTime;
+}, z.core.$strip>;
+/** `POST /v1/pair/token` 201 response (bare). The durable token is issued exactly once. */
+declare const pairTokenResponseSchema: z.ZodObject<{
+    machine_token: z.ZodString;
+    machine_id: z.ZodString;
+}, z.core.$strip>;
+type PairStartRequest = z.infer<typeof pairStartRequestSchema>;
+type PairTokenRequest = z.infer<typeof pairTokenRequestSchema>;
+type PairStartResponse = z.infer<typeof pairStartResponseSchema>;
+type PairTokenResponse = z.infer<typeof pairTokenResponseSchema>;
+
+/** Absolute path to the BirdyBeep user DATA dir (queue, caches). */
+declare function birdyBeepDataDir(): string;
+/** Absolute path to the BirdyBeep user CONFIG dir (token store fallback). */
+declare function birdyBeepConfigDir(): string;
+
+/**
+ * @birdybeep/agent-core — the shared runtime every adapter and the CLI build on:
+ * the canonical event schema (kept in lockstep with the private product repo's
+ * `packages/schemas`), the normalizer/redaction layer, the 24h local queue, the
+ * sender, the machine token store, and the `AgentAdapter` interface.
+ *
+ * The canonical event schema + enums (CORE-SCHEMA) are exported below. The
+ * normalizer/queue/sender/token-store/adapter-interface land in the remaining
+ * agent-core epic (CORE-*) tickets — see `bd ready`.
+ */
+
+/** Package version marker — replaced by the real build/version pipeline (REL-*). */
+declare const AGENT_CORE_VERSION = "0.0.0";
+/**
+ * Minimal identity an adapter reports about the harness it integrates with.
+ * The full {@link https://birdybeep.dev | AgentAdapter} interface (detect /
+ * install / uninstall / status / doctor / normalizeEvent) is defined in CORE-ADAPTER.
+ */
+interface AdapterMeta {
+    /** Stable harness id, e.g. `"claude_code"`, `"codex"`, `"opencode"`. */
+    readonly harness: string;
+}
+
+export { AGENT_CORE_VERSION, AGENT_SESSION_STATUSES, APPROVAL_COLLAPSE_WINDOW_MS, type AdapterMeta, type AgentAdapter, type AgentEventsRequest, type AgentSessionStatus, BIRDYBEEP_EVENT_TYPES, BODY_MAX_CHARS, type BirdyBeepAgentEvent, type BirdyBeepEventType, CLAIM_RECLAIM_MS, DEFAULT_DEDUP_WINDOW_MS, DEFAULT_DRAIN_MAX, DEFAULT_SEND_TIMEOUT_MS, DEFAULT_TOTAL_BUDGET_MS, type DetectionResult, type DoctorCheck, type DoctorResult, type DrainOutcome, type DrainResult, ERROR_CODES, ERROR_STATUS, type ErrorCode, type ErrorEnvelope, type EventMetadata, FileTokenStore, type FileTokenStoreOptions, HARNESS_IDS, type HarnessId, type HookOutcome, type HookResult, INTEGRATION_STATUSES, type InstallOptions, type InstallResult, type IntegrationStatus, type IntegrationStatusItem, type IntegrationStatusReport, type IntegrationStatusResponse, type KeychainBackend, KeychainTokenStore, LABEL_MAX_CHARS, LocalEventQueue, type LocalEventQueueOptions, MAX_AGENT_EVENT_BYTES, METADATA_MAX_DEPTH, METADATA_MAX_KEYS, METADATA_VALUE_MAX_CHARS, type Machine, type MachineIdentity, type MachineSignals, NormalizeError, type NormalizeOptions, type PairStartRequest, type PairStartResponse, type PairTokenRequest, type PairTokenResponse, QUEUE_RETENTION_MS, RecentEventLedger, type RecentEventLedgerOptions, type RunHookOptions, STATUS_REPORT_MAX_ITEMS, STATUS_REPORT_MAX_PAYLOAD_BYTES, type SendOutcome, type SendResult, type Sender, type SenderConfig, type SuccessEnvelope, TITLE_MAX_CHARS, type TokenStore, type TokenStoreKind, type TokenStoreOptions, type UninstallOptions, type UninstallResult, type Workspace, agentEventsRequestSchema, approvalCollapseIdentity, birdyBeepAgentEventSchema, birdyBeepConfigDir, birdyBeepDataDir, clearToken, collectMachineSignals, createSender, defaultKeychainBackend, errorCodeSchema, errorEnvelopeSchema, eventIdentity, eventMetadataSchema, eventTypeSchema, fingerprintFromSignals, getMachineFingerprintHash, getMachineIdentity, getMachineLabel, getOS, getToken, harnessSchema, hashPath, integrationStatusItemSchema, integrationStatusReportSchema, integrationStatusResponseSchema, integrationStatusSchema, isWithinMaxAgentEventSize, isoDateTimeSchema, machineSchema, macosKeychainBackend, normalizeEvent, pairStartRequestSchema, pairStartResponseSchema, pairTokenRequestSchema, pairTokenResponseSchema, redactSecrets, resolveTokenStore, runAgentHook, scrubAbsolutePaths, sessionStatusSchema, setToken, successEnvelopeSchema, truncate, unavailableKeychainBackend, workspaceSchema };