@wrongstack/core 0.284.0 → 0.285.0

package/dist/coordination/knowledge-graph.d.ts

@@ -0,0 +1,217 @@
+export type NodeType = 'fact' | 'goal' | 'decision' | 'change' | 'vote';
+export type FactCategory = 'bug' | 'refactor' | 'security' | 'test' | 'perf' | 'deps' | 'architecture' | 'quality';
+export type GoalStatus = 'pending' | 'in_progress' | 'blocked' | 'done' | 'failed';
+export type GoalPriority = 'critical' | 'high' | 'medium' | 'low';
+export type ChangeStatus = 'proposed' | 'approved' | 'rejected' | 'applied' | 'rolled_back';
+export type VoteValue = 'approve' | 'reject' | 'abstain';
+export type DecisionType = 'spawn' | 'assign' | 'approve_change' | 'reject_change' | 'escalate' | 'rollback' | 'merge_results';
+export interface FactNode {
+    id: string;
+    type: 'fact';
+    category: FactCategory;
+    subject: string;
+    detail: string;
+    file?: string;
+    line?: number;
+    severity?: 'critical' | 'high' | 'medium' | 'low';
+    discoveredBy: string;
+    discoveredAt: string;
+    tags: string[];
+    /** Stable key — dedup facts about the same subject */
+    key: string;
+    /** References to other nodes this fact relates to */
+    related: string[];
+}
+export interface GoalNode {
+    id: string;
+    type: 'goal';
+    title: string;
+    description: string;
+    status: GoalStatus;
+    priority: GoalPriority;
+    assignee?: string;
+    blockedBy: string[];
+    dependsOn: string[];
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+    tags: string[];
+    /** Sub-goals spawned from this goal */
+    children: string[];
+    /** The top-level goal this belongs to (for hierarchy) */
+    parentGoal?: string;
+    result?: string;
+}
+export interface DecisionNode {
+    id: string;
+    type: 'decision';
+    decisionType: DecisionType;
+    question: string;
+    options: {
+        id: string;
+        label: string;
+        risk?: string;
+    }[];
+    chosen: string;
+    rationale: string;
+    madeBy: string;
+    madeAt: string;
+    context?: string;
+}
+export interface ChangeNode {
+    id: string;
+    type: 'change';
+    title: string;
+    description: string;
+    files: {
+        path: string;
+        action: 'create' | 'modify' | 'delete';
+    }[];
+    status: ChangeStatus;
+    proposedBy: string;
+    proposedAt: string;
+    approvedBy: string[];
+    rejectedBy: string[];
+    appliedAt?: string;
+    rolledBackAt?: string;
+    rollbackReason?: string;
+    votes: VoteRecord[];
+    qualityGate: QualityGateResult;
+    /** Goals satisfied by this change */
+    satisfiesGoals: string[];
+}
+export interface VoteRecord {
+    agentId: string;
+    agentName: string;
+    value: VoteValue;
+    rationale?: string | undefined;
+    votedAt: string;
+}
+export interface QualityGateResult {
+    passed: boolean;
+    checks: QualityCheck[];
+}
+export interface QualityCheck {
+    name: string;
+    passed: boolean;
+    detail?: string;
+}
+export interface VoteNode {
+    id: string;
+    type: 'vote';
+    changeId: string;
+    voterId: string;
+    voterName: string;
+    value: VoteValue;
+    rationale?: string;
+    votedAt: string;
+}
+export type GraphNode = FactNode | GoalNode | DecisionNode | ChangeNode | VoteNode;
+export interface GraphSubscription {
+    id: string;
+    agentId: string;
+    /** JSONPath-like filter */
+    filter: NodeFilter;
+    /** Channel for this specific subscription */
+    channel: string;
+}
+export interface NodeFilter {
+    type?: NodeType;
+    category?: FactCategory;
+    status?: GoalStatus | ChangeStatus;
+    tags?: string[];
+    assignee?: string;
+    discoveredBy?: string;
+    proposedBy?: string;
+    /** Only nodes added after this timestamp */
+    since?: string;
+}
+export declare class KnowledgeGraph {
+    private readonly nodes;
+    private readonly index;
+    private readonly subs;
+    private readonly pendingDeliveries;
+    private readonly filePath;
+    private readonly graphFilePath;
+    /**
+     * Stable per-node insertion sequence. `nodes` (a Map) preserves insertion
+     * order even across `update()` (Map.set on an existing key keeps its slot),
+     * but the type index's `Set<string>` does NOT — `update()` removes then
+     * re-adds a node's id, moving it to the set's tail. Index-routed queries sort
+     * by this sequence so they return nodes in creation order, matching the old
+     * `nodes.values()` scan that callers like decision-history `slice(-10)` rely on.
+     */
+    private readonly seq;
+    private seqCounter;
+    /** Assign a stable insertion sequence the first time a node id is seen. */
+    private _trackSeq;
+    /** Exposed for unit-testing only: read current index contents. */
+    getIndex(): ReadonlyMap<string, ReadonlySet<string>>;
+    constructor(sessionDir: string);
+    /**
+     * Add a node. Fires to all matching subscriptions synchronously.
+     * Returns the node with its assigned id.
+     */
+    add(node: Omit<GraphNode, 'id'>): Promise<GraphNode>;
+    /** Update an existing node by id. Returns updated node or null if not found. */
+    update(id: string, patch: Partial<GraphNode>): Promise<GraphNode | null>;
+    get(id: string): GraphNode | undefined;
+    getAll(filter?: NodeFilter): GraphNode[];
+    getGoals(filter?: Partial<{
+        status: GoalStatus;
+        assignee: string;
+        priority: GoalPriority;
+    }>): GoalNode[];
+    getFacts(filter?: Partial<{
+        category: FactCategory;
+        severity: string;
+    }>): FactNode[];
+    getChanges(filter?: Partial<{
+        status: ChangeStatus;
+    }>): ChangeNode[];
+    getOpenGoals(): GoalNode[];
+    getTopLevelGoals(): GoalNode[];
+    getBlockedGoals(): GoalNode[];
+    getPendingChanges(): ChangeNode[];
+    getDecisions(since?: string): DecisionNode[];
+    searchFacts(query: string): FactNode[];
+    getRelatedFacts(factId: string): FactNode[];
+    /**
+     * Subscribe to nodes matching a filter. Returns a channel id that can be
+     * used to poll for new nodes since the last check.
+     */
+    subscribe(agentId: string, filter: NodeFilter): string;
+    /**
+     * Poll for new nodes delivered to a channel since last check.
+     * Clears the delivery buffer after reading.
+     */
+    poll(channel: string): GraphNode[];
+    unsubscribe(channel: string): void;
+    /**
+     * Create a quality gate result. Call this when a change is being proposed
+     * so the change node carries the gate result.
+     */
+    static makeQualityGate(checks: {
+        name: string;
+        passed: boolean;
+        detail?: string;
+    }[]): QualityGateResult;
+    /** Pure: compute the set of index keys a node would belong to. */
+    private _indexKeys;
+    /** Mutate the index: add a node's id to every set for the given keys. */
+    private _addToIndex;
+    /** Remove a node's id from all index sets for the given keys. */
+    private _removeFromIndex;
+    private _matches;
+    private _deliver;
+    private _persist;
+    private _append;
+    /** Rebuild in-memory state from the log file. Call on startup. */
+    load(): Promise<void>;
+    /** Snapshot for serialization. */
+    snapshot(): {
+        nodes: GraphNode[];
+        subs: number;
+    };
+}
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/coordination/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../../src/coordination/knowledge-graph.ts"],"names":[],"mappings":"AA0BA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExE,MAAM,MAAM,YAAY,GACpB,KAAK,GACL,UAAU,GACV,UAAU,GACV,MAAM,GACN,MAAM,GACN,MAAM,GACN,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AACnF,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAElE,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;AAC5F,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,gBAAgB,GAAG,eAAe,GAAG,UAAU,GAAG,UAAU,GAAG,eAAe,CAAC;AAE/H,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;KAAE,EAAE,CAAC;IAClE,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,qCAAqC;IACrC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;AAInF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwC;IAC7D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAkC;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IACjD,OAAO,CAAC,UAAU,CAAK;IAEvB,2EAA2E;IAC3E,OAAO,CAAC,SAAS;IAIjB,kEAAkE;IAClE,QAAQ,IAAI,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAEnD;IAED,YAAY,UAAU,EAAE,MAAM,EAG7B;IAID;;;OAGG;IACG,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAQzD;IAED,gFAAgF;IAC1E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAc7E;IAID,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAErC;IAED,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,EAAE,CAwBvC;IAED,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC,GAAG,QAAQ,EAAE,CAEvG;IAED,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAE,QAAQ,EAAE,YAAY,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,QAAQ,EAAE,CAEnF;IAED,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC,GAAG,UAAU,EAAE,CAEnE;IAED,YAAY,IAAI,QAAQ,EAAE,CAIzB;IAED,gBAAgB,IAAI,QAAQ,EAAE,CAE7B;IAED,eAAe,IAAI,QAAQ,EAAE,CAE5B;IAED,iBAAiB,IAAI,UAAU,EAAE,CAEhC;IAED,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAE3C;IAID,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CASrC;IAED,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAM1C;IAID;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAMrD;IAED;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAMjC;IAED,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAGjC;IAID;;;OAGG;IACH,MAAM,CAAC,eAAe,CACpB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAC3D,iBAAiB,CAEnB;IAID,kEAAkE;IAClE,OAAO,CAAC,UAAU;IAgClB,yEAAyE;IACzE,OAAO,CAAC,WAAW;IAQnB,iEAAiE;IACjE,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,QAAQ;IAoBhB,OAAO,CAAC,QAAQ;YASF,QAAQ;YAQR,OAAO;IAQrB,kEAAkE;IAC5D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B1B;IAED,kCAAkC;IAClC,QAAQ,IAAI;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAK/C;CACF"}

