@wrongstack/core 0.284.1 → 0.285.0

package/dist/coordination/subagent-budget.d.ts

@@ -0,0 +1,323 @@
+import type { Usage } from '../types/provider.js';
+import type { EventBus } from '../kernel/events.js';
+export type BudgetKind = 'tool_calls' | 'iterations' | 'tokens' | 'timeout' | 'idle_timeout' | 'cost';
+/**
+ * Fraction of the wall-clock `timeoutMs` window at which a PROACTIVE extension
+ * is negotiated — BEFORE the deadline is actually crossed. The coordinator
+ * watchdog (`executeWithTimeout`) arms at `timeoutMs * TIMEOUT_PREEMPT_FRACTION`
+ * so a still-progressing subagent gets its ceiling raised while it is below the
+ * limit, and never enters a "timed out" state. Reactive enforcement at the real
+ * deadline still stands for the no-progress / denied case. Shared so the asking
+ * side and any future caller agree on the same lead point.
+ */
+export declare const TIMEOUT_PREEMPT_FRACTION = 0.85;
+/**
+ * Hard safety net for budget negotiation decisions. If no listener responds to
+ * `budget.threshold_reached` within this window the negotiation defaults to
+ * `'stop'`. Exported so the coordinator's watchdog can reuse the same ceiling
+ * without hardcoding a second copy.
+ */
+export declare const DECISION_TIMEOUT_MS = 60000;
+export declare class BudgetExceededError extends Error {
+    readonly kind: BudgetKind;
+    readonly limit: number;
+    readonly observed: number;
+    constructor(kind: BudgetKind, limit: number, observed: number);
+}
+export interface BudgetLimits {
+    maxIterations?: number | undefined;
+    maxToolCalls?: number | undefined;
+    maxTokens?: number | undefined;
+    /** Estimated USD cost ceiling. */
+    maxCostUsd?: number | undefined;
+    /**
+     * Hard wall-clock timeout measured from `start()`. Off by default — set it
+     * explicitly only when a task must finish within an absolute window. For
+     * the everyday "don't kill an agent that's still working" guard, prefer
+     * `idleTimeoutMs`, which resets on activity.
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * Idle timeout: the maximum gap (ms) between activity signals (iterations,
+     * tool calls, token usage, streamed progress) before the subagent is
+     * considered hung and reaped. Unlike `timeoutMs`, an actively-working
+     * agent continuously resets this clock via `markActivity()`, so it never
+     * trips on a long-but-productive run — only on a genuine stall.
+     */
+    idleTimeoutMs?: number | undefined;
+}
+/**
+ * Controls how the budget behaves when `onThreshold` is set and a limit is hit.
+ *
+ * `'auto'` — emit `budget.threshold_reached` on the EventBus and wait for a
+ * coordinator response (extend/stop). If no listener responds within
+ * `DECISION_TIMEOUT_MS` the decision defaults to `'stop'`.
+ * `'sync'` — do not emit any event; treat the threshold as a hard stop and
+ * throw `BudgetExceededError` synchronously. Useful for fire-and-forget
+ * subagents that have an `onThreshold` handler for logging/metrics but are
+ * not wired into a coordinator.
+ *
+ * @default 'auto'
+ */
+export type BudgetNegotiationMode = 'auto' | 'sync';
+export type BudgetSessionIdSource = string | (() => string | undefined);
+export interface SubagentBudgetOptions {
+    sessionId?: BudgetSessionIdSource | undefined;
+}
+export interface BudgetUsage {
+    iterations: number;
+    toolCalls: number;
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    costUsd: number;
+    elapsedMs: number;
+}
+/**
+ * Thrown by `SubagentBudget.record*` when a soft limit is hit and
+ * an `onThreshold` handler is configured that wants to ask the
+ * coordinator (via `budget.threshold_reached` event). The runner
+ * catches this and awaits the embedded `decision` promise to get
+ * the coordinator's extend/stop decision.
+ *
+ * Distinct from `BudgetExceededError` which is a hard stop.
+ */
+export declare class BudgetThresholdSignal extends Error {
+    readonly kind: BudgetKind;
+    readonly limit: number;
+    readonly used: number;
+    /** Resolves to 'extend' (with optional new limits) or 'stop' */
+    readonly decision: Promise<BudgetThresholdDecision>;
+    constructor(kind: BudgetKind, limit: number, used: number, decision: Promise<BudgetThresholdDecision>);
+}
+export type BudgetThresholdDecision = 'stop' | {
+    extend: Partial<BudgetLimits>;
+};
+/**
+ * Callback invoked when a budget limit is about to be exceeded.
+ * Return 'throw' for hard stop (default — throws BudgetExceededError).
+ * Return 'continue' to allow one more unit and re-check next time.
+ * Return a Promise to ask the coordinator via `budget.threshold_reached`
+ * event (uses the same grant/deny pattern as `iteration.limit_reached`).
+ */
+export type BudgetThresholdHandler = (info: {
+    kind: BudgetKind;
+    used: number;
+    limit: number;
+    requestDecision: () => Promise<BudgetThresholdDecision>;
+    /**
+     * Direct grant/deny hooks for SYNCHRONOUS policy or recording handlers that
+     * decide in-process without a wired `budget.threshold_reached` listener
+     * (e.g. the coordinator watchdog). `extend` patches the limits in place;
+     * `deny` records the intent to stop. Production listener-driven handlers use
+     * `requestDecision()` instead and can ignore these.
+     */
+    extend?: (extra: Partial<BudgetLimits>) => void;
+    deny?: () => void;
+}) => 'throw' | 'continue' | 'stop' | {
+    extend: Partial<BudgetLimits>;
+} | Promise<BudgetThresholdDecision>;
+/**
+ * Per-subagent budget enforcement. Each subagent gets its own instance so a
+ * runaway agent can't drain the cost ceiling of its siblings. All record/check
+ * methods are O(1) and safe to call from hot paths.
+ *
+ * Behavior without `onThreshold`: hard stops synchronously on every limit hit.
+ *
+ * Behavior with `onThreshold` and `_mode === 'auto'`: emits `budget.threshold_reached`
+ * on the EventBus and throws `BudgetThresholdSignal`. The coordinator's verdict
+ * (extend/stop) resolves the embedded promise. If no listener responds within
+ * `DECISION_TIMEOUT_MS` the decision defaults to `'stop'`.
+ *
+ * Behavior with `onThreshold` and `_mode === 'sync'`: throws `BudgetExceededError`
+ * synchronously regardless of EventBus state or listener presence. This is useful
+ * for fire-and-forget subagents that have an `onThreshold` handler for logging/metrics
+ * but are not wired into a coordinator — the `'sync'` mode makes the hard-stop
+ * behavior explicit and means tests can use `expect().toThrow()` even without
+ * a fully-wired EventBus.
+ */
+export declare class SubagentBudget {
+    readonly limits: Readonly<BudgetLimits>;
+    /** Patch one or more budget limits in-place after construction.
+     * Used by the coordinator watchdog when granting an extension.
+     * All fields are optional — only provided fields are updated.
+     * This is the single write path for limit mutations so that future
+     * validation or side-effects live in one place (M1). */
+    patchLimits(ext: Partial<BudgetLimits>): void;
+    private iterations;
+    private toolCalls;
+    private tokenInput;
+    private tokenOutput;
+    private costUsd;
+    private startTime;
+    /**
+     * Timestamp of the most recent activity (iteration / tool call / token
+     * usage / streamed progress). Drives the idle timeout — reset by
+     * `markActivity()`. Initialised to `start()` time so a never-active agent
+     * still eventually trips its idle window.
+     */
+    private lastActivityTime;
+    private _onThreshold;
+    private readonly _sessionId;
+    /**
+     * Hard cap on how long `_negotiateExtension` waits for the coordinator to
+     * respond before defaulting to 'stop'. Without this fallback an absent
+     * or hung listener (Director not built / event filter detached mid-run)
+     * leaves the budget over-limit and never enforces anything.
+     */
+    private static readonly DECISION_TIMEOUT_MS;
+    /**
+     * Injected by the runner when wiring the budget to its EventBus.
+     * Used to emit `budget.threshold_reached` events in `'auto'` mode.
+     */
+    _events?: EventBus | undefined;
+    /**
+     * Guard against dual-path races between the coordinator watchdog
+     * (`executeWithTimeout`) and the budget's own `checkTimeout()`.
+     * Both paths detect `elapsed >= timeoutMs` and can emit
+     * `budget.threshold_reached` for kind `'timeout'` simultaneously.
+     * Set to the current `timeoutMs` ceiling by the coordinator BEFORE
+     * calling `onThreshold`, and cleared after the negotiation resolves.
+     * `checkTimeout()` skips its wall-clock check while this is set so
+     * the coordinator's watchdog is the sole source of wall-clock timeout
+     * events — `checkTimeout()` focuses exclusively on `idle_timeout`.
+     */
+    private _watchdogActive;
+    /** Returns the timeout ceiling currently being negotiated by the watchdog,
+     * or `undefined` when no wall-clock negotiation is in flight.
+     * Used by `executeWithTimeout` to detect a stale lock (M3). */
+    get watchdogActive(): number | undefined;
+    /** Called by the coordinator watchdog BEFORE calling `onThreshold` so that
+     * `checkTimeout()` skips its wall-clock check for this ceiling. Prevents
+     * the budget's own `checkTimeout()` from emitting a second
+     * `budget.threshold_reached` event while the watchdog is already
+     * negotiating the same wall-clock deadline (C1). */
+    setWatchdogNegotiation(timeoutMs: number): void;
+    /** Clears the watchdog guard after negotiation resolves. Called in the
+     * `finally` block of both the pre-empt and deadline branches so it fires
+     * on every exit path: grant, deny, throw, or error. */
+    clearWatchdogNegotiation(): void;
+    /**
+     * Negotiation mode — controls whether a threshold hit tries to emit
+     * `budget.threshold_reached` and wait for a coordinator decision, or
+     * falls straight through to a synchronous hard stop.
+     *
+     * `'auto'` (default) — emit on the EventBus and wait; times out to 'stop'.
+     * `'sync'` — throw `BudgetExceededError` immediately regardless of listeners.
+     */
+    private _mode;
+    /**
+     * Optional callback for soft-limit handling. When set, the budget will
+     * invoke it rather than throw immediately. The handler decides whether to
+     * throw synchronously, continue, or ask the coordinator for an extension.
+     */
+    get onThreshold(): BudgetThresholdHandler | undefined;
+    set onThreshold(fn: BudgetThresholdHandler | undefined);
+    /** Returns the current negotiation mode. */
+    get mode(): BudgetNegotiationMode;
+    constructor(limits?: BudgetLimits, mode?: BudgetNegotiationMode, options?: SubagentBudgetOptions);
+    private currentSessionId;
+    start(): void;
+    /**
+     * Reset the idle clock. Called on any sign of forward progress —
+     * iterations, tool calls, token usage, and streamed tool/text progress —
+     * so a long-but-productive subagent never trips its `idleTimeoutMs`.
+     */
+    markActivity(): void;
+    /**
+     * Milliseconds since the last activity signal. Returns 0 before `start()`
+     * (nothing to measure yet). Used by the coordinator watchdog to decide
+     * whether to re-arm (still active) or reap (genuinely idle).
+     */
+    idleMs(): number;
+    /** Returns true if we're within 10% of any limit — useful for pre-flight checks. */
+    isNearLimit(): boolean;
+    /**
+     * Synchronous budget check. Always throws synchronously so callers (especially
+     * test event handlers using `expect().toThrow()`) get an unhandled rejection
+     * when the budget is exceeded without a handler.
+     *
+     * Decision table:
+     * - no `onThreshold` handler         → throw `BudgetExceededError` (hard stop, always)
+     * - `mode === 'sync'`               → throw `BudgetExceededError` (hard stop, always)
+     * - `mode === 'auto'` + no listener  → throw `BudgetExceededError` (hard stop; no one to ask)
+     * - `mode === 'auto'` + listener     → throw `BudgetThresholdSignal` with async decision promise
+     */
+    /**
+     * Collects all exceeded budget kinds into a single NOOP-free negotiation.
+     * Called by recordIteration / recordToolCall / recordUsage — each may call
+     * this for its own kind. The first call starts the negotiation and stores
+     * the Promise in _pendingNegotiation. Subsequent calls for DIFFERENT
+     * kinds (while a negotiation is in flight) are NOOPs — they don't start
+     * new conversations with the coordinator. This prevents an EventBus flood
+     * when multiple budget kinds are exceeded simultaneously in one iteration.
+     *
+     * Returns the kinds that were found to be exceeded (for logging/debugging).
+     */
+    private checkLimits;
+    /**
+     * Invoke `onThreshold` once for `entry` on the NO-LISTENER path and report
+     * whether it decided synchronously. Returns `true` when the handler returned
+     * a synchronous decision (already honored — an `extend` patched the limits),
+     * or `false` when it returned a Promise (async; the caller hard-stops, since
+     * there is no listener to resolve the negotiation). The handler is given the
+     * full info shape (`requestDecision` plus direct `extend`/`deny`) so both
+     * recording handlers and policy handlers work without a wired listener.
+     */
+    private _invokeHandlerSync;
+    /**
+     * Emit `budget.threshold_reached` and resolve to the listener's verdict.
+     * Resolves to `'stop'` immediately when there is no listener (or no bus) so
+     * no negotiation can hang and no fallback timer leaks. Mirrors the
+     * coordinator watchdog's own request path so both agree on the no-listener
+     * default.
+     */
+    private _busRequestDecision;
+    /**
+     * Per-kind in-flight negotiation Promises. Each budget kind can have its
+     * own concurrent negotiation — e.g. iterations and timeout can both
+     * be exceeded simultaneously without blocking each other. The same kind
+     * cannot start two concurrent negotiations (dedup guard).
+     * Cleared in `_negotiateExtension`'s `finally` block.
+     */
+    private _pendingNegotiations;
+    /**
+     * Drive the threshold handler to a decision. Resolves with `'stop'`
+     * (signal the runner to abort) or `{ extend: ... }` (limits already
+     * patched in-place; the runner should not abort). Clears the
+     * per-kind slot in `_pendingNegotiations` in `finally`.
+     *
+     * The 'continue' return from a sync handler is treated as
+     * `{ extend: {} }` — keep going without patching; next overrun fires
+     * a fresh signal.
+     */
+    private _negotiateExtension;
+    recordIteration(): void;
+    recordToolCall(): void;
+    recordUsage(usage: Usage, costUsd?: number): void;
+    /**
+     * Wall-clock / idle budget check. Delegates to `checkLimits(elapsed)`, so
+     * `timeout` and `idle_timeout` follow the SAME negotiation path as the other
+     * kinds — they are NOT a special-cased hard stop. This is deliberate: a
+     * heartbeat-aware policy (see `attachAutoExtend` and `CollabSession`) grants
+     * a timeout extension only while the agent is making progress and denies it
+     * once the agent is genuinely stuck, which is safer than an unconditional
+     * hard kill of a long-but-working agent. The runner translates the resulting
+     * `BudgetThresholdSignal` decision (`extend` → patch limits in place,
+     * `stop` → abort) just like every other kind.
+     *
+     * Decision table (same as `checkLimits`):
+     * - no `onThreshold` handler        → throw `BudgetExceededError` (hard stop)
+     * - `mode === 'sync'`               → throw `BudgetExceededError` (hard stop)
+     * - `mode === 'auto'` + no listener → throw `BudgetExceededError` (no one to ask)
+     * - `mode === 'auto'` + listener    → throw `BudgetThresholdSignal` (negotiated;
+     *                                     a heartbeat-aware policy may extend the timeout)
+     */
+    checkTimeout(): void;
+    /** Returns true if a wall-clock or idle timeout has occurred without throwing. */
+    isTimedOut(): boolean;
+    usage(): BudgetUsage;
+}
+//# sourceMappingURL=subagent-budget.d.ts.map

