@makaio/framework 1.0.0-dev-1783615060726 → 1.0.0-dev-1783705652236

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/dist/.makaio-build.json +2 -2
  2. package/dist/adapter-CA8rPIUz.mjs +1 -0
  3. package/dist/adapters/config/index.d.mts +1 -1
  4. package/dist/adapters/index.d.mts +186 -8
  5. package/dist/adapters/index.mjs +6 -6
  6. package/dist/bus/index.mjs +1 -1
  7. package/dist/client-DaR4mzqn.mjs +1 -0
  8. package/dist/contracts/adapter/index.d.mts +2 -2
  9. package/dist/contracts/adapter/index.mjs +1 -1
  10. package/dist/contracts/adapter/schemas/session-lineage.d.mts +1 -1
  11. package/dist/contracts/artifact/index.d.mts +1 -1
  12. package/dist/contracts/client/index.d.mts +2 -2
  13. package/dist/contracts/client/index.mjs +1 -1
  14. package/dist/contracts/extension/index.d.mts +2 -2
  15. package/dist/contracts/facet/index.d.mts +1 -1
  16. package/dist/contracts/index.d.mts +97 -45
  17. package/dist/contracts/index.mjs +1 -1
  18. package/dist/contracts/materialization/index.d.mts +3 -3
  19. package/dist/contracts/session/index.d.mts +3 -3
  20. package/dist/contracts/session/index.mjs +1 -1
  21. package/dist/contracts/workflow/index.d.mts +3 -3
  22. package/dist/contracts/workflow/index.mjs +1 -1
  23. package/dist/{definition-DePb3ke-.d.mts → definition-s9PIua2B.d.mts} +1 -1
  24. package/dist/drizzle/0024_external_settlement_fingerprint.sql +1 -0
  25. package/dist/drizzle/0025_external_registration_frame.sql +1 -0
  26. package/dist/drizzle/meta/_journal.json +14 -0
  27. package/dist/{index-BbQpQ1N3.d.mts → index-B2DjrVb8.d.mts} +84 -0
  28. package/dist/{index-DWu3qrwe.d.mts → index-B9d_8_V2.d.mts} +8 -8
  29. package/dist/{index-2fK9iSHI.d.mts → index-BWIkf5oJ.d.mts} +6 -6
  30. package/dist/{index-BSprsrul.d.mts → index-BcvG3wPv.d.mts} +96 -57
  31. package/dist/{index-CqCe7Phc.d.mts → index-BcwOnvUh.d.mts} +6 -6
  32. package/dist/{index-Qd1Qom8M.d.mts → index-D6aAzr32.d.mts} +4 -4
  33. package/dist/{index-D8wmMJLi.d.mts → index-DScUb-hF.d.mts} +1 -1
  34. package/dist/{index-DKaEpPFS.d.mts → index-DnnKUwHm.d.mts} +5 -5
  35. package/dist/{index-S7lj2TLp.d.mts → index-FFVwQMad.d.mts} +440 -60
  36. package/dist/{index-BMbmoarE.d.mts → index-O08Q2ikz.d.mts} +8 -8
  37. package/dist/{index-DZ14azod.d.mts → index-PIlYSC73.d.mts} +160 -1
  38. package/dist/loop-gate-handlers-o2B5FPdF.mjs +1 -0
  39. package/dist/{namespace-DuUCiVmK.d.mts → namespace-B4cV_pk3.d.mts} +6 -6
  40. package/dist/{namespace-Ceg3zkt2.d.mts → namespace-BGIeqwfU.d.mts} +20 -20
  41. package/dist/{namespace-Dc94fHZW.d.mts → namespace-D9PLFmPQ.d.mts} +9 -9
  42. package/dist/package-Co_GO3UD.mjs +7 -0
  43. package/dist/{package-B6mEMD8r.d.mts → package-DmVZxufT.d.mts} +1 -1
  44. package/dist/package.json +1 -1
  45. package/dist/{schema-B9goOieO.d.mts → schema-B5vHi7Uu.d.mts} +1 -1
  46. package/dist/{schemas-D512XweP.d.mts → schemas-CJ2JvA7d.d.mts} +3 -3
  47. package/dist/schemas-CVo8qAK-.mjs +1 -0
  48. package/dist/services/adapter-subsystem/index.d.mts +2 -2
  49. package/dist/services/adapter-subsystem/namespace.d.mts +1 -1
  50. package/dist/services/execution-target/index.d.mts +1 -1
  51. package/dist/services/filesystem/namespace.d.mts +6 -6
  52. package/dist/services/filesystem/schemas.d.mts +3 -3
  53. package/dist/services/index.d.mts +14 -14
  54. package/dist/services/session/index.d.mts +4 -4
  55. package/dist/services/session/session-events/namespace.d.mts +1 -1
  56. package/dist/services/session/storage/namespace.d.mts +1 -1
  57. package/dist/services/session/storage/schema.d.mts +1 -1
  58. package/dist/services/settings/namespace.d.mts +3 -3
  59. package/dist/services/settings/storage/extension-configs/namespace.d.mts +3 -3
  60. package/dist/session-DBfQkgdy.mjs +1 -0
  61. package/dist/{session-lineage-NBFNVkUE.d.mts → session-lineage-C1M7-O3C.d.mts} +1 -1
  62. package/dist/{transition-CmI3q3FA.d.mts → transition-OzGXyy3p.d.mts} +1 -1
  63. package/dist/{types-VwMx5_lS.d.mts → types-BrUOVfwe.d.mts} +26 -2
  64. package/dist/{types-Dhou-Itn.d.mts → types-CBLPaQXe.d.mts} +36 -22
  65. package/dist/workflow-C3dgVwTY.mjs +1 -0
  66. package/dist/workflow-engine/index.d.mts +289 -21
  67. package/dist/workflow-engine/index.mjs +1 -1
  68. package/dist/workflow-engine/package.d.mts +1 -1
  69. package/dist/workflow-engine/package.mjs +1 -1
  70. package/dist/workflow-engine/workflow-orchestrator.mjs +1 -1
  71. package/package.json +1 -1
  72. package/dist/adapter-Lx6K7yQS.mjs +0 -1
  73. package/dist/client-l1Rq5p6X.mjs +0 -1
  74. package/dist/loop-gate-handlers-Bjmat-K3.mjs +0 -1
  75. package/dist/package-BQn_RTo7.mjs +0 -1
  76. package/dist/schemas-CkOigLAT.mjs +0 -1
  77. package/dist/session-D5rVMqmE.mjs +0 -1
  78. package/dist/workflow-C1z7I5CI.mjs +0 -1
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "version": 1,
3
- "fingerprint": "305e2b44c67a83ae6ba9698f20dcf72efb14d497813db06ded1e9cfde150809f",
4
- "builtAt": "2026-07-09T16:38:44.937Z"
3
+ "fingerprint": "8ffadc741e4269410d04cacdf8ffc8987d1276b9861fb2562c15b58e5a881d96",
4
+ "builtAt": "2026-07-10T17:48:41.489Z"
5
5
  }