package/dist/coordination/large-answer-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * LargeAnswerStore — prevents `ask_subagent` results from bloating the
+ * director's context window.
+ *
+ * Problem: `ask_subagent` returns full subagent responses as tool_result
+ * content. A single response can be 10-50K+ tokens. When the director
+ * calls `ask` multiple times, these accumulate in ctx.messages and can
+ * push context pressure past 100%, causing provider overflow errors or
+ * silent quality degradation.
+ *
+ * Solution: responses above `sizeThreshold` chars are stored here
+ * (in-memory Map keyed by stable id). The tool result returns only a
+ * compact summary + the store key. Callers retrieve the full result
+ * via `retrieveAnswer(key)` when they need it.
+ *
+ * The store is scoped to a single Director.run() lifecycle.
+ * It is NOT persisted — if the process crashes the results are lost,
+ * which is acceptable since the subagent already finished and the
+ * summary is in context.
+ */
+export interface AnswerEntry {
+    key: string;
+    value: unknown;
+    size: number;
+    storedAt: number;
+}
+export declare class LargeAnswerStore {
+    /**
+     * Responses above this size (in characters) are stored out-of-context.
+     * Below this, the full answer is returned inline (no overhead).
+     * Default: 2000 chars ≈ 400-600 tokens.
+     */
+    readonly sizeThreshold: number;
+    private readonly store;
+    constructor(sizeThreshold?: number);
+    /**
+     * Store a value, returning a summary + key for inline use.
+     * If the value is below sizeThreshold, returns it as-is (no store entry).
+     */
+    storeAnswer(value: unknown): {
+        key?: string | undefined;
+        summary: string;
+        inline: boolean;
+    };
+    /**
+     * Retrieve a previously stored answer by its key.
+     * Returns undefined if the key is unknown or the store was cleared.
+     */
+    retrieveAnswer(key: string): unknown | undefined;
+    /**
+     * Check if a key exists in the store.
+     */
+    hasAnswer(key: string): boolean;
+    /** Number of stored entries. */
+    get size(): number;
+    /** Total characters stored. */
+    get totalChars(): number;
+    /** Clear all stored entries. Call at the end of a director run. */
+    clear(): void;
+}
+//# sourceMappingURL=large-answer-store.d.ts.map