package/dist/coordination/subagent-budget.d.ts.map

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

package/dist/coordination/subagent-nicknames.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Subagent nickname pool — famous scientists, mathematicians, and computing pioneers.
+ * Names are grouped by domain affinity so the nickname hints at the agent's role.
+ */
+/** Result of a nickname assignment. */
+export interface NicknameAssignment {
+    /**
+     * Canonical pool key (e.g. `von-neumann`). This — NOT the display string — is
+     * what callers must add to their `used` set and later remove on release.
+     * Deriving the key by parsing the display string is unsafe: multi-word names
+     * like "Von Neumann" would be truncated to "von" and never dedupe correctly.
+     */
+    key: string;
+    /** Human display string, e.g. `Von Neumann (Backend)`. */
+    display: string;
+}
+/**
+ * Assign a unique nickname to a subagent based on its role.
+ *
+ * Returns both the canonical pool `key` (for the `used` set) and the formatted
+ * `display` string (`Name (Role)`, e.g. `Einstein (Bug Hunter)`).
+ *
+ * @param role - The subagent's role id (e.g. 'bug-hunter', 'security-scanner')
+ * @param used - Set of nickname KEYS already assigned in this fleet
+ *               (so no two subagents share the same base name)
+ */
+export declare function assignNickname(role: string, used: ReadonlySet<string>): NicknameAssignment;
+/**
+ * Resolve a previously-assigned display string back to its canonical pool key,
+ * for release paths that only retained the formatted name (e.g. a manifest
+ * entry). Strips the trailing ` (Role)` suffix, then matches the base name
+ * against the pool. Returns `undefined` when the name is not a known nickname.
+ *
+ * Use this instead of `name.split(' ')[0]` — the latter mangles multi-word
+ * names like "Von Neumann" and "Berners-Lee".
+ */
+export declare function nicknameKeyFromDisplay(display: string): string | undefined;
+/**
+ * Returns all available nickname keys. Useful for testing or reset logic.
+ */
+export declare function getAllNicknameKeys(): string[];
+//# sourceMappingURL=subagent-nicknames.d.ts.map