@@ -0,0 +1 @@
1
+ import{_ as e,b as t,c as n,d as r,f as i,g as a,h as o,ht as s,l as c,m as l,o as u,p as d,s as f,t as p,u as m,v as h,y as g}from"./schemas-CVo8qAK-.mjs";import"./compression-C5JAWdgZ.mjs";import"./provider-context-CqMgPOWF.mjs";import"./contracts/adapter/schemas/session-lineage.mjs";import{createBusNamespace as _}from"@makaio/framework/core";const v={getCapabilities:s,startAgent:t,infer:g,listAgents:h,getAgent:e,stopAgent:a,rehydrateAgent:o,getConfigSchema:l,"agent.created":d,"session.created":i,"session.discovered":p,"session.usage":r,"session.closed":m,log:c,error:n,initialized:f,quota:u},y=_(`adapter`,v),b=y.subjects;export{b as n,v as r,y as t};
@@ -1,4 +1,4 @@
1
- import { _ as BaseAgentConnectorConfig } from "../../types-VwMx5_lS.mjs";
1
+ import { _ as BaseAgentConnectorConfig } from "../../types-BrUOVfwe.mjs";
2
2
  import { z } from "zod";
3
3
  import { IMakaioBus, MakaioBusContext } from "@makaio/framework/bus";
4
4
  import { AIModelSchema, ProtocolId, ProviderContext } from "@makaio/framework/contracts";
@@ -1,10 +1,10 @@
1
- import { A as MessageDeliveryMode, B as AIReasoningLevel, C as NormalizedCallUsage, D as ConfigFactoryInput, E as StartAgentOptions, F as MessageResult, G as ToolLedgerEntry, H as ISessionToolLedger, I as MessageState, L as ProcessingState, M as markCompletedWithFinalResult, N as NormalizedMessageInput, O as IAdapterConfigFactory, P as normalizeMessageInput, R as SendMessageOptions, S as GetCapabilitiesResponsePayload, T as SendMessageResponsePayload, U as LedgerSessionContext, V as ReasoningLevelMap, W as SessionToolLedger, _ as BaseAgentConnectorConfig, a as AgentCredentialChangeResponsePayload, b as ContextWindowInput, c as AgentIdentity, d as AgentMcpServersSetRequestPayload, f as AgentMcpServersSetResponsePayload, g as AgentStartResult, h as AgentSendMessageOptions, i as AgentCredentialChangeRequestPayload, j as MessageHandle, k as AIAgentConnector, l as AgentInterruptRequestPayload, m as AgentModelChangeResponsePayload, n as AgentConnectorConfigOverrides, o as AgentCwdChangeRequestPayload, p as AgentModelChangeRequestPayload, r as AgentContext, s as AgentCwdChangeResponsePayload, t as AIAgentConfig, u as AgentInterruptResponsePayload, v as ConnectorSendMessageOptions, w as SendMessageRequestPayload, x as ExecutionContext, y as ConnectorStartOptions, z as AIModel } from "../types-VwMx5_lS.mjs";
1
+ import { A as MessageDeliveryMode, B as AIReasoningLevel, C as NormalizedCallUsage, D as ConfigFactoryInput, E as StartAgentOptions, F as MessageResult, G as ToolLedgerEntry, H as ISessionToolLedger, I as MessageState, L as ProcessingState, M as markCompletedWithFinalResult, N as NormalizedMessageInput, O as IAdapterConfigFactory, P as normalizeMessageInput, R as SendMessageOptions, S as GetCapabilitiesResponsePayload, T as SendMessageResponsePayload, U as LedgerSessionContext, V as ReasoningLevelMap, W as SessionToolLedger, _ as BaseAgentConnectorConfig, a as AgentCredentialChangeResponsePayload, b as ContextWindowInput, c as AgentIdentity, d as AgentMcpServersSetRequestPayload, f as AgentMcpServersSetResponsePayload, g as AgentStartResult, h as AgentSendMessageOptions, i as AgentCredentialChangeRequestPayload, j as MessageHandle, k as AIAgentConnector, l as AgentInterruptRequestPayload, m as AgentModelChangeResponsePayload, n as AgentConnectorConfigOverrides, o as AgentCwdChangeRequestPayload, p as AgentModelChangeRequestPayload, r as AgentContext, s as AgentCwdChangeResponsePayload, t as AIAgentConfig, u as AgentInterruptResponsePayload, v as ConnectorSendMessageOptions, w as SendMessageRequestPayload, x as ExecutionContext, y as ConnectorStartOptions, z as AIModel } from "../types-BrUOVfwe.mjs";
2
2
  import { S as toImportSegment, _ as LogImporter, a as CompactionMetadata, b as ProcessLogFileResult, c as ExternalToolIdentifiers, d as ImportMetadata, f as ImportSegment, g as LogImportTestConfig, h as LogImportSessionContext, l as ExternalToolMeta, m as ImportSegmentTurn, n as LogOrchestratorConfig, o as DiscoveryMetadata, p as ImportSegmentLineage, r as ParseFileResult, s as ExternalToolIdentifier, u as ImportCursorPosition, v as LogImporterConfig, x as StorageMessagePayload, y as NormalizedEvent } from "../base-orchestrator-J1WKAUkF.mjs";