package/dist/coordination/large-answer-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"large-answer-store.d.ts","sourceRoot":"","sources":["../../src/coordination/large-answer-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,gBAAgB;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IAExD,YAAY,aAAa,SAAO,EAE/B;IAED;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CA4B1F;IAED;;;OAGG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAE/C;IAED;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9B;IAED,gCAAgC;IAChC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,+BAA+B;IAC/B,IAAI,UAAU,IAAI,MAAM,CAIvB;IAED,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/coordination/mail-tools.d.ts

@@ -0,0 +1,34 @@
+/**
+ * mail-tools — thin, high-affordance wrappers over the project mailbox.
+ *
+ * These are the PREFERRED mailbox tools for agents. The multi-action `mailbox`
+ * tool is the low-level power surface for advanced queries and agent status;
+ * `mail_send` and `mail_inbox` exist because explicit verbs ("send a mail",
+ * "read my inbox") are what makes agents USE the mailbox autonomously — a model
+ * reaches for `mail_send` mid-task far more readily than for
+ * `mailbox action=send ...`.
+ *
+ *   mail_send  — message one agent (`to: "leader@a1b2c3d4"`), every leader
+ *                (`to: "leader"`), or everyone (`to: "*"`)
+ *   mail_inbox — read unread mail (unique id + base alias + broadcasts),
+ *                marking it read so it isn't re-injected next iteration
+ *
+ * Both share the identity convention with the agent-loop checker
+ * (`<base>@<sessionTag>`, see mailbox-attach) via `resolveMailboxIdentity`.
+ *
+ * @module mail-tools
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { Tool } from '../types/tool.js';
+import { type MailboxResolver } from './mailbox-tool.js';
+export interface MailToolsOptions {
+    /** How to obtain a Mailbox given the execution Context (tests). */
+    resolveMailbox?: MailboxResolver | undefined;
+    /** Project dir for the shared mailbox. Prefer wpaths.projectDir. */
+    projectDir?: string | undefined;
+    /** EventBus for mailbox.agent_registered / heartbeat surface events. */
+    events?: EventBus | undefined;
+}
+export declare function makeMailSendTool(opts?: MailToolsOptions): Tool;
+export declare function makeMailInboxTool(opts?: MailToolsOptions): Tool;
+//# sourceMappingURL=mail-tools.d.ts.map

