@wrongstack/core 0.285.0 → 0.287.0

package/dist/hq/persistence.d.ts

@@ -68,6 +68,22 @@ export interface HqTimeseriesSample {
     toolCalls: number;
     /** Snapshot of active agents at bucket close (last-write per bucket). */
     activeAgents?: number;
+    /** Per-dimension cost/token breakdowns for richer trend charts. */
+    byModel?: Record<string, HqTimeseriesBreakdownEntry>;
+    byProvider?: Record<string, HqTimeseriesBreakdownEntry>;
+}
+/**
+ * One row of a per-dimension breakdown inside a {@link HqTimeseriesSample}
+ * (e.g. the cost + tokens attributed to a single model or provider within the
+ * bucket). Sums of these across a dimension equal the bucket's totals when
+ * every cost signal carried that dimension.
+ */
+export interface HqTimeseriesBreakdownEntry {
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead?: number | undefined;
+    cacheWrite?: number | undefined;
 }
 export interface HqTimeseriesStoreOptions {
     dataDir: string;
@@ -101,6 +117,12 @@ export declare class HqTimeseriesStore {
         outputTokens?: number;
         toolCalls?: number;
         activeAgents?: number;
+        /** When present, this signal is also attributed to a model dimension. */
+        model?: string;
+        /** When present, this signal is also attributed to a provider dimension. */
+        provider?: string;
+        cacheRead?: number;
+        cacheWrite?: number;
     }): void;
     /** Persist accumulated buckets to disk (append under lock), prune to maxBuckets. */
     flush(): void;
@@ -112,10 +134,30 @@ export declare class HqTimeseriesStore {
     /** Rehydrate buckets from disk (deduped, latest-per-bucket wins). */
     load(): Promise<void>;
 }
+/**
+ * A minimal append-only JSONL log used for records that don't need rotation
+ * compaction — command-audit entries and fired alerts. Each record is one
+ * JSON line appended under a FIFO write chain; {@link readAll} parses them
+ * oldest-first. Best-effort: a rejected append resolves (never rejects) so the
+ * HQ server hot path is never broken.
+ */
+export declare class HqSimpleLog<T> {
+    private readonly filePath;
+    private writeChain;
+    constructor(dataDir: string, filename: string);
+    /** Append one record as a JSON line. Best-effort, never rejects. */
+    append(record: T): void;
+    /** Resolves once all queued appends have settled. For tests. */
+    drain(): Promise<void>;
+    /** Read all records oldest-first. Returns `[]` if the file doesn't exist. */
+    readAll(): Promise<T[]>;
+}
 export interface HqPersistence {
     eventLog: HqEventLog;
     snapshotStore: HqSnapshotStore;
     timeseries: HqTimeseriesStore;
+    commandLog: HqSimpleLog<unknown>;
+    alertLog: HqSimpleLog<unknown>;
 }
 export declare function createHqPersistence(dataDir: string): HqPersistence;
 //# sourceMappingURL=persistence.d.ts.map

package/dist/hq/persistence.d.ts.map

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

package/dist/hq/protocol/brain.d.ts

@@ -0,0 +1,24 @@
+export type HqBrainEventKind = 'decision_requested' | 'decision_answered' | 'decision_ask_human' | 'human_answered' | 'decision_denied' | 'intervention';
+export interface HqBrainEventPayload {
+    /** Which brain lifecycle event this is (mirrors the EventBus `brain.*` name suffix). */
+    kind: HqBrainEventKind;
+    /** The decision request id, when present (decision_request/answer/deny). */
+    requestId?: string;
+    /** Short human-readable question the brain was asked. */
+    question?: string;
+    /** The source that triggered the decision (e.g. 'autonomy', 'system'). */
+    source?: string;
+    /** Resolved risk tier, when known (e.g. 'low' | 'medium' | 'high'). */
+    risk?: string;
+    /** The chosen decision kind, when answered/denied (e.g. 'answer' | 'ask_human' | 'deny'). */
+    decision?: string;
+    /** Free-text rationale or answer payload, when present. */
+    detail?: string;
+    /** For `intervention`: the watched signal that engaged the brain. */
+    interventionKind?: 'tool_failure_streak' | 'error_storm' | 'agent_stall' | 'file_churn';
+    /** For `intervention`: true when a steer was actually delivered to the agent. */
+    intervened?: boolean;
+    /** Epoch milliseconds at which the event occurred. */
+    at: number;
+}
+//# sourceMappingURL=brain.d.ts.map

package/dist/hq/protocol/brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../../src/hq/protocol/brain.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,CAAC;AAEnB,MAAM,WAAW,mBAAmB;IAClC,wFAAwF;IACxF,IAAI,EAAE,gBAAgB,CAAC;IACvB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,aAAa,GAAG,aAAa,GAAG,YAAY,CAAC;IACxF,iFAAiF;IACjF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;CACZ"}

