@wrongstack/core 0.5.5 → 0.5.6

package/dist/director-state-BmYi3DGA.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Director state checkpoint — written incrementally throughout a fleet
+ * run so a crashed director can be inspected (and eventually resumed)
+ * instead of leaving only a final `fleet.json` manifest after `shutdown()`.
+ *
+ * Schema is JSON-friendly and deliberately denormalized. Each mutation
+ * triggers an atomic-write of the whole file — small payloads (typically
+ * < 10 KB even with dozens of subagents) make this cheap.
+ */
+interface DirectorSubagentState {
+    id: string;
+    name?: string;
+    role?: string;
+    provider?: string;
+    model?: string;
+    spawnedAt: string;
+}
+interface DirectorTaskState {
+    taskId: string;
+    subagentId?: string;
+    description?: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped' | 'timeout';
+    assignedAt?: string;
+    completedAt?: string;
+    iterations?: number;
+    toolCalls?: number;
+    durationMs?: number;
+    error?: string;
+}
+interface DirectorStateSnapshot {
+    version: 1;
+    directorRunId: string;
+    updatedAt: string;
+    spawnCount: number;
+    maxSpawns?: number;
+    spawnDepth: number;
+    maxSpawnDepth: number;
+    directorBudget?: {
+        maxCostUsd?: number;
+    };
+    subagents: DirectorSubagentState[];
+    tasks: DirectorTaskState[];
+    /** Aggregated usage snapshot. Optional — populated by the Director on save when available. */
+    usage?: unknown;
+}
+declare function loadDirectorState(filePath: string): Promise<DirectorStateSnapshot | null>;
+/**
+ * In-memory accumulator with atomic-write checkpoint. The Director keeps
+ * an instance, mutates it on every spawn/assign/complete/fail event, and
+ * the instance debounces writes so a burst of activity collapses into a
+ * single disk hit.
+ *
+ * Supports crash recovery: use `loadDirectorState()` to read an existing
+ * checkpoint, then call `DirectorStateCheckpoint.resume(snapshot)` to
+ * re-attach to a fleet mid-flight. The lock mechanism ensures no two
+ * directors can claim the same checkpoint.
+ */
+declare class DirectorStateCheckpoint {
+    private snapshot;
+    private readonly filePath;
+    private readonly lockPath;
+    private timer;
+    private readonly debounceMs;
+    private writing;
+    private rewriteRequested;
+    constructor(filePath: string, init: {
+        directorRunId: string;
+        maxSpawns?: number;
+        spawnDepth: number;
+        maxSpawnDepth: number;
+        directorBudget?: {
+            maxCostUsd?: number;
+        };
+    }, debounceMs?: number);
+    /**
+     * Attempt to acquire the lock for this checkpoint. Call this before
+     * resuming a crashed director run. If it returns false, another
+     * director process is still running this fleet — do not resume.
+     */
+    acquireLock(): Promise<boolean>;
+    /**
+     * Release the lock on graceful shutdown. Call `flush()` first to ensure
+     * the final checkpoint state is on disk before removing the lock.
+     * Without this, the next resume will see a stale-lock and refuse.
+     */
+    releaseLock(): Promise<void>;
+    /**
+     * Resume from a snapshot previously loaded via `loadDirectorState()`.
+     * Use this when `--resume <runId>` is triggered — the snapshot has
+     * the full fleet state (subagents, tasks) from before the crash; the
+     * checkpoint continues from there.
+     */
+    resume(snapshot: DirectorStateSnapshot): void;
+    current(): DirectorStateSnapshot;
+    recordSpawn(sub: DirectorSubagentState, spawnCount: number): void;
+    recordTaskAssigned(task: DirectorTaskState): void;
+    recordTaskStatus(taskId: string, patch: Partial<DirectorTaskState> & {
+        status: DirectorTaskState['status'];
+    }): void;
+    setUsage(usage: unknown): void;
+    /** Force a synchronous flush — used by Director.shutdown(). */
+    flush(): Promise<void>;
+    private bumpUpdatedAt;
+    private schedule;
+    private persist;
+}
+
+export { DirectorStateCheckpoint as D, type DirectorStateSnapshot as a, type DirectorSubagentState as b, type DirectorTaskState as c, loadDirectorState as l };