package/dist/coordination/mail-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-tools.d.ts","sourceRoot":"","sources":["../../src/coordination/mail-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAK7C,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,cAAc,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,wEAAwE;IACxE,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC/B;AA4BD,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,gBAAqB,GAAG,IAAI,CAyElE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,gBAAqB,GAAG,IAAI,CAiGnE"}

package/dist/coordination/mailbox-actions.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Mailbox message action helpers (skeleton).
+ *
+ * Phase 1 skeleton: declares the {@link MailboxMessageAction} union
+ * (the verb that a user or agent issues against a single message) and
+ * the per-action input shapes. The actual implementations
+ * ({@link GlobalMailbox.markRead}, {@link GlobalMailbox.acknowledge},
+ * {@link GlobalMailbox.softDelete}, {@link GlobalMailbox.restore}) are
+ * added in Phase 2 alongside the corresponding `GlobalMailbox`
+ * methods.
+ *
+ * Keeping the verb+input types in their own file means the WebUI
+ * client (Phase 3) and the server route handlers (Phase 4) can
+ * import them independently of the `GlobalMailbox` implementation,
+ * and a future "message actions" CLI subcommand only has to add
+ * one verb to a single place.
+ */
+import type { MailboxAckInput, MailboxMessage } from './mailbox-types.js';
+/**
+ * High-level verbs the WebUI/server route handlers expose. The
+ * mapping to underlying `MailboxAckInput` is straightforward:
+ *   - `mark-read`  → `ack({ read: true,  completed: false })`
+ *   - `acknowledge`→ `ack({ read: true,  completed: true  })`
+ *   - `reopen`     → `ack({ read: false, completed: false })`
+ *   - `soft-delete`→ not an `ack` — a separate `Mailbox.softDelete()`
+ *     that flips `deletedAt` to "now" (recoverable) and is filtered
+ *     out of the default `query()`.
+ *   - `restore`    → the inverse of `soft-delete`. Undoes a
+ *     `softDelete` by clearing `deletedAt`.
+ */
+export type MailboxMessageAction = 'mark-read' | 'acknowledge' | 'reopen' | 'soft-delete' | 'restore';
+/** Per-action request body sent from the WebUI → server route. */
+export interface MailboxActionInput {
+    action: MailboxMessageAction;
+    mailId: string;
+    /** Acting agent / user. Required by the server to stamp
+     *  `readBy` / `completedBy`. */
+    readerId: string;
+    /** Optional human note (e.g. "triaged — will follow up"). */
+    note?: string | undefined;
+    /** Optional idempotency key so retried requests don't double-apply
+     *  the action. Phase 4 wires this through to the CLI. */
+    requestId?: string | undefined;
+}
+/** Per-action response. Echoes the action + the resulting message
+ *  state so the UI can reconcile optimistic updates. */
+export interface MailboxActionResult {
+    action: MailboxMessageAction;
+    mailId: string;
+    /** Updated message snapshot. `null` if the message was already in
+     *  the target state (e.g. `mark-read` on a message the user has
+     *  already read) — the WebUI can ignore the result in that case. */
+    message: MailboxMessage | null;
+    /** True if the action actually mutated state; false if it was a
+     *  no-op. Lets the WebUI decide whether to update its local copy. */
+    changed: boolean;
+}
+/**
+ * Convert a high-level action into the underlying
+ * {@link MailboxAckInput} the existing `GlobalMailbox.ack` already
+ * supports. `soft-delete` and `restore` do NOT go through `ack` —
+ * the caller must dispatch them to `GlobalMailbox.softDelete` /
+ * `GlobalMailbox.restore` instead. This helper returns `null` for
+ * those two so the type signature forces the caller to handle them
+ * separately.
+ */
+export declare function actionToAckInput(action: Exclude<MailboxMessageAction, 'soft-delete' | 'restore'>, input: MailboxActionInput): MailboxAckInput;
+//# sourceMappingURL=mailbox-actions.d.ts.map