package/dist/hq/protocol/browser.d.ts

@@ -0,0 +1,12 @@
+import type { HqAlertMessage, HqEventEnvelope, HqHeartbeatMessage } from './core.js';
+import type { HqSnapshot } from './session.js';
+export interface HqBrowserSnapshotMessage {
+    type: 'hq.snapshot';
+    snapshot: HqSnapshot;
+}
+export interface HqBrowserEventMessage<TPayload = unknown> {
+    type: 'hq.event';
+    event: HqEventEnvelope<TPayload>;
+}
+export type HqBrowserMessage = HqBrowserSnapshotMessage | HqBrowserEventMessage | HqAlertMessage | HqHeartbeatMessage;
+//# sourceMappingURL=browser.d.ts.map

package/dist/hq/protocol/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/hq/protocol/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB,CAAC,QAAQ,GAAG,OAAO;IACvD,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,qBAAqB,GACrB,cAAc,GACd,kBAAkB,CAAC"}

package/dist/hq/protocol/client.d.ts

@@ -0,0 +1,69 @@
+import type { HqEventEnvelope, HqProtocolVersion } from './core.js';
+import type { HqProjectIdentity, HqProjectStatus } from './project.js';
+import type { HqRedactionPolicy } from './tool.js';
+export type HqClientKind = 'tui' | 'repl' | 'webui' | 'cli' | 'unknown';
+export type HqClientCapability = 'telemetry.publish' | 'session.summary' | 'fleet.summary' | 'mailbox.summary' | 'control.receive';
+export interface HqClientIdentity {
+    clientId: string;
+    kind: HqClientKind;
+    version?: string;
+    machineId: string;
+    hostname?: string;
+    pid?: number;
+    startedAt: string;
+}
+export interface HqClientHelloPayload {
+    protocolVersion: HqProtocolVersion;
+    client: HqClientIdentity;
+    project: HqProjectIdentity;
+    capabilities: readonly HqClientCapability[];
+    /** Publisher-side policy already applied before telemetry leaves the client. */
+    redactionPolicy?: HqRedactionPolicy;
+}
+export interface HqClientHeartbeatPayload {
+    uptimeMs: number;
+    activeSessionId?: string;
+    activeRunId?: string;
+    status: HqProjectStatus;
+    activeSubagents?: number;
+    queuedTasks?: number;
+}
+export 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[];
+}
+export interface HqClientHelloMessage {
+    type: 'client.hello';
+    payload: HqClientHelloPayload;
+}
+export interface HqClientEventMessage<TPayload = unknown> {
+    type: 'client.event';
+    event: HqEventEnvelope<TPayload>;
+}
+export interface HqClientCommandPollMessage {
+    type: 'client.command_poll';
+    clientId: string;
+    projectId: string;
+    afterCommandId?: string;
+    limit?: number;
+}
+export interface HqClientCommandAckMessage {
+    type: 'client.command_ack';
+    clientId: string;
+    projectId: string;
+    commandId: string;
+    status: 'accepted' | 'completed' | 'failed' | 'rejected';
+    message?: string;
+}
+export type HqClientMessage = HqClientHelloMessage | HqClientEventMessage | HqClientCommandPollMessage | HqClientCommandAckMessage;
+//# sourceMappingURL=client.d.ts.map

package/dist/hq/protocol/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/hq/protocol/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;AAExE,MAAM,MAAM,kBAAkB,GAC1B,mBAAmB,GACnB,iBAAiB,GACjB,eAAe,GACf,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,iBAAiB,CAAC;IACnC,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC5C,gFAAgF;IAChF,eAAe,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,eAAe,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB,CAAC,QAAQ,GAAG,OAAO;IACtD,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,eAAe,GACvB,oBAAoB,GACpB,oBAAoB,GACpB,0BAA0B,GAC1B,yBAAyB,CAAC"}

package/dist/hq/protocol/core.d.ts