3
3
  import { z } from "zod";
4
4
  import * as _$_makaio_core0 from "@makaio/framework/core";
5
5
  import { CreateBusNamespaceOptions, ExtractSubjectPayload, FilterablePayloadIntersection, HandlerForSubjectDefinition, RegistrableBusNamespaceDefinition, RequestContext, SchemaRecord, ScopedSubjectDefinition, SubjectDefinition, SubjectRecordFromSchemaRecord } from "@makaio/framework/core";
6
6
  import { BusNamespace, IMakaioBus, OnOptions, ScopedBus, ScopedBusFor } from "@makaio/framework/bus";
7
- import { AIReasoningLevel as AIReasoningLevel$1, AdapterClientRef, AdapterDefinitionContract, AdapterProviderDefinitionContract, AdapterSubjects, AgentSchemas, AgentStarted, AgentSubjects, AgentToolApproveRequest, AgentToolApproveResponse, BlockData, HarnessDefinition, HarnessSubjects, JsonValue, McpResolvedServer, McpRuntimeSessionContext, McpSessionContext, McpToolState, Message, MessageInput, NativeForkDirective, ProviderContext, ProviderDefinitionInput, ReasoningLevelMap as ReasoningLevelMap$1, ResponseSchemaDescriptor, SendMessageRequest, SendMessageResponse, SessionContext, SessionMessageBlock, StartAgentRequest, StartAgentResponse, StartMode, StepType, SystemPrompt, ToolListItem } from "@makaio/framework/contracts";
7
+ import { AIReasoningLevel as AIReasoningLevel$1, AdapterClientRef, AdapterDefinitionContract, AdapterProviderDefinitionContract, AdapterSubjects, AgentSchemas, AgentStarted, AgentSubjects, AgentToolApproveRequest, AgentToolApproveResponse, BlockData, HarnessDefinition, HarnessSubjects, JsonValue, McpResolvedServer, McpRuntimeSessionContext, McpSessionContext, McpToolState, Message, MessageInput, NativeForkDirective, ProviderContext, ProviderDefinitionInput, ReasoningLevelMap as ReasoningLevelMap$1, RequestCorrelationContext, ResponseSchemaDescriptor, SendMessageRequest, SendMessageResponse, SessionContext, SessionMessageBlock, StartAgentRequest, StartAgentResponse, StartMode, StepType, SystemPrompt, ToolListItem } from "@makaio/framework/contracts";
8
8
  import * as _$_makaio_storage_core0 from "@makaio/framework/storage";
9
9
  import * as _$_makaio_ai_adapters_core0 from "@makaio/framework/adapters";
10
10
  import * as _$type_fest0 from "type-fest";
@@ -775,7 +775,39 @@ declare abstract class BaseConnectorSession<TConfig extends ConnectorSessionConf
775
775
  protected readonly bus: TConfig['bus'];
776
776
  protected sessionId?: string;
777
777
  protected currentTurn?: PausableTurn;
778
+ /**
779
+ * True once `close()` or `abort()` has begun; gates queue processing.
780
+ *
781
+ * ## Shutdown vs queue processing invariant
782
+ *
783
+ * Once `close()` or `abort()` begins, no new turn may start.
784
+ * `processQueue` implementations must refuse to dequeue or start turns
785
+ * when `this.closing` is `true`, and drain all remaining queued handles
786
+ * with an error outcome so that callers awaiting `waitForCompletion()`
787
+ * resolve deterministically instead of hanging.
788
+ *
789
+ * A dequeued handle that has entered the start-turn path either starts
790
+ * its turn before `close()` begins, or is completed with the closing
791
+ * error at every await point where `close()` can interleave. This is
792
+ * enforced by {@link completeHandleIfClosing}, which rechecks the flag
793
+ * after each awaited setup step and completes the handle with the same
794
+ * error contract used by {@link rejectQueuedHandles}.
795
+ */
796
+ protected closing: boolean;
778
797
  constructor(config: TConfig);
