@wrongstack/core 0.313.0 → 0.316.1

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

@@ -1,11 +1,14 @@
-import type { MailboxMessageType } from './mailbox-type-properties.js';
 import type { MailboxAudience, MailboxMessage, MailboxSessionAffinity, MailboxTaskContext } from './mailbox-message-types.js';
-export { MAILBOX_TYPE_PROPERTIES, type MailboxMessageType, type MailboxTypeCategory, } from './mailbox-type-properties.js';
-export { expandMailboxCapabilities, hasMailboxCapability, MAILBOX_CAPABILITY_IMPLICATIONS, type MailboxActorContext, type MailboxAuthMode, type MailboxCapability, type MailboxPrincipalKind, } from './mailbox-auth-types.js';
-export { isActionRequiredForActor, isMailboxLeader, isMailboxMessageVisibleTo, isMailboxReceiptRecordV2, isMailboxSenderInFamily, mailboxIdentityBase, normalizeRecipient, SESSION_RECIPIENT_PREFIX, sessionRecipient, validateSendType, } from './mailbox-predicates.js';
+import type { MailboxMessageType } from './mailbox-type-properties.js';
 import type { MailboxSessionAffinityContext } from './mailbox-session-sync.js';
-export { acceptMailboxMessageForSession, acceptMailboxMessageForSessionSync, type MailboxSessionAffinityContext, } from './mailbox-session-sync.js';
-export { type ActorMailboxMessage, type MailboxAudience, type MailboxLegacyReportSessionAffinity, type MailboxMessage, type MailboxReceiptRecordV2, type MailboxScopedSessionAffinity, type MailboxSessionAffinity, type MailboxTaskContext, type ReadReceipts, } from './mailbox-message-types.js';
+export type { MailboxActorContext, MailboxAuthMode, MailboxCapability, MailboxPrincipalKind, } from './mailbox-auth-types.js';
+export { expandMailboxCapabilities, hasMailboxCapability, MAILBOX_CAPABILITY_IMPLICATIONS } from './mailbox-auth-types.js';
+export { isActionRequiredForActor, isMailboxLeader, isMailboxMessageVisibleTo, isMailboxReceiptRecordV2, isMailboxSenderInFamily, mailboxIdentityBase, normalizeRecipient, SESSION_RECIPIENT_PREFIX, sessionRecipient, validateSendType, } from './mailbox-predicates.js';
+export type { MailboxMessageType } from './mailbox-type-properties.js';
+export { MAILBOX_TYPE_PROPERTIES } from './mailbox-type-properties.js';
+export type { MailboxSessionAffinityContext } from './mailbox-session-sync.js';
+export type { ActorMailboxMessage, MailboxAudience, MailboxLegacyReportSessionAffinity, MailboxMessage, MailboxReceiptRecordV2, MailboxScopedSessionAffinity, MailboxSessionAffinity, MailboxTaskContext, ReadReceipts, } from './mailbox-message-types.js';
+export { acceptMailboxMessageForSession, acceptMailboxMessageForSessionSync } from './mailbox-session-sync.js';
 export interface RegisteredAgent {
     agentId: string;
     sessionId: string;
@@ -145,6 +148,21 @@ export interface AgentHeartbeatInput {
     currentTask?: string | undefined;
     iterations?: number | undefined;
     toolCalls?: number | undefined;
+    /**
+     * Identity fields, carried so a heartbeat can REBUILD a pruned row.
+     *
+     * A registry row is deleted once it is older than AGENT_STALE_MS — either by
+     * the agent's own prune or by any observer calling getAgentStatuses(). Without
+     * these, `heartbeat` can only refresh a row that still exists, so a live agent
+     * that lost its row stays invisible forever (it never calls registerAgent
+     * again). They are optional to keep the RPC wire-compatible: a caller that
+     * omits them gets the previous refresh-only behavior.
+     */
+    sessionId?: string | undefined;
+    name?: string | undefined;
+    role?: string | undefined;
+    pid?: number | undefined;
+    source?: 'cli' | 'webui' | 'mcp' | 'acp' | 'http' | undefined;
 }
 export interface PurgeOptions {
     completedMaxAgeMs?: number | undefined;

package/dist/coordination/model-tier-leader.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Leader tier self-switching policy.
+ *
+ * The leader may notice mid-session that it is doing cheap work on an
+ * expensive model (or the reverse) and want to move itself to another tier.
+ * That is genuinely useful and genuinely dangerous, so every decision goes
+ * through the pure guards in this module.
+ *
+ * Why guards at all — a tier switch is NOT free:
+ *
+ *   1. It invalidates the provider prompt cache. The next turn re-reads the
+ *      whole conversation at full input price on the new model. A switch that
+ *      saves $0.002/turn but costs $0.40 to re-warm is a loss, and a switch
+ *      that happens every time a heuristic wobbles across a threshold is a
+ *      permanent tax. Hence {@link ModelTierLeaderConfig.dwellTurns} and the
+ *      break-even test.
+ *   2. A downgrade can land on a model with a SMALLER context window. If the
+ *      conversation already exceeds it, the session is stranded. Hence the
+ *      context-fill gate.
+ *   3. Spending authority belongs to the user. The leader may never raise
+ *      itself above `maxTier`, and in the default 'propose' mode it may not
+ *      switch at all without a human accepting.
+ *
+ * Everything here is pure: prices, window sizes and turn counts are injected,
+ * so the policy is unit-testable and holds no I/O or layer dependencies.
+ */
+import type { Config, ModelTierLeaderMode } from '../types/config.js';
+/** Per-1M-token prices and window for one model, as published by models.dev. */
+export interface TierModelEconomics {
+    /** USD per 1M uncached input tokens. */
+    inputPerMTok?: number | undefined;
+    /** USD per 1M output tokens. */
+    outputPerMTok?: number | undefined;
+    /** USD per 1M cache-read input tokens. */
+    cacheReadPerMTok?: number | undefined;
+    /** USD per 1M cache-write input tokens. */
+    cacheWritePerMTok?: number | undefined;
+    /** Context window in tokens. */
+    maxContext?: number | undefined;
+}
+export interface LeaderTierSwitchRequest {
+    /** Tier the leader is on now (undefined when it has never been set). */
+    fromTier?: string | undefined;
+    /** Tier the leader wants to move to. */
+    toTier: string;
+    /** Current conversation size in tokens — what a switch would have to re-read. */
+    contextTokens: number;
+    /** Turns elapsed since the last tier switch. Large when there has been none. */
+    turnsSinceSwitch: number;
+    /** Economics of the current and target models. */
+    economics: {
+        from: TierModelEconomics;
+        to: TierModelEconomics;
+    };
+    /**
+     * How many further turns to amortize the re-warm cost over. Defaults to the
+     * configured `dwellTurns`, which is the minimum the session is committed to
+     * staying on the new tier anyway — deliberately conservative.
+     */
+    projectedTurns?: number | undefined;
+}
+export type LeaderTierRefusalCode = 'disabled' | 'same-tier' | 'unknown-tier' | 'dwell' | 'context-window' | 'ceiling' | 'not-worth-it';
+export interface LeaderTierEconomicsSummary {
+    /** One-off cost of re-reading the context on the target model. */
+    reWarmCostUsd: number;
+    /** Per-turn context cost on the current model. */
+    stayCostPerTurnUsd: number;
+    /** Per-turn context cost on the target model. */
+    switchCostPerTurnUsd: number;
+    /** Net saving over `projectedTurns`, after paying the re-warm cost. */
+    projectedSavingsUsd: number;
+    /** True when the target is cheaper per input token than the current model. */
+    isDowngrade: boolean;
+}
+export type LeaderTierVerdict = {
+    allowed: true;
+    /** 'auto' means apply now; 'propose' means ask a human first. */
+    mode: Extract<ModelTierLeaderMode, 'auto' | 'propose'>;
+    economics: LeaderTierEconomicsSummary;
+    reason: string;
+} | {
+    allowed: false;
+    code: LeaderTierRefusalCode;
+    economics?: LeaderTierEconomicsSummary | undefined;
+    reason: string;
+};
+/** The leader policy with every default resolved to a concrete value. */
+export interface ResolvedLeaderTierPolicy {
+    mode: ModelTierLeaderMode;
+    dwellTurns: number;
+    minSavingsUsd: number;
+    maxContextFillForSwitch: number;
+    maxTier?: string | undefined;
+}
+/** Read the leader policy with defaults applied. */
+export declare function leaderTierPolicy(config: Config): ResolvedLeaderTierPolicy;
+/**
+ * Rank of a tier within the configured ladder. Config declaration order IS the
+ * ladder — the first declared level is the cheapest rung. Ranking by name would
+ * mean guessing at user-defined level names, and ranking by live price would
+ * make a ceiling flip whenever a provider changed its price list.
+ */
+export declare function tierRank(config: Config, tier: string | undefined): number;
+/**
+ * Cost model for the switch.
+ *
+ * `contextTokens` is the quantity that actually matters: it is re-read on every
+ * turn, cached on the current model and uncached on the first turn of the new
+ * one. Output tokens are not modeled — they do not change with the switch
+ * decision and would only add noise to the comparison.
+ */
+export declare function evaluateSwitchEconomics(request: LeaderTierSwitchRequest, projectedTurns: number): LeaderTierEconomicsSummary;
+/**
+ * The full decision. Returns whether the switch may happen, and — in 'propose'
+ * mode — that a human has to accept it first.
+ *
+ * Guard order is deliberate: the cheap structural checks run before the
+ * economics, so a refusal reason is always the most fundamental one rather than
+ * whichever gate happened to be evaluated first.
+ */
+export declare function evaluateLeaderTierSwitch(config: Config, request: LeaderTierSwitchRequest): LeaderTierVerdict;
+//# sourceMappingURL=model-tier-leader.d.ts.map

package/dist/coordination/model-tier.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Model tier resolution — the deterministic "how expensive should this job be?"
+ * layer that sits on top of the existing fallback-profile and model-matrix
+ * primitives.
+ *
+ * A tier binds three things that were previously configured independently:
+ *
+ *   fallbackProfile  →  which models, in what failover order
+ *   budget           →  maxCostUsd / maxIterations / maxToolCalls / timeoutMs
+ *   modelRuntime     →  reasoning effort, cache ttl, generation params
+ *
+ * Everything here is deterministic: no LLM call, no scoring, no heuristic over
+ * task text. A tier is chosen by an explicit argument, or by a table lookup
+ * with the SAME precedence the model matrix already uses (exact role → the
+ * role's phase → the `*` default). That precedence is deliberately identical so
+ * a reader only has to learn one rule for both tables.
+ *
+ * Fail-safe by construction: an unconfigured or unknown tier resolves to
+ * `undefined` rather than to an invented model id, and callers then fall
+ * through to their existing behavior (matrix → session). A tier can only ever
+ * ADD a decision the config actually expresses.
+ */
+import type { Config, ModelTierLevel, ModelTiersConfig } from '../types/config.js';
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { ResolvedModelTarget } from './model-matrix.js';
+/** Fallback default when the config names no default tier. */
+export declare const DEFAULT_TIER_ID = "standard";
+/** Where a tier decision came from. Mirrors `ModelMatrixResolutionSource`. */
+export type ModelTierSource = 'explicit' | 'role' | 'phase' | 'default' | 'config-default';
+export interface ModelTierDecision {
+    /** The chosen tier id. */
+    tier: string;
+    /** Which rung of the ladder produced it. */
+    source: ModelTierSource;
+    /** The routing key that matched, when the decision came from the table. */
+    key?: string | undefined;
+    /** True when the tier id has a configured level backing it. */
+    configured: boolean;
+}
+export interface ModelTierBudget {
+    maxCostUsd?: number | undefined;
+    maxIterations?: number | undefined;
+    maxToolCalls?: number | undefined;
+    maxTokens?: number | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface ResolvedTierTarget extends ResolvedModelTarget {
+    tier: string;
+    source: ModelTierSource;
+    /** Budget fields declared by the level, if any. */
+    budget: ModelTierBudget;
+}
+/** The tier config, normalized. Returns undefined when the layer is off. */
+export declare function activeTierConfig(config: Config): ModelTiersConfig | undefined;
+/** All configured level ids, in config order. Empty when the layer is off. */
+export declare function listTierIds(config: Config): string[];
+/** The configured level for a tier id, or undefined. */
+export declare function tierLevel(config: Config, tier: string | undefined): ModelTierLevel | undefined;
+/** True when `tier` names a level this config actually defines. */
+export declare function isConfiguredTier(config: Config, tier: string | undefined): boolean;
+/**
+ * Deterministic tier ladder.
+ *
+ *   1. `explicit`  — the tool/task/caller named a tier outright.
+ *   2. `role`      — routing[<roster role>].
+ *   3. `phase`     — routing[<the role's phase>].
+ *   4. `default`   — the routing table's `*` entry.
+ *   5. config default (`modelTiers.default`), else {@link DEFAULT_TIER_ID}.
+ *
+ * An explicit tier naming no configured level is still returned (with
+ * `configured: false`) rather than silently rewritten — callers surface it as
+ * an error instead of quietly running the job at the wrong expense.
+ */
+export declare function classifyTier(config: Config, input?: {
+    role?: string | undefined;
+    tier?: string | undefined;
+}): ModelTierDecision | undefined;
+/** Extract only the budget fields a level declares. */
+export declare function tierBudget(level: ModelTierLevel | undefined): ModelTierBudget;
+/**
+ * Expand a level into a concrete model target by reusing the model-matrix
+ * expander. A level IS a matrix entry plus a budget, so the profile-as-primary
+ * semantics (chain[0] primary, remainder failover) come for free and stay
+ * identical between the two tables.
+ */
+export declare function tierModelTarget(config: Config, level: ModelTierLevel | undefined): ResolvedModelTarget | undefined;
+/**
+ * Full resolution: classify, then expand. Returns undefined when the layer is
+ * off or the chosen tier has no configured level — in both cases the caller
+ * keeps whatever it already resolved.
+ */
+export declare function resolveTier(config: Config, input?: {
+    role?: string | undefined;
+    tier?: string | undefined;
+}): ResolvedTierTarget | undefined;
+/**
+ * Apply a resolved tier to a subagent config.
+ *
+ * Model fields are FILL-ONLY: an explicit `delegate({ model })` or a `/setmodel`
+ * role pin is a decision the user already made, and a tier is only a default.
+ *
+ * Spend budgets are different, and getting this wrong makes the whole feature
+ * pointless. By the time a spawn reaches here, `applyRosterBudget` /
+ * `instantiateRosterConfig` have ALREADY populated every budget field with the
+ * role's generous default — so a fill-only rule would mean a 'budget' tier
+ * changes the model but never the spend ceiling, which is not a budget at all.
+ * The rule is therefore:
+ *
+ *   - caller-pinned (`cfg.budgetPins`) → never touched; a number the user typed wins.
+ *   - unset                            → set from the tier.
+ *   - set by a roster/generic default  → TIGHTENED to the tier value (min), never raised.
+ *
+ * Tightening only, never raising: a tier must not be able to silently grant a
+ * worker more money than its role was designed to spend.
+ *
+ * `timeoutMs` is excluded from tightening on purpose. Clamping a wall-clock
+ * budget down is the exact shape of the bug that once capped 10-hour roster
+ * agents at ~4 minutes, and a cost label is not a good reason to kill a
+ * long-running job mid-flight. It stays fill-only.
+ */
+export declare function applyTierToSubagentConfig(cfg: SubagentConfig, resolved: ResolvedTierTarget | undefined): void;
+//# sourceMappingURL=model-tier.d.ts.map

package/dist/coordination/multi-agent-coordinator.d.ts

@@ -53,6 +53,30 @@ export declare class DefaultMultiAgentCoordinator extends EventEmitter implement
     private readonly terminating;
     constructor(config: MultiAgentConfig, options?: MultiAgentCoordinatorOptions);
     private currentSessionId;
+    /**
+     * The session that owns a subagent — its spawn-time stamp.
+     *
+     * Every per-subagent emission routes through here instead of
+     * `currentSessionId()`. The fallback covers ids the coordinator never
+     * spawned (a caller reporting `completeTask` for an unknown worker); a
+     * subagent this coordinator created always has its own stamp.
+     */
+    sessionOf(subagentId: string): string;
+    /** Every subagent this coordinator holds for one session. */
+    subagentIdsForSession(sessionId: string): string[];
+    /**
+     * Stop every subagent belonging to ONE session, and drop that session's
+     * still-queued tasks.
+     *
+     * This is what a tab's Stop button needs. `stopAll()` is the wrong tool with
+     * four tabs live — it would kill three other tabs' work — and until subagents
+     * carried a session stamp there was no way to express the narrower intent, so
+     * stopping a run left its workers grinding on in the background.
+     *
+     * Pending tasks pinned to those subagents are drained as aborted so anything
+     * awaiting them (the delegate tool, report-back) resolves instead of hanging.
+     */
+    stopSession(sessionId: string): Promise<void>;
     /**
      * Replace the runner after construction. Used when the runner depends
      * on infrastructure (e.g. FleetBus) that isn't available until after

package/dist/coordination/origin-session.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `callerSessionId` — which conversation is asking?
+ *
+ * Spawning tools run inside the caller's `Context`, and the answer they need
+ * is the run-pinned session: with several tabs sharing one process, the host's
+ * own writer names the session it booted with, not the one that just called
+ * `delegate`. The pinned id is set for the whole run (see `Agent.run`), so it
+ * survives a tab switch mid-run — which the live reading does not.
+ *
+ * The parameter is typed loosely on purpose: tool `execute` receives an opaque
+ * context, and a few hosts pass partial stand-ins.
+ *
+ * @module origin-session
+ */
+export declare function callerSessionId(ctx: unknown, fallback?: string): string | undefined;
+//# sourceMappingURL=origin-session.d.ts.map

package/dist/coordination/provider-status-tracker.d.ts

@@ -22,9 +22,12 @@
  *   | Metric | Threshold | Action |
  *   |--------|-----------|--------|
  *   | consecutive failures ≥ 2 | → `degraded` for 30 s |
- *   | rate-limit hits ≥ 1 | → `blocked` for 5 min |
- *   | consecutive failures ≥ 5 | → `blocked` for 5 min |
- *   | success streak ≥ 3 | → back to `healthy` |
+ *   | rate-limit hits ≥ 1 | → `blocked` for 2 min |
+ *   | consecutive failures ≥ 5 | → `blocked` for 2 min |
+ *   | quota exhaustion (1st) | → `blocked` for 15 min |
+ *   | quota exhaustion (repeat) | → `blocked` 30 min, then capped at 1 h |
+ *   | quota reset time published | → `blocked` until exactly that time |
+ *   | success streak ≥ 3 | → back to `healthy` (also resets quota escalation) |
  *   | `blocked` timeout elapses | → back to `healthy` |
  *
  * - **Error history**: keeps the last N errors per pair, with session id,
@@ -98,16 +101,28 @@ export interface ProviderStatusTrackerConfig {
      */
     blockAfterFailures?: number;
     /**
-     * Duration (ms) the provider stays `blocked`. Default: 300_000 (5 min).
+     * Duration (ms) the provider stays `blocked` for ordinary failures
+     * (rate-limit threshold, consecutive-failure threshold). These are
+     * transient — short cooldowns re-probe quickly instead of parking a
+     * recoverable model for minutes. Default: 120_000 (2 min).
      */
     blockDurationMs?: number;
     /**
-     * Cooldown for an explicit exhausted-credit/quota response when the
+     * Cooldown for the FIRST exhausted-credit/quota response when the
      * provider does not publish a reset hint. These failures enter the waiting
      * room immediately instead of consuming the ordinary rate-limit threshold.
+     * Repeated quota blocks escalate via {@link quotaBlockEscalationMs}.
      * Default: 900_000 (15 min).
      */
     quotaBlockDurationMs?: number;
+    /**
+     * Escalating cooldowns (ms) for REPEATED quota blocks: each time a quota
+     * block expires and the next result is quota-exhausted again, the next
+     * tier applies; the last entry caps the escalation. A recorded success
+     * (or manual unblock/clear) resets the ladder. Default:
+     * [1_800_000, 3_600_000] — 2nd block 30 min, 3rd+ blocks 1 h max.
+     */
+    quotaBlockEscalationMs?: number[];
     /**
      * Consecutive successes needed to leave `degraded` or `blocked` and return
      * to `healthy` (if the timeout hasn't already cleared it). Default: 3.
@@ -159,6 +174,14 @@ export declare class ProviderModelStatusTracker {
         agentId?: string | undefined;
         retryAfterMs?: number | undefined;
     }): ProviderModelState;
+    /**
+     * Quarantine fan-out expiry: the fixed quota cooldown, never the
+     * hint-extended trigger expiry. A weekly-cap reset time applies to the
+     * model that published it; sibling models (and unseen pairs behind the
+     * provider-wide gate) re-open after the base cooldown so one misclassified
+     * or hint-stretched failure cannot silence a whole provider for hours.
+     */
+    private fanOutExpiryFor;
     /**
      * Mark every other tracked pair on the same provider as blocked with the
      * same expiry as the triggering pair. Only pairs already known to the
@@ -173,6 +196,10 @@ export declare class ProviderModelStatusTracker {
      * kind is `auth` (no point retrying ever).
      */
     isAvailable(providerId: string, model: string): boolean;
+    /**
+     * Manually unblock/reset a provider/model pair (e.g. after a manual model switch or key update).
+     */
+    unblock(providerId: string, model: string): void;
     /**
      * Check if a (providerId, model) pair is currently rate-limited.
      * This is a stronger signal than just `!isAvailable()` — it tells
@@ -201,6 +228,8 @@ export declare class ProviderModelStatusTracker {
     /**
      * Release one entry for an immediate half-open probe on its next real use.
      * History and totals are retained so operators do not lose diagnostics.
+     * The quota escalation streak is also retained on purpose: a probe that
+     * fails with quota exhaustion again keeps climbing the ladder.
      */
     retryNow(providerId: string, model: string): boolean;
     /**
@@ -244,6 +273,13 @@ export declare class ProviderModelStatusTracker {
     getSnapshot(): ProviderStatusSnapshot;
     /** Restore non-expired waiting-room entries from a previous process. */
     restoreSnapshot(value: unknown): number;
+    /**
+     * Cooldown for the Nth consecutive quota block: the base duration for the
+     * first block, then the escalation ladder for repeats, capped at the last
+     * ladder entry. A provider-published reset hint bypasses this entirely
+     * (the pair is closed until that exact time instead).
+     */
+    private quotaBlockDurationForStreak;
     private getOrCreate;
     private freezeStatus;
     private emitStatusChanged;

package/dist/coordination/session-note-hub.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SessionNoteHub — in-process, same-session delivery for agent notes.
+ *
+ * Mailbox is the durable, cross-session letter. This hub is the live talk
+ * channel: register an inbox per running agent, post a note, the recipient
+ * folds it at its next iteration. Fail-closed on session id. No disk, no
+ * capability.mail, no wait.
+ *
+ * @module session-note-hub
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { SessionNote, SessionNoteKind } from '../core/session-notes.js';
+export interface SessionNotePost {
+    sessionId: string;
+    from: string;
+    /** `leader`, a live agent id, `@session`, or `*` (session-local broadcast). */
+    to: string;
+    kind: SessionNoteKind;
+    body: string;
+    subject?: string | undefined;
+    /** Observability bus (typically the leader/session bus). */
+    events?: EventBus | undefined;
+}
+export interface SessionNoteInbox {
+    sessionId: string | (() => string | undefined);
+    agentId: string;
+    aliases?: readonly string[] | undefined;
+    deliver: (note: SessionNote) => void;
+    /** First bus registered for a session is used to emit `session.note`. */
+    events?: EventBus | undefined;
+}
+export interface SessionNotePostResult {
+    delivered: number;
+}
+export declare class SessionNoteHub {
+    private readonly inboxes;
+    private readonly buses;
+    register(inbox: SessionNoteInbox): () => void;
+    post(input: SessionNotePost): SessionNotePostResult;
+}
+/** Process-wide hub. Agent loops register; tools and hosts post. */
+export declare const sessionNoteHub: SessionNoteHub;
+export declare function postSessionNote(input: SessionNotePost): SessionNotePostResult;
+//# sourceMappingURL=session-note-hub.d.ts.map

package/dist/coordination/session-note-tool.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `session_note` — same-session, in-process talk between the leader and
+ * live agents. Not mailbox: nothing is persisted, other sessions never
+ * see it, and `coordination.mail` is not required.
+ *
+ * @module session-note-tool
+ */
+import type { Tool } from '../types/tool.js';
+export declare function makeSessionNoteTool(): Tool;
+//# sourceMappingURL=session-note-tool.d.ts.map

package/dist/core/agent.d.ts

@@ -14,7 +14,7 @@ import type { Tool } from '../types/tool.js';
 import type { ToolExecutorLike } from '../types/tool-executor.js';
 import { type AgentInit, type AgentInput, type AgentPipelines, type ResolvedLoopDetectionConfig, type RunResult } from './agent-types.js';
 import type { Context, RunOptions } from './context.js';
-export { type AgentInit, type AgentInput, type AgentPipelines, createDefaultPipelines, DEFAULT_MAX_ITERATIONS, normalizeInput, type ResolvedLoopDetectionConfig, type RunResult, resolveLoopDetection, type ToolCallPipelinePayload, type UserInputPayload, } from './agent-types.js';
+export { type AgentInit, type AgentInput, type AgentPipelines, createDefaultPipelines, DEFAULT_MAX_ITERATIONS, normalizeInput, type ResolvedLoopDetectionConfig, resolveLoopDetection, type RunResult, type ToolCallPipelinePayload, type UserInputPayload, } from './agent-types.js';
 export declare class Agent {
     readonly container: Container;
     readonly tools: ToolRegistry;
@@ -48,8 +48,21 @@ export declare class Agent {
      * conversation or racing abort signals.
      */
     private _runInProgress;
-    /** SHA-256 of the last submitted input content — prevents duplicate runs. */
+    /**
+     * Dedup window for byte-identical consecutive inputs. Only accidental
+     * back-to-back duplicates fall inside it — terminal \r\n re-entrancy,
+     * stuck-key bursts, client auto-resubmit loops. A deliberate re-send later
+     * (the classic "continue" nudge after a model switch, or retyping the same
+     * instruction after a failed run) must always execute.
+     */
+    static readonly INPUT_DEDUP_WINDOW_MS = 1500;
+    /**
+     * SHA-256 + submission time of the last committed input content. The pair
+     * powers burst-only dedup: identical text skips a run solely when it lands
+     * within {@link Agent.INPUT_DEDUP_WINDOW_MS} of the previous submission.
+     */
     private _lastInputHash;
+    private _lastInputHashAt;
     constructor(init: AgentInit);
     get logger(): Logger;
     get retry(): RetryPolicy;

package/dist/core/context.d.ts

@@ -1,15 +1,14 @@
 import type { TextBlock } from '../types/blocks.js';
+import type { AgentContext, ContextMessageLimits, TodoItem } from '../types/context.js';
 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 { RunEnv } from '../types/run-env.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 { TodoItem } from '../types/context.js';
 export type { TodoItem };
 export interface RunOptions {
     signal?: AbortSignal | undefined;
@@ -321,9 +320,11 @@ export declare class Context implements RunEnv, AgentContext {
         event: SessionEvent;
         bytes: number;
         writer: SessionWriter;
+        attempts?: number;
     }>;
     _conversationJournalBytes: number;
     _conversationJournalDrain: Promise<void> | null;
+    _conversationJournalLastError: Error | null;
     private static readonly CONVERSATION_JOURNAL_MAX_EVENTS;
     private static readonly CONVERSATION_JOURNAL_MAX_BYTES;
     private static readonly MAX_FILE_EVENTS;
@@ -500,4 +501,22 @@ export declare class Context implements RunEnv, AgentContext {
  * `session` may be missing despite the non-optional type.
  */
 export declare function resolveEventSessionId(ctx: AgentContext): string;
+/**
+ * Session that OWNS this agent — the conversation a surface is showing.
+ *
+ * Different question from {@link resolveEventSessionId}, which answers "where
+ * do this run's journal events go". A subagent spawned with `sessionsRoot`
+ * configured (the real CLI always configures it) is handed its own journal, so
+ * both `ctx.session.id` and the run-pinned id name a private transcript that no
+ * tab is subscribed to. Anything routed BETWEEN agents of one conversation —
+ * mailbox identity and registration, `@session` recipient normalisation,
+ * `session_note` inboxes — has to key off the spawning conversation instead, or
+ * a worker's report reaches nobody.
+ *
+ * `meta.sessionId` is that spawn-time stamp, fixed for the worker's lifetime
+ * (deliberately not a live read of the host's session, which moves whenever the
+ * user switches tabs). Leaders carry no stamp and fall through to the event id,
+ * which for them is the same session and follows resume / session.new.
+ */
+export declare function resolveOwningSessionId(ctx: AgentContext): string;
 //# sourceMappingURL=context.d.ts.map

package/dist/core/index.d.ts

@@ -1,6 +1,7 @@
 export { Agent, type RunResult, type UserInputPayload, } from './agent.js';
 export { type AgentInit, type AgentInput, type AgentPipelines, createDefaultPipelines, type ToolCallPipelinePayload, } from './agent-types.js';
 export { buildBtwBlock, consumeBtwNotes, pendingBtwCount, setBtwNote, } from './btw.js';
+export { buildSessionNoteBlock, consumeSessionNotes, enqueueSessionNote, pendingSessionNoteCount, type SessionNote, type SessionNoteKind, } from './session-notes.js';
 export { Context, type ContextInit, type ProviderMemoryEvidence, type RunOptions, type TodoItem, } from './context.js';
 export { type ContinuationInput, type ContinuationSource, detectContinueIntent, type ResolvedContinuation, resolveContinuation, } from './continue-intent.js';
 export { ConversationState, type ReadonlyConversationState, type StateChange, type StateChangeHandler, wrapAsState, } from './conversation-state.js';
@@ -16,4 +17,5 @@ export { runProviderWithRetry } from './provider-runner.js';
 export { setQueuedMessagesSnapshot } from './queued-messages.js';
 export { buildIdentityLayer, DefaultSystemPromptBuilder, type DefaultSystemPromptBuilderOptions, type SystemBlockSource, } from './system-prompt-builder.js';
 export { type DomainGlossaryOptions, renderDomainGlossary, } from './system-prompt-glossary.js';
+export { countSystemPromptTokens, isSystemInstructionVariant, persistSystemPromptVariant, readSavedSystemPromptVariant, SYSTEM_PROMPT_VARIANT_OPTIONS, SYSTEM_PROMPT_VARIANTS, type SystemPromptVariantPaths, systemPromptVariantLabel, } from './system-prompt-variants.js';
 //# sourceMappingURL=index.d.ts.map