@wrongstack/core 0.313.1 → 0.316.2

package/dist/coordination/fleet.d.ts

@@ -1,8 +1,3 @@
-/**
- * Pre-built subagent role configurations for the WrongStack fleet.
- * These can be passed to `MultiAgentHost.spawn()` or used as templates
- * for the director's roster.
- */
 import type { SubagentConfig } from '../types/multi-agent.js';
 /**
  * Audit Log Agent — analyzes session logs, event streams, and traces.
@@ -24,12 +19,26 @@ export declare const REFACTOR_PLANNER_AGENT: SubagentConfig;
  * Use for: CI checks, pre-release audits, dependency vulnerability scanning.
  */
 export declare const SECURITY_SCANNER_AGENT: SubagentConfig;
+/**
+ * Read-only discovery surface for the Explore Companion.
+ *
+ * Index tools first (the point of the role: save the leader those calls).
+ * `codebase-impact-analysis` is read-only blast radius — the leader is about
+ * to edit; the companion should say who breaks. File tools are fallbacks
+ * when the index is cold or the probe needs a cited `file:line`.
+ *
+ * Deliberately omitted from `TOOLS.read`:
+ *   - `search` — web search, not codebase search
+ *   - `mailbox` — cross-session mail; same-session talk is `session_note`
+ *     (injected by the host, like `submit_result`)
+ */
+export declare const EXPLORE_COMPANION_TOOLS: readonly string[];
 /**
  * Explore Companion — state-triggered background codebase explorer.
  * Runs behind a leader agent: triggered by the in-progress state of the
  * work (unread-file edits, zero-hit searches, todo flips, explicit asks),
- * scans the codebase read-only, and feeds findings back via mailbox
- * `result`/`btw` + `submit_result`. See
+ * scans the codebase read-only, and feeds findings back via `submit_result`
+ * (the host mails a compact copy to the leader). See
  * docs/architecture/explore-companion-subagent.md.
  *
  * Operational role — deliberately NOT in ALL_AGENT_DEFINITIONS (like

package/dist/coordination/index.d.ts

@@ -28,6 +28,8 @@ export type { ICoordinator } from './icoordinator.js';
 export type { IFleetManager } from './ifleet-manager.js';
 export { LargeAnswerStore } from './large-answer-store.js';
 export { type MailToolsOptions, makeMailInboxTool, makeMailSendTool } from './mail-tools.js';
+export { postSessionNote, SessionNoteHub, sessionNoteHub, type SessionNoteInbox, type SessionNotePost, type SessionNotePostResult, } from './session-note-hub.js';
+export { makeSessionNoteTool } from './session-note-tool.js';
 export type { MailboxActionInput, MailboxActionResult, MailboxMessageAction, } from './mailbox-actions.js';
 export { actionToAckInput } from './mailbox-actions.js';
 export { parseMailboxAckInput, parseMailboxQueryInput, parseMailboxSendInput, } from './mailbox-codecs.js';
@@ -46,6 +48,8 @@ export { applyMailboxSendPolicy, type MailboxResolver, type MailboxToolOptions,
 export type { AgentHeartbeatInput, AgentRegistrationInput, ClientHeartbeatInput, ClientRegistrationInput, ClientSource, ClientStatus, Mailbox, MailboxAckBatchInput, MailboxAckInput, MailboxAgentStatus, MailboxAudience, MailboxMessage, MailboxMessageProjection, MailboxMessageType, MailboxQuery, MailboxRecipientState, MailboxSendInput, MailboxTaskContext, PurgeOptions, PurgeResult, ReadReceipts, RegisteredAgent, } from './mailbox-types.js';
 export { isMailboxLeader, isMailboxMessageVisibleTo, MAILBOX_TYPE_PROPERTIES, mailboxIdentityBase, normalizeRecipient, SESSION_RECIPIENT_PREFIX, sessionRecipient, } from './mailbox-types.js';
 export { isValidMatrixKey, MATRIX_PHASE_KEYS, type MatrixKeyKind, type ModelMatrixResolution, type ModelMatrixResolutionSource, type ModelReference, matrixKeyKind, phaseForRole, type ResolvedModelTarget, type ResolvedSubagentModelTarget, resolveImplementationModelTarget, resolveModelMatrix, resolveModelMatrixResolution, resolveModelTargetFromEntry, resolveSubagentModelTarget, roleNeedsIndependentReviewModel, sameModelReference, } from './model-matrix.js';
+export { activeTierConfig, applyTierToSubagentConfig, classifyTier, DEFAULT_TIER_ID, isConfiguredTier, listTierIds, type ModelTierBudget, type ModelTierDecision, type ModelTierSource, type ResolvedTierTarget, resolveTier, tierBudget, tierLevel, tierModelTarget, } from './model-tier.js';
+export { evaluateLeaderTierSwitch, evaluateSwitchEconomics, type LeaderTierRefusalCode, type LeaderTierSwitchRequest, type LeaderTierVerdict, leaderTierPolicy, type ResolvedLeaderTierPolicy, type TierModelEconomics, tierRank, } from './model-tier-leader.js';
 export { DefaultMultiAgentCoordinator, type MultiAgentCoordinatorOptions, } from './multi-agent-coordinator.js';
 export { NULL_FLEET_BUS } from './null-fleet-bus.js';
 export { detectEcosystem, getFullPackageLog, getManifestPackages, getPackageAuthor, getPackagesByAgent, type PackageAuthorEntry, type PackageAuthorLog, type PackageAuthorTrackerOptions, recordPackageAction, updatePackageOutdatedStatus, } from './package-author-tracker.js';

package/dist/coordination/index.js

@@ -100,6 +100,7 @@ import {
   makeMutationTestTool,
   makeQualityGateTool,
   makeRollUpTool,
+  makeSessionNoteTool,
   makeSpawnTool,
   makeTerminateAllTool,
   makeTerminateTool,
@@ -125,11 +126,20 @@ import {
   updatePackageOutdatedStatus,
   validateWatchdogOptions,
   wrapSubagentRunnerWithWorktrees
-} from "../chunk-FW5LDDMJ.js";
-import "../chunk-UIWONWVG.js";
+} from "../chunk-45WI72ZB.js";
+import "../chunk-NSOFPKGT.js";
 import {
+  DEFAULT_TIER_ID,
   MATRIX_PHASE_KEYS,
+  activeTierConfig,
+  applyTierToSubagentConfig,
+  classifyTier,
+  evaluateLeaderTierSwitch,
+  evaluateSwitchEconomics,
+  isConfiguredTier,
   isValidMatrixKey,
+  leaderTierPolicy,
+  listTierIds,
   matrixKeyKind,
   phaseForRole,
   resolveImplementationModelTarget,
@@ -137,15 +147,21 @@ import {
   resolveModelMatrixResolution,
   resolveModelTargetFromEntry,
   resolveSubagentModelTarget,
+  resolveTier,
   roleNeedsIndependentReviewModel,
-  sameModelReference
-} from "../chunk-2BUUIMQB.js";
+  sameModelReference,
+  tierBudget,
+  tierLevel,
+  tierModelTarget,
+  tierRank
+} from "../chunk-RTOTNK3P.js";
 import {
   MailboxEventEmitter
 } from "../chunk-JX7VBZDK.js";
 import "../chunk-SZ6AYUIZ.js";
-import "../chunk-52RTVH4M.js";
-import "../chunk-E6I5RXVK.js";
+import "../chunk-F3JWNST7.js";
+import "../chunk-JMULFFLN.js";
+import "../chunk-AYW5YINX.js";
 import {
   ACP_AGENTS,
   ALL_FLEET_AGENTS,
@@ -187,7 +203,7 @@ import {
   scoreAgents,
   terminalPolicyDecision,
   withDisabledToolFiltering
-} from "../chunk-T3KGZBU5.js";
+} from "../chunk-S45JPKQN.js";
 import {
   AGENTS_BY_PHASE,
   AGENT_CATALOG,
@@ -281,18 +297,35 @@ import {
   updateProjectAgentLearned,
   updateProjectAgentLearningPolicy,
   validateProjectAgentConfig
-} from "../chunk-FHAMQS7Q.js";
+} from "../chunk-FCBTO76Z.js";
+import "../chunk-J2WRWR37.js";
+import "../chunk-LHOA5DWA.js";
+import "../chunk-LA7CLDRW.js";
+import "../chunk-WAHQVNWT.js";
+import "../chunk-EODDVJBM.js";
+import "../chunk-ZT7JNIGX.js";
+import "../chunk-W5VITDM2.js";
+import "../chunk-YPT4A46F.js";
+import "../chunk-B7F4WVP4.js";
+import "../chunk-WQTOVMGV.js";
+import "../chunk-FNXVT7HF.js";
+import "../chunk-5BMIE7QG.js";
+import "../chunk-DYLPMV4Q.js";
+import "../chunk-5S437PRC.js";
 import {
   MailboxProjectServerConnection,
   RemoteMailbox,
+  SessionNoteHub,
   applyMailboxSendPolicy,
   createProjectMailbox,
   getSharedProjectMailbox,
   isMailboxProjectServerAvailable,
   mailboxSessionTag,
   makeMailboxTool,
-  resolveMailboxIdentity
-} from "../chunk-RD6DEE36.js";
+  postSessionNote,
+  resolveMailboxIdentity,
+  sessionNoteHub
+} from "../chunk-JO4MGB6Z.js";
 import {
   CREDENTIAL_VERIFY_COOLDOWN_MS,
   CREDENTIAL_VERIFY_MAX_FAILURES,
@@ -301,13 +334,13 @@ import {
   credentialVerifyThrottle,
   mailboxProjectServerEndpoint,
   mailboxProjectServerMetadataPath
-} from "../chunk-5RP3QTRL.js";
+} from "../chunk-PQNS3U7Z.js";
 import {
   MAILBOX_MAX_ACK_BATCH,
   MAILBOX_MAX_QUERY_LIMIT,
   redactMailboxCredential,
   resolveProjectDir
-} from "../chunk-GM54GJBU.js";
+} from "../chunk-IRUTEHCE.js";
 import {
   MAILBOX_TYPE_PROPERTIES,
   SESSION_RECIPIENT_PREFIX,
@@ -316,56 +349,42 @@ import {
   mailboxIdentityBase,
   normalizeRecipient,
   sessionRecipient
-} from "../chunk-W4A6QA3D.js";
+} from "../chunk-FWNLEZYG.js";
 import "../chunk-SQJVFEBV.js";
-import "../chunk-H72H4XDU.js";
-import "../chunk-4ZHTKJHM.js";
-import "../chunk-PAAWLLZX.js";
+import "../chunk-U45AXT5D.js";
+import "../chunk-4SJNS7OB.js";
+import "../chunk-Y5YXDM7D.js";
 import "../chunk-HA4ZYA6T.js";
-import "../chunk-A455ATZB.js";
 import "../chunk-WQQON3SV.js";
 import "../chunk-2YU4WVBW.js";
-import "../chunk-H5E77KUJ.js";
-import "../chunk-3E244UDA.js";
-import "../chunk-RJIZEJ42.js";
-import "../chunk-NFAYHPRH.js";
-import "../chunk-TYW2GI5I.js";
-import "../chunk-LHOA5DWA.js";
-import "../chunk-GFJOMSHG.js";
-import "../chunk-QRTG4XTI.js";
-import "../chunk-EODDVJBM.js";
-import "../chunk-CQQL4ZOQ.js";
-import "../chunk-RPOA7IAE.js";
-import "../chunk-FFSX2QDQ.js";
-import "../chunk-DEIQMBD2.js";
-import "../chunk-FNXVT7HF.js";
-import "../chunk-WQTOVMGV.js";
-import "../chunk-AD7ZFZCS.js";
-import "../chunk-KBZGE6LN.js";
-import "../chunk-5S437PRC.js";
-import "../chunk-WZO23AWO.js";
+import "../chunk-QSTSJOCK.js";
+import "../chunk-6FHWXLPT.js";
+import "../chunk-UBGDX6FI.js";
+import "../chunk-M27LIEKV.js";
 import "../chunk-XEBHSJLT.js";
-import "../chunk-VB3H5WWB.js";
-import "../chunk-M2WF6AXG.js";
-import "../chunk-4XV6IR37.js";
+import "../chunk-6NWEVFEL.js";
+import "../chunk-LSMMOS2Z.js";
 import "../chunk-4VWO3ZXL.js";
-import "../chunk-EFEHDQGY.js";
-import "../chunk-AWNQ6ED6.js";
-import "../chunk-FSWCWSTS.js";
+import "../chunk-ZHZ2Y2DH.js";
+import "../chunk-HI3JGZR2.js";
+import "../chunk-HMLIGAU7.js";
 import "../chunk-TRT2HRWZ.js";
 import "../chunk-LX5QWLBL.js";
-import "../chunk-FAYRX2AD.js";
-import "../chunk-7ZHZE5EO.js";
+import "../chunk-POOOIWE5.js";
+import "../chunk-OSGLYW5J.js";
+import "../chunk-FC2ZGRF3.js";
+import "../chunk-THEGTRAG.js";
 import "../chunk-SVT4RNTR.js";
-import "../chunk-WEBMSQP2.js";
-import "../chunk-YNCVSFGF.js";
-import "../chunk-CB2HFKTP.js";
+import "../chunk-SAFHACFA.js";
+import "../chunk-RJIZEJ42.js";
+import "../chunk-3ECENVHL.js";
+import "../chunk-VVBP6KGT.js";
 import "../chunk-KJ2ZTQSL.js";
 import "../chunk-B4AMLZPB.js";
+import "../chunk-PFZO3C6H.js";
 import "../chunk-O37BQ65S.js";
-import "../chunk-WOEZV3Q4.js";
+import "../chunk-25LSLC3G.js";
 import "../chunk-TBRL2RCC.js";
-import "../chunk-PFZO3C6H.js";
 export {
   ACP_AGENTS,
   AGENTS_BY_PHASE,
@@ -411,6 +430,7 @@ export {
   DEFAULT_PROBE_COOLDOWN_MS,
   DEFAULT_QUALITY_CHECKS,
   DEFAULT_SUBAGENT_BASELINE,
+  DEFAULT_TIER_ID,
   DELIVERY_AGENTS,
   DEPENDENCY_FILE_PATTERNS,
   DIRECTIVE_QUARANTINE_MAX_UTILITY,
@@ -481,6 +501,7 @@ export {
   SESSION_RECIPIENT_PREFIX,
   SKILL_AUGMENTATION_MAX_BYTES,
   SUBAGENT_STRUCTURED_REPORT_META_KEY,
+  SessionNoteHub,
   SubagentBudget,
   TIMEOUT_PREEMPT_FRACTION,
   TaskAuctioneer,
@@ -489,9 +510,11 @@ export {
   WorktreeIntegrationError,
   acquireOrJoin,
   actionToAckInput,
+  activeTierConfig,
   applyMailboxSendPolicy,
   applyProjectAgentConfig,
   applyRosterBudget,
+  applyTierToSubagentConfig,
   assertProjectAgentRole,
   assessCommitSafety,
   assignNickname,
@@ -509,6 +532,7 @@ export {
   canCaptureNewLearned,
   captureLearnedFromAgentOutput,
   captureLearnedFromAgentOutputDetailed,
+  classifyTier,
   clearProjectAgentConsolidated,
   clearProjectSkillAugmentation,
   collabInjectMiddleware,
@@ -534,6 +558,8 @@ export {
   directiveWasApplied,
   dispatchAgent,
   evaluateAutoOptimize,
+  evaluateLeaderTierSwitch,
+  evaluateSwitchEconomics,
   finalize,
   formatHumanPrompt,
   formatSubagentStructuredReport,
@@ -545,6 +571,7 @@ export {
   getProjectAgentLearnStats,
   getSharedProjectMailbox,
   hintLearnedNeedsSummarization,
+  isConfiguredTier,
   isConsolidated,
   isMailboxLeader,
   isMailboxMessageVisibleTo,
@@ -553,9 +580,11 @@ export {
   isValidMatrixKey,
   kanbanBoundaryOps,
   kanbanDispatch,
+  leaderTierPolicy,
   listProjectAgentLearnedEntries,
   listProjectAgentRoles,
   listProjectSkillAugmentations,
+  listTierIds,
   loadConsolidationMetadata,
   loadProjectAgentConfig,
   loadProjectAgentConsolidated,
@@ -589,6 +618,7 @@ export {
   makeMutationTestTool,
   makeQualityGateTool,
   makeRollUpTool,
+  makeSessionNoteTool,
   makeSpawnTool,
   makeSubagentResultTool,
   makeTerminateAllTool,
@@ -603,6 +633,7 @@ export {
   parseMailboxSendInput,
   parseTaskBoundary,
   phaseForRole,
+  postSessionNote,
   quarantinePath,
   rankRoleSkills,
   readLiveLock,
@@ -633,6 +664,7 @@ export {
   resolveRoleSkillCandidates,
   resolveSubagentModelTarget,
   resolveSubagentWorktreeDecision,
+  resolveTier,
   retiredDirectivesToWarnAbout,
   roleNeedsIndependentReviewModel,
   rosterSummaryFromConfigs,
@@ -643,6 +675,7 @@ export {
   scoreAgents,
   scoreSkillAffinity,
   scrubRetiredLines,
+  sessionNoteHub,
   sessionRecipient,
   setKanbanBoundaryOps,
   setKanbanDispatch,
@@ -653,6 +686,10 @@ export {
   subagentNeedsWorktree,
   taskBoundarySchemaProperties,
   terminalPolicyDecision,
+  tierBudget,
+  tierLevel,
+  tierModelTarget,
+  tierRank,
   unwrapWholeDocumentFence,
   updatePackageOutdatedStatus,
   updateProjectAgentConfig,

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

@@ -20,8 +20,8 @@ export interface KanbanDispatchPort {
     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>;
+    }, eventContext: KanbanEventContext): Promise<KanbanBoard | null>;
+    heartbeatTaskAssignment(projectRoot: string, boardId: string, taskId: string, input: HeartbeatKanbanTaskAssignmentInput, eventContext: KanbanEventContext): Promise<KanbanBoard | null>;
 }
 /** Composition-root hook: register the real kanban-backed implementation. */
 export declare function setKanbanDispatch(impl: KanbanDispatchPort): void;