package/dist/coordination/subagent-nicknames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-nicknames.d.ts","sourceRoot":"","sources":["../../src/coordination/subagent-nicknames.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoGH,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,kBAAkB,CA2B1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM1E;AAUD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C"}

package/dist/coordination/subagent-result-tool.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from '../core/context.js';
+import type { SubagentStructuredReport } from '../types/multi-agent.js';
+import type { Tool } from '../types/tool.js';
+/** Context metadata key used to hand the submitted report to the task runner. */
+export declare const SUBAGENT_STRUCTURED_REPORT_META_KEY = "subagentStructuredReport";
+export declare const MAX_SUBAGENT_STRUCTURED_REPORT_CHARS = 8000;
+/**
+ * Validate and normalize a model-supplied structured result. The tool executor
+ * already applies JSON Schema validation, but this guard keeps direct callers,
+ * custom executors, and data read back from Context metadata honest too.
+ */
+export declare function normalizeSubagentStructuredReport(value: unknown): SubagentStructuredReport | undefined;
+export declare function readSubagentStructuredReport(ctx: Pick<Context, 'meta'> | {
+    meta?: Record<string, unknown>;
+} | undefined): SubagentStructuredReport | undefined;
+/** Stable compact text form for mailbox/roll-up surfaces. */
+export declare function formatSubagentStructuredReport(report: SubagentStructuredReport): string;
+/** Safe, task-local handoff channel from a subagent to its Director. */
+export declare function makeSubagentResultTool(): Tool;
+//# sourceMappingURL=subagent-result-tool.d.ts.map