@@ -0,0 +1,130 @@
+import type { HqClientCapability, HqClientMessage } from './client.js';
+import type { HqQueuedCommand } from './fleet.js';
+import type { HqRedactionPolicy } from './tool.js';
+export declare const HQ_PROTOCOL_VERSION: 1;
+export type HqProtocolVersion = typeof HQ_PROTOCOL_VERSION;
+export interface HqWelcomePayload {
+    type: 'hq.welcome';
+    protocolVersion: HqProtocolVersion;
+    serverTime: string;
+    acceptedCapabilities: readonly HqClientCapability[];
+    redactionPolicy: HqRedactionPolicy;
+}
+export 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;
+}
+export 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' | 'agent.message' | 'agent.status' | 'session.snapshot' | 'session.transcript' | 'session.ended' | 'brain.event' | 'worktree.event' | 'mcp.health.snapshot' | 'mcp.operation';
+export interface HqUsagePayload {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+    durationMs?: number;
+    /** Provider id that produced this usage (e.g. 'anthropic'), when known. */
+    provider?: string;
+    /** Model id the cost was priced against, when known. */
+    model?: string;
+    /** Cache-read (prompt-cache hit) tokens, when reported. */
+    cacheRead?: number;
+    /** Cache-write tokens, when reported. */
+    cacheWrite?: number;
+}
+/** A physical machine, aggregated by HQ from connected clients' machineId. */
+export interface HqMachineRecord {
+    machineId: string;
+    hostname?: string;
+    clientCount: number;
+    sessionCount: number;
+    agentCount: number;
+    projectIds: readonly string[];
+    lastActivityAt: string;
+}
+export interface HqGitSnapshotPayload {
+    branch?: string;
+    dirtyFiles?: number;
+    stagedFiles?: number;
+    ahead?: number;
+    behind?: number;
+}
+export interface HqAlertMessage {
+    type: 'hq.alert';
+    severity: 'info' | 'warn' | 'error';
+    message: string;
+    timestamp: string;
+}
+export interface HqHeartbeatMessage {
+    type: 'hq.heartbeat';
+    serverTime: string;
+}
+export interface HqServerCommandBatchMessage {
+    type: 'hq.command_batch';
+    commands: readonly HqQueuedCommand[];
+}
+export 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`.
+ */
+export 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.
+ */
+export 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.
+ */
+export type HqEventPayloadResult<T> = {
+    ok: true;
+    payload: T;
+} | {
+    ok: false;
+    reason: 'unknown-event-type' | 'malformed-payload';
+};
+export declare function parseHqEventPayload(eventType: string, payload: unknown): HqEventPayloadResult<unknown>;
+export 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>;
+//# sourceMappingURL=core.d.ts.map

package/dist/hq/protocol/core.d.ts.map

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

package/dist/hq/protocol/fleet.d.ts

@@ -0,0 +1,73 @@
+import type { HqSubagentSummary } from './session.js';
+export interface HqFleetSnapshotPayload {
+    runId: string;
+    activeSubagents: number;
+    queuedTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    totalCostUsd?: number;
+    subagents: readonly HqSubagentSummary[];
+}
+export interface HqFleetEventPayload {
+    runId: string;
+    subagentId?: string;
+    event: string;
+    summary?: string;
+    data?: unknown;
+}
+export type HqWorktreeEventKind = 'allocated' | 'committed' | 'merged' | 'conflict' | 'released' | 'failed';
+export interface HqWorktreeEventPayload {
+    /** Which worktree lifecycle event this is (mirrors `worktree.<kind>`). */
+    kind: HqWorktreeEventKind;
+    handleId: string;
+    ownerId: string;
+    ownerLabel?: string;
+    slug?: string;
+    branch?: string;
+    baseBranch?: string;
+    /** For `committed`: diff stats. */
+    insertions?: number;
+    deletions?: number;
+    files?: number;
+    sha?: string;
+    /** For `merged`: whether the merge was a squash. */
+    squash?: boolean;
+    /** For `conflict`: the list of conflicting files. */
+    conflictFiles?: readonly string[];
+    /** For `released`: whether the worktree was kept (true) or pruned (false). */
+    kept?: boolean;
+    /** For `failed`: the error message. */
+    error?: string;
+}
+export interface HqWorklistSnapshotPayload {
+    todos?: HqWorklistCounts;
+    tasks?: HqWorklistCounts;
+    plans?: HqWorklistCounts;
+    activeItem?: string;
+}
+export interface HqWorklistCounts {
+    total: number;
+    pending: number;
+    inProgress: number;
+    completed: number;
+    failed?: number;
+}
+export interface HqFleetSummary {
+    runId: string;
+    projectId: string;
+    clientId: string;
+    activeSubagents: number;
+    queuedTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    totalCostUsd?: number;
+    lastActivityAt: string;
+}
+export interface HqQueuedCommand {
+    commandId: string;
+    type: string;
+    createdAt: string;
+    payload: unknown;
+    requiresAck?: boolean;
+}
+//# sourceMappingURL=fleet.d.ts.map

package/dist/hq/protocol/fleet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../../src/hq/protocol/fleet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAUD,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,WAAW,GACX,QAAQ,GACR,UAAU,GACV,UAAU,GACV,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,IAAI,EAAE,mBAAmB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}

package/dist/hq/protocol/mailbox.d.ts

@@ -0,0 +1,76 @@
+export type HqMailboxMessageType = 'note' | 'ask' | 'assign' | 'steer' | 'btw' | 'broadcast' | 'status' | 'result' | 'review' | 'control';
+export type HqMailboxPriority = 'low' | 'normal' | 'high';
+export type HqMailboxAgentStatus = 'idle' | 'running' | 'streaming' | 'waiting_user' | 'error' | 'offline';
+export interface HqMailboxMessageSummary {
+    mailId: string;
+    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';
+    };
+}
+export 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' | 'http';
+}
+export interface HqMailboxSnapshotPayload {
+    mailboxId: string;
+    scope: 'project' | 'global';
+    messages: readonly HqMailboxMessageSummary[];
+    agents: readonly HqMailboxAgentSummary[];
+    totals: {
+        messages: number;
+        unread: number;
+        incomplete: number;
+        highPriority: number;
+        onlineAgents: number;
+    };
+}
+export interface HqMailboxEventPayload {
+    mailboxId: string;
+    action: 'message.sent' | 'message.read' | 'message.completed' | 'message.updated' | 'agent.registered' | 'agent.heartbeat' | 'agent.offline' | 'agent.deregistered';
+    message?: HqMailboxMessageSummary;
+    agent?: HqMailboxAgentSummary;
+    summary?: string;
+}
+export interface HqMailboxSummary {
+    mailboxId: string;
+    projectId: string;
+    scope: 'project' | 'global';
+    messageCount: number;
+    unreadCount: number;
+    incompleteCount: number;
+    highPriorityCount: number;
+    onlineAgentCount: number;
+    lastActivityAt: string;
+}
+//# sourceMappingURL=mailbox.d.ts.map

package/dist/hq/protocol/mailbox.d.ts.map

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

package/dist/hq/protocol/mcp.d.ts

@@ -0,0 +1,51 @@
+export interface HqMcpLatencySummary {
+    count: number;
+    lastMs?: number | undefined;
+    minMs?: number | undefined;
+    maxMs?: number | undefined;
+    p50Ms?: number | undefined;
+    p95Ms?: number | undefined;
+}
+export interface HqMcpFailureCounts {
+    transport: number;
+    protocol: number;
+    tool: number;
+}
+export interface HqMcpHealthCheck {
+    name: string;
+    passed: boolean;
+    value?: number | undefined;
+    threshold?: number | undefined;
+}
+export type HqMcpHealthState = 'disabled' | 'dormant' | 'connecting' | 'healthy' | 'degraded' | 'failed';
+export type HqMcpConnectionState = 'idle' | 'dormant' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed';
+export interface HqMcpServerHealth {
+    name: string;
+    projectId: string;
+    clientId: string;
+    connectionState: HqMcpConnectionState;
+    healthState: HqMcpHealthState;
+    lastSuccessAt?: string | undefined;
+    lastFailureAt?: string | undefined;
+    lastFailureKind?: 'transport' | 'protocol' | 'tool' | undefined;
+    consecutiveFailures: number;
+    failures: HqMcpFailureCounts;
+    reconnectCount: number;
+    wakeCount: number;
+    sleepCount: number;
+    restartCount: number;
+    connectionLatency: HqMcpLatencySummary;
+    discoveryLatency: HqMcpLatencySummary;
+    callLatency: HqMcpLatencySummary;
+    inFlightCalls: number;
+    peakInFlightCalls: number;
+    healthChecks: HqMcpHealthCheck[];
+}
+export interface HqMcpHealthSnapshotPayload {
+    servers: HqMcpServerHealth[];
+}
+export interface HqMcpOperationPayload {
+    operation: Record<string, unknown>;
+    servers: HqMcpServerHealth[];
+}
+//# sourceMappingURL=mcp.d.ts.map

package/dist/hq/protocol/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/hq/protocol/mcp.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,SAAS,GACT,YAAY,GACZ,SAAS,GACT,UAAU,GACV,QAAQ,CAAC;AAEb,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN,SAAS,GACT,YAAY,GACZ,WAAW,GACX,cAAc,GACd,cAAc,GACd,QAAQ,CAAC;AAEb,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,oBAAoB,CAAC;IACtC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IAChE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,gBAAgB,EAAE,mBAAmB,CAAC;IACtC,WAAW,EAAE,mBAAmB,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,gBAAgB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B"}

package/dist/hq/protocol/project.d.ts

@@ -0,0 +1,26 @@
+export type HqWorkspaceKind = 'git' | 'directory' | 'unknown';
+export type HqProjectStatus = 'active' | 'idle' | 'stale' | 'error';
+export type HqPathPolicy = 'none' | 'project-relative' | 'redacted' | 'full';
+export interface HqProjectIdentity {
+    projectId: string;
+    projectRoot: string;
+    projectName: string;
+    gitRemote?: string;
+    gitBranch?: string;
+    machineId: string;
+    workspaceKind: HqWorkspaceKind;
+}
+export 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;
+}
+//# sourceMappingURL=project.d.ts.map

package/dist/hq/protocol/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/hq/protocol/project.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,kBAAkB,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,eAAe,CAAC;CACzB"}