798
+ /**
799
+ * Recheck the shutdown flag after an awaited setup step in the start path.
800
+ *
801
+ * When `close()` sets `this.closing` while the subclass start-turn method
802
+ * is awaiting an async setup step (schema rotation, query creation, MCP
803
+ * registration, env resolution), the dequeued handle is no longer in the
804
+ * queue and {@link rejectQueuedHandles} cannot reach it. This helper
805
+ * completes the handle with the same error contract so callers see a
806
+ * consistent shutdown outcome.
807
+ * @param handle - Dequeued message handle currently being set up
808
+ * @returns `true` when the session is closing and the handle was completed
809
+ */
810
+ protected completeHandleIfClosing(handle: MessageHandle): boolean;
779
811
  /**
780
812
  * Abort the session and cleanup resources.
781
813
  * Pauses the current turn if one is active.
@@ -1081,6 +1113,16 @@ declare class UserMessageQueue {
1081
1113
  }
1082
1114
  //#endregion
1083
1115
  //#region adapters/core/src/session/process-queue.d.ts
1116
+ /**
1117
+ * Canonical error message used when a queued message cannot be processed
1118
+ * because the session has entered the shutdown path.
1119
+ *
1120
+ * Shared between {@link rejectQueuedHandles} (queue drain) and the per-handle
1121
+ * shutdown gate ({@link BaseConnectorSession.completeHandleIfClosing}) so that
1122
+ * callers see a consistent error contract regardless of whether the handle was
1123
+ * still in the queue or had already been dequeued when `close()` interleaved.
1124
+ */
1125
+ declare const SESSION_CLOSED_QUEUE_ERROR = "Session closed before queued message could be processed";
1084
1126
  /**
1085
1127
  * Minimal turn interface required by processQueue orchestration.
1086
1128
  *
@@ -1141,11 +1183,18 @@ interface ProcessQueueCallbacks<TExtra = unknown> {
1141
1183
  onBeforeImmediateTurn?: () => Promise<void>;
1142
1184
  /**
1143
1185
  * Start a new turn with the given message and optional merge data.
1186
+ *
1187
+ * Returns `void` (or `undefined`) when the turn was started normally.
1188
+ * Returns `false` explicitly when the turn was **not** started (e.g.,
1189
+ * shutdown interleaved during setup and the handle was completed with
1190
+ * an error). `processQueueMessages` propagates this so callers see an
1191
+ * accurate "no turn started" result and can transition to idle.
1144
1192
  * @param handle - The message handle to process
1145
1193
  * @param mergedContent - Text content from superseded/merged messages
1146
1194
  * @param extra - Adapter-specific extra merge data
1195
+ * @returns `false` when the turn was skipped; `void` otherwise
1147
1196
  */
1148
- startNewTurn: (handle: MessageHandle, mergedContent?: string[], extra?: TExtra) => Promise<void>;
1197
+ startNewTurn: (handle: MessageHandle, mergedContent?: string[], extra?: TExtra) => Promise<void | false>;
1149
1198
  }
1150
1199
  /**
1151
1200
  * Shared processQueue orchestration for all session implementations.
@@ -1170,6 +1219,16 @@ interface ProcessQueueCallbacks<TExtra = unknown> {
1170
1219
  * @typeParam TExtra - Type of adapter-specific extra merge data
1171
1220
  */
1172
1221
  declare function processQueueMessages<TExtra = unknown>(queue: UserMessageQueue, callbacks: ProcessQueueCallbacks<TExtra>): Promise<boolean>;
1222
+ /**
1223
+ * Drain all remaining handles from the queue and complete each with an error
1224
+ * outcome so callers awaiting `waitForCompletion()` resolve deterministically.
1225
+ *
1226
+ * Used by session implementations during shutdown to prevent queued messages
1227
+ * from hanging indefinitely when the session refuses to start new turns.
1228
+ * @param queue - User message queue to drain
1229
+ * @param message - Error message to attach to each rejected handle
1230
+ */
1231
+ declare function rejectQueuedHandles(queue: UserMessageQueue, message?: string): void;
1173
1232
  //#endregion
1174
1233
  //#region adapters/core/src/connector/procedural-agent-connector.d.ts
1175
1234
  /**
@@ -1576,10 +1635,63 @@ interface MessageLifecycleTrackOptions {
1576
1635
  *
1577
1636
  * This provides a clean separation between message lifecycle tracking
1578
1637
  * and the core AIAgent functionality.
1638
+ *
1639
+ * ## Turn pairing contract
1640
+ *
1641
+ * `agent.turn.started` and `agent.turn.completed` are emitted **only as a
1642
+ * matched pair** for handles that actually start a provider turn (i.e. whose
1643
+ * acknowledgment is delivered). The pairing decision is derived from
1644
+ * `handle.wasDelivered` — `acknowledge()` ensures the handle is marked as
1645
+ * delivered, so `complete()` can gate `turn.completed` emission without
1646
+ * maintaining parallel tracking state. Handles completed before dispatch —
1647
+ * merged, superseded, or rejected while queued — never receive `turn.started`
1648
+ * and therefore never receive `turn.completed`. The message-level event
1649
+ * `user_message.completed` always fires regardless of delivery, carrying the
1650
+ * terminal outcome so downstream consumers (storage, UI cleanup) can react
1651
+ * to every message disposition.
1652
+ *
1653
+ * ## Correlation source contract
1654
+ *
1655
+ * The "active" handle (`currentMessageHandle`) is the correlation source for
1656
+ * usage events emitted by the provider. The invariant:
1657
+ *
1658
+ * 1. A handle becomes the active correlation source **only when no other
1659
+ * tracked handle is still in-flight**. This ensures usage from the executing
1660
+ * turn is attributed to the correct request.
1661
+ * 2. When a handle is tracked via `track()` while another handle is already
1662
+ * active, it is appended to `pendingTrackedHandles` (a FIFO queue). It does
1663
+ * NOT become the correlation source until all handles ahead of it in the
1664
+ * queue have been promoted or removed.
1665
+ * 3. When the active handle completes, the head of the pending queue (if any)
1666
+ * is promoted to active — making its correlation visible for usage emitted
1667
+ * by its turn. This preserves FIFO ordering with the connector's
1668
+ * `UserMessageQueue`.
1669
+ * 4. A pending handle that completes before promotion (e.g. cancelled or
1670
+ * superseded while queued) is removed from wherever it sits in the queue,
1671
+ * without disrupting the order of remaining pending handles.
1672
+ * 5. For the first handle dispatched (no prior active), the handle is set
1673
+ * eagerly so that usage arriving before the provider acknowledges the
1674
+ * message is still correlated (closes the early-close / result-only stream
1675
+ * window from the previous fix).
1676
+ * 6. A handle that is already processed (`isProcessed === true`) at `track()`
1677
+ * time — e.g. completed by shutdown gates before the agent's
1678
+ * `onMessageHandle` callback ran — **never becomes the correlation source**.
1679
+ * It is neither promoted to active nor queued as pending. Completion
1680
+ * transforms are skipped (the pipeline already ran), but the completion
1681
+ * subscription still fires and `onTerminal` is still called, preserving
1682
+ * the terminal lifecycle contract for the caller.
1579
1683
  */
