@wrongstack/core 0.309.0 → 0.310.0

package/dist/coordination/kanban-dispatch-port.d.ts

@@ -0,0 +1,30 @@
+/**
+ * kanban-dispatch-port — composition seam for the Director's kanban
+ * dispatch and assignment operations (Roadmap #11).
+ *
+ * The coordination layer must not import `@wrongstack/kanban` at runtime;
+ * it resolves the concrete operations through this port, wired at the
+ * CLI composition root (see `setKanbanDispatch`). Type imports from
+ * `@wrongstack/kanban` are erased at compile time and do not create a
+ * runtime edge.
+ */
+import type { CompleteDispatchInput, CompleteDispatchResult, FailDispatchInput, HeartbeatKanbanTaskAssignmentInput, KanbanAgentAssignment, KanbanAgentRunStatus, KanbanBoard, KanbanEventContext, KanbanSearchInput, KanbanSearchResult, ReserveDispatchInput, ReserveDispatchResult, StartDispatchInput, StartDispatchResult } from '@wrongstack/kanban';
+export interface KanbanDispatchPort {
+    getBoard(projectRoot: string, boardId: string): Promise<KanbanBoard | null>;
+    listReadyTasks(projectRoot: string, input?: KanbanSearchInput & {
+        limit?: number | undefined;
+    }): Promise<KanbanSearchResult[]>;
+    reserveKanbanDispatch(projectRoot: string, input: ReserveDispatchInput): Promise<ReserveDispatchResult | null>;
+    startKanbanDispatch(projectRoot: string, input: StartDispatchInput): Promise<StartDispatchResult | null>;
+    completeKanbanDispatch(projectRoot: string, input: CompleteDispatchInput): Promise<CompleteDispatchResult | null>;
+    failKanbanDispatch(projectRoot: string, input: FailDispatchInput): Promise<KanbanBoard | null>;
+    updateTaskAssignment(projectRoot: string, boardId: string, taskId: string, patch: Partial<KanbanAgentAssignment> & {
+        status?: KanbanAgentRunStatus | undefined;
+    }, eventContext?: KanbanEventContext): Promise<KanbanBoard | null>;
+    heartbeatTaskAssignment(projectRoot: string, boardId: string, taskId: string, input?: HeartbeatKanbanTaskAssignmentInput): Promise<KanbanBoard | null>;
+}
+/** Composition-root hook: register the real kanban-backed implementation. */
+export declare function setKanbanDispatch(impl: KanbanDispatchPort): void;
+/** Runtime accessor used by director-tools; throws loudly when unwired. */
+export declare function kanbanDispatch(): KanbanDispatchPort;
+//# sourceMappingURL=kanban-dispatch-port.d.ts.map