package/dist/coordination/mailbox-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-actions.d.ts","sourceRoot":"","sources":["../../src/coordination/mailbox-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE1E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,aAAa,GACb,QAAQ,GACR,aAAa,GACb,SAAS,CAAC;AAEd,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf;oCACgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;6DACyD;IACzD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;wDACwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf;;wEAEoE;IACpE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B;yEACqE;IACrE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,OAAO,CAAC,oBAAoB,EAAE,aAAa,GAAG,SAAS,CAAC,EAChE,KAAK,EAAE,kBAAkB,GACxB,eAAe,CASjB"}

package/dist/coordination/mailbox-health.d.ts

@@ -0,0 +1,131 @@
+/**
+ * MailboxHealthWatchdog — probes the mailbox HTTP bridge and posts a
+ * status message when it goes down.
+ *
+ * Designed to be embedded inside the WrongStack REPL/TUI/WebUI process —
+ * NOT a standalone agent. WrongStack has its own cross-agent
+ * coordination channel, so the cheapest reliable signal is "ask the
+ * bridge if it's alive, and if it's not, tell the rest of the team
+ * via the same channel the bridge exposes."
+ *
+ * Usage:
+ *
+ *   const mailbox = new GlobalMailbox(projectDir);
+ *   const watchdog = new MailboxHealthWatchdog({
+ *     mailbox,
+ *     url: 'http://127.0.0.1:7788',
+ *     probeIntervalMs: 15_000,
+ *     onAlert: (event) => console.warn(event),
+ *   });
+ *   await watchdog.start();
+ *   // ...later...
+ *   await watchdog.stop();
+ *
+ * The watchdog is a passive observer: it does NOT start the bridge.
+ * Starting the bridge is the user's job (`wstack mailbox serve` or
+ * `/mailbox-serve`). The watchdog then reports on what the user did.
+ */
+import type { GlobalMailbox } from './global-mailbox.js';
+import type { MailboxSendInput } from './mailbox-types.js';
+export interface MailboxHealthWatchdogOptions {
+    /** Project mailbox to probe-and-report on. Required. */
+    mailbox: GlobalMailbox;
+    /** URL of the mailbox bridge (no trailing slash). Required. */
+    url: string;
+    /** Probe interval in milliseconds. Default: 15_000. */
+    probeIntervalMs?: number;
+    /** Per-probe timeout in milliseconds. Default: 3_000. */
+    probeTimeoutMs?: number;
+    /**
+     * After this many consecutive failures the watchdog posts an alert.
+     * Default: 2 (so a single transient timeout doesn't trigger spam).
+     */
+    failureThreshold?: number;
+    /**
+     * Optional callback for local observability — fired on every state
+     * transition. The mailbox post is independent of this callback.
+     */
+    onAlert?: ((event: MailboxHealthEvent) => void) | undefined;
+    /**
+     * Agent id used to post the alert message. Default: 'mailbox-bridge-watchdog'.
+     */
+    from?: string;
+}
+export type MailboxHealthEvent = {
+    kind: 'probe-failed';
+    status?: number;
+    error?: string;
+} | {
+    kind: 'alert-posted';
+    consecutiveFailures: number;
+} | {
+    kind: 'recovery-posted';
+    downtimeMs: number;
+} | {
+    kind: 'started';
+    intervalMs: number;
+} | {
+    kind: 'stopped';
+};
+export declare const MAILBOX_HEALTH_DEFAULT_INTERVAL_MS = 15000;
+export declare const MAILBOX_HEALTH_DEFAULT_TIMEOUT_MS = 3000;
+export declare const MAILBOX_HEALTH_DEFAULT_FAILURE_THRESHOLD = 2;
+export declare const MAILBOX_HEALTH_DEFAULT_FROM = "mailbox-bridge-watchdog";
+export declare class MailboxHealthWatchdog {
+    private readonly mailbox;
+    private readonly url;
+    private readonly intervalMs;
+    private readonly timeoutMs;
+    private readonly failureThreshold;
+    private readonly from;
+    private readonly onAlert?;
+    private timer;
+    private consecutiveFailures;
+    private downSince;
+    private alerting;
+    private inFlight;
+    private aborted;
+    constructor(opts: MailboxHealthWatchdogOptions);
+    /** Start probing on `intervalMs`. Idempotent — second call is a no-op. */
+    start(): Promise<void>;
+    /** Stop probing. Safe to call multiple times. */
+    stop(): Promise<void>;
+    /** True between start() and stop(). */
+    isRunning(): boolean;
+    /** Number of consecutive failed probes since the last successful probe. */
+    get currentFailureStreak(): number;
+    /** True iff the watchdog currently considers the bridge down. */
+    isBridgeDown(): boolean;
+    private emit;
+    private tick;
+    private probe;
+    private recordSuccess;
+    private recordFailure;
+    private postDown;
+    private postRecovery;
+}
+export interface DownAlertInput {
+    from: string;
+    url: string;
+    consecutiveFailures: number;
+}
+export declare function buildDownAlert(input: DownAlertInput): MailboxSendInput;
+export interface RecoveryAlertInput {
+    from: string;
+    url: string;
+    downtimeMs: number;
+    consecutiveFailures: number;
+}
+export declare function buildRecoveryAlert(input: RecoveryAlertInput): MailboxSendInput;
+export interface WatchdogConfig {
+    probeIntervalMs: number;
+    probeTimeoutMs: number;
+    failureThreshold: number;
+}
+/**
+ * Throws if the watchdog config is invalid. Called from the
+ * MailboxHealthWatchdog constructor so misconfiguration fails fast
+ * (at startup), not silently after the first probe.
+ */
+export declare function validateWatchdogOptions(cfg: WatchdogConfig): void;
+//# sourceMappingURL=mailbox-health.d.ts.map

