@wrongstack/core 0.285.0 → 0.287.0

package/skills/wrongstack-mailbox/SKILL.md

@@ -87,6 +87,12 @@ but once that bridge dies the next start mints a new one. So always read
 it freshly from the token file (or accept it from the user); never
 hardcode it into prompts or committed code, and re-read it after a 401.
 
+The project token authorizes the route, **not the caller's identity**. The
+bridge accepts caller-supplied `from`, message type, registration ids, and
+acknowledgement `readerId`; it does not separately authorize control/steer
+messages. Use an honest, stable agent id, never impersonate `hq@...` or another
+agent, and treat every token holder as fully trusted for that project mailbox.
+
 If you're working with explicit env vars:
 
 ```ts
@@ -371,18 +377,55 @@ setInterval(() => {
 }, 30_000);
 ```
 
-### Poll, don't long-poll
+### Real-time push via SSE (preferred) or polling
+
+The bridge supports **Server-Sent Events (SSE)** on `GET /mailbox/events`
+for real-time push. This is the preferred approach — no polling needed.
+
+```ts
+// Open an SSE connection that pushes events in real-time.
+const res = await fetch(`${url}/mailbox/events`, {
+  headers: { Authorization: `Bearer ${token}` },
+});
+const reader = res.body!.getReader();
+const decoder = new TextDecoder();
+
+for (;;) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  const text = decoder.decode(value);
+  // SSE events arrive as: data: {"type":"message.sent",...}\n\n
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('data: ')) continue;
+    const event = JSON.parse(line.slice(6));
+    if (event.type === 'message.sent') {
+      console.log(`[${event.type}] ${event.from} → ${event.to}: ${event.messageId}`);
+      // Fetch the full message via /mailbox/query or /mailbox/check.
+    }
+  }
+}
+```
+
+**SSE event types:**
+
+| Event `type` | When | Payload fields |
+|--------------|------|---------------|
+| `message.sent` | A message was sent via `POST /mailbox/send` | `messageId`, `from`, `to`, `timestamp` |
+
+The SSE stream sends a `: connected` comment on open and a
+`: keepalive` comment every 15 s to prevent proxy/CDN timeouts.
 
-The bridge does not support long-polling or websockets. Poll for new
-messages on a 5–10 s interval. Don't poll faster than 1 Hz — that's noisy
-and gives nothing useful.
+**Important:** SSE events carry only the message id and metadata — not
+the full message body. When you receive an event, call `/mailbox/check`
+or `/mailbox/query` to fetch the complete message content.
 