1580
1684
  declare class MessageLifecycleTracker {
1581
- /** Current messageId being processed (set on acknowledgment, cleared on completion) */
1582
- private currentMessageId?;
1685
+ /** Handle of the currently executing turn the active correlation source. */
1686
+ private currentMessageHandle?;
1687
+ /**
1688
+ * FIFO queue of handles tracked while another turn was still in-flight.
1689
+ * The head of the queue is promoted to `currentMessageHandle` when the
1690
+ * active handle completes. Handles that complete while queued (e.g.
1691
+ * cancelled or superseded) are removed from wherever they sit without
1692
+ * disrupting the order of remaining entries.
1693
+ */
1694
+ private readonly pendingTrackedHandles;
1583
1695
  /** Current turnId from the session orchestrator (set at sendMessage entry, cleared on completion) */
1584
1696
  private currentTurnId?;
1585
1697
  /** Emit function injected from AIAgent */
@@ -1587,10 +1699,16 @@ declare class MessageLifecycleTracker {
1587
1699
  constructor(config: MessageLifecycleTrackerConfig);
1588
1700
  /**
1589
1701
  * Get the current messageId being processed.
1702
+ * Derived from the active message handle to avoid dual state.
1590
1703
  * Used by enrichPayload() to add messageId to intermediate events.
1591
1704
  * @returns The current messageId or undefined if no message is being processed
1592
1705
  */
1593
1706
  getCurrentMessageId(): string | undefined;
1707
+ /**
1708
+ * Get the active message handle being processed.
1709
+ * @returns The active message handle or undefined if no message is being processed
1710
+ */
1711
+ getCurrentMessageHandle(): MessageHandle | undefined;
1594
1712
  /**
1595
1713
  * Set the current turnId from the session orchestrator.
1596
1714
  * Called at the start of sendMessage processing.
@@ -1610,6 +1728,13 @@ declare class MessageLifecycleTracker {
1610
1728
  /**
1611
1729
  * Acknowledge a message - marks turn start.
1612
1730
  *
1731
+ * This should only be called for handles whose acknowledgment was
1732
+ * genuinely delivered (i.e. `waitForAcknowledgment()` resolved with
1733
+ * `true`). Handles completed before dispatch (merged, superseded, or
1734
+ * rejected) resolve acknowledgment with `false` — calling acknowledge()
1735
+ * for those would steal the active correlation slot from the real
1736
+ * in-flight turn.
1737
+ *
1613
1738
  * Emits:
1614
1739
  * - user_message.acknowledged
1615
1740
  * - agent.turn.started
@@ -1621,13 +1746,19 @@ declare class MessageLifecycleTracker {
1621
1746
  * Complete a message - marks turn end.
1622
1747
  *
1623
1748
  * Emits:
1624
- * - agent.turn.completed (always, with outcome paired with agent.turn.started)
1625
- * - user_message.completed (always, with outcome)
1749
+ * - agent.turn.completed — **only** when `acknowledge()` emitted
1750
+ * `agent.turn.started` for this handle (turn pairing contract)
1751
+ * - user_message.completed — always, with outcome details
1626
1752
  * @param handle - The message handle being completed
1627
1753
  * @param result - The completion result with outcome
1628
1754
  * @param turnId - Turn ID captured when the handle was registered
1629
1755
  */
1630
1756
  complete(handle: MessageHandle, result: MessageResult, turnId?: string): void;
1757
+ /**
1758
+ * Remove a handle from the pending queue if present.
1759
+ * @param handle - The handle to remove
1760
+ */
1761
+ private removePendingHandle;
1631
1762
  /**
1632
1763
  * Wire up a message handle for lifecycle tracking.
1633
1764
  *
@@ -1635,6 +1766,15 @@ declare class MessageLifecycleTracker {
1635
1766
  * and emits the appropriate events. When `transformTerminal` is provided,
1636
1767
  * it is registered on the handle so validation or other post-processing
1637
1768
  * amends the public completion result before lifecycle events fire.
1769
+ *
1770
+ * **Already-processed handles:** When a handle is already completed or
1771
+ * cancelled at `track()` time (e.g. shutdown gates completed it before
1772
+ * the agent's `onMessageHandle` callback ran), it is never promoted to
1773
+ * the active correlation source and never queued as pending. The
1774
+ * completion transform is skipped (the handle already ran its transform
1775
+ * pipeline), but the completion and terminal subscriptions still fire so
1776
+ * the caller receives the full lifecycle contract (events emitted,
1777
+ * `onTerminal` called).
1638
1778
  * @param handle - The message handle to track
1639
1779
  * @param onTerminal - Optional callback for any terminal outcome (emits agent.complete)
1640
1780
  * @param transformTerminal - Optional async transform applied before public completion resolves
@@ -1729,6 +1869,8 @@ interface AgentEventBridgeConfig {
1729
1869
  incrementBlockIndex: () => void;
1730
1870
  /** Resolve model name for usage events. */
1731
1871
  getUsageModel: () => string | undefined;
1872
+ /** Get the message handle whose provider request is currently active. */
1873
+ getActiveMessageHandle: () => MessageHandle | undefined;
1732
1874
  }
1733
1875
  /**
1734
1876
  * Resolution metadata returned when emitting tool output.
@@ -1756,6 +1898,7 @@ declare class AgentEventBridge {
1756
1898
  private readonly getBlockIndex;
1757
1899
  private readonly incrementBlockIndex;
1758
1900
  private readonly getUsageModel;
1901
+ private readonly getActiveMessageHandle;
1759
1902
  /**
1760
1903
  * Create an event bridge with emission and correlation dependencies.
1761
1904
  * @param config - Event bridge dependencies (emitters, tracker, and block-index accessors)
@@ -2990,6 +3133,41 @@ declare function extractMcpCallTarget(args: Record<string, unknown>): string | u
2990
3133
  */
2991
3134
  declare function isMcpCallTool(toolName: string): boolean;
2992
3135
  //#endregion
3136
+ //#region adapters/core/src/agent/request-correlation.d.ts
3137
+ /** Exact Factory Gateway headers accepted by its content-free usage boundary. */
3138
+ declare const FactoryUsageCorrelationHeaders: {
3139
+ readonly sessionId: "x-factory-session-id";
3140
+ readonly turnId: "x-factory-turn-id";
3141
+ readonly messageId: "x-factory-message-id";
3142
+ readonly llmCallId: "x-factory-llm-call-id";
3143
+ readonly executionId: "x-factory-execution-id";
3144
+ readonly frameId: "x-factory-frame-id";
3145
+ };
3146
+ type ProviderRequestCorrelation = RequestCorrelationContext & {
3147
+ llmCallId: string;
3148
+ };
3149
+ /**
3150
+ * Bind caller correlation to identifiers owned by the active runtime request.
3151
+ * Runtime values always win, preventing stale or spoofed session/message IDs.
3152
+ * @param context - Optional orchestrator-supplied workflow correlation
3153
+ * @param runtime - IDs known by the connector for this concrete API request
3154
+ * @returns Fully bound correlation including one LLM-call ID
3155
+ */
3156
+ declare function bindProviderRequestCorrelation(context: RequestCorrelationContext | undefined, runtime: {
3157
+ sessionId?: string;
3158
+ messageId: string;
3159
+ llmCallId: string;
3160
+ }): ProviderRequestCorrelation;
3161
+ /**
3162
+ * Project a validated correlation context to the Factory Gateway allowlist.
3163
+ *
3164
+ * No arbitrary metadata or headers can cross this boundary. Callers must also
3165
+ * explicitly opt into the `factory-v1` transport mode before using the result.
3166
+ * @param correlation - Content-free runtime and workflow identifiers
3167
+ * @returns Header record accepted by the Factory Gateway usage boundary
3168
+ */
3169
+ declare function buildFactoryUsageCorrelationHeaders(correlation: ProviderRequestCorrelation): Record<string, string>;
3170
+ //#endregion
2993
3171
  //#region adapters/core/src/adapter/ai-adapter.d.ts
2994
3172
  /**
2995
3173
  * Base class for AI adapters.
@@ -4338,4 +4516,4 @@ declare const ToolCompletedEventSchema: z.ZodObject<{
4338
4516
  type ToolStartedEvent = z.infer<typeof ToolStartedEventSchema>;
4339
4517
  type ToolCompletedEvent = z.infer<typeof ToolCompletedEventSchema>;
4340
4518
  //#endregion
4341
- export { AIAdapter, type AIAdapterCapabilities, type AIAdapterCapability, type AIAdapterCapabilityRegistry, type AIAdapterConfig, type AIAdapterConstructorConfig, type AIAdapterContext, type AIAdapterDefinition, type AIAdapterInitOptions, type AIAdapterPromptFailureResult, type AIAdapterPromptOptions, type AIAdapterPromptResult, type AIAdapterPromptSuccessResult, AIAgent, type AIAgentConfig, AIAgentConnector, type AIModel, type AIReasoningLevel, type AdapterNamespace, type AdapterProviderDefinition, type AgentBusHandlerRegistrarConfig, type AgentCompleteEvent, AgentCompleteEventSchema, AgentConnectorLifecycleManager, type AgentConnectorLifecycleManagerConfig, type AgentContext, AgentEventBridge, type AgentEventBridgeConfig, type AgentIdentity, AgentLifecycleEmitter, type AgentLifecycleEmitterConfig, AgentPayloadEmitter, type AgentPayloadEmitterConfig, type AgentRuntimeCreationResult, AgentRuntimeMutationManager, type AgentRuntimeMutationManagerConfig, type AgentSendMessageOptions, type AgentStartResult, type AgentStartedEvent, AgentStartedEventSchema, AgentTurnExecutor, type AgentTurnExecutorConfig, type AgentUsageTotals, type BaseAgentConnectorConfig, BaseConnectorSession, BaseConnectorTurn, BaseLogImporter, type CompactionMetadata, type ConfigFactoryInput, type ConformanceEnvReader, type ConformanceTestConfig, type ConnectorSendMessageOptions, type ConnectorSessionConfig, type ConnectorStartOptions, type CreateConformanceTestConfigOptions, type CreateTestAgentOptions, type DiscoveryMetadata, type DiscriminatedHandler, type DiscriminatedHandlersConfig, type DiscriminatedHandlersMap, type ErrorEvent, ErrorEventSchema, type ExecutionContext, type ExternalToolIdentifier, type ExternalToolIdentifiers, type ExternalToolMeta, type FromGlobalToolApprovalFn, type GeneratedCapabilityProperties, type HarnessRequester, type IAdapterConfigFactory, type ISessionToolLedger, type ImportCursorPosition, ImportCursorPositionSchema, ImportCursorStorageNamespace, ImportCursorStorageSubjects, type ImportMetadata, type ImportSegment, type ImportSegmentLineage, type ImportSegmentTurn, type LedgerSessionContext, type LogImportConfig, type LogImportOrchestrator, type LogImportRegistration, type LogImportSessionContext, type LogImportTestConfig, type LogImporter, type LogImporterConfig, type LogImporterConstructor, type LogOrchestratorConfig, type LogOrchestratorConstructor, MAKAIO_CONFORMANCE_PRIMARY_MODEL_ENV, MAKAIO_CONFORMANCE_PROVIDER_DEFINITIONS_ENV, MAKAIO_CONFORMANCE_PROVIDER_ENV, MAKAIO_CONFORMANCE_SECONDARY_MODEL_ENV, type McpIntegrationStrategy, type McpSessionResources, type McpToolChange, type MergeResult, type MergeScopedToolApprovalOptions, type MessageDeliveryMode, MessageHandle, MessageLifecycleTracker, type MessageResult, type MessageState, type NormalizedCallUsage, type NormalizedEvent, type NormalizedMessageInput, type ParseFileResult, type PauseResult, type PlatformDefaults, ProceduralAgentConnector, type ProceduralConnectorSession, ProceduralConnectorTurn, type ProceduralTurnConfig, type ProceduralTurnState, type ProcessLogFileResult, type ProcessQueueCallbacks, type ProcessingState, type QueueableTurn, type ReasoningLevelMap, type ResolveConformanceTestPresetOptions, type ResolveHints, type ResolvedConformanceTestPreset, type ScopedBusFor, type ScopedToolApprovalRequest, type ScopedToolApprovalResponse, ScopedToolApprovalSchema, type SendMessageOptions, type SendMessageRequest, type SendMessageResponse, type SerializedContextBlock, SessionLifecycle, SessionToolLedger, type ShouldUseNativeResumeFn, type StartAgentOptions, type StartAgentRequest, type StartAgentResponse, type StorageMessagePayload, type SyncDiscriminatedHandler, type SyncDiscriminatedHandlersConfig, type SyncDiscriminatedHandlersMap, type SyncTypedEmitFn, type TestModelRef, type ToGlobalToolApprovalFn, type ToolApprovalContext, ToolCallTracker, type ToolCompletedEvent, ToolCompletedEventSchema, type ToolLedgerEntry, type ToolStartedEvent, ToolStartedEventSchema, type TurnEvent, type TurnState, type TurnSubjects, TurnTracker, type TurnTrackerOptions, type TurnTrackerSerializedState, TurnTrackerSerializedStateSchema, type TypedEmitFn, UserMessageQueue, type ValidCapability, type WireSessionConfig, type WireSessionSubjects, cleanEnvForAdapter, createAdapterNamespace, createTestProviderContext, createToolApprovalHandler, defineDiscriminatedHandlers, defineDiscriminatedHandlersSync, extractMcpCallTarget, formatContextBlockAsText, formatContextBlocksAsText, formatMessageHistoryAsTranscript, isMcpCallTool, isTextLikeMimeType, markCompletedWithFinalResult, mergeScopedToolApproval, normalizeEnvValue, normalizeMessageInput, normalizeMimeType, parseAIAdapterCapabilities, processDiscriminatedItems, processDiscriminatedItemsSync, processQueueMessages, registerAgentBusHandlers, registerMemoryImportCursorStorage, resolveConformanceTestPreset, resolveDisabledNativeTools, resolvePresetCredentials, resolveRequiredSessionId, resolveTestConfig, safeJsonStringify, serializeBlockToText, serializeTurnContext, toImportSegment };
4519
+ export { AIAdapter, type AIAdapterCapabilities, type AIAdapterCapability, type AIAdapterCapabilityRegistry, type AIAdapterConfig, type AIAdapterConstructorConfig, type AIAdapterContext, type AIAdapterDefinition, type AIAdapterInitOptions, type AIAdapterPromptFailureResult, type AIAdapterPromptOptions, type AIAdapterPromptResult, type AIAdapterPromptSuccessResult, AIAgent, type AIAgentConfig, AIAgentConnector, type AIModel, type AIReasoningLevel, type AdapterNamespace, type AdapterProviderDefinition, type AgentBusHandlerRegistrarConfig, type AgentCompleteEvent, AgentCompleteEventSchema, AgentConnectorLifecycleManager, type AgentConnectorLifecycleManagerConfig, type AgentContext, AgentEventBridge, type AgentEventBridgeConfig, type AgentIdentity, AgentLifecycleEmitter, type AgentLifecycleEmitterConfig, AgentPayloadEmitter, type AgentPayloadEmitterConfig, type AgentRuntimeCreationResult, AgentRuntimeMutationManager, type AgentRuntimeMutationManagerConfig, type AgentSendMessageOptions, type AgentStartResult, type AgentStartedEvent, AgentStartedEventSchema, AgentTurnExecutor, type AgentTurnExecutorConfig, type AgentUsageTotals, type BaseAgentConnectorConfig, BaseConnectorSession, BaseConnectorTurn, BaseLogImporter, type CompactionMetadata, type ConfigFactoryInput, type ConformanceEnvReader, type ConformanceTestConfig, type ConnectorSendMessageOptions, type ConnectorSessionConfig, type ConnectorStartOptions, type CreateConformanceTestConfigOptions, type CreateTestAgentOptions, type DiscoveryMetadata, type DiscriminatedHandler, type DiscriminatedHandlersConfig, type DiscriminatedHandlersMap, type ErrorEvent, ErrorEventSchema, type ExecutionContext, type ExternalToolIdentifier, type ExternalToolIdentifiers, type ExternalToolMeta, FactoryUsageCorrelationHeaders, type FromGlobalToolApprovalFn, type GeneratedCapabilityProperties, type HarnessRequester, type IAdapterConfigFactory, type ISessionToolLedger, type ImportCursorPosition, ImportCursorPositionSchema, ImportCursorStorageNamespace, ImportCursorStorageSubjects, type ImportMetadata, type ImportSegment, type ImportSegmentLineage, type ImportSegmentTurn, type LedgerSessionContext, type LogImportConfig, type LogImportOrchestrator, type LogImportRegistration, type LogImportSessionContext, type LogImportTestConfig, type LogImporter, type LogImporterConfig, type LogImporterConstructor, type LogOrchestratorConfig, type LogOrchestratorConstructor, MAKAIO_CONFORMANCE_PRIMARY_MODEL_ENV, MAKAIO_CONFORMANCE_PROVIDER_DEFINITIONS_ENV, MAKAIO_CONFORMANCE_PROVIDER_ENV, MAKAIO_CONFORMANCE_SECONDARY_MODEL_ENV, type McpIntegrationStrategy, type McpSessionResources, type McpToolChange, type MergeResult, type MergeScopedToolApprovalOptions, type MessageDeliveryMode, MessageHandle, MessageLifecycleTracker, type MessageResult, type MessageState, type NormalizedCallUsage, type NormalizedEvent, type NormalizedMessageInput, type ParseFileResult, type PauseResult, type PlatformDefaults, ProceduralAgentConnector, type ProceduralConnectorSession, ProceduralConnectorTurn, type ProceduralTurnConfig, type ProceduralTurnState, type ProcessLogFileResult, type ProcessQueueCallbacks, type ProcessingState, type ProviderRequestCorrelation, type QueueableTurn, type ReasoningLevelMap, type ResolveConformanceTestPresetOptions, type ResolveHints, type ResolvedConformanceTestPreset, SESSION_CLOSED_QUEUE_ERROR, type ScopedBusFor, type ScopedToolApprovalRequest, type ScopedToolApprovalResponse, ScopedToolApprovalSchema, type SendMessageOptions, type SendMessageRequest, type SendMessageResponse, type SerializedContextBlock, SessionLifecycle, SessionToolLedger, type ShouldUseNativeResumeFn, type StartAgentOptions, type StartAgentRequest, type StartAgentResponse, type StorageMessagePayload, type SyncDiscriminatedHandler, type SyncDiscriminatedHandlersConfig, type SyncDiscriminatedHandlersMap, type SyncTypedEmitFn, type TestModelRef, type ToGlobalToolApprovalFn, type ToolApprovalContext, ToolCallTracker, type ToolCompletedEvent, ToolCompletedEventSchema, type ToolLedgerEntry, type ToolStartedEvent, ToolStartedEventSchema, type TurnEvent, type TurnState, type TurnSubjects, TurnTracker, type TurnTrackerOptions, type TurnTrackerSerializedState, TurnTrackerSerializedStateSchema, type TypedEmitFn, UserMessageQueue, type ValidCapability, type WireSessionConfig, type WireSessionSubjects, bindProviderRequestCorrelation, buildFactoryUsageCorrelationHeaders, cleanEnvForAdapter, createAdapterNamespace, createTestProviderContext, createToolApprovalHandler, defineDiscriminatedHandlers, defineDiscriminatedHandlersSync, extractMcpCallTarget, formatContextBlockAsText, formatContextBlocksAsText, formatMessageHistoryAsTranscript, isMcpCallTool, isTextLikeMimeType, markCompletedWithFinalResult, mergeScopedToolApproval, normalizeEnvValue, normalizeMessageInput, normalizeMimeType, parseAIAdapterCapabilities, processDiscriminatedItems, processDiscriminatedItemsSync, processQueueMessages, registerAgentBusHandlers, registerMemoryImportCursorStorage, rejectQueuedHandles, resolveConformanceTestPreset, resolveDisabledNativeTools, resolvePresetCredentials, resolveRequiredSessionId, resolveTestConfig, safeJsonStringify, serializeBlockToText, serializeTurnContext, toImportSegment };