@kb-labs/agent-contracts 2.118.2 → 2.119.0-canary.cee505c72

package/dist/index.d.ts

@@ -715,8 +715,47 @@ interface Turn {
         runId?: string;
         /** Summary of files changed during this turn (populated on run completion) */
         fileChanges?: FileChangeSummary[];
+        /**
+         * Client-generated id echoed back on user turns, so the frontend can
+         * reconcile its optimistic message by id instead of fuzzy text-matching.
+         */
+        clientId?: string;
     };
 }
+/**
+ * Incremental change to a Turn, addressed by the session's monotonic `seq`.
+ * The server emits these instead of resending the full Turn on every event —
+ * the client applies them as ordered patches against its local turn map.
+ * `turn:created` carries the turn WITHOUT steps; steps arrive via their own
+ * `turn:step:appended` deltas (including any present at creation time).
+ */
+type TurnDelta = {
+    kind: 'turn:created';
+    seq: number;
+    turn: Turn;
+} | {
+    kind: 'turn:step:appended';
+    seq: number;
+    turnId: string;
+    step: TurnStep;
+} | {
+    kind: 'turn:step:updated';
+    seq: number;
+    turnId: string;
+    step: TurnStep;
+} | {
+    kind: 'turn:status';
+    seq: number;
+    turnId: string;
+    status: Turn['status'];
+    completedAt: string | null;
+    error?: Turn['error'];
+} | {
+    kind: 'turn:metadata';
+    seq: number;
+    turnId: string;
+    patch: Partial<Turn['metadata']>;
+};
 /**
  * A step is a single action within a turn.
  * Maps to event types from the event stream.
@@ -2435,6 +2474,14 @@ interface RunCompletedMessage {
         success: boolean;
         summary: string;
         durationMs: number;
+        /** Session-wide cursor value for this event, for gap detection. */
+        seq: number;
+        /**
+         * Final state of the assistant turn this run produced, if any. Carried
+         * here so the client has a guaranteed-fresh terminal state without
+         * depending on the ordering of a separate delta message arriving first.
+         */
+        turn?: Turn;
     };
     timestamp: number;
 }
@@ -2463,32 +2510,37 @@ interface CorrectionAckMessage {
     timestamp: number;
 }
 /**
- * Turn snapshot message (server → client)
- * Sent whenever a turn is created or updated (incremental updates)
+ * Turn delta message (server → client)
+ * Sent for every incremental change to a turn's projection. This is the
+ * SOLE live-update channel — the client applies deltas as ordered patches
+ * against its local turn map, gated by `delta.seq`. Replaces the previous
+ * full-Turn-per-event `turn:snapshot` message.
  */