-For normal inbox catch-up, prefer `/mailbox/check` over manual
-`/mailbox/query` + `/mailbox/ack-many`. It checks direct mail,
-`baseId` alias mail, and broadcasts in one call, dedupes messages, and
-can optionally mark them read or completed via one batch ack.
+**Fallback: polling.** If your HTTP client doesn't support SSE (or you're
+behind a proxy that buffers responses), poll on a 5–10 s interval. Don't
+poll faster than 1 Hz — the bridge enforces a rate limit of 120 requests
+per minute per bearer token.
 
 ```ts
+// Fallback: poll every 5 s when SSE is unavailable.
 async function pollOnce(): Promise<void> {
   const result = await mb('/mailbox/check', {
     agentId,
@@ -504,7 +547,7 @@ All routes take JSON bodies on POST (or no body on GET). All require
 
 | Method | Path | Purpose |
 |--------|------|---------|
-| POST | `/mailbox/send` | Send a message |
+| POST | `/mailbox/send` | Send a message (supports optional `ttlMs` for auto-expiry) |
 | POST | `/mailbox/query` | Query messages (filters: `to`, `from`, `unreadBy`, `type`, `minPriority`, `incompleteOnly`, `limit`, `since`) |
 | POST | `/mailbox/check` | Read inbox mail for `agentId`/`baseId` plus broadcasts; optionally `markRead=false`, `completed=true`, `outcome` |
 | POST | `/mailbox/ack` | Acknowledge one message |
@@ -516,6 +559,7 @@ All routes take JSON bodies on POST (or no body on GET). All require
 | POST | `/mailbox/heartbeat` | Update client heartbeat |
 | GET | `/mailbox/agents` | List all registered agents |
 | GET | `/mailbox/agents/online` | List agents with a live heartbeat (within 60 s) |
+| GET | `/mailbox/events` | **SSE stream** — real-time push of mailbox events (auth required) |
 | GET | `/healthz` | Liveness probe — does NOT require auth |
 
 ### Error shape
@@ -528,6 +572,7 @@ All routes take JSON bodies on POST (or no body on GET). All require
 |------|------|----------------------------|
 | `VALIDATION_ERROR` | 400 | Missing or wrong-type field. Read the message; it tells you which field. |
 | `UNAUTHORIZED` | 401 | Token mismatch. Re-read `~/.wrongstack/projects/<slug>/.mailbox.token` and try again — the bridge may have restarted. |
+| `RATE_LIMITED` | 429 | Rate limit exceeded (max 120 requests/min per token). Slow down or use SSE instead of polling. |
 | `NOT_FOUND` | 404 | Wrong route. Check the path table above. |
 | `INTERNAL_ERROR` | 500 | WrongStack-side failure. Retry once; if it persists, surface to the user. |
 
@@ -606,9 +651,9 @@ await mb('/mailbox/send', {
 - **Don't reuse one `agentId` across multiple external sessions.** If
   two processes register under the same id, heartbeats overwrite each
   other and read receipts become unreliable.
-- **Don't poll faster than 1 Hz.** The bridge isn't load-tested for
-  high-frequency polling, and there's no rate limit at the server side
-  — your noisy client can starve other agents.
+- **Don't poll faster than 1 Hz.** The bridge enforces a rate limit of
+  120 requests/min per bearer token (returns `429 RATE_LIMITED` beyond
+  that). Prefer SSE (`GET /mailbox/events`) over polling when possible.
 - **Don't include the token in any logged output.** It's the only
   credential. If you must print the URL, redact the token (`[REDACTED]`).
 - **Don't reply to a broadcast with another broadcast.** Replies should

package/dist/coordination/director-construction.d.ts

@@ -1,90 +0,0 @@
-/**
- * Director construction helpers.
- *
- * The `Director` constructor was historically a single 300+ line function
- * that interleaved field assignments with two pieces of event-listener
- * wiring: the `task.completed` listener on the coordinator (which mirrors
- * completions into the in-memory wait table, the on-disk checkpoint, and
- * the session JSONL event stream) and the `budget.threshold_reached`
- * filter on the FleetBus (which implements the heartbeat-driven timeout
- * policy and the per-kind auto-extension logic).
- *
- * Both wirings were inlined because they close over a lot of Director
- * private state (`completed`, `taskWaiters`, `taskDescriptions`,
- * `appendSessionEvent`, `scheduleManifest`, `recordExtension`,
- * `maxBudgetExtensions`, `maxFleetCostUsd`, etc.). Pulling them out
- * without losing the closures requires a narrow `DirectorInternals`
- * shape — exactly what this module exposes.
- *
- * The constructor itself stays a member-initializer; the helpers below
- * are called *during* construction, after the relevant fields are
- * populated. Each helper ends with `coordinator.on(...)` /
- * `fleet.filter(...)` registration so the listener is wired exactly
- * once, at construction time.
- */
-import type { TaskResult, TaskSpec } from '../types/multi-agent.js';
-/** Cap on the in-memory `completed` map. Trimmed oldest-first when exceeded. */
-export declare const MAX_COMPLETED = 10000;
-/** Narrow shape the wiring helpers need from a partially-constructed Director.
- *  The helpers accept a `Director` instance (structural typing — the class
- *  exposes every field this interface requires), so the constructor can pass
- *  `this` directly without an explicit cast.
- *
- *  Note: Private/protected members cannot be picked via Pick<> because keyof
- *  only returns public keys. We define the interface explicitly rather than
- *  deriving from Director to include private fields the wiring code needs. */
-export interface DirectorInternals {
-    id: string;
-    directorRunId: string;
-    completed: Map<string, import('../types/multi-agent.js').TaskResult>;
-    taskWaiters: Map<string, {
-        promise: Promise<import('../types/multi-agent.js').TaskResult>;
-        resolve: (r: import('../types/multi-agent.js').TaskResult) => void;
-    }>;
-    taskDescriptions: Map<string, string>;
-    stateCheckpoint: import('../storage/director-state.js').DirectorStateCheckpoint | null;
-    usage: import('./fleet-bus.js').FleetUsageAggregator;
-    fleetManager: import('./fleet-manager.js').FleetManager | undefined;
-    fleet: import('./fleet-bus.js').FleetBus;
-    coordinator: import('./icoordinator.js').ICoordinator;
-    maxBudgetExtensions: number;
-    maxFleetCostUsd: number;
-    recordExtension: (subagentId: string, taskId: string | undefined, kind: string, newLimit: number) => void;
-    appendSessionEvent: (event: Parameters<import('../types/session.js').SessionWriter['append']>[0]) => Promise<void>;
-    scheduleManifest: () => void;
-    brain: import('./brain.js').BrainArbiter | undefined;
-}
-export { TIMEOUT_PREEMPT_FRACTION } from './subagent-budget.js';
-/**
- * Wire the coordinator's `task.completed` event into the Director's
- * in-memory wait table, the on-disk state checkpoint, and the session
- * JSONL event stream.
- *
- * Mirrors coordinator completion events into:
- * - `d.completed` (capped at `Director.MAX_COMPLETED`, oldest-first trim)
- * - `d.taskWaiters` (resolve and clear the matching waiter)
- * - `d.stateCheckpoint.recordTaskStatus(...)` + `setUsage(...)`
- * - session event stream via `d.appendSessionEvent(...)`
- * - fleet manifest via `d.fleetManager?.flushManifest()` or `d.scheduleManifest()`
- *
- * Returns the listener so the Director can call `coordinator.off(...)`
- * during `shutdown()`.
- */
-export declare function wireTaskCompletedListener(d: DirectorInternals): (payload: {
-    task: TaskSpec;
-    result: TaskResult;
-}) => void;
-/**
- * Wire the FleetBus's `budget.threshold_reached` filter with the
- * Director's auto-extend/deny policy. Implements:
- *
- * - Heartbeat-driven timeout policy: while a subagent keeps executing
- *   tools it never dies on time; once it stops making progress between
- *   grants, deny. Wall-clock time alone is never a reliable "stuck" signal.
- * - Per-kind auto-extension with `maxBudgetExtensions` cap.
- * - Brain-decision routing when a brain arbiter is configured.
- * - Collab-subagent passthrough (BugHunter / RefactorPlanner / Critic
- *   own their own budget routing via the CollabSession).
- */
-export declare function wireBudgetHandler(d: DirectorInternals): void;
-//# sourceMappingURL=director-construction.d.ts.map

package/dist/coordination/director-construction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"director-construction.d.ts","sourceRoot":"","sources":["../../src/coordination/director-construction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEpE,gFAAgF;AAChF,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC;;;;;;;8EAO8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,yBAAyB,EAAE,UAAU,CAAC,CAAC;IACrE,WAAW,EAAE,GAAG,CACd,MAAM,EACN;QAAE,OAAO,EAAE,OAAO,CAAC,OAAO,yBAAyB,EAAE,UAAU,CAAC,CAAC;QAAC,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,yBAAyB,EAAE,UAAU,KAAK,IAAI,CAAA;KAAE,CACvI,CAAC;IACF,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACvF,KAAK,EAAE,OAAO,gBAAgB,EAAE,oBAAoB,CAAC;IACrD,YAAY,EAAE,OAAO,oBAAoB,EAAE,YAAY,GAAG,SAAS,CAAC;IACpE,KAAK,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAC;IACzC,WAAW,EAAE,OAAO,mBAAmB,EAAE,YAAY,CAAC;IACtD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1G,kBAAkB,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnH,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,KAAK,EAAE,OAAO,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;CACtD;AAyBD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAShE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,KAAK,IAAI,CAiEzH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CA2J5D"}

package/dist/hq/agent-bridge.d.ts

@@ -1,27 +0,0 @@
-/**
- * AgentMonitorEventBridge — forwards local agent timeline and status events
- * to the HQ publisher as structured HQ event envelopes, so the HQ browser
- * dashboard sees real-time agent conversation streams.
- */
-import type { EventBus } from '../kernel/events.js';
-import { type HqEventEnvelope } from './protocol.js';
-export type HqAgentEventPublisher = (envelope: HqEventEnvelope) => void;
-export interface AgentMonitorEventBridgeOptions {
-    /** Local EventBus emitting agent.timeline.* and agent.status_changed events. */
-    events: EventBus;
-    /** Client/project identifiers for HQ envelope authorship. */
-    clientId: string;
-    projectId: string;
-    /**
-     * Publish callback — called with each HQ event envelope. Wire this to
-     * your HQ publisher's `send()` or queue method when connected.
-     * When null (no HQ connection), events are silently dropped.
-     */
-    publish?: HqAgentEventPublisher | undefined;
-}
-/**
- * Start forwarding agent monitoring events to HQ. Returns a disposer that
- * unsubscribes all listeners — call on shutdown.
- */
-export declare function startAgentMonitorEventBridge(opts: AgentMonitorEventBridgeOptions): () => void;
-//# sourceMappingURL=agent-bridge.d.ts.map

package/dist/hq/agent-bridge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/hq/agent-bridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAgF,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnI,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC;AAExE,MAAM,WAAW,8BAA8B;IAC7C,gFAAgF;IAChF,MAAM,EAAE,QAAQ,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;CAC7C;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,8BAA8B,GAAG,MAAM,IAAI,CAyD7F"}

package/dist/plugins/git-plugin.d.ts

@@ -1,15 +0,0 @@
-import type { Plugin } from '../types/plugin.js';
-import type { SlashCommand } from '../index.js';
-/**
- * GitPlugin — built-in git helpers.
- *
- * Registers `/commit`, `/gitcheck` and `/push`. First-party ("official")
- * plugin, so the commands keep their bare names and `gc` / `gcstatus` aliases.
- * `/commit` generates an LLM commit message from the session provider when one
- * is available, falling back to diff heuristics. No configuration required.
- */
-export declare function createGitPlugin(): Plugin;
-export declare function buildCommitCommand(): SlashCommand;
-export declare function buildGitcheckCommand(): SlashCommand;
-export declare function buildPushCommand(): SlashCommand;
-//# sourceMappingURL=git-plugin.d.ts.map

package/dist/plugins/git-plugin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"git-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/git-plugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,aAAa,CAAC;AAEzD;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CA2BxC;AAgLD,wBAAgB,kBAAkB,IAAI,YAAY,CA+FjD;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAmBnD;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAiC/C"}

package/dist/plugins/observability-plugin.d.ts

@@ -1,19 +0,0 @@
-import type { Plugin } from '../types/plugin.js';
-import type { SlashCommand } from '../index.js';
-import type { HealthRegistry, MetricsSink } from '../types/observability.js';
-interface ObservabilityPluginOptions {
-    metricsSink?: MetricsSink | undefined;
-    healthRegistry?: HealthRegistry | undefined;
-}
-/**
- * ObservabilityPlugin — runtime metrics + health checks.
- *
- * Registers `/metrics` and `/health`. First-party ("official") plugin, so the
- * commands keep their bare names. Both require the host to have started the
- * metrics subsystem (`--metrics`); without it they report that and no-op.
- */
-export declare function createObservabilityPlugin(opts?: ObservabilityPluginOptions): Plugin;
-export declare function buildMetricsCommand(metricsSink?: MetricsSink): SlashCommand;
-export declare function buildHealthCommand(healthRegistry?: HealthRegistry): SlashCommand;
-export {};
-//# sourceMappingURL=observability-plugin.d.ts.map

package/dist/plugins/observability-plugin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"observability-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/observability-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7E,UAAU,0BAA0B;IAClC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,CAAC,EAAE,0BAA0B,GAAG,MAAM,CA8BnF;AAQD,wBAAgB,mBAAmB,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,YAAY,CAqC3E;AAED,wBAAgB,kBAAkB,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,YAAY,CAmBhF"}

package/dist/plugins/plan-plugin.d.ts

@@ -1,16 +0,0 @@
-import type { Plugin } from '../types/plugin.js';
-import type { SlashCommand } from '../index.js';
-import type { WstackPaths } from '../utils/wstack-paths.js';
-interface PlanPluginOptions {
-    paths?: WstackPaths | undefined;
-}
-/**
- * PlanPlugin — strategic plan board (`/plan`), the higher-level counterpart to
- * `/todos`. First-party ("official") plugin, so the command keeps its bare
- * name. Plans persist to `<projectDir>/plan.json` (from the injected
- * `WstackPaths`); the live context is read off `ctx` at dispatch.
- */
-export declare function createPlanPlugin(opts?: PlanPluginOptions): Plugin;
-export declare function buildPlanCommand(planPath?: string): SlashCommand;
-export {};
-//# sourceMappingURL=plan-plugin.d.ts.map

package/dist/plugins/plan-plugin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"plan-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/plan-plugin.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,UAAU,iBAAiB;IACzB,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAyBjE;AAYD,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAuHhE"}

package/dist/storage/memory-store.d.ts

@@ -1,119 +0,0 @@
-import type { MemoryEntry, MemoryRelevanceContext, MemoryScope, MemoryStore, ScoredEntry } from '../types/memory.js';
-import type { EventBus } from '../kernel/events.js';
-import type { WstackPaths } from '../utils/wstack-paths.js';
-import { type MemoryBackend } from './memory-backend.js';
-export interface MemoryStoreOptions {
-    paths: WstackPaths;
-    /**
-     * Optional event bus — when provided, mutations emit events so plugins
-     * and other subsystems can react to memory changes.
-     */
-    events?: EventBus | undefined;
-    /**
-     * Storage backend. Defaults to FileMemoryBackend when omitted.
-     * Plugins can register a custom backend (graph, semantic, vector)
-     * via the DI container to override storage behavior.
-     */
-    backend?: MemoryBackend | undefined;
-}
-/**
- * Three scopes:
- *   project-agents → <project>/.wrongstack/AGENTS.md     (committed)
- *   project-memory → ~/.wrongstack/projects/<hash>/memory.md   (per-project agent notes)
- *   user-memory    → ~/.wrongstack/memory.md             (global personal memory)
- */
-export declare class DefaultMemoryStore implements MemoryStore {
-    private readonly files;
-    private readonly events?;
-    private traceId?;
-    private readonly backend;
-    /**
-     * Per-scope serialization queue. `remember` / `forget` / `consolidate` /
-     * `clear` are read-modify-write against a single file; without a lock,
-     * two concurrent calls on the same scope can read the same baseline and
-     * the later write silently drops the earlier entry. We chain each
-     * mutation onto the prior promise for the same scope so they run in
-     * issue order. Different scopes still proceed in parallel.
-     *
-     * The chain tracks only the last pending write. If a write fails, its
-     * error is caught and swallowed so the chain stays alive for subsequent
-     * calls. The error is stored in `writeErrors` so callers can learn about
-     * it on the next read operation.
-     */
-    private readonly writeChain;
-    /** Last write error per scope — surfaced as warnings on the next readAll(). */
-    private readonly writeErrors;
-    /**
-     * When the global root is a temporary directory (opencode, CI sandboxes),
-     * memory files are also mirrored to the project tree so they survive
-     * session cleanup. The primary path stays in the temp root for isolation;
-     * this backup ensures memory is never lost.
-     */
-    private readonly persistBackup;
-    private readonly backupDir;
-    /**
-     * Per-scope tracked byte sizes — incremented on `remember()`, decremented on
-     * `forget()`, recalculated after `consolidate()`. Eliminates the redundant
-     * readAll() call that previously checked the file size after every write.
-     */
-    private readonly _trackedByteSizes;
-    /** Result cache for scoreRelevant() — keyed by scope + context hash, TTL 30s. */
-    private readonly _scoreCache;
-    /**
-     * Per-entry cached lowercase strings — lazily allocated once and reused
-     * across scoreRelevant() calls so repeated scoring of the same entries skips
-     * re-lowercasing. Keyed by entry object identity; cleared (set to null) on
-     * every mutation (remember/forget/consolidate/clear) via invalidateScoreCaches().
-     */
-    private _cachedLower;
-    constructor(opts: MemoryStoreOptions);
-    /** Expose the backend for plugin introspection and advanced queries. */
-    getBackend(): MemoryBackend;
-    private runSerialized;
-    /**
-     * Recalculate the tracked byte size for a scope by re-reading the file and
-     * summing the serialized byte length of each line. Called after consolidate()
-     * (which modifies the file) to keep the tracker accurate.
-     */
-    private _recalcTrackedByteSize;
-    readAll(): Promise<string>;
-    read(scope: MemoryScope): Promise<string>;
-    /**
-     * List entries from a scope, newest first. Delegates to the backend
-     * so graph/semantic backends can return enriched or filtered results.
-     */
-    list(scope?: MemoryScope, limit?: number): Promise<MemoryEntry[]>;
-    /**
-     * Find memories related to the given text via graph traversal.
-     * Falls back to content search when no graph backend is available.
-     */
-    findRelated(text: string, scope?: MemoryScope, limit?: number): Promise<MemoryEntry[]>;
-    search(query: string, scope?: MemoryScope, limit?: number): Promise<MemoryEntry[]>;
-    remember(text: string, scope?: MemoryScope, metadata?: Omit<Partial<MemoryEntry>, 'scope' | 'text' | 'ts'>): Promise<void>;
-    /**
-     * Drop the relevance caches after a mutation. Both the per-context score
-     * cache and the per-entry lowercase cache are keyed on entry objects that a
-     * mutation invalidates, so they must be cleared together when entries change.
-     */
-    private invalidateScoreCaches;
-    /**
-     * Score and rank memories by relevance to the current context.
-     * Returns entries with score >= MIN_RELEVANCE_SCORE, sorted highest first.
-     */
-    scoreRelevant(ctx: MemoryRelevanceContext, scope?: MemoryScope, limit?: number): Promise<ScoredEntry[]>;
-    forget(query: string, scope?: MemoryScope): Promise<number>;
-    consolidate(scope: MemoryScope): Promise<void>;
-    clear(scope?: MemoryScope): Promise<void>;
-    /**
-     * Return a new MemoryStore proxy that carries `traceId` on every storage
-     * event. The original store is left unchanged — callers that need a
-     * trace-decorated view (e.g. session-run tools) receive the proxy while
-     * the singleton remains trace-free for boot-time use.
-     *
-     * The proxy implements the full `MemoryStore` interface; all other
-     * properties (backend, etc.) are delegated to the original store.
-     */
-    withTraceId(traceId: string): MemoryStore;
-    private mirrorBackup;
-}
-//# sourceMappingURL=memory-store.d.ts.map

package/dist/storage/memory-store.d.ts.map

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