package/dist/coordination/subagent-result-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-result-tool.d.ts","sourceRoot":"","sources":["../../src/coordination/subagent-result-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,6BAA6B,CAAC;AAC9E,eAAO,MAAM,oCAAoC,OAAQ,CAAC;AAQ1D;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,GACb,wBAAwB,GAAG,SAAS,CAoCtC;AAED,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,SAAS,GAC1E,wBAAwB,GAAG,SAAS,CAEtC;AAED,6DAA6D;AAC7D,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAevF;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,IAAI,IAAI,CA8D7C"}

package/dist/coordination/task-auctioneer.d.ts

@@ -0,0 +1,143 @@
+import type { GoalNode, GoalStatus, GoalPriority } from './knowledge-graph.js';
+import type { KnowledgeGraph } from './knowledge-graph.js';
+import type { FleetBus } from './fleet-bus.js';
+import type { Mailbox } from './mailbox-types.js';
+export type { GoalStatus, GoalPriority };
+export interface TaskBid {
+    id: string;
+    taskId: string;
+    agentId: string;
+    agentName: string;
+    agentRole: string;
+    /** Dispatcher score for this task */
+    score: number;
+    /** Why this agent is a good fit */
+    rationale: string;
+    submittedAt: string;
+}
+export interface TaskAuctionOptions {
+    graph: KnowledgeGraph;
+    fleet?: FleetBus | undefined;
+    mailbox?: Mailbox | undefined;
+    selfAgentId?: string | undefined;
+    /** How long a bid window stays open before auto-awarding. Default: 30s */
+    bidWindowMs?: number | undefined;
+    /** Maximum concurrent tasks per agent. Default: 3 */
+    maxTasksPerAgent?: number | undefined;
+    /** Minimum confidence threshold for dispatcher scoring. Default: 0.3 */
+    minConfidence?: number | undefined;
+    /**
+     * Maximum times a task can be republished when no bids are received.
+     * After this, the task is marked as 'failed' with reason 'no_bids'.
+     * Default: 3.
+     */
+    maxBidRetries?: number | undefined;
+}
+export declare class TaskAuctioneer {
+    private readonly graph;
+    private readonly fleet?;
+    private readonly mailbox?;
+    private readonly selfAgentId;
+    private readonly bidWindowMs;
+    private readonly maxTasksPerAgent;
+    private readonly minConfidence;
+    private readonly maxBidRetries;
+    /** Pending bids keyed by taskId. */
+    private readonly pendingBids;
+    /** Active bid windows keyed by taskId. */
+    private readonly bidTimers;
+    /** FleetBus subscription disposers, detached in dispose(). */
+    private readonly unsubs;
+    /** How many times a task has been republished with no bids received. */
+    private readonly bidRetryCounts;
+    /** Agent → current task count (from graph + in-flight). */
+    private readonly agentTaskCounts;
+    constructor(opts: TaskAuctionOptions);
+    /**
+     * Detach all FleetBus subscriptions and cancel any open bid-window timers.
+     * Call when the owning coordinator stops/restarts so handlers and timers
+     * don't accumulate across cycles.
+     */
+    dispose(): void;
+    /**
+     * Publish a new task to the auction. Creates a GoalNode and broadcasts
+     * it to all online agents. Returns the goal id.
+     *
+     * If `targetAgent` is specified, the task is assigned directly without auction.
+     */
+    publishTask(input: {
+        title: string;
+        description: string;
+        priority?: GoalPriority;
+        tags?: string[];
+        targetAgent?: string;
+        parentGoal?: string;
+        satisfiesGoals?: string[];
+        /** Goal ids that must reach 'done' before this goal becomes workable. */
+        blockedBy?: string[];
+        deadline?: string;
+        reward?: string;
+    }): Promise<string>;
+    /**
+     * Submit a bid for a task. Called by agents who want to work on it.
+     * Returns true if the bid was accepted, false if the task was already claimed.
+     */
+    bid(taskId: string, agent: {
+        agentId: string;
+        agentName: string;
+        agentRole: string;
+    }, rationale: string): Promise<boolean>;
+    /**
+     * Award a task to a specific agent. Called internally by the bid window
+     * expiry, or can be called directly to force an award.
+     */
+    claim(taskId: string, agentId: string, agentName: string): Promise<boolean>;
+    /**
+     * Mark a task as done. Called by the agent when it finishes.
+     */
+    complete(taskId: string, _result?: string): Promise<void>;
+    /**
+     * Mark a task as failed. Optionally spawn a retry.
+     */
+    fail(taskId: string, error: string): Promise<void>;
+    /**
+     * Find the best available tasks for an agent based on its capabilities.
+     * Returns tasks sorted by match score (best first).
+     */
+    findWork(_agentId: string, agentRole: string, limit?: number): Promise<{
+        task: GoalNode;
+        score: number;
+        bids: number;
+    }[]>;
+    /** Get all pending tasks (available for bidding). */
+    getPendingTasks(): GoalNode[];
+    /** Get tasks assigned to a specific agent. */
+    getTasksForAgent(agentId: string): GoalNode[];
+    /** Get the current bid count for a task. */
+    getBidCount(taskId: string): number;
+    /** Get bids for a task. */
+    getBids(taskId: string): TaskBid[];
+    /** Get task stats for a project-wide dashboard. */
+    getStats(): {
+        total: number;
+        pending: number;
+        in_progress: number;
+        done: number;
+        failed: number;
+        totalBids: number;
+        avgBidsPerTask: number;
+    };
+    private _emit;
+    private _broadcastTask;
+    private _mailboxPublish;
+    private _notifyAgent;
+    private _startBidWindow;
+    private _cancelBidWindow;
+    private _evaluateBids;
+    private _assignDirect;
+    private _onBidEvent;
+    private _onClaimedEvent;
+    private _getAgentTaskCount;
+    private agentTaskCount;
+}
+//# sourceMappingURL=task-auctioneer.d.ts.map