package/dist/coordination/mailbox-http-router.d.ts

@@ -1,15 +1,16 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { MailboxEventEmitter } from './mailbox-events.js';
 import type { MailboxCredentialVerifier } from './mailbox-credential-store.js';
+import type { MailboxEventEmitter } from './mailbox-events.js';
 import { type MailboxHttpAccessDecision } from './mailbox-http-auth.js';
+export type { MailboxHttpAccessDecision };
+import type { MailboxHttpRateLimiter } from './mailbox-http-rate-limit.js';
 import { MAILBOX_HTTP_MAX_AGE_CEILING_MS } from './mailbox-http-validation.js';
 import type { Mailbox } from './mailbox-types.js';
-import type { MailboxHttpRateLimiter } from './mailbox-http-rate-limit.js';
 export { MAILBOX_HTTP_RATE_LIMIT_PER_MINUTE, MAILBOX_HTTP_RATE_LIMIT_WINDOW_MS, MailboxHttpRateLimiter, } from './mailbox-http-rate-limit.js';
 export declare const MAILBOX_HTTP_MAX_BODY_BYTES: number;
 export declare const MAILBOX_HTTP_DEFAULT_MAX_AGE_MS: number;
+export { authorizeMailboxBearerToken, authorizePersistedMailboxCredential } from './mailbox-http-auth.js';
 export { MAILBOX_HTTP_MAX_AGE_CEILING_MS };