package/dist/{index-De4R4rQ7.d.ts → index-BDnUCRvL.d.ts}

@@ -1,3 +1,4 @@
+import { a as DirectorStateSnapshot } from './director-state-BmYi3DGA.js';
 import { M as MultiAgentConfig, i as SubagentRunner, c as SubagentConfig, k as TaskSpec, j as TaskResult, a as CoordinatorStatus, b as MultiAgentCoordinator, S as SpawnResult, l as BridgeMessage, A as AgentBridge } from './multi-agent-Cv8wk47i.js';
 import { r as SessionWriter, v as Tool, p as SessionStore } from './context-CLZXPPYk.js';
 import { I as InMemoryAgentBridge } from './agent-bridge-B07AYFBk.js';
@@ -217,6 +218,51 @@ interface DirectorOptions {
      * writes (the manifest will then only be written on `shutdown()`).
      */
     manifestDebounceMs?: number;
+    /**
+     * Fleet-wide cost ceiling. When set, `spawn()` refuses any new subagent
+     * that would push the fleet's total cost above this limit. The cap
+     * is checked BEFORE the spawn is recorded — a refused spawn must not
+     * leak partial state into the manifest or fleet bus. Let in-flight
+     * tasks complete; refuse new spawns only. When `maxCostUsd` is absent
+     * or Infinity, no cost cap applies.
+     */
+    directorBudget?: {
+        /**
+         * Maximum total USD the fleet may spend across all subagents.
+         * Default: Infinity (no cap).
+         */
+        maxCostUsd?: number;
+    };
+    /**
+     * Maximum auto-extensions per subagent per budget kind before the
+     * director denies further extensions. A subagent hitting the same
+     * soft limit repeatedly (e.g. 3× budget.threshold_reached for
+     * tool_calls) is likely looping on a prompt/config issue, not
+     * making legitimate progress. Default: 2. Set to Infinity to
+     * disable the cap (use with caution — a misconfigured subagent
+     * could burn unlimited budget).
+     */
+    maxBudgetExtensions?: number;
+    /**
+     * Debounce window for state-checkpoint writes. Default: 250ms.
+     * Bursts of spawn/assign/complete events collapse into one disk
+     * hit. Higher values reduce write amplification on fast machines;
+     * lower values improve crash-recovery fidelity (less state lost
+     * on sudden process exit).
+     */
+    checkpointDebounceMs?: number;
+    /**
+     * Sessions root directory for per-subagent JSONL transcripts.
+     * When set, the director can read subagent transcripts directly for
+     * `fleet_session` tool — no bridge round-trip needed. Path convention:
+     * `<sessionsRoot>/<directorRunId>/<subagentId>.jsonl`.
+     */
+    sessionsRoot?: string;
+    /**
+     * Director run id — namespaced under `sessionsRoot` to locate per-subagent
+     * JSONLs. Defaults to the director's own `id` when omitted.
+     */
+    directorRunId?: string;
 }
 /**
  * Thrown by `Director.spawn()` when a configured spawn cap (`maxSpawns`,
@@ -230,6 +276,18 @@ declare class DirectorBudgetError extends Error {
     readonly observed: number;
     constructor(kind: 'max_spawns' | 'max_spawn_depth', limit: number, observed: number);
 }
+/**
+ * Thrown by `Director.spawn()` when the fleet-wide cost cap is exceeded.
+ * Distinct from `DirectorBudgetError` (spawn count/depth) — this is a
+ * dollar-denominated ceiling that tracks cumulative spend across all
+ * subagents in the fleet.
+ */
+declare class DirectorCostCapError extends Error {
+    readonly kind: 'max_cost_usd';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
 declare class Director {
     readonly id: string;
     readonly fleet: FleetBus;
@@ -284,6 +342,14 @@ declare class Director {
     /** Debounce timer for periodic manifest writes. */
     private manifestTimer;
     private readonly manifestDebounceMs;
+    /** Fleet-wide cost cap. Infinity means no cap. */
+    private readonly maxCostUsd;
+    /** Max auto-extensions per subagent per budget kind before denying. */
+    private readonly maxBudgetExtensions;
+    /** Sessions root for direct subagent JSONL reads (fleet_session tool). */
+    private readonly sessionsRoot?;
+    /** Director run id for JSONL path resolution. */
+    private readonly directorRunId;
     /** Resolves task descriptions back from `assign()` so completion events
      *  can also carry a human-readable title. */
     private readonly taskDescriptions;
@@ -404,6 +470,28 @@ declare class Director {
      * paint the completed table without reaching into private state.
      */
     completedResults(): TaskResult[];
+    /**
+     * Inject a previously-saved checkpoint snapshot. Call this right after
+     * constructing a Director during a `--resume` run so the in-memory state
+     * (subagents, tasks, waiters) reflects the pre-crash reality instead of
+     * starting from a blank slate. The director then resumes from there —
+     * completing any in-flight tasks and ignoring tasks that already reached
+     * a terminal state in the prior run.
+     */
+    setCheckpointState(snapshot: DirectorStateSnapshot): void;
+    /**
+     * Read a subagent's JSONL transcript directly from disk (no bridge
+     * round-trip needed). Returns the last assistant text, stop reason,
+     * tool-use count, and line count — or null if the file is unavailable.
+     * Requires `sessionsRoot` to be set on construction.
+     */
+    readSession(subagentId: string, tail?: number): Promise<{
+        lastAssistantText?: string;
+        lastStopReason?: string;
+        toolUsesObserved: number;
+        events: number;
+        path?: string;
+    } | null>;
     snapshot(): FleetUsage;
     /**
      * Look up provider/model metadata for a spawned subagent. Returns
@@ -453,6 +541,18 @@ declare class Director {
      * still permission-checked normally.
      */
     tools(roster?: Record<string, SubagentConfig>): Tool[];
+    /**
+     * Attempt to acquire the checkpoint lock. Must be called before
+     * resuming — if another director process is alive, this returns
+     * false and the caller should not proceed with the resume.
+     */
+    acquireCheckpointLock(): Promise<boolean>;
+    /**
+     * Resume from a prior checkpoint snapshot (loaded via
+     * `loadDirectorState()`). Re-attach to the fleet mid-flight so
+     * subsequent spawn/assign calls update the checkpoint normally.
+     */
+    resumeFromCheckpoint(snapshot: DirectorStateSnapshot): void;
 }
 
 /**
@@ -511,6 +611,13 @@ interface CreateDelegateToolOptions {
      * JSONLs at `<sessionsRoot>/<runId>/<subagentId>.jsonl`.
      */
     directorRunId?: string;
+    /**
+     * Buffer subtracted from the caller's `timeoutMs` before passing it
+     * to the subagent. Gives the host a window to detect a subagent that
+     * has gone silent and surface a partial result rather than a generic
+     * timeout. Default: 30_000 ms.
+     */
+    subagentTimeoutBufferMs?: number;
 }
 /**
  * `delegate` — the only multi-agent tool a regular (non-director) agent
@@ -896,4 +1003,4 @@ declare function applyRosterBudget(cfg: SubagentConfig): SubagentConfig;
 /** Quick-access list for spawning all at once. */
 declare const ALL_FLEET_AGENTS: SubagentConfig[];
 
-export { ALL_FLEET_AGENTS as A, BUG_HUNTER_AGENT as B, type CreateDelegateToolOptions as C, DEFAULT_DIRECTOR_PREAMBLE as D, rosterSummaryFromConfigs as E, FLEET_ROSTER as F, type MultiAgentCoordinatorOptions as M, REFACTOR_PLANNER_AGENT as R, SECURITY_SCANNER_AGENT as S, AUDIT_LOG_AGENT as a, type AgentFactory as b, type AgentFactoryResult as c, type AgentRunnerOptions as d, DEFAULT_SUBAGENT_BASELINE as e, DefaultMultiAgentCoordinator as f, type DelegateHost as g, Director as h, DirectorBudgetError as i, type DirectorPromptParts as j, type DirectorSessionFactory as k, type DirectorSessionFactoryOptions as l, FLEET_ROSTER_BUDGETS as m, FleetBus as n, type FleetEvent as o, type FleetHandler as p, type FleetUsage as q, FleetUsageAggregator as r, type SubagentPromptParts as s, type SubagentUsageSnapshot as t, applyRosterBudget as u, composeDirectorPrompt as v, composeSubagentPrompt as w, createDelegateTool as x, makeAgentSubagentRunner as y, makeDirectorSessionFactory as z };
+export { ALL_FLEET_AGENTS as A, BUG_HUNTER_AGENT as B, type CreateDelegateToolOptions as C, DEFAULT_DIRECTOR_PREAMBLE as D, rosterSummaryFromConfigs as E, FLEET_ROSTER as F, DirectorCostCapError as G, type MultiAgentCoordinatorOptions as M, REFACTOR_PLANNER_AGENT as R, SECURITY_SCANNER_AGENT as S, AUDIT_LOG_AGENT as a, type AgentFactory as b, type AgentFactoryResult as c, type AgentRunnerOptions as d, DEFAULT_SUBAGENT_BASELINE as e, DefaultMultiAgentCoordinator as f, type DelegateHost as g, Director as h, DirectorBudgetError as i, type DirectorPromptParts as j, type DirectorSessionFactory as k, type DirectorSessionFactoryOptions as l, FLEET_ROSTER_BUDGETS as m, FleetBus as n, type FleetEvent as o, type FleetHandler as p, type FleetUsage as q, FleetUsageAggregator as r, type SubagentPromptParts as s, type SubagentUsageSnapshot as t, applyRosterBudget as u, composeDirectorPrompt as v, composeSubagentPrompt as w, createDelegateTool as x, makeAgentSubagentRunner as y, makeDirectorSessionFactory as z };

package/dist/index.d.ts

@@ -33,11 +33,12 @@ export { C as CriticalPathResult, D as DEFAULT_SPEC_TEMPLATE, S as SpecAnalysis,
 export { A as AggregateHealth, H as HealthCheck, a as HealthCheckResult, b as HealthRegistry, c as HealthStatus, M as MetricLabels, d as MetricSeries, e as MetricsSink, f as MetricsSnapshot, S as Span, T as Tracer } from './observability-BhnVLBLS.js';
 export { AtomicWriteOptions, BuildChildEnvOptions, CompileFail, CompileResult, MessageRepairReport, MessageRepairResult, NewlineStyle, RequestTokenBreakdown, SafeParseResult, ToolOutputSerializerOptions, UnifiedDiffOptions, ValidationError, ValidationResult, atomicWrite, buildChildEnv, color, compileGlob, compileUserRegex, createToolOutputSerializer, detectNewlineStyle, ensureDir, estimateRequestTokens, estimateTextTokens, estimateToolDefTokens, estimateToolInputTokens, estimateToolResultTokens, formatTodosList, matchAny, matchGlob, normalizeToLf, repairToolUseAdjacency, safeParse, safeStringify, sanitizeJsonString, stripAnsi, toStyle, unifiedDiff, validateAgainstSchema } from './utils/index.js';
 export { a as WstackPathOptions, W as WstackPaths, p as projectHash, r as resolveWstackPaths } from './wstack-paths-86YPFktR.js';
-export { A as AbandonedSession, a as AttachmentStoreOptions, C as ConfigLoaderOptions, b as ConfigMigration, c as ConfigMigrationError, d as ConfigSource, D as DEFAULT_CONFIG_MIGRATIONS, e as DefaultAttachmentStore, f as DefaultConfigLoader, g as DefaultConfigStore, h as DefaultMemoryStore, i as DefaultSessionStore, j as DirectorStateCheckpoint, k as DirectorStateSnapshot, l as DirectorSubagentState, m as DirectorTaskState, M as MemoryStoreOptions, n as MigrationContext, o as MigrationResult, P as PersistedQueueItem, p as PlanFile, q as PlanItem, Q as QueueStore, R as RecoveryLock, r as RecoveryLockOptions, S as SessionAnalyzer, s as SessionStoreOptions, T as TodosCheckpointFile, t as addPlanItem, u as attachPlanCheckpoint, v as attachTodosCheckpoint, w as clearPlan, x as emptyPlan, y as formatPlan, z as loadDirectorState, B as loadPlan, E as loadTodosCheckpoint, F as removePlanItem, G as runConfigMigrations, H as savePlan, I as saveTodosCheckpoint, J as setPlanItemStatus } from './director-state-BUxlqkOa.js';
+export { A as AbandonedSession, a as AttachmentStoreOptions, C as ConfigLoaderOptions, b as ConfigMigration, c as ConfigMigrationError, d as ConfigSource, D as DEFAULT_CONFIG_MIGRATIONS, e as DefaultAttachmentStore, f as DefaultConfigLoader, g as DefaultConfigStore, h as DefaultMemoryStore, i as DefaultSessionStore, M as MemoryStoreOptions, j as MigrationContext, k as MigrationResult, P as PersistedQueueItem, l as PlanFile, m as PlanItem, n as PlanTemplate, Q as QueueStore, R as RecoveryLock, o as RecoveryLockOptions, S as SessionAnalyzer, p as SessionStoreOptions, T as TodosCheckpointFile, q as addPlanItem, r as attachPlanCheckpoint, s as attachTodosCheckpoint, t as clearPlan, u as deriveTodosFromPlanItem, v as emptyPlan, w as formatPlan, x as formatPlanTemplates, y as getPlanTemplate, z as listPlanTemplates, B as loadPlan, E as loadTodosCheckpoint, F as removePlanItem, G as runConfigMigrations, H as savePlan, I as saveTodosCheckpoint, J as setPlanItemStatus } from './plan-templates-DaxTCPfk.js';
+export { D as DirectorStateCheckpoint, a as DirectorStateSnapshot, b as DirectorSubagentState, c as DirectorTaskState, l as loadDirectorState } from './director-state-BmYi3DGA.js';
 export { AutoApprovePermissionPolicy, DefaultPermissionPolicy, PermissionPolicyOptions } from './security/index.js';
 export { AutoCompactionMiddleware, AutonomousRunner, AutonomousRunnerOptions, DefaultSkillLoader, DoneCheckResult, DoneConditionChecker, IntelligentCompactor, IntelligentCompactorOptions, SelectiveCompactor, SelectiveCompactorOptions, SkillLoaderOptions } from './execution/index.js';
 export { DefaultProviderRunner } from './defaults/index.js';
-export { A as ALL_FLEET_AGENTS, a as AUDIT_LOG_AGENT, b as AgentFactory, c as AgentFactoryResult, d as AgentRunnerOptions, B as BUG_HUNTER_AGENT, C as CreateDelegateToolOptions, D as DEFAULT_DIRECTOR_PREAMBLE, e as DEFAULT_SUBAGENT_BASELINE, f as DefaultMultiAgentCoordinator, g as DelegateHost, h as Director, i as DirectorBudgetError, j as DirectorPromptParts, k as DirectorSessionFactory, l as DirectorSessionFactoryOptions, F as FLEET_ROSTER, m as FLEET_ROSTER_BUDGETS, n as FleetBus, o as FleetEvent, p as FleetHandler, q as FleetUsage, r as FleetUsageAggregator, M as MultiAgentCoordinatorOptions, R as REFACTOR_PLANNER_AGENT, S as SECURITY_SCANNER_AGENT, s as SubagentPromptParts, t as SubagentUsageSnapshot, u as applyRosterBudget, v as composeDirectorPrompt, w as composeSubagentPrompt, x as createDelegateTool, y as makeAgentSubagentRunner, z as makeDirectorSessionFactory, E as rosterSummaryFromConfigs } from './index-De4R4rQ7.js';
+export { A as ALL_FLEET_AGENTS, a as AUDIT_LOG_AGENT, b as AgentFactory, c as AgentFactoryResult, d as AgentRunnerOptions, B as BUG_HUNTER_AGENT, C as CreateDelegateToolOptions, D as DEFAULT_DIRECTOR_PREAMBLE, e as DEFAULT_SUBAGENT_BASELINE, f as DefaultMultiAgentCoordinator, g as DelegateHost, h as Director, i as DirectorBudgetError, j as DirectorPromptParts, k as DirectorSessionFactory, l as DirectorSessionFactoryOptions, F as FLEET_ROSTER, m as FLEET_ROSTER_BUDGETS, n as FleetBus, o as FleetEvent, p as FleetHandler, q as FleetUsage, r as FleetUsageAggregator, M as MultiAgentCoordinatorOptions, R as REFACTOR_PLANNER_AGENT, S as SECURITY_SCANNER_AGENT, s as SubagentPromptParts, t as SubagentUsageSnapshot, u as applyRosterBudget, v as composeDirectorPrompt, w as composeSubagentPrompt, x as createDelegateTool, y as makeAgentSubagentRunner, z as makeDirectorSessionFactory, E as rosterSummaryFromConfigs } from './index-BDnUCRvL.js';
 export { DefaultModeStore, LLMSelector, LLMSelectorOptions, ModeLoaderOptions, loadProjectModes, loadUserModes } from './models/index.js';
 export { AISpecBuilder, AISpecBuilderOptions, AISpecPhase, AISpecSession, AutoExecutor, AutoExecutorOptions, BottleneckTask, CollectedAnswer, CriticalPathAnalysis, DefaultTaskStore, ExecutionSummary, GeneratedTask, SPEC_TEMPLATES, SpecDiff, SpecDrivenDev, SpecDrivenDevOptions, SpecIndexEntry, SpecParser, SpecStore, SpecStoreOptions, SpecVersion, SpecVersioning, TaskExecutionContext, TaskExecutionResult, TaskFlow, TaskFlowEventMap, TaskFlowEventName, TaskFlowExecutionContext, TaskFlowOptions, TaskFlowPhase, TaskGenerator, TaskGeneratorOptions, TaskGraphIndexEntry, TaskGraphStore, TaskGraphStoreOptions, TaskStore, TaskTracker, TaskTrackerOptions, TaskTransition, analyzeCriticalPath, createAutoExecutor, getTemplate, listTemplates, renderProgress, renderSpecAnalysis, renderTaskGraph, renderTaskList, templateToMarkdown } from './sdd/index.js';
 export { DefaultHealthRegistry, InMemoryMetricsSink, MetricsServerHandle, MetricsServerOptions, NoopMetricsSink, NoopTracer, OTelTracer, OtlpMetricsExporterHandle, OtlpMetricsExporterOptions, OtlpTraceExporterHandle, OtlpTraceExporterOptions, PROMETHEUS_CONTENT_TYPE, buildOtlpMetricsRequest, buildOtlpTracesRequest, renderPrometheus, startMetricsServer, startOtlpMetricsExporter, startOtlpTraceExporter, wireMetricsToEvents } from './observability/index.js';