package/dist/coordination/mailbox-health.d.ts.map

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

package/dist/coordination/mailbox-hooks.d.ts

@@ -0,0 +1,55 @@
+/**
+ * mailbox-hooks — Tool-execution hooks for mailbox integration.
+ *
+ * 1. Before each tool call, checks the mailbox for unread high-priority
+ *    steer messages and emits a `mailbox.unread_count` event.
+ * 2. After each tool call, updates the agent heartbeat so other agents
+ *    know this one is still alive.
+ *
+ * This gives near-real-time mailbox checking (every tool call, not just
+ * iteration boundaries) and powers the "new mail" badge in the WebUI/TUI.
+ *
+ * @module mailbox-hooks
+ */
+import type { Mailbox } from '../coordination/mailbox-types.js';
+export interface MailboxHooksOptions {
+    /** The mailbox instance. */
+    mailbox: Mailbox;
+    /** Agent id for read-receipt and unread-check purposes. */
+    agentId: string;
+    /** Whether to emit new-mail notifications. Default: true. */
+    notifyNewMail?: boolean | undefined;
+    /** Whether to update heartbeat. Default: true. */
+    heartbeat?: boolean | undefined;
+}
+/**
+ * Create a pair of hooks for the tool execution pipeline.
+ *
+ * Usage:
+ *   const hooks = createMailboxHooks({ mailbox, agentId });
+ *   // In the tool executor, before each tool call:
+ *   await hooks.beforeTool({ events });
+ *   // After each tool call:
+ *   await hooks.afterTool();
+ *
+ * The `beforeTool` hook checks for unread messages and emits
+ * `mailbox.unread_count` events. The `afterTool` hook updates
+ * the agent heartbeat.
+ */
+export declare function createMailboxHooks(opts: MailboxHooksOptions): {
+    /**
+     * Call before each tool execution. Checks mailbox and emits events.
+     * @param events — EventBus-like object with emit method.
+     */
+    beforeTool(events: {
+        emit: (type: string, payload: unknown) => void;
+    }): Promise<void>;
+    /**
+     * Call after each tool execution. Updates heartbeat and optionally
+     * current tool status.
+     */
+    afterTool(toolName?: string): Promise<void>;
+    /** Reset the cached unread count (e.g., after the agent checks manually). */
+    reset(): void;
+};
+//# sourceMappingURL=mailbox-hooks.d.ts.map

package/dist/coordination/mailbox-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-hooks.d.ts","sourceRoot":"","sources":["../../src/coordination/mailbox-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB;IAMxD;;;OAGG;IACG,UAAU,SAAS;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3F;;;OAGG;IACG,SAAS,YAAY,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAajD,6EAA6E;IAC7E,KAAK;EAIR"}