-export { authorizeMailboxBearerToken, authorizePersistedMailboxCredential, type MailboxHttpAccessDecision, type MailboxHttpCredentialDecision, } from './mailbox-http-auth.js';
 export interface MailboxHttpRouterOptions {
     mailbox: Mailbox;
     eventEmitter?: MailboxEventEmitter;

package/dist/coordination/mailbox-http-validation.d.ts

@@ -47,7 +47,7 @@ export declare function validateCheck(body: unknown, actorId?: string): MailboxC
 export declare function validateAck(body: unknown, actorId?: string): MailboxAckInput;
 export declare function validateAckMany(body: unknown, actorId?: string): MailboxAckBatchInput;
 export declare function validateAgentRegistration(body: unknown, actor?: MailboxActorContext): AgentRegistrationInput;
-export declare function validateAgentHeartbeat(body: unknown, actorId?: string): AgentHeartbeatInput;
+export declare function validateAgentHeartbeat(body: unknown, actor?: MailboxActorContext): AgentHeartbeatInput;
 export declare function validateClientRegistration(body: unknown): ClientRegistrationInput;
 export declare function validateClientHeartbeat(body: unknown): ClientHeartbeatInput;
 //# sourceMappingURL=mailbox-http-validation.d.ts.map

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

@@ -2,9 +2,15 @@
 import {
   MailboxEventEmitter
 } from "../chunk-JX7VBZDK.js";
+import {
+  useDaemonPerfDefaults
+} from "../chunk-FNXVT7HF.js";
+import {
+  startSharedHeapWatchdog
+} from "../chunk-DYLPMV4Q.js";
 import {
   EventBus
-} from "../chunk-4LJJYBAU.js";
+} from "../chunk-FHZVFYSL.js";
 import {
   MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS,
   MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION,
@@ -14,27 +20,21 @@ import {
   isMailboxProjectServerClientMessage,
   mailboxProjectServerEndpoint,
   mailboxProjectServerMetadataPath
-} from "../chunk-5RP3QTRL.js";
+} from "../chunk-PQNS3U7Z.js";
 import {
   redactMailboxCredential
-} from "../chunk-GM54GJBU.js";
-import "../chunk-W4A6QA3D.js";
+} from "../chunk-IRUTEHCE.js";
+import "../chunk-FWNLEZYG.js";
 import {
   restrictFilePermissions
-} from "../chunk-H5E77KUJ.js";
-import {
-  useDaemonPerfDefaults
-} from "../chunk-FNXVT7HF.js";
-import {
-  startSharedHeapWatchdog
-} from "../chunk-KBZGE6LN.js";
+} from "../chunk-6FHWXLPT.js";
 import "../chunk-LX5QWLBL.js";
-import "../chunk-FAYRX2AD.js";
+import "../chunk-POOOIWE5.js";
 import {
   atomicWrite
-} from "../chunk-7ZHZE5EO.js";
-import "../chunk-YNCVSFGF.js";
-import "../chunk-WOEZV3Q4.js";
+} from "../chunk-OSGLYW5J.js";
+import "../chunk-SAFHACFA.js";
+import "../chunk-25LSLC3G.js";
 import "../chunk-TBRL2RCC.js";
 
 // src/coordination/mailbox-project-server.ts

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