@wrongstack/core 0.284.1 → 0.285.0

package/dist/hq/index.d.ts

@@ -1,816 +1,18 @@
-import { $ as HqRedactionPolicy, t as HqEventEnvelope, W as HqPublisher, p as HqClientIdentity, ac as HqSocketFactory, i as HqClientCapability, X as HqPublisherCommandHandler, G as GlobalMailbox, ab as HqSnapshot, _ as HqQueuedCommand, c as HqAlertMessage, aj as HqTranscriptEntry } from '../global-mailbox-sZwyI6CS.js';
-export { D as DEFAULT_HQ_REDACTION_POLICY, H as HQ_PROTOCOL_VERSION, a as HqAgentMessagePayload, b as HqAgentStatusPayload, d as HqBrainEventKind, e as HqBrainEventPayload, f as HqBrowserEventMessage, g as HqBrowserMessage, h as HqBrowserSnapshotMessage, j as HqClientCommandAckMessage, k as HqClientCommandPollMessage, l as HqClientEventMessage, m as HqClientHeartbeatPayload, n as HqClientHelloMessage, o as HqClientHelloPayload, q as HqClientKind, r as HqClientMessage, s as HqClientRecord, u as HqEventPayloadResult, v as HqEventType, w as HqFleetEventPayload, x as HqFleetSnapshotPayload, y as HqFleetSummary, z as HqGitSnapshotPayload, A as HqMachineRecord, B as HqMailboxAgentStatus, C as HqMailboxAgentSummary, E as HqMailboxEventAction, F as HqMailboxEventPayload, I as HqMailboxMappingOptions, J as HqMailboxMessageSummary, K as HqMailboxMessageType, L as HqMailboxPriority, M as HqMailboxSnapshotOptions, N as HqMailboxSnapshotPayload, O as HqMailboxSummary, P as HqParseResult, Q as HqPathPolicy, R as HqProjectIdentity, S as HqProjectRecord, T as HqProjectStatus, U as HqProtocolVersion, V as HqPublishEventOptions, Y as HqPublisherCommandResult, Z as HqPublisherOptions, a0 as HqServerCommandBatchMessage, a1 as HqServerMessage, a2 as HqSessionAgentLiveStatus, a3 as HqSessionAgentSummary, a4 as HqSessionEndedPayload, a5 as HqSessionLiveStatus, a6 as HqSessionSnapshotPayload, a7 as HqSessionStartedPayload, a8 as HqSessionStatus, a9 as HqSessionStatusPayload, aa as HqSessionSummary, ad as HqSocketLike, ae as HqSubagentSummary, af as HqToolArgsPolicy, ag as HqToolCompletedPayload, ah as HqToolStartedPayload, ai as HqTranscriptAppendPayload, ak as HqTranscriptRole, al as HqUsagePayload, am as HqWelcomePayload, an as HqWorklistCounts, ao as HqWorklistSnapshotPayload, ap as HqWorkspaceKind, aq as HqWorktreeEventKind, ar as HqWorktreeEventPayload, as as createHqEventEnvelope, at as createMailboxEventPayload, au as createMailboxSnapshotPayload, av as createMailboxSnapshotPayloadFromMailbox, aw as mapMailboxAgentToHqSummary, ax as mapMailboxMessageToHqSummary, ay as parseHqEventPayload, az as parseHqFrame } from '../global-mailbox-sZwyI6CS.js';
-import { E as EventBus, T as TrackedAgentSnapshot } from '../events-Bgnh43r9.js';
-import { V as HqClientConfig } from '../config-MRqn1V-u.js';
-import '../mailbox-types-BGZWrYTJ.js';
-import '../tool-BNlnIJvo.js';
-import '../permission-ByDKXEcG.js';
-
-interface HqRedactOptions {
-    policy?: Partial<HqRedactionPolicy>;
-    projectRoot?: string;
-    maxSummaryLength?: number;
-}
-interface HqRedactionResult<T> {
-    value: T;
-    redacted: boolean;
-}
-/**
- * Scrub a free-text preview field and truncate it to a maximum length so
- * it is safe to embed in HQ event envelopes and broadcast to browsers
- * without leaking secrets or running away on unbounded input.
- *
- * Returns `undefined` when the input is empty or non-string. Truncation
- * suffix is `"…[truncated:N]"` where N is the number of dropped chars.
- */
-declare function scrubAndTruncateHqPreview(value: unknown, maxLength?: number): string | undefined;
-declare function redactHqValue<T>(value: T, options?: HqRedactOptions): HqRedactionResult<T>;
-declare function redactHqEvent<TPayload>(event: HqEventEnvelope<TPayload>, options?: HqRedactOptions): HqRedactionResult<HqEventEnvelope<TPayload>>;
-declare function summarizeHqToolArgs(value: unknown, options?: HqRedactOptions): unknown;
-
-interface HqPublisherEnvConfig {
-    url: string;
-    token?: string;
-    enabled?: boolean;
-    rawContent?: boolean;
-    projectAlias?: string;
-    /**
-     * Same-machine auto-discovery mode: no explicit URL was configured, so the
-     * publisher should re-resolve the endpoint from `<dataDir>/runtime.json`
-     * (+ the first client token in `auth.json`) before every connect attempt.
-     * This lets every client on the machine attach to a `wstack --hq` that is
-     * already running, starts later, or restarts on a different port.
-     */
-    discover?: boolean;
-    /** Resolved HQ data dir the discovery reads from. */
-    dataDir?: string;
-}
-/**
- * Discover a locally running `wstack --hq` endpoint: reads the runtime
- * marker (pid-liveness-checked) and the first client token. Returns
- * `undefined` when no live HQ is advertised on this machine.
- */
-declare function discoverLocalHqEndpoint(options?: {
-    dataDir?: string | undefined;
-    env?: NodeJS.ProcessEnv | undefined;
-}): {
-    url: string;
-    token?: string | undefined;
-} | undefined;
-declare function resolveHqConfigFromEnv(env?: NodeJS.ProcessEnv): HqPublisherEnvConfig | undefined;
-declare function resolveHqConfig(options?: {
-    env?: NodeJS.ProcessEnv | undefined;
-    config?: HqClientConfig | undefined;
-}): HqPublisherEnvConfig | undefined;
-interface CreateHqPublisherOptions {
-    clientKind: HqClientIdentity['kind'];
-    projectRoot: string;
-    projectName?: string;
-    machineId?: string;
-    hostnameOverride?: string;
-    socketFactory?: HqSocketFactory;
-    config?: HqPublisherEnvConfig;
-    appConfig?: {
-        hq?: HqClientConfig | undefined;
-    } | undefined;
-    redactionPolicy?: Partial<HqRedactionPolicy>;
-    /** Forwarded to the HqPublisher constructor (Phase 4 control plane). */
-    capabilities?: readonly HqClientCapability[];
-    /** Forwarded to the HqPublisher constructor (Phase 4 control plane). */
-    onCommand?: HqPublisherCommandHandler;
-    /** Dormant discovery re-check interval override (tests / tight loops). */
-    discoveryPollMs?: number;
-}
-declare function createHqPublisherFromEnv(options: CreateHqPublisherOptions): HqPublisher | undefined;
-interface CreateGlobalMailboxOptions {
-    projectDir: string;
-    events?: EventBus;
-    hqPublisher?: HqPublisher;
-}
-declare function createGlobalMailbox(options: CreateGlobalMailboxOptions): GlobalMailbox;
-
-/** Current auth-file schema version. Bump on breaking shape changes. */
-declare const HQ_AUTH_FILE_VERSION: 1;
-/** Default HQ data directory: `~/.wrongstack/hq` (honors WRONGSTACK_HOME). */
-declare function defaultHqDataDir(): string;
-/**
- * Resolve an HQ data directory from an optional override.
- *
- * Resolution order:
- *   1. Explicit `override` (from `--data-dir`) — resolved against
- *      `process.cwd()` if relative.
- *   2. `WRONGSTACK_HQ_DATA_DIR` env var (same resolution rules).
- *   3. `defaultHqDataDir()` — `~/.wrongstack/hq`.
- *
- * The env var exists so tests (and sandboxed runs) can redirect HQ state
- * away from the real user home without threading a CLI flag everywhere.
- */
-declare function resolveHqDataDir(override?: string, env?: NodeJS.ProcessEnv): string;
-/**
- * A generic HQ-issued token. Used for both browser tokens (validated on
- * `/ws/browser`) and client tokens (validated on `/ws/client`). The two
- * are stored in separate lists so a browser-only token cannot be replayed
- * against the client channel and vice versa.
- *
- * `capabilities` scopes what a token may do. When absent the token is
- * unrestricted (backward-compat with tokens minted before Phase 3). Known
- * capability strings:
- *   - `control.enqueue` — browser token may enqueue commands to clients
- *   - `control.execute` — client token may execute `run-command` commands
- *   - `telemetry.publish` — client token may publish telemetry
- */
-interface HqToken {
-    id: string;
-    token: string;
-    label?: string;
-    createdAt: string;
-    lastUsedAt?: string;
-    /**
-     * Optional capability scope. When absent, the token is unrestricted
-     * (backward-compat). When present, only the listed capabilities are
-     * granted.
-     */
-    capabilities?: string[];
-}
-/**
- * Check whether a token grants a capability. A token with no `capabilities`
- * field is unrestricted (backward-compat). Otherwise the capability must be
- * explicitly listed.
- */
-declare function tokenHasCapability(token: HqToken | undefined, capability: string): boolean;
-/**
- * Alias kept for backward-compat with Phase 3 callers/tests. New code
- * should prefer `HqToken`.
- */
-type HqBrowserToken = HqToken;
-/** On-disk shape of `<dataDir>/auth.json`. */
-interface HqRuntimeFile {
-    url: string;
-    updatedAt: string;
-    pid?: number;
-}
-interface HqAuthFile {
-    version: typeof HQ_AUTH_FILE_VERSION;
-    updatedAt: string;
-    /**
-     * Operator-configured redaction policy override. When present, the HQ
-     * server applies these settings AFTER any publisher-declared policy —
-     * i.e. the operator can always tighten, never loosen.
-     */
-    redactionPolicy?: Partial<HqRedactionPolicy>;
-    /** Browser tokens — validated on `/ws/browser` upgrades (Phase 3). */
-    browserTokens?: HqToken[];
-    /** Client tokens — validated on `/ws/client` upgrades (Phase 4). */
-    clientTokens?: HqToken[];
-}
-/** An empty auth file — what a brand-new HQ install starts with. */
-declare function emptyHqAuthFile(): HqAuthFile;
-/** Path to `auth.json` under the given data directory. */
-declare function hqAuthFilePath(dataDir: string): string;
-/** Path to the best-effort runtime endpoint marker under the given data directory. */
-declare function hqRuntimeFilePath(dataDir: string): string;
-declare function writeHqRuntimeFile(dataDir: string, file: Omit<HqRuntimeFile, 'updatedAt'>): Promise<void>;
-declare function readHqRuntimeFileSync(dataDir: string): HqRuntimeFile | undefined;
-/**
- * Read `auth.json` from disk. Returns `emptyHqAuthFile()` when:
- *   - the file does not exist (ENOENT), or
- *   - the file cannot be parsed (the `warn` callback surfaces the error).
- *
- * Never throws for routine I/O — a missing or corrupt auth file should not
- * prevent the HQ server from starting. The operator can recover by editing
- * or deleting the file.
- */
-declare function readHqAuthFile(dataDir: string, opts?: {
-    warn?: (msg: string) => void;
-}): Promise<HqAuthFile>;
-/**
- * Write `auth.json` atomically with mode 0o600. Creates the data directory
- * if needed. Throws on I/O failure — callers (CLI commands) should surface
- * the error to the operator.
- */
-declare function writeHqAuthFile(dataDir: string, file: HqAuthFile): Promise<void>;
-interface EnsureHqFirstRunAuthResult {
-    authFile: HqAuthFile;
-    created: boolean;
-    browserToken?: HqToken;
-    clientToken?: HqToken;
-}
-/**
- * Ensure a brand-new HQ data directory has the auth required for safe
- * first-run operation. Only a missing auth.json is bootstrapped; an existing
- * file, including one with empty token arrays, is treated as operator intent.
- */
-declare function ensureHqFirstRunAuthFile(dataDir: string, opts?: {
-    warn?: (msg: string) => void;
-}): Promise<EnsureHqFirstRunAuthResult>;
-/**
- * Load → mutate → write. The mutator receives the current file (or an empty
- * one) and returns the next file. Use this for any read-modify-write cycle
- * to avoid clobbering concurrent edits from another CLI invocation.
- *
- * Note: this does NOT take a file lock. HQ auth edits are rare (operator
- * running `wstack --hq-token add` etc.) and the atomic rename protects
- * against torn writes; a race between two concurrent edits would be
- * last-write-wins, which is acceptable for this low-frequency file.
- */
-declare function mutateHqAuthFile(dataDir: string, mutator: (current: HqAuthFile) => HqAuthFile | Promise<HqAuthFile>, opts?: {
-    warn?: (msg: string) => void;
-}): Promise<HqAuthFile>;
-/**
- * Mint a fresh token. Used for both browser and client tokens; the caller
- * decides which list to append to.
- */
-declare function mintHqToken(label?: string): HqToken;
-/**
- * Backward-compat alias for `mintHqToken`. Phase 3 callers/tests use this.
- */
-declare const mintHqBrowserToken: typeof mintHqToken;
-/**
- * Watch `auth.json` for changes and invoke `onChange` with the freshly-read
- * file. Returns a `close()` function that stops watching.
- *
- * The watcher debounces events (default 200ms) because most editors do a
- * tmp+rename dance that emits multiple events. On any read failure (file
- * deleted, corrupt, etc.) the `warn` callback is invoked with the same
- * semantics as `readHqAuthFile`; the watcher stays active so a future
- * valid write re-triggers the callback.
- *
- * Notes:
- * - `fs.watch` is best-effort across platforms. On some network
- *   filesystems events may not fire; the operator must restart the server
- *   to pick up changes in that case.
- * - The watcher polls the parent directory (not the file itself) so that
- *   atomic rename events surface reliably.
- */
-declare function watchHqAuthFile(dataDir: string, onChange: (file: HqAuthFile) => void, opts?: {
-    warn?: (msg: string) => void;
-    debounceMs?: number;
-}): {
-    close: () => void;
-};
-
-/**
- * AgentMonitorEventBridge — forwards local agent timeline and status events
- * to the HQ publisher as structured HQ event envelopes, so the HQ browser
- * dashboard sees real-time agent conversation streams.
- */
-
-type HqAgentEventPublisher = (envelope: HqEventEnvelope) => void;
-interface AgentMonitorEventBridgeOptions {
-    /** Local EventBus emitting agent.timeline.* and agent.status_changed events. */
-    events: EventBus;
-    /** Client/project identifiers for HQ envelope authorship. */
-    clientId: string;
-    projectId: string;
-    /**
-     * Publish callback — called with each HQ event envelope. Wire this to
-     * your HQ publisher's `send()` or queue method when connected.
-     * When null (no HQ connection), events are silently dropped.
-     */
-    publish?: HqAgentEventPublisher | undefined;
-}
-/**
- * Start forwarding agent monitoring events to HQ. Returns a disposer that
- * unsubscribes all listeners — call on shutdown.
- */
-declare function startAgentMonitorEventBridge(opts: AgentMonitorEventBridgeOptions): () => void;
-
-interface SessionTelemetryBridgeOptions {
-    publisher: HqPublisher;
-    /** Local bus carrying `session.agents_updated`. When omitted, snapshots
-     * still publish (with empty/last-known agents) and the transcript still
-     * streams from disk. */
-    events?: EventBus | undefined;
-    sessionId: string;
-    projectRoot: string;
-    projectName?: string | undefined;
-    /** Override the global root used to resolve the session JSONL path. */
-    globalRoot?: string | undefined;
-    /** Last-known agents to publish immediately before the next bus update. */
-    initialAgents?: readonly TrackedAgentSnapshot[] | undefined;
-    gitBranch?: string | undefined;
-    startedAt?: string | undefined;
-    /** Snapshot republish interval (also refreshes lastActivity). Default 2500ms. */
-    snapshotIntervalMs?: number | undefined;
-    /** Transcript tail poll interval. Default 1200ms. */
-    transcriptIntervalMs?: number | undefined;
-    now?: (() => string) | undefined;
-}
-/**
- * Start streaming this surface's session telemetry to HQ. Returns a disposer
- * that stops both streams and publishes a final `session.ended`.
- */
-declare function startSessionTelemetryBridge(opts: SessionTelemetryBridgeOptions): () => void;
-
-/**
- * FleetTelemetryBridge — forwards local multi-agent coordinator stats to the
- * HQ publisher as `fleet.snapshot` envelopes, so the command center can render
- * a global fleet roll-up (queued/completed/failed tasks, per-subagent status,
- * fleet cost) across every connected machine.
- *
- * Source: the `coordinator.stats` EventBus event (originating on the FleetBus
- * and re-emitted onto the host EventBus by `fleet/host.ts`). All payload
- * fields are plain serializable data — no closures, no decoupled relay needed.
- *
- * The snapshot is republished on every `coordinator.stats` change (hash-dedup,
- * mirroring {@link startSessionTelemetryBridge}) so the HQ browser sees live
- * fleet counters without polling.
- *
- * @module hq/fleet-bridge
- */
-
-interface FleetTelemetryBridgeOptions {
-    /** Local EventBus emitting `coordinator.stats` (host EventBus after the FleetBus hop). */
-    events: EventBus;
-    /** HQ publisher to forward envelopes to. */
-    publisher: HqPublisher;
-    /** Coordinator run id — identifies this fleet instance. Falls back to a stable per-session id. */
-    runId: string;
-    /** Optional sessionId to tag envelopes with. */
-    sessionId?: string;
-    /** Override `now()` for deterministic tests. */
-    now?: () => string;
-}
-/**
- * Start forwarding coordinator stats to HQ. Returns a disposer that
- * unsubscribes the listener — call on shutdown.
- */
-declare function startFleetTelemetryBridge(opts: FleetTelemetryBridgeOptions): () => void;
-
-/**
- * BrainTelemetryBridge — forwards local Brain (decision layer) events to the
- * HQ publisher as `brain.event` envelopes, so the command center can observe
- * decision requests, answers, denials, ask-human escalations, and
- * self-activated interventions across every connected machine.
- *
- * Source: the `brain.*` EventBus events emitted by `ObservableBrainArbiter`
- * (`coordination/brain.ts`) and `BrainMonitor` (`coordination/brain-monitor.ts`).
- * All payloads are plain serializable data (request id, question, source, risk,
- * decision kind, rationale) — no closures, no decoupled relay needed.
- *
- * The webui `setup-events.ts` already forwards these verbatim to its browser;
- * this bridge does the same for the cross-machine HQ plane.
- *
- * @module hq/brain-bridge
- */
-
-interface BrainTelemetryBridgeOptions {
-    /** Local EventBus emitting `brain.*` events. */
-    events: EventBus;
-    /** HQ publisher to forward envelopes to. */
-    publisher: HqPublisher;
-    /** Optional sessionId to tag envelopes with. */
-    sessionId?: string;
-    /** Override `now()` for deterministic tests. */
-    now?: () => string;
-}
-/**
- * Start forwarding brain events to HQ. Returns a disposer that unsubscribes
- * all listeners — call on shutdown.
- */
-declare function startBrainTelemetryBridge(opts: BrainTelemetryBridgeOptions): () => void;
-
-/**
- * WorktreeTelemetryBridge — forwards local git-worktree lifecycle events to
- * the HQ publisher as `worktree.event` envelopes, so the command center can
- * render live build phase swim-lanes / DAG across every connected machine.
- *
- * Source: the `worktree.*` EventBus events emitted by `WorktreeManager`
- * (`worktree/worktree-manager.ts`): allocated, committed, merged, conflict,
- * released, failed. All payload fields are plain serializable data
- * (handleId, ownerId, branch, diff stats, conflict files) — no closures, no
- * decoupled relay needed.
- *
- * @module hq/worktree-bridge
- */
-
-interface WorktreeTelemetryBridgeOptions {
-    /** Local EventBus emitting `worktree.*` events. */
-    events: EventBus;
-    /** HQ publisher to forward envelopes to. */
-    publisher: HqPublisher;
-    /** Optional sessionId to tag envelopes with. */
-    sessionId?: string;
-    /** Override `now()` for deterministic tests. */
-    now?: () => string;
-}
-/**
- * Start forwarding worktree lifecycle events to HQ. Returns a disposer that
- * unsubscribes all listeners — call on shutdown.
- */
-declare function startWorktreeTelemetryBridge(opts: WorktreeTelemetryBridgeOptions): () => void;
-
-/**
- * ToolTelemetryBridge — forwards local tool execution events to the HQ
- * publisher as `tool.started` and `tool.completed` envelopes, so the command
- * center can surface live tool activity (what's running, durations, success
- * rates) across every connected machine.
- *
- * Sources:
- *  - `tool.started` (EventBus) → `tool.started` envelope. Raw tool input is
- *    summarized via {@link summarizeHqToolArgs} so no secrets or oversized
- *    payloads leak to the HQ browser.
- *  - `tool.executed` (EventBus) → `tool.completed` envelope (carries the
- *    richer post-execution signal: duration, ok/error, output bytes).
- *
- * All payload fields are plain serializable data — no closures. The
- * `tool.started.input` raw args are the only sensitive surface and are
- * reduced to a summary before publishing.
- *
- * @module hq/tool-bridge
- */
-
-interface ToolTelemetryBridgeOptions {
-    /** Local EventBus emitting `tool.started` and `tool.executed` events. */
-    events: EventBus;
-    /** HQ publisher to forward envelopes to. */
-    publisher: HqPublisher;
-    /** Project root for path redaction in tool input summaries. */
-    projectRoot?: string;
-    /** Optional sessionId to tag envelopes with. */
-    sessionId?: string;
-    /** Override `now()` for deterministic tests. */
-    now?: () => string;
-}
-/**
- * Start forwarding tool execution events to HQ. Returns a disposer that
- * unsubscribes all listeners — call on shutdown.
- */
-declare function startToolTelemetryBridge(opts: ToolTelemetryBridgeOptions): () => void;
-
-/**
- * CostTelemetryBridge — forwards local token/cost accounting events to the HQ
- * publisher as `session.usage` envelopes, giving the command center the
- * granular per-call cost signal it needs to render live cost trends and
- * roll-ups across every connected machine.
- *
- * Source: the `token.accounted` EventBus event, emitted by the TokenCounter
- * (`infrastructure/token-counter.ts`) after every provider call. The payload
- * is plain serializable data (usage counts + a cost breakdown) — no closures.
- *
- * This is the high-frequency cost feed; HQ's persistence layer (Phase 2)
- * time-buckets these into trend series.
- *
- * @module hq/cost-bridge
- */
-
-interface CostTelemetryBridgeOptions {
-    /** Local EventBus emitting `token.accounted`. */
-    events: EventBus;
-    /** HQ publisher to forward envelopes to. */
-    publisher: HqPublisher;
-    /** Optional sessionId to tag envelopes with (overrides the event's, when set). */
-    sessionId?: string;
-    /** Override `now()` for deterministic tests. */
-    now?: () => string;
-}
-/**
- * Start forwarding token/cost events to HQ. Returns a disposer that
- * unsubscribes the listener — call on shutdown.
- */
-declare function startCostTelemetryBridge(opts: CostTelemetryBridgeOptions): () => void;
-
-interface HqEventLogOptions {
-    dataDir: string;
-    maxLines?: number;
-    rotateKeep?: number;
-}
-/**
- * Append-only JSONL event log. Every received event envelope is appended to
- * `events.jsonl`; when the file exceeds `maxLines` it is rotated under a file
- * lock to keep only the most recent `rotateKeep` lines.
- *
- * Writes are serialized through a FIFO chain so concurrent appends never
- * interleave. All operations are best-effort: a rejected append resolves
- * (never rejects) and the caller's `await` never breaks the server loop.
- */
-declare class HqEventLog {
-    private readonly filePath;
-    private readonly maxLines;
-    private readonly rotateKeep;
-    private writeChain;
-    private lineCount;
-    private counted;
-    constructor(opts: HqEventLogOptions);
-    /** Append an event envelope as one JSON line. Best-effort, never rejects. */
-    append(event: HqEventEnvelope): void;
-    /** Resolves once all queued appends have settled. For tests. */
-    drain(): Promise<void>;
-    private appendInternal;
-    private rotate;
-    private countLines;
-    /**
-     * Read the most recent `limit` events, optionally filtered by envelope
-     * `type`. Newest first. Returns `[]` if the file doesn't exist yet.
-     */
-    recent(limit: number, typeFilter?: string): Promise<HqEventEnvelope[]>;
-    /** Initialize the line count cache from disk (call once at boot). */
-    hydrate(): Promise<void>;
-}
-interface HqSnapshotStoreOptions {
-    dataDir: string;
-}
-/**
- * Atomic checkpoint of the latest snapshot, written to `snapshot.json`.
- * The HQ server writes on every debounced broadcast and reads on boot to
- * re-seed its in-memory state. Best-effort, never rejects.
- */
-declare class HqSnapshotStore {
-    private readonly filePath;
-    private writeChain;
-    constructor(opts: HqSnapshotStoreOptions);
-    /** Persist a snapshot. Best-effort, never rejects. */
-    save(snapshot: HqSnapshot): void;
-    /** Resolves once all queued saves have settled. For tests. */
-    drain(): Promise<void>;
-    /** Read the last persisted snapshot, or `null` if none. */
-    load(): Promise<HqSnapshot | null>;
-}
-interface HqTimeseriesSample {
-    /** Bucket start (epoch ms, floored to the bucket width). */
-    ts: number;
-    /** Total cost (USD) accumulated in this bucket. */
-    costUsd: number;
-    /** Total input tokens in this bucket. */
-    inputTokens: number;
-    /** Total output tokens in this bucket. */
-    outputTokens: number;
-    /** Number of tool executions in this bucket. */
-    toolCalls: number;
-    /** Snapshot of active agents at bucket close (last-write per bucket). */
-    activeAgents?: number;
-}
-interface HqTimeseriesStoreOptions {
-    dataDir: string;
-    /** Bucket width in ms. Default 5 minutes. */
-    bucketMs?: number;
-    /** How many buckets to retain. Default 2016 (1 week of 5-min buckets). */
-    maxBuckets?: number;
-}
-/**
- * Time-bucketed cost + activity samples for trend charts. Each {@link record}
- * call folds a cost/tool signal into the current bucket; {@link flush} writes
- * the accumulated buckets to `timeseries.jsonl` (append under lock) and prunes
- * to `maxBuckets`.
- *
- * The store keeps an in-memory ring of buckets for cheap reads; {@link load}
- * rehydrates them on boot.
- */
-declare class HqTimeseriesStore {
-    private readonly filePath;
-    private readonly bucketMs;
-    private readonly maxBuckets;
-    private readonly buckets;
-    private flushChain;
-    constructor(opts: HqTimeseriesStoreOptions);
-    private bucketStart;
-    /** Fold a cost/tool signal into the current bucket. Best-effort. */
-    record(signal: {
-        ts?: number;
-        costUsd?: number;
-        inputTokens?: number;
-        outputTokens?: number;
-        toolCalls?: number;
-        activeAgents?: number;
-    }): void;
-    /** Persist accumulated buckets to disk (append under lock), prune to maxBuckets. */
-    flush(): void;
-    /** Resolves once all queued flushes have settled. For tests. */
-    drain(): Promise<void>;
-    private flushInternal;
-    /** Read buckets within `[since, now]`, oldest-first. */
-    read(sinceMs?: number): Promise<HqTimeseriesSample[]>;
-    /** Rehydrate buckets from disk (deduped, latest-per-bucket wins). */
-    load(): Promise<void>;
-}
-interface HqPersistence {
-    eventLog: HqEventLog;
-    snapshotStore: HqSnapshotStore;
-    timeseries: HqTimeseriesStore;
-}
-declare function createHqPersistence(dataDir: string): HqPersistence;
-
-/**
- * HQ control-plane command definitions — typed payloads for the commands the
- * HQ dashboard can enqueue to connected machines (Phase 3+ of the HQ command
- * center). These are carried over the existing `HqQueuedCommand` wire shape
- * (`{commandId, type, payload, …}`) whose `type`/`payload` were previously
- * type-erased. This module gives them a discriminated union for type-safe
- * dispatch on the client side (Phase 4).
- *
- * Security model: `run-command` (raw shell) is gated by a per-token
- * `control.execute` capability AND an operator opt-in; the other four commands
- * route through the agent's own decision loop / mailbox and inherit their
- * existing guardrails. See `docs/plans/hq-command-center-2026-07.md`.
- *
- * @module hq/commands
- */
-
-/** HQ_COMMAND_TYPES — the full set of recognized command `type` strings. */
-declare const HQ_COMMAND_TYPES: readonly ["steer", "btw", "queue", "abort", "spawn", "broadcast", "run-command"];
-type HqCommandType = (typeof HQ_COMMAND_TYPES)[number];
-/** Inject a steer text into a target agent's conversation. */
-interface HqSteerCommand {
-    type: 'steer';
-    /** Target agent address: a unique id (`leader@<tag>`), an alias (`leader`), or `*` for all. */
-    to: string;
-    subject: string;
-    body: string;
-    priority?: 'low' | 'normal' | 'high';
-}
-/**
- * Post a non-urgent FYI (`btw`) into a target agent's mailbox. Unlike a steer,
- * a btw is absorbed as context — it does not demand the agent change course.
- * Same wire shape as steer; only the emitted mailbox `type` differs.
- */
-interface HqBtwCommand {
-    type: 'btw';
-    /** Target agent address: a unique id (`leader@<tag>`), an alias (`leader`), or `*` for all. */
-    to: string;
-    subject: string;
-    body: string;
-    priority?: 'low' | 'normal' | 'high';
-}
-/**
- * Queue a prompt/note (`queue`) for a target agent. Delivered as a plain
- * `note` mailbox message the agent picks up before its next step — used when
- * the prompt should wait its turn rather than steer the current operation.
- */
-interface HqQueueCommand {
-    type: 'queue';
-    /** Target agent address: a unique id (`leader@<tag>`), an alias (`leader`), or `*` for all. */
-    to: string;
-    subject: string;
-    body: string;
-    priority?: 'low' | 'normal' | 'high';
-}
-/** Abort a running agent run or fleet. */
-interface HqAbortCommand {
-    type: 'abort';
-    /** `'leader'` aborts the session leader; a subagentId aborts one agent; `'fleet'` stops all. */
-    target: 'leader' | 'fleet' | string;
-}
-/** Spawn a subagent of the given role. */
-interface HqSpawnCommand {
-    type: 'spawn';
-    role: string;
-    /** Optional task description for dispatch routing. */
-    task?: string;
-    maxIterations?: number;
-}
-/** Broadcast a mailbox message to all agents on the target's project. */
-interface HqBroadcastCommand {
-    type: 'broadcast';
-    subject: string;
-    body: string;
-    priority?: 'low' | 'normal' | 'high';
-}
-/** Run a shell command on the target machine. GATED by `control.execute`. */
-interface HqRunCommandCommand {
-    type: 'run-command';
-    command: string;
-    /** Optional working directory (defaults to the agent's project root). */
-    cwd?: string;
-}
-type HqCommand = HqSteerCommand | HqBtwCommand | HqQueueCommand | HqAbortCommand | HqSpawnCommand | HqBroadcastCommand | HqRunCommandCommand;
-/**
- * Validate that an inbound `HqQueuedCommand` has a recognized `type` and a
- * minimally well-formed payload. Returns the narrowed command on success, or
- * `null` when the command should be rejected.
- *
- * This is a shape check, not a security gate — capability enforcement happens
- * at enqueue time (browser token must have `control.enqueue`) and at execute
- * time (`run-command` requires `control.execute`).
- */
-declare function validateHqCommand(queued: HqQueuedCommand): HqCommand | null;
-interface HqCommandAuditEntry {
-    commandId: string;
-    type: HqCommandType;
-    clientId: string;
-    /** Who enqueued the command (browser token id, or 'anonymous' in open mode). */
-    enqueuedBy: string;
-    enqueuedAt: string;
-    status: 'queued' | 'delivered' | 'acked';
-    /** Ack status when the client has responded. */
-    ackStatus?: 'accepted' | 'completed' | 'failed' | 'rejected';
-    ackMessage?: string;
-    ackedAt?: string;
-}
-/**
- * In-memory command audit ring. Capped; the Phase 2 persistence layer can
- * sink entries to disk when wired (future). For now this gives the server a
- * queryable history for `/api/commands` and snapshot enrichment.
- */
-declare class HqCommandAuditLog {
-    private readonly entries;
-    private readonly max;
-    constructor(max?: number);
-    record(entry: HqCommandAuditEntry): void;
-    update(commandId: string, patch: Partial<HqCommandAuditEntry>): void;
-    recent(limit?: number): HqCommandAuditEntry[];
-}
-
-/**
- * HQ alerting engine — evaluates the current snapshot against a set of
- * operator-configurable rules and emits `hq.alert` messages when a threshold
- * is crossed. Mirrors the BrainMonitor's self-activation logic (tool-failure
- * streaks, error storms) but at the fleet-wide command-center scope.
- *
- * Rules are evaluated on a periodic tick (default 15s, unref'd) against the
- * latest in-memory snapshot. Deduplication prevents alert storms: a rule that
- * is still firing is not re-emitted until it clears (state machine per rule).
- *
- * @module hq/alerts
- */
-
-/** Severity levels for alerts, mirroring {@link HqAlertMessage}. */
-type HqAlertSeverity = HqAlertMessage['severity'];
-interface HqAlert {
-    id: string;
-    ruleId: string;
-    severity: HqAlertSeverity;
-    message: string;
-    /** Epoch ms when the alert first fired in its current episode. */
-    firstFiredAt: number;
-    /** Epoch ms of the most recent evaluation that confirmed the alert. */
-    lastFiredAt: number;
-}
-interface HqAlertRuleConfig {
-    /** Maximum cost (USD) across the whole fleet before alerting. Default 50. */
-    costThresholdUsd?: number;
-    /** Seconds of silence from ALL machines before a stale alert fires. Default 120. */
-    staleMachineSeconds?: number;
-    /** Minimum number of active agents before concurrency alert fires. Default: disabled (0). */
-    maxAgents?: number;
-}
-/**
- * In-memory alert state. Tracks which rules are currently firing so the same
- * alert is not re-emitted every tick — only state transitions (cleared →
- * firing) emit. Optionally persists to disk via a callback.
- */
-declare class HqAlertEngine {
-    private readonly active;
-    private readonly history;
-    private readonly maxHistory;
-    private timer;
-    private readonly onAlert;
-    constructor(opts: {
-        onAlert: (alert: HqAlert) => void;
-        maxHistory?: number;
-    });
-    /**
-     * Evaluate all rules against the snapshot. Emits (via the `onAlert`
-     * callback) only for rules that newly transition to firing. Clears rules
-     * that are no longer firing. Returns the list of newly-fired alerts.
-     */
-    evaluate(snapshot: HqSnapshot | null, config?: HqAlertRuleConfig, now?: number): HqAlert[];
-    /** Currently-active (firing) alerts. */
-    activeAlerts(): HqAlert[];
-    /** Historical alerts (newest-last), capped at maxHistory. */
-    recentAlerts(limit?: number): HqAlert[];
-    /**
-     * Start periodic evaluation against a snapshot getter. The timer is
-     * unref'd so it never keeps the process alive. Returns a disposer.
-     */
-    startPeriodic(getSnapshot: () => HqSnapshot | null, config?: HqAlertRuleConfig | (() => HqAlertRuleConfig | undefined), intervalMs?: number): () => void;
-}
-/** Map an internal {@link HqAlert} to the wire {@link HqAlertMessage}. */
-declare function toAlertMessage(alert: HqAlert): HqAlertMessage;
-
-/**
- * Transcript mapper — converts raw session JSONL events into the canonical
- * {@link HqTranscriptEntry} shape used by HQ for full chat-history rendering.
- *
- * On-disk reality (see `types/session.ts` + `core/agent-tools.ts`):
- *   - A tool CALL (with its arguments) is NOT a standalone event — it is a
- *     `tool_use` content block inside the assistant's `llm_response`.
- *   - The tool RESULT is a separate `tool_result` event carrying the matching
- *     `id`.
- * So we extract each `tool_use` block as a tool entry (args) at the assistant's
- * position, then merge the later `tool_result` (matched by `id`) INTO that same
- * entry — giving one box per tool (args + result) in strict chronological order.
- *
- * @module hq/transcript-mapper
- */
-
-/**
- * Map a single raw JSONL session event to zero or more transcript entries.
- * An `llm_response` can yield an assistant text entry PLUS one tool entry per
- * embedded `tool_use` block.
- */
-declare function mapSessionEventToEntries(ev: Record<string, unknown>): HqTranscriptEntry[];
-/**
- * Merge each tool result into its matching args entry (by `toolUseId`),
- * keeping the args entry's chronological position. Results with no matching
- * args entry are kept as their own entries. Mutates/keeps order; pure w.r.t.
- * input ordering.
- */
-declare function mergeToolResults(flat: readonly HqTranscriptEntry[]): HqTranscriptEntry[];
-/**
- * Map + merge an array of raw JSONL events into the final transcript-entry
- * list: strict chronological order, with each tool's args and result combined
- * into a single entry.
- */
-declare function buildTranscriptFromEvents(events: Iterable<Record<string, unknown>>): HqTranscriptEntry[];
-
-export { type AgentMonitorEventBridgeOptions, type BrainTelemetryBridgeOptions, type CostTelemetryBridgeOptions, type CreateGlobalMailboxOptions, type CreateHqPublisherOptions, type EnsureHqFirstRunAuthResult, type FleetTelemetryBridgeOptions, HQ_AUTH_FILE_VERSION, HQ_COMMAND_TYPES, type HqAbortCommand, type HqAgentEventPublisher, type HqAlert, HqAlertEngine, HqAlertMessage, type HqAlertRuleConfig, type HqAlertSeverity, type HqAuthFile, type HqBroadcastCommand, type HqBrowserToken, type HqBtwCommand, HqClientCapability, HqClientIdentity, type HqCommand, type HqCommandAuditEntry, HqCommandAuditLog, type HqCommandType, HqEventEnvelope, HqEventLog, type HqEventLogOptions, type HqPersistence, HqPublisher, HqPublisherCommandHandler, type HqPublisherEnvConfig, type HqQueueCommand, HqQueuedCommand, type HqRedactOptions, HqRedactionPolicy, type HqRedactionResult, type HqRunCommandCommand, type HqRuntimeFile, HqSnapshot, HqSnapshotStore, type HqSnapshotStoreOptions, HqSocketFactory, type HqSpawnCommand, type HqSteerCommand, type HqTimeseriesSample, HqTimeseriesStore, type HqTimeseriesStoreOptions, type HqToken, HqTranscriptEntry, type SessionTelemetryBridgeOptions, type ToolTelemetryBridgeOptions, type WorktreeTelemetryBridgeOptions, buildTranscriptFromEvents, createGlobalMailbox, createHqPersistence, createHqPublisherFromEnv, defaultHqDataDir, discoverLocalHqEndpoint, emptyHqAuthFile, ensureHqFirstRunAuthFile, hqAuthFilePath, hqRuntimeFilePath, mapSessionEventToEntries, mergeToolResults, mintHqBrowserToken, mintHqToken, mutateHqAuthFile, readHqAuthFile, readHqRuntimeFileSync, redactHqEvent, redactHqValue, resolveHqConfig, resolveHqConfigFromEnv, resolveHqDataDir, scrubAndTruncateHqPreview, startAgentMonitorEventBridge, startBrainTelemetryBridge, startCostTelemetryBridge, startFleetTelemetryBridge, startSessionTelemetryBridge, startToolTelemetryBridge, startWorktreeTelemetryBridge, summarizeHqToolArgs, toAlertMessage, tokenHasCapability, validateHqCommand, watchHqAuthFile, writeHqAuthFile, writeHqRuntimeFile };
+export * from './protocol.js';
+export * from './redaction.js';
+export * from './mailbox-mapper.js';
+export * from './publisher.js';
+export * from './factory.js';
+export * from './auth-store.js';
+export * from './agent-bridge.js';
+export * from './session-bridge.js';
+export * from './fleet-bridge.js';
+export * from './brain-bridge.js';
+export * from './worktree-bridge.js';
+export * from './tool-bridge.js';
+export * from './cost-bridge.js';
+export * from './persistence.js';
+export * from './commands.js';
+export * from './alerts.js';
+export * from './transcript-mapper.js';
+//# sourceMappingURL=index.d.ts.map