@wrongstack/core 0.265.1 → 0.268.0

package/dist/execution/prompt-enhancer.d.ts

@@ -1,4 +1,4 @@
-import { P as Provider, M as Message } from '../context-MRk5PhNv.js';
+import { P as Provider, M as Message } from '../context-C0U8B9NF.js';
 
 /**
  * Prompt refinement ("did you mean this?").

package/dist/extension/index.d.ts

@@ -1,8 +1,9 @@
-export { i as AfterIterationHook, j as AfterRunHook, k as AfterToolExecutionHook, l as AgentExtension, B as BeforeIterationHook, m as BeforeRunHook, n as BeforeToolExecutionHook, E as ExtensionRegistry, O as OnErrorHook, v as ProviderRunnerFn, t as ProviderRunnerWrapper } from '../index-CEDeNodM.js';
-import '../context-MRk5PhNv.js';
+export { i as AfterIterationHook, j as AfterRunHook, k as AfterToolExecutionHook, l as AgentExtension, B as BeforeIterationHook, m as BeforeRunHook, n as BeforeToolExecutionHook, E as ExtensionRegistry, O as OnErrorHook, v as ProviderRunnerFn, t as ProviderRunnerWrapper } from '../index-gCv830d7.js';
+import '../context-C0U8B9NF.js';
 import '../logger-B63L5bTg.js';
-import '../pipeline-DPDxH_7m.js';
-import '../config-BMCj_XDs.js';
+import '../pipeline-BDNvENyV.js';
+import '../mailbox-types-Ct2hJq0P.js';
+import '../config-VKfOZ-6X.js';
 import '../observability-D-HZN_mF.js';
-import '../brain-BXd_61kQ.js';
-import '../permission-B9SB45lp.js';
+import '../brain-69wzMKp1.js';
+import '../permission-Bd-57Lbl.js';

package/dist/global-mailbox-KByEFFBa.d.ts

@@ -0,0 +1,663 @@
+import { E as EventBus } from './brain-69wzMKp1.js';
+import { M as MailboxMessage, a as MailboxAgentStatus, b as Mailbox, c as MailboxSendInput, d as MailboxQuery, e as MailboxAckInput, f as MailboxAckBatchInput, A as AgentRegistrationInput, g as AgentHeartbeatInput, C as ClientRegistrationInput, h as ClientHeartbeatInput, i as ClientStatus, P as PurgeOptions, j as PurgeResult } from './mailbox-types-Ct2hJq0P.js';
+
+declare const HQ_PROTOCOL_VERSION: 1;
+type HqProtocolVersion = typeof HQ_PROTOCOL_VERSION;
+type HqClientKind = 'tui' | 'repl' | 'webui' | 'cli' | 'unknown';
+type HqWorkspaceKind = 'git' | 'directory' | 'unknown';
+type HqProjectStatus = 'active' | 'idle' | 'stale' | 'error';
+type HqClientCapability = 'telemetry.publish' | 'session.summary' | 'fleet.summary' | 'mailbox.summary' | 'control.receive';
+type HqToolArgsPolicy = 'none' | 'summary' | 'redacted';
+type HqPathPolicy = 'none' | 'project-relative' | 'redacted' | 'full';
+interface HqRedactionPolicy {
+    rawContent: boolean;
+    toolArgs: HqToolArgsPolicy;
+    paths: HqPathPolicy;
+}
+declare const DEFAULT_HQ_REDACTION_POLICY: HqRedactionPolicy;
+interface HqClientIdentity {
+    clientId: string;
+    kind: HqClientKind;
+    version?: string;
+    machineId: string;
+    hostname?: string;
+    pid?: number;
+    startedAt: string;
+}
+interface HqProjectIdentity {
+    projectId: string;
+    projectRoot: string;
+    projectName: string;
+    gitRemote?: string;
+    gitBranch?: string;
+    machineId: string;
+    workspaceKind: HqWorkspaceKind;
+}
+interface HqClientHelloPayload {
+    protocolVersion: HqProtocolVersion;
+    client: HqClientIdentity;
+    project: HqProjectIdentity;
+    capabilities: readonly HqClientCapability[];
+}
+interface HqWelcomePayload {
+    type: 'hq.welcome';
+    protocolVersion: HqProtocolVersion;
+    serverTime: string;
+    acceptedCapabilities: readonly HqClientCapability[];
+    redactionPolicy: HqRedactionPolicy;
+}
+interface HqEventEnvelope<TPayload = unknown> {
+    id: string;
+    type: HqEventType | (string & {});
+    schemaVersion: HqProtocolVersion;
+    timestamp: string;
+    clientId: string;
+    projectId: string;
+    sessionId?: string;
+    runId?: string;
+    seq: number;
+    payload: TPayload;
+}
+type HqEventType = 'client.hello' | 'client.heartbeat' | 'session.started' | 'session.status' | 'session.usage' | 'tool.started' | 'tool.completed' | 'fleet.snapshot' | 'fleet.event' | 'mailbox.snapshot' | 'mailbox.event' | 'worklist.snapshot' | 'git.snapshot';
+interface HqClientHeartbeatPayload {
+    uptimeMs: number;
+    activeSessionId?: string;
+    activeRunId?: string;
+    status: HqProjectStatus;
+    activeSubagents?: number;
+    queuedTasks?: number;
+}
+type HqSessionStatus = 'idle' | 'running' | 'paused' | 'completed' | 'failed';
+interface HqSessionStartedPayload {
+    sessionId: string;
+    provider?: string;
+    model?: string;
+    startedAt: string;
+}
+interface HqSessionStatusPayload {
+    status: HqSessionStatus;
+    phase?: string;
+    message?: string;
+}
+interface HqUsagePayload {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+    durationMs?: number;
+}
+interface HqToolStartedPayload {
+    toolName: string;
+    capabilities?: readonly string[];
+    risk?: string;
+    inputSummary?: unknown;
+}
+interface HqToolCompletedPayload {
+    toolName: string;
+    status: 'success' | 'error' | 'timeout' | 'cancelled';
+    durationMs: number;
+    outputSummary?: unknown;
+    errorClass?: string;
+}
+interface HqSubagentSummary {
+    subagentId: string;
+    role?: string;
+    status: 'pending' | 'running' | 'idle' | 'completed' | 'failed' | 'stopped';
+    task?: string;
+    currentTool?: string;
+    runtimeMs?: number;
+    costUsd?: number;
+    lastActivityAt?: string;
+}
+interface HqFleetSnapshotPayload {
+    runId: string;
+    activeSubagents: number;
+    queuedTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    totalCostUsd?: number;
+    subagents: readonly HqSubagentSummary[];
+}
+interface HqFleetEventPayload {
+    runId: string;
+    subagentId?: string;
+    event: string;
+    summary?: string;
+    data?: unknown;
+}
+type HqMailboxMessageType = 'note' | 'ask' | 'assign' | 'steer' | 'btw' | 'broadcast' | 'status' | 'result' | 'control';
+type HqMailboxPriority = 'low' | 'normal' | 'high';
+type HqMailboxAgentStatus = 'idle' | 'running' | 'streaming' | 'waiting_user' | 'error' | 'offline';
+interface HqMailboxMessageSummary {
+    messageId: string;
+    from: string;
+    to: string;
+    type: HqMailboxMessageType;
+    subject: string;
+    priority: HqMailboxPriority;
+    timestamp: string;
+    replyTo?: string;
+    senderSessionId?: string;
+    completed: boolean;
+    completedBy?: string;
+    completedAt?: string;
+    unreadCount?: number;
+    readCount?: number;
+    hasBody: boolean;
+    bodyPreview?: string;
+    outcomePreview?: string;
+    task?: {
+        taskId?: string;
+        agentRole?: string;
+        agentName?: string;
+        status?: 'pending' | 'in_progress' | 'completed' | 'failed';
+    };
+}
+interface HqMailboxAgentSummary {
+    agentId: string;
+    name: string;
+    role?: string;
+    sessionId: string;
+    status: HqMailboxAgentStatus;
+    currentTool?: string;
+    currentTask?: string;
+    iterations: number;
+    toolCalls: number;
+    lastActivityAt: string;
+    lastSeenAt: string;
+    online: boolean;
+    source?: 'cli' | 'webui' | 'mcp' | 'acp';
+}
+interface HqMailboxSnapshotPayload {
+    mailboxId: string;
+    scope: 'project' | 'global';
+    messages: readonly HqMailboxMessageSummary[];
+    agents: readonly HqMailboxAgentSummary[];
+    totals: {
+        messages: number;
+        unread: number;
+        incomplete: number;
+        highPriority: number;
+        onlineAgents: number;
+    };
+}
+interface HqMailboxEventPayload {
+    mailboxId: string;
+    action: 'message.sent' | 'message.read' | 'message.completed' | 'message.updated' | 'agent.registered' | 'agent.heartbeat' | 'agent.offline';
+    message?: HqMailboxMessageSummary;
+    agent?: HqMailboxAgentSummary;
+    summary?: string;
+}
+interface HqWorklistSnapshotPayload {
+    todos?: HqWorklistCounts;
+    tasks?: HqWorklistCounts;
+    plans?: HqWorklistCounts;
+    activeItem?: string;
+}
+interface HqWorklistCounts {
+    total: number;
+    pending: number;
+    inProgress: number;
+    completed: number;
+    failed?: number;
+}
+interface HqGitSnapshotPayload {
+    branch?: string;
+    dirtyFiles?: number;
+    stagedFiles?: number;
+    ahead?: number;
+    behind?: number;
+}
+interface HqClientRecord {
+    clientId: string;
+    kind: HqClientKind;
+    machineId: string;
+    hostname?: string;
+    pid?: number;
+    version?: string;
+    connected: boolean;
+    connectedAt?: string;
+    lastSeenAt: string;
+    projectId: string;
+    sessionId?: string;
+    capabilities: readonly HqClientCapability[];
+}
+interface HqProjectRecord {
+    projectId: string;
+    projectName: string;
+    projectRootDisplay: string;
+    machineIds: readonly string[];
+    gitBranch?: string;
+    activeClients: number;
+    activeSessions: number;
+    activeSubagents: number;
+    totalCostUsd: number;
+    lastActivityAt: string;
+    status: HqProjectStatus;
+}
+interface HqSessionSummary {
+    sessionId: string;
+    projectId: string;
+    clientId: string;
+    status: HqSessionStatus;
+    provider?: string;
+    model?: string;
+    startedAt?: string;
+    lastActivityAt: string;
+    costUsd?: number;
+}
+interface HqFleetSummary {
+    runId: string;
+    projectId: string;
+    clientId: string;
+    activeSubagents: number;
+    queuedTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    totalCostUsd?: number;
+    lastActivityAt: string;
+}
+interface HqMailboxSummary {
+    mailboxId: string;
+    projectId: string;
+    scope: 'project' | 'global';
+    messageCount: number;
+    unreadCount: number;
+    incompleteCount: number;
+    highPriorityCount: number;
+    onlineAgentCount: number;
+    lastActivityAt: string;
+}
+interface HqSnapshot {
+    generatedAt: string;
+    clients: readonly HqClientRecord[];
+    projects: readonly HqProjectRecord[];
+    sessions: readonly HqSessionSummary[];
+    fleets: readonly HqFleetSummary[];
+    mailboxes: readonly HqMailboxSummary[];
+    totals: {
+        activeProjects: number;
+        activeClients: number;
+        activeSessions: number;
+        activeSubagents: number;
+        unreadMailboxMessages: number;
+        incompleteMailboxMessages: number;
+        totalCostUsd: number;
+    };
+}
+interface HqBrowserSnapshotMessage {
+    type: 'hq.snapshot';
+    snapshot: HqSnapshot;
+}
+interface HqBrowserEventMessage<TPayload = unknown> {
+    type: 'hq.event';
+    event: HqEventEnvelope<TPayload>;
+}
+interface HqAlertMessage {
+    type: 'hq.alert';
+    severity: 'info' | 'warn' | 'error';
+    message: string;
+    timestamp: string;
+}
+type HqBrowserMessage = HqBrowserSnapshotMessage | HqBrowserEventMessage | HqAlertMessage;
+interface HqClientHelloMessage {
+    type: 'client.hello';
+    payload: HqClientHelloPayload;
+}
+interface HqClientEventMessage<TPayload = unknown> {
+    type: 'client.event';
+    event: HqEventEnvelope<TPayload>;
+}
+interface HqClientCommandPollMessage {
+    type: 'client.command_poll';
+    clientId: string;
+    projectId: string;
+    afterCommandId?: string;
+    limit?: number;
+}
+interface HqClientCommandAckMessage {
+    type: 'client.command_ack';
+    clientId: string;
+    projectId: string;
+    commandId: string;
+    status: 'accepted' | 'completed' | 'failed' | 'rejected';
+    message?: string;
+}
+interface HqQueuedCommand {
+    commandId: string;
+    type: string;
+    createdAt: string;
+    payload: unknown;
+    requiresAck?: boolean;
+}
+interface HqServerCommandBatchMessage {
+    type: 'hq.command_batch';
+    commands: readonly HqQueuedCommand[];
+}
+type HqClientMessage = HqClientHelloMessage | HqClientEventMessage | HqClientCommandPollMessage | HqClientCommandAckMessage;
+type HqServerMessage = HqServerCommandBatchMessage | HqWelcomePayload;
+/**
+ * Discriminated parse result for {@link parseHqFrame}. The `reason` field
+ * is only present when `ok` is `false`; consumers should narrow on `ok`
+ * before accessing `frame` or `reason`.
+ */
+type HqParseResult = {
+    ok: true;
+    frame: HqClientMessage;
+} | {
+    ok: false;
+    reason: 'invalid-json' | 'unknown-type' | 'malformed';
+};
+/**
+ * Strictly parse a raw client → server frame into a {@link HqParseResult}.
+ *
+ * Validates, in order:
+ *  1. JSON syntax (`invalid-json` on failure)
+ *  2. Top-level object with string `type` discriminator
+ *  3. `type` is one of {@link HqClientMessage} union members (`unknown-type`)
+ *  4. Per-type field-shape presence checks (`malformed` on failure)
+ *
+ * On success, `frame` is narrowed to {@link HqClientMessage} and consumers
+ * can switch on `frame.type` for type-safe access to per-union-member
+ * fields without `as` casts.
+ */
+declare function parseHqFrame(raw: string | Buffer): HqParseResult;
+/**
+ * Validate the `payload` field of a {@link HqEventEnvelope} for known
+ * event types. Returns `{ ok: true, payload }` with a narrowed payload
+ * type when the event type has a registered shape guard and the payload
+ * matches it; `{ ok: true, payload: unknown }` for event types that the
+ * server does not yet validate; or `{ ok: false, reason }` when the
+ * payload fails the registered guard.
+ *
+ * Use this after {@link parseHqFrame} has produced a valid frame, when
+ * the frame is `client.event` and the server is about to consume the
+ * event payload.
+ */
+type HqEventPayloadResult<T> = {
+    ok: true;
+    payload: T;
+} | {
+    ok: false;
+    reason: 'unknown-event-type' | 'malformed-payload';
+};
+declare function parseHqEventPayload(eventType: string, payload: unknown): HqEventPayloadResult<unknown>;
+declare function createHqEventEnvelope<TPayload>(input: {
+    id: string;
+    type: HqEventType | (string & {});
+    timestamp: string;
+    clientId: string;
+    projectId: string;
+    seq: number;
+    payload: TPayload;
+    sessionId?: string;
+    runId?: string;
+}): HqEventEnvelope<TPayload>;
+
+interface HqMailboxMappingOptions {
+    mailboxId: string;
+    scope?: 'project' | 'global';
+    limit?: number;
+    previewLength?: number;
+    redactionPolicy?: Partial<HqRedactionPolicy>;
+}
+interface HqMailboxSnapshotOptions extends HqMailboxMappingOptions {
+    includeCompleted?: boolean;
+}
+type HqMailboxEventAction = HqMailboxEventPayload['action'];
+declare function mapMailboxMessageToHqSummary(message: MailboxMessage, options?: Pick<HqMailboxMappingOptions, 'previewLength' | 'redactionPolicy'>): HqMailboxMessageSummary;
+declare function mapMailboxAgentToHqSummary(agent: MailboxAgentStatus): HqMailboxAgentSummary;
+declare function createMailboxSnapshotPayload(messages: readonly MailboxMessage[], agents: readonly MailboxAgentStatus[], options: HqMailboxSnapshotOptions): HqMailboxSnapshotPayload;
+declare function createMailboxSnapshotPayloadFromMailbox(mailbox: Pick<Mailbox, 'query' | 'getAgentStatuses'>, options: HqMailboxSnapshotOptions): Promise<HqMailboxSnapshotPayload>;
+declare function createMailboxEventPayload(input: {
+    mailboxId: string;
+    action: HqMailboxEventAction;
+    message?: MailboxMessage;
+    agent?: MailboxAgentStatus;
+    summary?: string;
+    previewLength?: number;
+    redactionPolicy?: Partial<HqRedactionPolicy>;
+}): HqMailboxEventPayload;
+
+interface HqSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+    removeEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+    on?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+    off?(type: 'open' | 'close' | 'error' | 'message', listener: (event: unknown) => void): void;
+}
+type HqSocketFactory = (url: string, init: {
+    token?: string;
+}) => HqSocketLike;
+interface HqPublisherCommandResult {
+    commandId: string;
+    status: 'accepted' | 'completed' | 'failed' | 'rejected';
+    message?: string;
+}
+type HqPublisherCommandHandler = (command: HqQueuedCommand) => void | HqPublisherCommandResult | Promise<void | HqPublisherCommandResult>;
+interface HqPublisherOptions {
+    url: string;
+    token?: string;
+    client: HqClientIdentity;
+    project: HqProjectIdentity;
+    capabilities?: readonly HqClientCapability[];
+    socketFactory?: HqSocketFactory;
+    now?: () => string;
+    idFactory?: () => string;
+    reconnect?: boolean;
+    reconnectBaseMs?: number;
+    reconnectMaxMs?: number;
+    maxQueuedMessages?: number;
+    redactionPolicy?: Partial<HqRedactionPolicy>;
+    commandPollIntervalMs?: number;
+    commandPollLimit?: number;
+    onCommand?: HqPublisherCommandHandler;
+}
+interface HqPublishEventOptions {
+    type: HqEventType | (string & {});
+    payload: unknown;
+    sessionId?: string;
+    runId?: string;
+    timestamp?: string;
+}
+declare class HqPublisher {
+    private readonly options;
+    private readonly socketFactory;
+    private readonly now;
+    private readonly idFactory;
+    private readonly capabilities;
+    private readonly reconnect;
+    private readonly reconnectBaseMs;
+    private readonly reconnectMaxMs;
+    private readonly maxQueuedMessages;
+    private socket;
+    private seq;
+    private queue;
+    private stopped;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private commandPollTimer;
+    private lastCommandId;
+    constructor(options: HqPublisherOptions);
+    connect(): void;
+    close(): void;
+    publishEvent<TPayload>(options: HqPublishEventOptions & {
+        payload: TPayload;
+    }): HqEventEnvelope<TPayload>;
+    publishMailboxSnapshot(mailbox: Pick<Mailbox, 'query' | 'getAgentStatuses'>, options: Omit<HqMailboxSnapshotOptions, 'redactionPolicy'> & {
+        sessionId?: string;
+        timestamp?: string;
+    }): Promise<HqEventEnvelope<HqMailboxSnapshotPayload>>;
+    publishMailboxEvent(input: {
+        mailboxId: string;
+        action: HqMailboxEventAction;
+        message?: MailboxMessage;
+        agent?: MailboxAgentStatus;
+        summary?: string;
+        previewLength?: number;
+        sessionId?: string;
+        timestamp?: string;
+    }): HqEventEnvelope<HqMailboxEventPayload>;
+    pollCommands(): void;
+    ackCommand(result: HqPublisherCommandResult): void;
+    private sendHello;
+    private sendFrame;
+    private enqueue;
+    private flushQueue;
+    private startCommandPolling;
+    private stopCommandPolling;
+    private handleServerMessage;
+    private parseServerMessage;
+    private extractMessageData;
+    private handleCommandBatch;
+    private scheduleReconnect;
+}
+
+/**
+ * GlobalMailbox — project-level inter-agent mailbox with cross-session support.
+ *
+ * Stores messages at `~/.wrongstack/projects/<slug>/_mailbox.jsonl` so all
+ * sessions (terminals, WebUIs) working on the same project share one inbox.
+ *
+ * Features:
+ * - Agent registration + heartbeat (agents go stale after 60s without heartbeat)
+ * - Per-recipient read receipts (readBy[agentId] = ISO8601)
+ * - Atomic file-locking for concurrent multi-process writes
+ * - Unread count for new-mail notifications
+ * - Online agent list
+ *
+ * @module GlobalMailbox
+ */
+
+/**
+ * Derive the project-level mailbox directory path.
+ *
+ * Delegates to the CANONICAL `projectSlug()` from wstack-paths so every
+ * surface (CLI, TUI, WebUI, mailbox tool, loop checker) lands in the exact
+ * same `~/.wrongstack/projects/<slug>/` directory. A previous inline copy
+ * skipped the leading/trailing-hyphen strip, which silently split agents
+ * working on projects with non-alphanumeric name edges into TWO mailboxes.
+ *
+ * @param projectRoot  — absolute path to the project root
+ * @param globalRoot   — `~/.wrongstack` (or custom global root)
+ */
+declare function resolveProjectDir(projectRoot: string, globalRoot: string): string;
+declare class GlobalMailbox implements Mailbox {
+    /** Path to the JSONL message file. */
+    readonly messagePath: string;
+    /** Path to the JSON agent registry file. */
+    readonly registryPath: string;
+    /** Path to the JSON client registry file. */
+    readonly clientRegistryPath: string;
+    /** Optional event bus for emitting agent registration/heartbeat events. */
+    private readonly _events?;
+    /** Optional HQ publisher for cross-project command-center telemetry. */
+    private readonly _hqPublisher?;
+    /**
+     * Local cache of the agent registry to avoid re-reading on every call.
+     * Time-bounded: the registry file is shared ACROSS PROCESSES (that's the
+     * whole point of GlobalMailbox), so a cache served forever would never see
+     * agents registered by other sessions. Writers always bypass it.
+     */
+    private _registryCache;
+    /** When the registry cache was last refreshed from disk (epoch ms). */
+    private _registryCacheAt;
+    /**
+     * Local cache of the client registry to avoid re-reading on every call.
+     * Same reasoning as agent registry cache.
+     */
+    private _clientRegistryCache;
+    /** When the client registry cache was last refreshed from disk (epoch ms). */
+    private _clientRegistryCacheAt;
+    /** Last time each local agent sent a heartbeat (throttle). */
+    private _lastHeartbeat;
+    /** Last time each local client sent a heartbeat (throttle). */
+    private _lastClientHeartbeat;
+    /**
+     * In-memory mirror of the JSONL message file. The mailbox is shared
+     * ACROSS PROCESSES, so reads cannot trust the cache blindly — we pair it
+     * with an mtime check. The file lock serializes every write, so a
+     * changed mtimeMs is a definitive signal that another process (or this
+     * one) wrote; an unchanged mtimeMs guarantees no write happened and the
+     * cache is current. This collapses the per-iteration `query()` cost from
+     * O(file_size) disk + parse to O(messages) in memory.
+     */
+    private _messageCache;
+    /** mtimeMs of the file when `_messageCache` was populated. */
+    private _messageCacheMtime;
+    /** Size of the file when `_messageCache` was populated (extra guard). */
+    private _messageCacheSize;
+    /**
+     * @param projectDir — `~/.wrongstack/projects/<slug>/`
+     * @param events — optional EventBus for real-time TUI/WebUI notifications
+     * @param hqPublisher — optional HQ publisher for cross-project telemetry
+     */
+    constructor(projectDir: string, events?: EventBus, hqPublisher?: HqPublisher);
+    private get hqMailboxId();
+    private publishHqMailboxEvent;
+    private publishHqMailboxSnapshot;
+    send(input: MailboxSendInput): Promise<MailboxMessage>;
+    query(q: MailboxQuery): Promise<MailboxMessage[]>;
+    ack(input: MailboxAckInput): Promise<MailboxMessage | null>;
+    ackMany(input: MailboxAckBatchInput): Promise<MailboxMessage[]>;
+    unreadCount(forAgentId: string): Promise<number>;
+    registerAgent(input: AgentRegistrationInput): Promise<void>;
+    heartbeat(input: AgentHeartbeatInput): Promise<void>;
+    getAgentStatuses(): Promise<MailboxAgentStatus[]>;
+    getOnlineAgents(): Promise<MailboxAgentStatus[]>;
+    registerClient(input: ClientRegistrationInput): Promise<void>;
+    clientHeartbeat(input: ClientHeartbeatInput): Promise<void>;
+    getClientStatuses(): Promise<ClientStatus[]>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    purgeStale(opts?: PurgeOptions): Promise<PurgeResult>;
+    /**
+     * Read all messages from the JSONL file. Always reads + parses the file.
+     * Callers that can tolerate a stale-by-mtime view should use
+     * {@link _readMessagesCached}; writers that need the post-lock truth
+     * should call this directly (it's what {@link _readMessagesFresh} aliases).
+     */
+    private _readMessages;
+    /**
+     * Read messages, then adopt the result as the in-memory cache. Use this
+     * from writers that just took the file lock — the read reflects the
+     * authoritative post-lock state and should be served to subsequent
+     * queries without re-reading.
+     */
+    private _readMessagesFresh;
+    /**
+     * Read messages, consulting the mtime-bounded in-memory cache first.
+     * The mailbox file is shared across processes; every `send`/`ack`/
+     * `clearAll`/`purgeStale` takes the file lock, so writes are serialized
+     * and a changed mtimeMs is a definitive freshness signal. When the
+     * stat matches the cached mtime+size we return the cached array — no
+     * file read and no JSON.parse — collapsing the per-iteration query
+     * cost on the mailbox-loop hot path.
+     */
+    private _readMessagesCached;
+    /**
+     * Replace the in-memory cache. Caller is responsible for guaranteeing
+     * that `messages` reflects the current on-disk state (e.g. they just
+     * read or wrote it under the file lock).
+     */
+    private _setMessageCache;
+    /**
+     * Append a single just-sent message to the in-memory cache without
+     * re-reading the file. The caller must hold the file lock (or have
+     * just released it after a successful append) so the cache stays
+     * consistent with on-disk state.
+     */
+    private _pushToCache;
+    private _ensureRegistry;
+    private _readRegistry;
+    private _pruneStaleInPlace;
+    private _writeRegistry;
+    private _ensureClientRegistry;
+    private _readClientRegistry;
+    private _pruneStaleClientsInPlace;
+    private _writeClientRegistry;
+}
+
+export { type HqSessionStatusPayload as $, type HqMailboxMappingOptions as A, type HqMailboxMessageSummary as B, type HqMailboxMessageType as C, DEFAULT_HQ_REDACTION_POLICY as D, type HqMailboxPriority as E, type HqMailboxSnapshotOptions as F, GlobalMailbox as G, HQ_PROTOCOL_VERSION as H, type HqMailboxSnapshotPayload as I, type HqMailboxSummary as J, type HqParseResult as K, type HqPathPolicy as L, type HqProjectIdentity as M, type HqProjectRecord as N, type HqProjectStatus as O, type HqProtocolVersion as P, type HqPublishEventOptions as Q, HqPublisher as R, type HqPublisherCommandHandler as S, type HqPublisherCommandResult as T, type HqPublisherOptions as U, type HqQueuedCommand as V, type HqRedactionPolicy as W, type HqServerCommandBatchMessage as X, type HqServerMessage as Y, type HqSessionStartedPayload as Z, type HqSessionStatus as _, type HqAlertMessage as a, type HqSessionSummary as a0, type HqSnapshot as a1, type HqSocketFactory as a2, type HqSocketLike as a3, type HqSubagentSummary as a4, type HqToolArgsPolicy as a5, type HqToolCompletedPayload as a6, type HqToolStartedPayload as a7, type HqUsagePayload as a8, type HqWelcomePayload as a9, type HqWorklistCounts as aa, type HqWorklistSnapshotPayload as ab, type HqWorkspaceKind as ac, createHqEventEnvelope as ad, createMailboxEventPayload as ae, createMailboxSnapshotPayload as af, createMailboxSnapshotPayloadFromMailbox as ag, mapMailboxAgentToHqSummary as ah, mapMailboxMessageToHqSummary as ai, parseHqEventPayload as aj, parseHqFrame as ak, resolveProjectDir as al, type HqBrowserEventMessage as b, type HqBrowserMessage as c, type HqBrowserSnapshotMessage as d, type HqClientCapability as e, type HqClientCommandAckMessage as f, type HqClientCommandPollMessage as g, type HqClientEventMessage as h, type HqClientHeartbeatPayload as i, type HqClientHelloMessage as j, type HqClientHelloPayload as k, type HqClientIdentity as l, type HqClientKind as m, type HqClientMessage as n, type HqClientRecord as o, type HqEventEnvelope as p, type HqEventPayloadResult as q, type HqEventType as r, type HqFleetEventPayload as s, type HqFleetSnapshotPayload as t, type HqFleetSummary as u, type HqGitSnapshotPayload as v, type HqMailboxAgentStatus as w, type HqMailboxAgentSummary as x, type HqMailboxEventAction as y, type HqMailboxEventPayload as z };