package/dist/coordination/task-auctioneer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-auctioneer.d.ts","sourceRoot":"","sources":["../../src/coordination/task-auctioneer.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AAIzC,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAID,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAE5D,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAE/D,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAEhD,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAE5D,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAE7D,YAAY,IAAI,EAAE,kBAAkB,EAiBnC;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAUd;IAID;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE;QACvB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,YAAY,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,yEAAyE;QACzE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8DlB;IAID;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE;QAC/B,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAyDtC;IAID;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoChF;IAID;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8C9D;IAED;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBvD;IAID;;;OAGG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC;QACtE,IAAI,EAAE,QAAQ,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;KACd,EAAE,CAAC,CAsBH;IAID,qDAAqD;IACrD,eAAe,IAAI,QAAQ,EAAE,CAE5B;IAED,8CAA8C;IAC9C,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CAE5C;IAED,4CAA4C;IAC5C,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElC;IAED,2BAA2B;IAC3B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAEjC;IAED,mDAAmD;IACnD,QAAQ,IAAI;QACV,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;KACxB,CAmBA;IAID,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,cAAc;YAuBR,eAAe;YAmBf,YAAY;IAoB1B,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,gBAAgB;YAQV,aAAa;YA0Cb,aAAa;IAoB3B,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,cAAc;CAKvB"}