@makaio/framework 1.0.0-dev-1783355411417 → 1.0.0-dev-1783477169057

package/dist/{index-BYfSAJRC.d.mts → index-BvTd61i5.d.mts}

@@ -87,6 +87,8 @@ declare class Turn$1 {
   private readonly _agentIds;
   /** Messages sent during this turn */
   private readonly _messageIds;
+  /** Message IDs currently claiming this turn while their storage append is in-flight. */
+  private readonly _pendingMessageAppends;
   /** Agents that have completed successfully */
   private readonly _completedAgents;
   /** Agents that errored (agentId → error message) */
@@ -108,6 +110,11 @@ declare class Turn$1 {
    * @returns Immutable array of message IDs
    */
   get messageIds(): readonly string[];
+  /**
+   * Whether a user message has claimed this turn before its storage append completes.
+   * @returns True when at least one message append is in-flight
+   */
+  get hasPendingMessageAppends(): boolean;
   /**
    * Agents that have completed successfully.
    * @returns Read-only set of completed agent IDs
@@ -123,6 +130,16 @@ declare class Turn$1 {
    * @param messageId - The message ID to add
    */
   addMessage(messageId: string): void;
+  /**
+   * Claim this turn for a message whose durable append has started.
+   * @param messageId - Message ID whose append is in-flight
+   */
+  claimMessageAppend(messageId: string): void;
+  /**
+   * Release a failed message append claim without adding the message.
+   * @param messageId - Message ID whose append failed
+   */
+  releaseMessageAppend(messageId: string): void;
   /**
    * Mark an agent as completed successfully.
    * @param agentId - The agent that completed
@@ -165,6 +182,12 @@ declare class Turn$1 {
    * @returns Turn context with turnId and the specified messageId
    */
   getContextForMessage(messageId: string): TurnContext;
+  /**
+   * Return the recorded terminal outcome for an agent, if any.
+   * @param agentId - Agent ID to inspect.
+   * @returns Terminal outcome already recorded for the agent.
+   */
+  private getAgentTerminalOutcome;
   /**
    * Check if turn should complete and return appropriate state change.
    * @returns State change indicating completion status and result if complete
@@ -216,10 +239,14 @@ declare class SessionTurnManager {
   private readonly bus;
   /** Active turns keyed by sessionId (one turn per session). */
   private readonly activeTurns;
-  /** Per-session usage accumulators, parallel to activeTurns. */
+  /** Per-turn usage accumulators, keyed by turnId. */
   private readonly usageAccumulators;
-  /** Sessions currently persisting turn completion (prevents concurrent writes). */
-  private readonly completingSessions;
+  /** Turns currently persisting completion (prevents concurrent writes). */
+  private readonly completingTurnIds;
+  /** Completing turns retained for usage correlation after active routing is cleared. */
+  private readonly completingTurns;
+  /** Pending terminal completions keyed by turnId; value records whether turn storage handled the transition. */
+  private readonly pendingTerminalCompletions;
   /** Usage events received while completion persistence is in-flight. */
   private readonly bufferedUsageDuringCompletion;
   /**
@@ -265,12 +292,25 @@ declare class SessionTurnManager {
   /**
    * Discard active in-memory state for a turn that failed before routing began.
    *
-   * The storage contract has no turn-delete operation, so this only rolls back
-   * the active manager state that would otherwise make the next user message
-   * reuse a turn whose first message was never persisted.
+   * Use when no durable turn row needs a terminal status transition.
    * @param turn - Newly created active turn to discard
    */
   discardActiveTurn(turn: Turn$1): void;
+  /**
+   * Mark an unclaimed newly created turn as failed and discard its active in-memory state.
+   *
+   * This preserves the durable turn lifecycle invariant when setup fails after
+   * `storage:turn.create` has already assigned a turn number.
+   * @param turn - Newly created active turn whose setup failed before any message claimed it
+   * @param error - Durable error code to store on the terminal turn
+   */
+  failActiveTurnSetup(turn: Turn$1, error: string): Promise<void>;
+  /**
+   * Remove a turn from the active routing index when it is no longer routable.
+   * @param turn - Turn to remove when it still owns the session slot
+   * @returns Whether the turn owned and cleared the active routing slot
+   */
+  private clearActiveRoutingTurn;
   /**
    * Register bus listeners for `agent.usage` and `agent.complete` events.
    *
@@ -301,6 +341,12 @@ declare class SessionTurnManager {
    * @param result - Turn result (success status and error messages)
    */
   completeTurn(turn: Turn$1, result: TurnCompletionResult): Promise<void>;
+  /**
+   * Clear in-memory state retained only while a turn completion is in progress.
+   * @param turn - Turn whose completion state should be removed
+   * @param usageAccumulator - Optional accumulator retained for late usage merges
+   */
+  private clearCompletionState;
   /**
    * Get the active turn for a session, if any.
    * @param sessionId - Session identifier
@@ -340,14 +386,58 @@ declare class SessionTurnManager {
    * @param success - Whether the agent completed successfully
    * @param error - Error message if the agent failed
    * @param onTurnComplete - Callback to invoke when the turn is complete
+   * @param completionTurnId - Turn identifier supplied by the adapter completion event
    */
   private handleAgentCompletion;
   /**
    * Buffer a usage event that arrived while turn completion persistence is in-flight.
-   * @param sessionId - Session whose turn is currently completing
+   * @param turnId - Turn whose completion is currently being persisted
    * @param usageEvent - Usage event to defer until after persistence
    */
   private bufferUsageDuringCompletion;
+  /**
+   * Find a turn that may still accept usage by turnId.
+   * @param turnId - Turn identifier from an agent usage event
+   * @returns Active or completing turn, if usage can still be recorded
+   */
+  private findTurnForUsage;
+  /**
+   * Find a turn that may still accept agent completion by turnId.
+   * @param turnId - Turn identifier from an agent completion event
+   * @returns Active or completing turn, if completion can still be correlated
+   */
+  private findTurnForCompletion;
+  /**
+   * Find the active turn for a legacy completion event without turnId.
+   * @param agentId - Agent ID from the completion event.
+   * @returns Active turn to mutate, or undefined when the event is ambiguous.
+   */
+  private findTurnForUncorrelatedCompletion;
+  /**
+   * Check whether a terminal outcome has already been recorded for an agent.
+   * @param turn - Turn being completed.
+   * @param agentId - Agent ID from the terminal event.
+   * @returns Whether the agent already has a terminal outcome on the turn.
+   */
+  private hasTerminalOutcome;
+  /**
+   * Persist a turn's terminal status and optional usage snapshot.
+   * @param turn - Turn being completed
+   * @param result - Completion result to persist
+   * @param usage - Usage snapshot to include, when available
+   * @param expectedStatus - Optional status guard for the first terminal transition
+   * @returns Whether turn storage handled the request and terminalized the turn
+   */
+  private persistTurnCompletion;
+  /**
+   * Merge buffered usage and persist the updated snapshot.
+   * @param turn - Turn whose buffered usage should be merged
+   * @param result - Completion result for the turn
+   * @param usageAccumulator - Usage accumulator captured by the completing turn
+   * @param currentUsage - Current completed usage snapshot
+   * @returns Updated usage snapshot
+   */
+  private flushBufferedUsageDuringCompletion;
   /**
    * Subscribe to `storage:message.stored` and count stored assistant messages
    * per turnId, resolving any pending barrier waiter on each increment.
@@ -423,9 +513,10 @@ declare function registerCompressHandler(bus: IMakaioBus): () => void;
  * Creates a new session with parent reference. The forked session starts
  * empty - its full conversation is assembled by traversing the parent chain.
  * @param bus - Bus instance for communication
+ * @param machineId - Stable runtime machine identity to stamp on child sessions
  * @returns Cleanup function to unsubscribe
  */
-declare function registerForkHandler(bus: IMakaioBus): () => void;
+declare function registerForkHandler(bus: IMakaioBus, machineId?: string): () => void;
 //#endregion
 //#region services/core/src/session/handlers/merge-handler.d.ts
 /**
@@ -449,6 +540,50 @@ interface CwdSwapMeta {
   previousCwd: string;
   newCwd: string;
 }
+/**
+ * Options for routing a message to target agents.
+ */
+interface RouteToAgentsOptions {
+  /** Bus instance for communication. */
+  readonly bus: IMakaioBus;
+  /** Session metadata (for fork detection). */
+  readonly session: IMakaioSession;
+  /** Target agents to route to. */
+  readonly agents: MakaioSessionAgent[];
+  /** Message content to send. */
+  readonly message: MessageInput;
+  /** Message identifier. */
+  readonly messageId: string;
+  /** Turn tracking object. */
+  readonly turn: Turn$1;
+  /** How to deliver the message. */
+  readonly deliveryMode: 'enqueue' | 'immediate' | undefined;
+  /** Callback when turn completes (all agents done). */
+  readonly onTurnComplete: (turn: Turn$1, result: {
+    success: boolean;
+    errors: string[];
+  }) => Promise<void>;
+  /** Session context with curated messageHistory and decision signals. */
+  readonly sessionContext?: SessionContext;
+  /** Optional enricher for immediate message context. */
+  readonly turnContextEnricher?: ITurnContextEnricher;
+  /** Whether this is the first message in a new turn. */
+  readonly isNewTurn?: boolean;
+  /** Context enriched with messageHistory for agents that were just recovered. */
+  readonly recoveryContext?: SessionContext;
+  /** Set of agent IDs that were recovered in this handler invocation. */
+  readonly recoveredAgentIds?: ReadonlySet<string>;
+  /** Set of agent IDs that swapped connector due to cwd mismatch. */
+  readonly swappedAgentIds?: ReadonlySet<string>;
+  /** Previous/new cwd metadata keyed by agent ID. */
+  readonly swappedAgentCwd?: ReadonlyMap<string, CwdSwapMeta>;
+  /** Curated history for agents forced into fresh mode. */
+  readonly freshMessageHistory?: Message[];
+  /** Optional structured output descriptor for the turn. */
+  readonly responseSchema?: ResponseSchemaDescriptor;
+  /** Stable machine identity of the current host process for locality evaluation. */
+  readonly localMachineId?: string;
+}
 /**
  * Route a message to target agents via agent.sendMessage.
  *
@@ -456,28 +591,9 @@ interface CwdSwapMeta {
  * and checks for turn completion.
  *
  * For fork sessions on their first turn, assembles projected context from parent chain.
- * @param bus - Bus instance for communication
- * @param session - Session metadata (for fork detection)
- * @param agents - Target agents to route to
- * @param message - Message content to send
- * @param messageId - Message identifier
- * @param turn - Turn tracking object
- * @param deliveryMode - How to deliver the message
- * @param onTurnComplete - Callback when turn completes (all agents done)
- * @param sessionContext - Session context with curated messageHistory and decision signals
- * @param turnContextEnricher - Optional enricher for immediate message context
- * @param isNewTurn - Whether this is the first message in a new turn
- * @param recoveryContext - Context enriched with messageHistory for agents that were just recovered
- * @param recoveredAgentIds - Set of agent IDs that were recovered in this handler invocation
- * @param swappedAgentIds - Set of agent IDs that swapped connector due to cwd mismatch
- * @param swappedAgentCwd - Previous/new cwd metadata keyed by agent ID
- * @param freshMessageHistory - Curated history for agents forced into fresh mode
- * @param responseSchema - Optional structured output descriptor for the turn
+ * @param options - Routing options including bus, session, agents, message, and lifecycle dependencies
  */
-declare function routeToAgents(bus: IMakaioBus, session: IMakaioSession, agents: MakaioSessionAgent[], message: MessageInput, messageId: string, turn: Turn$1, deliveryMode: 'enqueue' | 'immediate' | undefined, onTurnComplete: (turn: Turn$1, result: {
-  success: boolean;
-  errors: string[];
-}) => Promise<void>, sessionContext?: SessionContext, turnContextEnricher?: ITurnContextEnricher, isNewTurn?: boolean, recoveryContext?: SessionContext, recoveredAgentIds?: ReadonlySet<string>, swappedAgentIds?: ReadonlySet<string>, swappedAgentCwd?: ReadonlyMap<string, CwdSwapMeta>, freshMessageHistory?: Message[], responseSchema?: ResponseSchemaDescriptor): Promise<void>;
+declare function routeToAgents(options: RouteToAgentsOptions): Promise<void>;
 //#endregion
 //#region services/core/src/session/handlers/route-to-agents-core.d.ts
 /**
@@ -486,6 +602,12 @@ declare function routeToAgents(bus: IMakaioBus, session: IMakaioSession, agents:
  * Fans out to all agents in parallel. On routing failure, marks the agent
  * as errored and checks for turn completion. On `HookAbortError`, marks
  * the agent as completed with `cancelled` outcome.
+ *
+ * Contract: `sessionContext` must not carry a `nativeFork` directive. This
+ * function dispatches exclusively via `agent.sendMessage`, which never
+ * consumes the directive — fork directives are consumed only on the
+ * `startAgent` path. Callers assembling fork contexts must degrade them to
+ * fresh-with-history first (see `routeToAgents`).
  * @param bus - Bus instance for communication
  * @param session - Session metadata (for session ID)
  * @param agents - Target agents to route to

package/dist/{index-3X0368CL.d.mts → index-CA-AJbq6.d.mts}

@@ -488,8 +488,8 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
         extensionName: z.ZodString;
         warnings: z.ZodArray<z.ZodObject<{
           severity: z.ZodEnum<{
-            degraded: "degraded";
             info: "info";
+            degraded: "degraded";
             recommended: "recommended";
           }>;
           title: z.ZodString;
@@ -528,8 +528,8 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
     extensionName: z.ZodString;
     warnings: z.ZodArray<z.ZodObject<{
       severity: z.ZodEnum<{
-        degraded: "degraded";
         info: "info";
+        degraded: "degraded";
         recommended: "recommended";
       }>;
       title: z.ZodString;
@@ -943,8 +943,8 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
         extensionName: z.ZodString;
         warnings: z.ZodArray<z.ZodObject<{
           severity: z.ZodEnum<{
-            degraded: "degraded";
             info: "info";
+            degraded: "degraded";
             recommended: "recommended";
           }>;
           title: z.ZodString;
@@ -983,8 +983,8 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
     extensionName: z.ZodString;
     warnings: z.ZodArray<z.ZodObject<{
       severity: z.ZodEnum<{
-        degraded: "degraded";
         info: "info";
+        degraded: "degraded";
         recommended: "recommended";
       }>;
       title: z.ZodString;