-interface TurnSnapshotMessage {
-    type: 'turn:snapshot';
+interface TurnDeltaMessage {
+    type: 'turn:delta';
     payload: {
         sessionId: string;
-        turn: Turn;
-        sequenceNumber: number;
+        delta: TurnDelta;
     };
     timestamp: number;
 }
 /**
  * Conversation snapshot message (server → client)
- * Sent on initial WebSocket connection to provide recent history
+ * Sent on initial WebSocket connection (or reconnect without a resume
+ * cursor) to provide the full current projection as a cold-start baseline.
  */
 interface ConversationSnapshotMessage {
     type: 'conversation:snapshot';
     payload: {
         sessionId: string;
-        /** Recent completed turns (last 20) */
+        /** Recent completed turns */
         completedTurns: Turn[];
         /** Currently streaming turns */
         activeTurns: Turn[];
         /** Total turns in session */
         totalTurns: number;
+        /** Session-wide cursor value this snapshot was taken at. */
+        seq: number;
         /** Snapshot timestamp */
         timestamp: string;
     };
@@ -2497,7 +2549,7 @@ interface ConversationSnapshotMessage {
 /**
  * Union of all server → client messages
  */
-type ServerMessage = ConnectionReadyMessage | RunCompletedMessage | ErrorMessage | CorrectionAckMessage | TurnSnapshotMessage | ConversationSnapshotMessage;
+type ServerMessage = ConnectionReadyMessage | RunCompletedMessage | ErrorMessage | CorrectionAckMessage | TurnDeltaMessage | ConversationSnapshotMessage;
 /**
  * User correction message (client → server)
  * User sends a correction/feedback to the orchestrator
@@ -2558,6 +2610,12 @@ interface RunRequest {
     smartTiering?: AgentSmartTieringConfig;
     /** Answer style depth (auto/brief/deep) */
     responseMode?: AgentResponseMode;
+    /**
+     * Client-generated id for the optimistic user message this run represents.
+     * Echoed back on `RunResponse.userTurn.metadata.clientId` so the frontend
+     * can reconcile its optimistic turn by id instead of text-matching.
+     */
+    clientId?: string;
 }
 /**
  * Response for POST /run
@@ -2576,6 +2634,12 @@ interface RunResponse {
     status: 'started' | 'queued';
     /** Timestamp */
     startedAt: string;
+    /**
+     * The persisted user turn this run created, returned synchronously so the
+     * frontend can reconcile its optimistic message immediately by id/clientId
+     * without waiting on a WS round-trip.
+     */
+    userTurn: Turn;
 }
 /**
  * Request body for POST /run/:runId/correct
@@ -3652,4 +3716,4 @@ interface SpawnAgentResult {
     preset: SubAgentPreset;
 }
 
-export { AGENTS_BASE_PATH, AGENTS_ROUTES, AGENTS_WS_BASE_PATH, AGENTS_WS_CHANNELS, AGENT_ANALYTICS_EVENTS, AGENT_MODES, type AgentAnalyticsEvent, type AgentConfig, type AgentEndEvent, type AgentErrorEvent, type AgentEvent, type AgentEventBase, type AgentEventCallback, type AgentEventEmitter, type AgentEventType, type AgentMemory, type AgentMode, type AgentResponseMode, type AgentSession, type AgentSessionInfo, type AgentSmartTieringConfig, type AgentSpecBudgetConfig, type AgentSpecification, type AgentStartEvent, type AgentTokenBudgetConfig, type AgentsPluginConfig, type AnalyzeResponse, type ApproveSessionPlanRequest, type ApproveSessionPlanResponse, type ArchiveEntry, type ArchiveStoreEvent, type AssumptionRecord, type AsyncTask, type AsyncTaskStatus, type BaseTraceEntry, type ClaimVerificationResult, type ClientMessage, type CompareResponse, type ConflictInfo, type ConflictResolutionConfig, type ConnectionReadyMessage, type ContextSnapshotEvent, type ContextTrimEvent, type ControlAction, type ConversationSnapshotMessage, type CorrectionAckMessage, type CorrectionRecord, type CorrectionRequest, type CorrectionResponse, type CreateSessionRequest, type CreateSessionResponse, DEFAULT_AGENT_TOKEN_BUDGET_CONFIG, DEFAULT_FEATURE_FLAGS, DEFAULT_FILE_HISTORY_CONFIG, DEFAULT_VERIFICATION_THRESHOLDS, type DebugContext, type DecisionPointEvent, type DecisionRecord, type DecompositionDecision, type DecompositionTaskType, type DetailedTraceEntry, type EditContext, type ErrorCapturedEvent, type ErrorMessage, type ErrorStep, type EscalationLevelConfig, type EscalationPolicy, type EvidenceRecord, type EvidenceRequirements, type ExecuteContext, type ExecuteSessionPlanRequest, type ExecuteSessionPlanResponse, type ExecutionMode, type ExecutionPlan, type ExportResponse, type FactAddedEvent, type FactCategory, type FactSheetEntry, type FeatureFlags, type FileChangeSummary, type FileHistoryConfig, type FileHistoryStorageConfig, type FilterResponse, type GenerateSpecRequest, type GenerateSpecResponse, type GetSessionPlanResponse, type GetSessionRequest, type GetSessionResponse, type GetSpecResponse, type HumanEscalationConfig, type IterationDetailEvent, type IterationEndEvent, type IterationResponse, type IterationSnapshot, type IterationStartEvent, type KernelEntryKind, type KernelMemoryState, type KernelState, type LLMCallEvent, type LLMChunkEvent, type LLMDebugEvent, type LLMEndEvent, type LLMStartEvent, type LLMStreamEvent, type LLMTier, type LLMValidationEvent, type ListAgentsResponse, type ListSessionsRequest, type ListSessionsResponse, type LoopResult, type MemoryCategory, type MemoryConfig, type MemoryEntry, type MemoryReadEvent, type MemoryRollup, type MemorySnapshotEvent, type MemorySummary, type MemoryWriteEvent, type MiddlewareConfig, type MiddlewareDecisionEvent, type MiddlewareFailPolicy, type ModeConfig, type ModeContext, type OpenQuestionRecord, type PackedTool, type PendingActionRecord, type PersistentMemory, type Phase, type PingMessage, type PlanContext, type PlanUpdate, type PlanUpdateAction, type ProgressUpdateEvent, type ProjectContext, type PromptContextSelection, type PromptDiffEvent, type QualityMetrics, type ReflectionResult, type ReplayResponse, type RepositoryConventions, type RepositoryFingerprints, type RepositoryModel, type RepositorySignal, type RepositoryStack, type RepositoryTopology, type RepositoryWorkspaceLayout, type ResolvedTool, type ResultProcessor, type RollbackResult, type RoutingHints, type RunCompletedMessage, type RunEvaluation, type RunEvaluationRecommendation, type RunHandoff, type RunRequest, type RunResponse, type RunStatusResponse, type RuntimeTurnRecord, type ServerMessage, type SessionEntry, type SessionProgress, type SessionSnapshot, type SnapshotResponse, type SpawnAgentRequest, type SpawnAgentResult, type SpecChange, type SpecSection, type StatsResponse, type StatusChangeEvent, type Step, type StopConditionResult, StopPriority, type StopRequest, type StopRequestMessage, type StopResponse, type StoppingAnalysisEvent, type SubAgentPreset, type SubAgentStep, type Subtask, type SubtaskEndEvent, type SubtaskStartEvent, type SummarizationLLMCallEvent, type SummarizationResultEvent, type SynthesisCompleteEvent, type SynthesisForcedEvent, type SynthesisForcedTraceEvent, type SynthesisStartEvent, TASK_STATUSES, TODO_PRIORITIES, TODO_STATUSES, type TailResponse, type TaskEndEvent, type TaskPlan, type TaskResult, type TaskSpec, type TaskStartEvent, type TaskStatus, type TextStep, type ThinkingChunkEvent, type ThinkingEndEvent, type ThinkingStartEvent, type ThinkingStep, type TodoItem, type TodoList, type TodoPriority, type TodoStatus, type ToolCall, type ToolCallRecord, type ToolCapability, type ToolConflictPolicy, type ToolDefinition, type ToolEndEvent, type ToolErrorEvent, type ToolEventMetadata, type ToolExecutionEvent, type ToolFilter, type ToolFilterEvent, type ToolPack, type ToolPermissions, type ToolResult, type ToolResultArtifact, type ToolResultRecord, type ToolResultStep, type ToolResultsSummary, type ToolStartEvent, type ToolUseStep, type TraceCommandResponse, type TraceEntry, type TraceErrorCode, TraceErrorCodes, type TraceEventType, type Tracer, type Turn, type TurnInterpretation, type TurnKind, type TurnSnapshotMessage, type TurnStep, type TwoTierMemoryConfig, type UserCorrectionMessage, type VerificationCompleteEvent, type VerificationEventData, type VerificationInput, type VerificationOutput, type VerificationResult, type VerificationStartEvent, type VerificationThresholds, type VerificationWarning, type VerificationWarningCode, buildRestRoute, buildWsChannel, schemas };
+export { AGENTS_BASE_PATH, AGENTS_ROUTES, AGENTS_WS_BASE_PATH, AGENTS_WS_CHANNELS, AGENT_ANALYTICS_EVENTS, AGENT_MODES, type AgentAnalyticsEvent, type AgentConfig, type AgentEndEvent, type AgentErrorEvent, type AgentEvent, type AgentEventBase, type AgentEventCallback, type AgentEventEmitter, type AgentEventType, type AgentMemory, type AgentMode, type AgentResponseMode, type AgentSession, type AgentSessionInfo, type AgentSmartTieringConfig, type AgentSpecBudgetConfig, type AgentSpecification, type AgentStartEvent, type AgentTokenBudgetConfig, type AgentsPluginConfig, type AnalyzeResponse, type ApproveSessionPlanRequest, type ApproveSessionPlanResponse, type ArchiveEntry, type ArchiveStoreEvent, type AssumptionRecord, type AsyncTask, type AsyncTaskStatus, type BaseTraceEntry, type ClaimVerificationResult, type ClientMessage, type CompareResponse, type ConflictInfo, type ConflictResolutionConfig, type ConnectionReadyMessage, type ContextSnapshotEvent, type ContextTrimEvent, type ControlAction, type ConversationSnapshotMessage, type CorrectionAckMessage, type CorrectionRecord, type CorrectionRequest, type CorrectionResponse, type CreateSessionRequest, type CreateSessionResponse, DEFAULT_AGENT_TOKEN_BUDGET_CONFIG, DEFAULT_FEATURE_FLAGS, DEFAULT_FILE_HISTORY_CONFIG, DEFAULT_VERIFICATION_THRESHOLDS, type DebugContext, type DecisionPointEvent, type DecisionRecord, type DecompositionDecision, type DecompositionTaskType, type DetailedTraceEntry, type EditContext, type ErrorCapturedEvent, type ErrorMessage, type ErrorStep, type EscalationLevelConfig, type EscalationPolicy, type EvidenceRecord, type EvidenceRequirements, type ExecuteContext, type ExecuteSessionPlanRequest, type ExecuteSessionPlanResponse, type ExecutionMode, type ExecutionPlan, type ExportResponse, type FactAddedEvent, type FactCategory, type FactSheetEntry, type FeatureFlags, type FileChangeSummary, type FileHistoryConfig, type FileHistoryStorageConfig, type FilterResponse, type GenerateSpecRequest, type GenerateSpecResponse, type GetSessionPlanResponse, type GetSessionRequest, type GetSessionResponse, type GetSpecResponse, type HumanEscalationConfig, type IterationDetailEvent, type IterationEndEvent, type IterationResponse, type IterationSnapshot, type IterationStartEvent, type KernelEntryKind, type KernelMemoryState, type KernelState, type LLMCallEvent, type LLMChunkEvent, type LLMDebugEvent, type LLMEndEvent, type LLMStartEvent, type LLMStreamEvent, type LLMTier, type LLMValidationEvent, type ListAgentsResponse, type ListSessionsRequest, type ListSessionsResponse, type LoopResult, type MemoryCategory, type MemoryConfig, type MemoryEntry, type MemoryReadEvent, type MemoryRollup, type MemorySnapshotEvent, type MemorySummary, type MemoryWriteEvent, type MiddlewareConfig, type MiddlewareDecisionEvent, type MiddlewareFailPolicy, type ModeConfig, type ModeContext, type OpenQuestionRecord, type PackedTool, type PendingActionRecord, type PersistentMemory, type Phase, type PingMessage, type PlanContext, type PlanUpdate, type PlanUpdateAction, type ProgressUpdateEvent, type ProjectContext, type PromptContextSelection, type PromptDiffEvent, type QualityMetrics, type ReflectionResult, type ReplayResponse, type RepositoryConventions, type RepositoryFingerprints, type RepositoryModel, type RepositorySignal, type RepositoryStack, type RepositoryTopology, type RepositoryWorkspaceLayout, type ResolvedTool, type ResultProcessor, type RollbackResult, type RoutingHints, type RunCompletedMessage, type RunEvaluation, type RunEvaluationRecommendation, type RunHandoff, type RunRequest, type RunResponse, type RunStatusResponse, type RuntimeTurnRecord, type ServerMessage, type SessionEntry, type SessionProgress, type SessionSnapshot, type SnapshotResponse, type SpawnAgentRequest, type SpawnAgentResult, type SpecChange, type SpecSection, type StatsResponse, type StatusChangeEvent, type Step, type StopConditionResult, StopPriority, type StopRequest, type StopRequestMessage, type StopResponse, type StoppingAnalysisEvent, type SubAgentPreset, type SubAgentStep, type Subtask, type SubtaskEndEvent, type SubtaskStartEvent, type SummarizationLLMCallEvent, type SummarizationResultEvent, type SynthesisCompleteEvent, type SynthesisForcedEvent, type SynthesisForcedTraceEvent, type SynthesisStartEvent, TASK_STATUSES, TODO_PRIORITIES, TODO_STATUSES, type TailResponse, type TaskEndEvent, type TaskPlan, type TaskResult, type TaskSpec, type TaskStartEvent, type TaskStatus, type TextStep, type ThinkingChunkEvent, type ThinkingEndEvent, type ThinkingStartEvent, type ThinkingStep, type TodoItem, type TodoList, type TodoPriority, type TodoStatus, type ToolCall, type ToolCallRecord, type ToolCapability, type ToolConflictPolicy, type ToolDefinition, type ToolEndEvent, type ToolErrorEvent, type ToolEventMetadata, type ToolExecutionEvent, type ToolFilter, type ToolFilterEvent, type ToolPack, type ToolPermissions, type ToolResult, type ToolResultArtifact, type ToolResultRecord, type ToolResultStep, type ToolResultsSummary, type ToolStartEvent, type ToolUseStep, type TraceCommandResponse, type TraceEntry, type TraceErrorCode, TraceErrorCodes, type TraceEventType, type Tracer, type Turn, type TurnDelta, type TurnDeltaMessage, type TurnInterpretation, type TurnKind, type TurnStep, type TwoTierMemoryConfig, type UserCorrectionMessage, type VerificationCompleteEvent, type VerificationEventData, type VerificationInput, type VerificationOutput, type VerificationResult, type VerificationStartEvent, type VerificationThresholds, type VerificationWarning, type VerificationWarningCode, buildRestRoute, buildWsChannel, schemas };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kb-labs/agent-contracts",
   "description": "Type definitions and contracts for KB Labs Agents. IDs, Session, Specification, Gates, Multi-Agent types.",
-  "version": "2.118.2",
+  "version": "2.119.0-canary.cee505c72",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",