package/dist/coordination/kanban-ops-port.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Kanban operations port for the coordination area (director queue tools).
+ *
+ * The director queue helpers previously imported `describeKanbanBoundary`
+ * (a pure formatter) directly from `@wrongstack/kanban`, keeping a
+ * core → kanban runtime edge (roadmap #11 / report §2.1). This port is
+ * the leaf contract; the CLI composition root registers the real
+ * implementation at boot alongside the storage BoardStorePort.
+ *
+ * Type-only imports of kanban's data shapes remain permitted — they erase
+ * at compile time and do not create a runtime edge.
+ */
+import type { KanbanBoundaryPolicy } from '@wrongstack/kanban';
+export interface KanbanBoundaryOpsPort {
+    describeKanbanBoundary(policy: KanbanBoundaryPolicy | undefined): string;
+}
+/** Composition-root hook: register the real kanban-backed implementation. */
+export declare function setKanbanBoundaryOps(impl: KanbanBoundaryOpsPort): void;
+/** Resolve the boundary-ops port (throws when not wired, mirroring BoardStorePort). */
+export declare function kanbanBoundaryOps(): KanbanBoundaryOpsPort;
+//# sourceMappingURL=kanban-ops-port.d.ts.map

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

@@ -11,7 +11,7 @@
  *
  * @module mailbox-hooks
  */
-import type { Mailbox } from '../coordination/mailbox-types.js';
+import type { Mailbox } from './mailbox-types.js';
 export interface MailboxHooksOptions {
     /** The mailbox instance. */
     mailbox: Mailbox;

package/dist/coordination/mailbox-project-server.js

@@ -384,7 +384,10 @@ var withFileLock = primitives.withFileLock;
 import * as fs from "node:fs";
 import * as fsp2 from "node:fs/promises";
 import * as path3 from "node:path";
-import { PerformanceObserver, constants as performanceConstants } from "node:perf_hooks";
+import {
+  PerformanceObserver,
+  constants as performanceConstants
+} from "node:perf_hooks";
 import * as v8 from "node:v8";
 
 // src/utils/memory-flight-recorder.ts
@@ -690,7 +693,8 @@ function createMemoryFlightRecorder(options = {}) {
   const now = options.now ?? Date.now;
   const startedAt2 = now();
   const root = options.diagnosticsRoot ?? path2.join(wstackGlobalRoot(), "diagnostics", "memory");
-  const enabled = options.enabled ?? (process.env["WRONGSTACK_MEMORY_FLIGHT_RECORDER"] !== "0" && process.env["NODE_ENV"] !== "test");
+  const isBunRuntime = typeof globalThis.Bun !== "undefined";
+  const enabled = options.enabled ?? (!isBunRuntime && process.env["WRONGSTACK_MEMORY_FLIGHT_RECORDER"] !== "0" && process.env["NODE_ENV"] !== "test");
   const writer = options.captureWriter ?? (enabled ? new ContinuousMemoryCaptureWriter(root) : disabledWriter(path2.join(root, `${timestampSlug()}-pid-${process.pid}`)));
   const observations = [];
   const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
@@ -800,7 +804,11 @@ function defaultHeapLogPath() {
 function takeHeapSample() {
   const m = process.memoryUsage();
   const heap = v8.getHeapStatistics();
-  const spaces = v8.getHeapSpaceStatistics();
+  let spaces = [];
+  try {
+    spaces = v8.getHeapSpaceStatistics();
+  } catch {
+  }
   const spaceUsed = (name) => spaces.find((space) => space.space_name === name)?.space_used_size ?? 0;
   const limit = heap.heap_size_limit || 0;
   let activeResources = 0;
@@ -2230,8 +2238,8 @@ function previousCredentialTtlMs(credential) {
 
 // src/coordination/sqlite-mailbox-schema.ts
 import * as fs2 from "node:fs";
-import { createRequire } from "node:module";
 import * as path5 from "node:path";
+import { loadRuntimeDatabaseSync } from "@wrongstack/persistence";
 
 // src/utils/sqlite-warning.ts
 var SQLITE_EXPERIMENTAL_WARNING_RE = /sqlite is an experimental feature/i;
@@ -2379,8 +2387,7 @@ var DatabaseSyncCtor;
 function loadDatabaseSync() {
   if (DatabaseSyncCtor) return DatabaseSyncCtor;
   return withSqliteExperimentalWarningSuppressed(() => {
-    const require2 = createRequire(import.meta.url);
-    DatabaseSyncCtor = require2("node:sqlite").DatabaseSync;
+    DatabaseSyncCtor = loadRuntimeDatabaseSync();
     return DatabaseSyncCtor;
   });
 }
@@ -2536,9 +2543,7 @@ function migrateLegacyFiles(ctx) {
 }
 function readLegacyMessages(projectDir2) {
   try {
-    return parseMailboxFile(
-      fs2.readFileSync(path5.join(projectDir2, GLOBAL_MAILBOX_FILE), "utf8")
-    );
+    return parseMailboxFile(fs2.readFileSync(path5.join(projectDir2, GLOBAL_MAILBOX_FILE), "utf8"));
   } catch (error) {
     if (error.code === "ENOENT") return [];
     throw error;

package/dist/coordination/mutation-engine.d.ts

@@ -45,8 +45,10 @@ export interface PlanMutationsOptions {
  * Plan mutations for one file's source text.
  *
  * The scan is line-by-line with the file's own line splits preserved so ids
- * stay (line, column) anchored. Mutations inside comments and string
- * literals are filtered out by `isMasked` below.
+ * stay (line, column) anchored. Mutations inside comments, string literals,
+ * and template literals (single- or multi-line, interpolation contents
+ * excepted) are filtered out by the cross-line scanner `computeLineMasks`
+ * below.
  */
 export declare function planMutations(file: string, source: string, opts?: PlanMutationsOptions): MutationPlanItem[];
 /**
@@ -66,7 +68,7 @@ export declare function parseMutationReport(text: string): {
         file: string;
         line: number;
         kind: string;
-        status: 'killed' | 'survived' | 'skipped';
+        status: 'killed' | 'survived' | 'skipped' | 'killed-by-hang';
         evidence?: string | undefined;
     }>;
     summary?: string | undefined;

package/dist/core/context.d.ts

@@ -3,36 +3,14 @@ import type { ContextEvidenceState } from '../types/context-evidence.js';
 import type { FileEventRecord } from '../types/file-event-record.js';
 import type { Message } from '../types/messages.js';
 import type { Provider, Usage } from '../types/provider.js';
-import type { SessionWriter } from '../types/session.js';
+import type { SessionEvent, SessionWriter } from '../types/session.js';
 import type { TokenCounter } from '../types/token-counter.js';
 import type { Tool } from '../types/tool.js';
+import type { AgentContext, ContextMessageLimits } from '../types/context.js';
+import type { RunEnv } from '../types/run-env.js';
 import { ConversationState } from './conversation-state.js';
-import type { RunEnv } from './run-env.js';
-export interface TodoItem {
-    id: string;
-    content: string;
-    status: 'pending' | 'in_progress' | 'completed';
-    activeForm?: string | undefined;
-    /** When promoted from a plan item, stores the plan item's id. */
-    promotedFromPlan?: string | undefined;
-    /** When promoted from a task, stores the task's id. */
-    promotedFromTask?: string | undefined;
-    /** Durable Kanban owner when the todo row is a UI projection of a real card. */
-    kanbanBoardId?: string | undefined;
-    /** Durable Kanban card represented by this todo row. */
-    kanbanTaskId?: string | undefined;
-    /**
-     * Titles of the unfinished work this row waits on, derived from the Kanban
-     * card's dependencies. Always board-derived, never model-supplied.
-     *
-     * A blocked item is genuinely `pending` — it has not started — so this is an
-     * extra field rather than a fourth status. What was missing was never the
-     * state but the *reason*: the board computes readiness on every mutation,
-     * then the projection dropped it, leaving blocked work indistinguishable
-     * from ready work on screen and in the model's context.
-     */
-    blockedBy?: string[] | undefined;
-}
+import type { TodoItem } from '../types/context.js';
+export type { TodoItem };
 export interface RunOptions {
     signal?: AbortSignal | undefined;
     model?: string | undefined;
@@ -103,7 +81,7 @@ export interface ProviderMemoryEvidence {
  * the agent and user to navigate within the project without spawning a new
  * process. All changes must stay inside `projectRoot`.
  */
-export declare class Context implements RunEnv {
+export declare class Context implements RunEnv, AgentContext {
     messages: Message[];
     /**
      * Maximum number of messages retained in the conversation history.
@@ -243,6 +221,10 @@ export declare class Context implements RunEnv {
      * so storage operations can include it in `storage.*` events.
      */
     traceId: string | undefined;
+    /** Logical provider request whose response produced the current tool calls. */
+    activeLogicalRequestId: string | undefined;
+    /** Content-addressed prompt composition for {@link activeLogicalRequestId}. */
+    activePromptManifestId: string | undefined;
     /**
      * Session id pinned to the currently-executing run. Set by `Agent.run()`
      * at run start and cleared when the run ends. Event-emission sites must
@@ -266,13 +248,14 @@ export declare class Context implements RunEnv {
      */
     eventSessionId(): string;
     /** Callbacks fired when `setWorkingDir()` changes the working directory. */
-    private _onWorkingDirChanged;
+    /** WorkingDir-change callbacks; public for structural typing (Roadmap 10A). */
+    readonly _onWorkingDirChanged: Array<(newDir: string, oldDir: string) => void>;
     /**
      * Serializes externally requested provider/model changes. Request creation
      * waits on this barrier so an automatic continuation cannot capture the old
      * model while a user-triggered switch is still building its provider.
      */
-    private _modelTransition;
+    _modelTransition: Promise<void>;
     runModelTransition<T>(transition: () => T | Promise<T>): Promise<T>;
     waitForModelTransition(): Promise<void>;
     /**
@@ -333,23 +316,27 @@ export declare class Context implements RunEnv {
      * mutations that go through `state.appendMessage()` etc. fire
      * `onChange`. New code should prefer the wrapper API.
      */
-    private _state;
-    private readonly _conversationJournalQueue;
-    private _conversationJournalBytes;
-    private _conversationJournalDrain;
+    _state: ConversationState | null;
+    readonly _conversationJournalQueue: Array<{
+        event: SessionEvent;
+        bytes: number;
+        writer: SessionWriter;
+    }>;
+    _conversationJournalBytes: number;
+    _conversationJournalDrain: Promise<void> | null;
     private static readonly CONVERSATION_JOURNAL_MAX_EVENTS;
     private static readonly CONVERSATION_JOURNAL_MAX_BYTES;
     private static readonly MAX_FILE_EVENTS;
     private static readonly MAX_SIDE_EFFECTS;
     /** Wait until every exact conversation-state event queued so far is in the writer buffer. */
     flushConversationJournal(): Promise<void>;
-    private conversationJournalBytes;
-    private _journalDropCount;
-    private _journalDropWarnAt;
+    conversationJournalBytes(event: SessionEvent): number;
+    _journalDropCount: number;
+    _journalDropWarnAt: number;
     /** Throttled notice that a conversation event never reached the journal. */
-    private warnConversationJournalDrop;
-    private enqueueConversationJournal;
-    private startConversationJournalDrain;
+    warnConversationJournalDrop(eventType: SessionEvent['type']): void;
+    enqueueConversationJournal(event: SessionEvent, writer: SessionWriter): void;
+    startConversationJournalDrain(): void;
     get state(): ConversationState;
     /**
      * Register a teardown hook tied to the current run's abort signal.
@@ -364,7 +351,10 @@ export declare class Context implements RunEnv {
      * For hooks that must survive across run boundaries (mailbox heartbeat,
      * awareness polling, HQ publisher), prefer `registerAgentHook` instead.
      */
-    private abortHooks;
+    /** Run-scoped abort hooks (drained by drainAbortHooks). Public for structural typing (Roadmap 10A). */
+    readonly abortHooks: Set<() => void | Promise<void>>;
+    /** Retention limits honoring runtime subclass overrides of the statics. */
+    get messageLimits(): ContextMessageLimits;
     registerAbortHook(fn: () => void | Promise<void>): () => void;
     drainAbortHooks(): Promise<void>;
     /**
@@ -377,7 +367,8 @@ export declare class Context implements RunEnv {
      * awareness polling interval, HQ publisher connection, and auto-compaction
      * timer — resources that must survive from the first run to the last.
      */
-    private agentHooks;
+    /** Session-lifetime teardown hooks (drained by drainAgentHooks). Public for structural typing (Roadmap 10A). */
+    readonly agentHooks: Set<() => void | Promise<void>>;
     registerAgentHook(fn: () => void | Promise<void>): () => void;
     drainAgentHooks(): Promise<void>;
     /**
@@ -421,7 +412,7 @@ export declare class Context implements RunEnv {
      * the tool will re-stat the file and re-populate the entry. The agent
      * never fails or misbehaves; it just pays one extra stat call.
      */
-    private trimTrackedFiles;
+    trimTrackedFiles(): void;
     private static trimSet;
     private static trimMap;
     /** Clear accumulated file-read metadata after compaction or at boundaries
@@ -508,5 +499,5 @@ export declare class Context implements RunEnv {
  * tests and lightweight embedders stub Context with partial objects whose
  * `session` may be missing despite the non-optional type.
  */
-export declare function resolveEventSessionId(ctx: Context): string;
+export declare function resolveEventSessionId(ctx: AgentContext): string;
 //# sourceMappingURL=context.d.ts.map

package/dist/core/conversation-state.d.ts

@@ -1,6 +1,9 @@
 import type { ContentBlock } from '../types/blocks.js';
 import type { Message } from '../types/messages.js';
-import type { Context, TodoItem } from './context.js';
+import type { AgentContext, TodoItem } from '../types/context.js';
+import type { ConversationStateApi, ReadonlyConversationState, StateChange } from '../types/conversation-state.js';
+export type { ConversationStateApi, ReadonlyConversationState, StateChange };
+export type StateChangeHandler = (change: StateChange, state: ConversationStateApi) => void;
 /**
  * Observable wrapper for mutable conversation state. Production code should
  * mutate messages, todos, and meta through this API so subscribers see a
@@ -13,51 +16,13 @@ import type { Context, TodoItem } from './context.js';
  * that reads `ctx.messages` directly still works — they are NOT safe for
  * external writes.
  */
-export type StateChange = {
-    kind: 'message_appended';
-    message: Message;
-} | {
-    kind: 'messages_replaced';
-    messages: readonly Message[];
-}
-/** The oldest `count` messages were evicted; see the `messages_dropped` SessionEvent. */
- | {
-    kind: 'messages_dropped';
-    count: number;
-} | {
-    kind: 'message_updated';
-    index: number;
-    message: Message;
-} | {
-    kind: 'todos_replaced';
-    todos: readonly TodoItem[];
-    /**
-     * Final all-completed snapshot when the tactical list auto-clears.
-     * Observational mirrors use this to move cards to Done instead of
-     * interpreting the empty active list as "the work vanished".
-     */
-    completedSnapshot?: readonly TodoItem[] | undefined;
-} | {
-    kind: 'meta_set';
-    key: string;
-    value: unknown;
-} | {
-    kind: 'meta_deleted';
-    key: string;
-} | {
-    kind: 'meta_cleared';
-};
-export type StateChangeHandler = (change: StateChange, state: ConversationState) => void;
-export interface ReadonlyConversationState {
-    readonly messages: readonly Message[];
-    readonly todos: readonly TodoItem[];
-    readonly meta: Readonly<Record<string, unknown>>;
-}
 export declare class ConversationState {
-    private readonly ctx;
-    private readonly listeners;
-    private _revision;
-    constructor(ctx: Context);
+    /** Owning context; public for structural typing (Roadmap 10A). */
+    readonly ctx: AgentContext;
+    /** Subscribers; public for structural typing (Roadmap 10A). */
+    readonly listeners: Set<StateChangeHandler>;
+    _revision: number;
+    constructor(ctx: AgentContext);
     get messages(): readonly Message[];
     get todos(): readonly TodoItem[];
     get meta(): Readonly<Record<string, unknown>>;
@@ -77,16 +42,15 @@ export declare class ConversationState {
     appendMessage(message: Message): void;
     /**
      * How many of the oldest messages must be dropped to satisfy both retention
-     * caps — count ({@link Context.MAX_MESSAGES}) and size
-     * ({@link Context.MAX_MESSAGE_TOKENS}). Returns 0 when the history already
-     * fits, which is the overwhelmingly common case.
+     * caps — count and size (see {@link AgentContext.messageLimits}). Returns 0
+     * when the history already fits, which is the overwhelmingly common case.
      *
      * The size pass reads the per-message `_estTokens` cache populated at
      * mutation time, so it is a sum over numbers rather than a re-walk of
      * content blocks.  It runs whenever the token cap is enabled; the count
      * cap determines the starting index for the sum but does not gate it.
      */
-    private overflowCount;
+    overflowCount(arr: readonly Message[]): number;
     /**
      * Front eviction must not retain a `tool_result` after evicting the
      * immediately preceding assistant `tool_use`. Long tool-heavy sessions sit
@@ -100,7 +64,7 @@ export declare class ConversationState {
      * the minimum lossless representation; once enough newer messages exist, the
      * next eviction boundary naturally moves past both halves together.
      */
-    private protocolSafeDropCount;
+    protocolSafeDropCount(arr: readonly Message[], drop: number): number;
     /**
      * Append a content block to the trailing user message's content array.
      * Mutates only that one message (a single indexed assignment) — avoids
@@ -124,10 +88,10 @@ export declare class ConversationState {
      * the compatibility arrays are intentionally not observed.
      */
     onChange(listener: StateChangeHandler): () => void;
-    private emit;
+    emit(change: StateChange): void;
 }
 /**
  * Convenience constructor. The wrapper holds a reference, not a copy.
  */
-export declare function wrapAsState(ctx: Context): ConversationState;
+export declare function wrapAsState(ctx: AgentContext): ConversationState;
 //# sourceMappingURL=conversation-state.d.ts.map