@meistrari/agent-core 0.2.0-experimental.1 → 0.2.0-experimental.2

package/src/protocol/agent-event.ts

@@ -7,6 +7,7 @@ import { agentToolCallStatusSchema, agentToolResultSchema } from './agent-tool'
 import { agentUsageAccountingSchema, agentUsageSchema } from './agent-usage'
 import { agentUserInputAnswersSchema, agentUserInputQuestionSchema } from './agent-user-input'
 import { agentWorkObservationSchema } from './agent-work'
+import { objectRejectingKeys } from './rejected-keys'
 
 export interface AgentError {
     message: string
@@ -17,12 +18,12 @@ export interface AgentError {
 }
 
 export const agentErrorSchema: z.ZodType<AgentError> = z.object({
-    message: z.string().min(1),
+    message: z.string(),
     code: z.string().min(1).optional(),
     name: z.string().min(1).optional(),
     stack: z.string().min(1).optional(),
     cause: z.lazy(() => agentErrorSchema).optional(),
-}).strict()
+})
 
 export const agentMessageRoleSchema = z.enum(['user', 'assistant', 'system'])
 export const agentSessionEndReasonSchema = z.enum(['completed', 'stopped', 'interrupted', 'failed'])
@@ -31,41 +32,53 @@ export const agentTurnEndStatusSchema = z.enum(['completed', 'failed', 'cancelle
 export const agentSubagentStatusSchema = z.enum(['completed', 'failed', 'cancelled'])
 export const agentContextCompactionTriggerSchema = z.enum(['manual', 'auto', 'unknown'])
 export const agentContextCompactionStatusSchema = z.enum(['completed', 'failed'])
+export const agentContextCompactionRequestResultSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('completed') }),
+    z.object({ status: z.literal('no_op'), reason: z.string() }),
+    z.object({ status: z.literal('failed'), error: agentErrorSchema }),
+    z.object({ status: z.literal('unknown') }),
+])
 export const agentErrorSourceSchema = z.enum(['provider', 'runtime', 'transport', 'unknown'])
 export const agentSkillScopeSchema = z.enum(['user', 'repository', 'system', 'admin'])
 
-export const agentSkillSchema = z.object({
+export const agentSkillSchema = z.strictObject({
     id: z.string().min(1),
     name: z.string().min(1),
     description: z.string().min(1),
     scope: agentSkillScopeSchema,
-}).strict()
+})
+
+const wireAgentSkillSchema = agentSkillSchema.strip()
 
-export const agentEventBaseSchema = z.object({
+// Provider turn identity never crosses this boundary; only the canonical turnId does.
+export const agentEventBaseSchema = objectRejectingKeys({
     eventId: z.string().min(1),
     provider: agentProviderIdSchema,
     sessionId: z.string().min(1),
     providerSessionId: z.string().min(1),
     timestamp: z.string().datetime(),
     sequence: z.number().int().nonnegative(),
-}).strict()
+}, ['providerTurnId'])
+
+// Session-scoped events are never turn- or actor-attributed; those keys are rejected, not stripped.
+const agentSessionEventBaseSchema = objectRejectingKeys(agentEventBaseSchema.shape, ['turnId', 'actor'])
 
 export const agentEventActorOriginSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('tool_call'),
         toolCallId: z.string().min(1),
-    }).strict(),
+    }),
     z.object({
         type: z.literal('provider_task'),
         taskId: z.string().min(1),
-    }).strict(),
+    }),
 ])
 
 export const agentEventActorSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('main'),
         actorId: z.literal('main'),
-    }).strict(),
+    }),
     z.object({
         type: z.literal('subagent'),
         actorId: z.string().min(1),
@@ -74,7 +87,7 @@ export const agentEventActorSchema = z.discriminatedUnion('type', [
         origin: agentEventActorOriginSchema,
         parentToolCallId: z.string().min(1).optional(),
         name: z.string().min(1).optional(),
-    }).strict(),
+    }),
 ])
 
 const subagentRefSchema = z.object({
@@ -84,19 +97,19 @@ const subagentRefSchema = z.object({
     origin: agentEventActorOriginSchema,
     parentToolCallId: z.string().min(1).optional(),
     name: z.string().min(1).optional(),
-}).strict()
+})
 
 export const agentTurnEventBaseSchema = agentEventBaseSchema.extend({
     turnId: z.string().min(1),
     actor: agentEventActorSchema,
-}).strict()
+})
 
-export const sessionStartedAgentEventSchema = agentEventBaseSchema.extend({
+export const sessionStartedAgentEventSchema = agentSessionEventBaseSchema.extend({
     type: z.literal('session.started'),
     payload: agentRunMetadataSchema,
-}).strict()
+})
 
-export const sessionConfiguredAgentEventSchema = agentEventBaseSchema.extend({
+export const sessionConfiguredAgentEventSchema = agentSessionEventBaseSchema.extend({
     type: z.literal('session.configured'),
     payload: z.object({
         model: z.string().min(1),
@@ -105,55 +118,84 @@ export const sessionConfiguredAgentEventSchema = agentEventBaseSchema.extend({
         tools: z.array(z.string().min(1)),
         reasoningEffort: z.string().min(1).optional(),
         environment: z.record(z.string().min(1), z.literal('[REDACTED]')),
-    }).strict(),
-}).strict()
+    }),
+})
+
+export const agentSettingsAppliesFromSchema = z.enum(['current_turn', 'next_turn'])
+
+export const currentTurnUnavailableReasonMaxLength = 300
 
-export const sessionSkillsUpdatedAgentEventSchema = agentEventBaseSchema.extend({
+// The session's current model and effort after a prompt changed them. `appliesFrom` states whether the
+// turn that handles that prompt runs on them. `current_turn`: it does, whether a steer switched the
+// running turn or the prompt started its own turn; `turnId` is that turn when the provider knows it.
+// `next_turn`: a steer could not switch the running turn, so the settings apply from the following turn.
+// `currentTurnUnavailableReason` is the provider's own diagnostic text, truncated, for why the running
+// turn could not change; only with `next_turn`, and only when the provider gave one.
+export const sessionSettingsChangedAgentEventSchema = agentSessionEventBaseSchema.extend({
+    type: z.literal('session.settings.changed'),
+    payload: z.object({
+        model: z.string().min(1),
+        reasoningEffort: z.string().min(1).optional(),
+        commandId: z.string().min(1),
+        turnId: z.string().min(1).optional(),
+        appliesFrom: agentSettingsAppliesFromSchema,
+        currentTurnUnavailableReason: z.string().min(1).max(currentTurnUnavailableReasonMaxLength).optional(),
+    }),
+})
+
+export const sessionSkillsUpdatedAgentEventSchema = agentSessionEventBaseSchema.extend({
     type: z.literal('session.skills.updated'),
     payload: z.object({
-        skills: z.array(agentSkillSchema),
-    }).strict(),
-}).strict()
+        skills: z.array(wireAgentSkillSchema),
+    }),
+})
 
-export const sessionStateChangedAgentEventSchema = agentEventBaseSchema.extend({
+export const sessionStateChangedAgentEventSchema = agentSessionEventBaseSchema.extend({
     type: z.literal('session.state.changed'),
     payload: z.object({
         state: agentSessionStateSchema,
         error: agentErrorSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
-export const sessionEndedAgentEventSchema = agentEventBaseSchema.extend({
+export const sessionEndedAgentEventSchema = agentSessionEventBaseSchema.extend({
     type: z.literal('session.ended'),
     payload: z.object({
         reason: agentSessionEndReasonSchema,
         exitCode: z.number().int().nullable().optional(),
         signal: z.string().min(1).nullable().optional(),
         error: agentErrorSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const turnStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('turn.started'),
-    payload: z.object({ commandId: z.string().min(1).optional() }).strict(),
-}).strict()
+    payload: z.object({ commandId: z.string().min(1).optional() }),
+})
+
+// Provider-confirmed input consumption; distinct from acceptance receipts.
+export const promptTurnCorrelatedAgentEventSchema = agentSessionEventBaseSchema.extend({
+    type: z.literal('prompt.turn-correlated'),
+    payload: z.object({ commandId: z.string().min(1), turnId: z.string().min(1) }),
+})
 
 export const turnEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('turn.ended'),
-    payload: z.object({
+    // Usage is reported only through the dedicated `usage` event.
+    payload: objectRejectingKeys({
         status: agentTurnEndStatusSchema,
         reason: z.string().min(1).optional(),
         error: agentErrorSchema.optional(),
         duration: z.number().int().nonnegative().optional(),
-    }).strict(),
-}).strict()
+    }, ['usage']),
+})
 
 export const workObservedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('work.observed'),
     payload: z.object({
         observations: z.array(agentWorkObservationSchema).min(1),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const messageStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('message.started'),
@@ -161,17 +203,18 @@ export const messageStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
         messageId: z.string().min(1),
         role: agentMessageRoleSchema,
         commandId: z.string().min(1).optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const messageDeltaAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('message.delta'),
-    payload: z.object({
+    // Command association belongs to message.started/ended only.
+    payload: objectRejectingKeys({
         messageId: z.string().min(1),
         role: agentMessageRoleSchema,
         delta: z.string(),
-    }).strict(),
-}).strict()
+    }, ['commandId']),
+})
 
 export const messageEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('message.ended'),
@@ -181,31 +224,31 @@ export const messageEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
         text: z.string().optional(),
         commandId: z.string().min(1).optional(),
         overflow: agentPayloadOverflowSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const reasoningStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('reasoning.started'),
     payload: z.object({
         reasoningId: z.string().min(1),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const reasoningSummaryDeltaAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('reasoning.summary.delta'),
     payload: z.object({
         reasoningId: z.string().min(1),
         text: z.string(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const reasoningEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('reasoning.ended'),
     payload: z.object({
         reasoningId: z.string().min(1),
         summary: z.string().optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const toolCallStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('tool.call.started'),
@@ -213,34 +256,43 @@ export const toolCallStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
         toolCallId: z.string().min(1),
         toolName: z.string().min(1),
         input: jsonValueSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const toolOutputDeltaAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('tool.output.delta'),
     payload: z.object({
         toolCallId: z.string().min(1),
         delta: z.string(),
-    }).strict(),
-}).strict()
+    }),
+})
+
+export const toolOutputUpdatedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('tool.output.updated'),
+    payload: z.object({
+        toolCallId: z.string().min(1),
+        output: agentToolResultSchema,
+    }),
+})
 
 export const toolCallCompletedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('tool.call.completed'),
     payload: z.object({
         toolCallId: z.string().min(1),
+        toolName: z.string().min(1).optional(),
         status: agentToolCallStatusSchema,
         output: agentToolResultSchema.optional(),
         error: agentErrorSchema.optional(),
         overflow: agentPayloadOverflowSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const subagentStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('subagent.started'),
     payload: subagentRefSchema.extend({
         description: z.string().min(1).optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const subagentProgressAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('subagent.progress'),
@@ -248,8 +300,8 @@ export const subagentProgressAgentEventSchema = agentTurnEventBaseSchema.extend(
         summary: z.string().min(1).optional(),
         lastToolName: z.string().min(1).optional(),
         usage: agentUsageSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const subagentEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('subagent.ended'),
@@ -258,24 +310,84 @@ export const subagentEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
         summary: z.string().optional(),
         usage: agentUsageSchema.optional(),
         error: agentErrorSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const usageAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('usage'),
     payload: z.object({
         usage: agentUsageSchema,
         accounting: agentUsageAccountingSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
+
+export type AgentContextWindow
+    = | { status: 'unknown' }
+        | { status: 'known', capacityTokens: number, remainingPercent: number }
+
+export type AgentContextSnapshot
+    = | { status: 'unknown' }
+        | { status: 'observed', usedTokens: number, window: AgentContextWindow }
+
+const knownAgentContextWindowShape = {
+    status: z.literal('known'),
+    capacityTokens: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    remainingPercent: z.number().int().min(0).max(100),
+}
+
+export const agentContextWindowSchema: z.ZodType<AgentContextWindow> = z.discriminatedUnion('status', [
+    z.strictObject({ status: z.literal('unknown') }),
+    z.strictObject(knownAgentContextWindowShape),
+])
+
+const wireAgentContextWindowSchema: z.ZodType<AgentContextWindow> = z.discriminatedUnion('status', [
+    z.object({
+        status: z.literal('unknown'),
+        capacityTokens: z.never().optional(),
+        remainingPercent: z.never().optional(),
+    }),
+    z.object(knownAgentContextWindowShape),
+])
+
+export const agentContextSnapshotSchema: z.ZodType<AgentContextSnapshot> = z.discriminatedUnion('status', [
+    z.strictObject({ status: z.literal('unknown') }),
+    z.strictObject({
+        status: z.literal('observed'),
+        usedTokens: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+        window: agentContextWindowSchema,
+    }),
+])
+
+const wireAgentContextSnapshotSchema: z.ZodType<AgentContextSnapshot> = z.discriminatedUnion('status', [
+    z.object({
+        status: z.literal('unknown'),
+        usedTokens: z.never().optional(),
+        window: z.never().optional(),
+        providerModel: z.never().optional(),
+    }),
+    z.object({
+        status: z.literal('observed'),
+        usedTokens: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+        window: wireAgentContextWindowSchema,
+        // Provider model identity is not part of the provider-neutral snapshot.
+        providerModel: z.never().optional(),
+    }),
+])
+
+export const contextUpdatedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('context.updated'),
+    payload: z.object({
+        snapshot: wireAgentContextSnapshotSchema,
+    }),
+})
 
 export const contextCompactionStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('context.compaction.started'),
     payload: z.object({
         compactionId: z.string().min(1),
         trigger: agentContextCompactionTriggerSchema,
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const contextCompactionCompletedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('context.compaction.completed'),
@@ -287,8 +399,16 @@ export const contextCompactionCompletedAgentEventSchema = agentTurnEventBaseSche
         inputTokensBefore: z.number().int().nonnegative().optional(),
         inputTokensAfter: z.number().int().nonnegative().optional(),
         error: agentErrorSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
+
+export const contextCompactionRequestCompletedAgentEventSchema = agentSessionEventBaseSchema.extend({
+    type: z.literal('context.compaction.request.completed'),
+    payload: z.object({
+        commandId: z.string().min(1),
+        result: agentContextCompactionRequestResultSchema,
+    }),
+})
 
 export const userInputRequestedAgentEventSchema = agentTurnEventBaseSchema.extend({
     type: z.literal('user-input.requested'),
@@ -297,36 +417,38 @@ export const userInputRequestedAgentEventSchema = agentTurnEventBaseSchema.exten
         toolCallId: z.string().min(1),
         prompt: z.string().min(1),
         questions: z.array(agentUserInputQuestionSchema).min(1),
-    }).strict(),
-}).strict()
+    }),
+})
 
-export const userInputResolvedAgentEventSchema = agentEventBaseSchema.extend({
+export const userInputResolvedAgentEventSchema = agentSessionEventBaseSchema.extend({
     type: z.literal('user-input.resolved'),
     payload: z.object({
         requestId: z.string().min(1),
         requestedTurnId: z.string().min(1),
         toolCallId: z.string().min(1),
         answers: agentUserInputAnswersSchema,
-    }).strict(),
-}).strict()
+    }),
+})
 
-export const errorAgentEventSchema = agentEventBaseSchema.extend({
+export const errorAgentEventSchema = agentSessionEventBaseSchema.extend({
     type: z.literal('error'),
     payload: z.object({
         message: z.string().min(1),
         fatal: z.boolean(),
         source: agentErrorSourceSchema.optional(),
         error: agentErrorSchema.optional(),
-    }).strict(),
-}).strict()
+    }),
+})
 
 export const agentEventSchema = z.discriminatedUnion('type', [
     sessionStartedAgentEventSchema,
     sessionConfiguredAgentEventSchema,
+    sessionSettingsChangedAgentEventSchema,
     sessionSkillsUpdatedAgentEventSchema,
     sessionStateChangedAgentEventSchema,
     sessionEndedAgentEventSchema,
     turnStartedAgentEventSchema,
+    promptTurnCorrelatedAgentEventSchema,
     turnEndedAgentEventSchema,
     workObservedAgentEventSchema,
     messageStartedAgentEventSchema,
@@ -338,12 +460,15 @@ export const agentEventSchema = z.discriminatedUnion('type', [
     toolCallStartedAgentEventSchema,
     toolOutputDeltaAgentEventSchema,
     toolCallCompletedAgentEventSchema,
+    toolOutputUpdatedAgentEventSchema,
     subagentStartedAgentEventSchema,
     subagentProgressAgentEventSchema,
     subagentEndedAgentEventSchema,
     usageAgentEventSchema,
+    contextUpdatedAgentEventSchema,
     contextCompactionStartedAgentEventSchema,
     contextCompactionCompletedAgentEventSchema,
+    contextCompactionRequestCompletedAgentEventSchema,
     userInputRequestedAgentEventSchema,
     userInputResolvedAgentEventSchema,
     errorAgentEventSchema,
@@ -356,6 +481,7 @@ export type AgentTurnEndStatus = z.infer<typeof agentTurnEndStatusSchema>
 export type AgentSubagentStatus = z.infer<typeof agentSubagentStatusSchema>
 export type AgentContextCompactionTrigger = z.infer<typeof agentContextCompactionTriggerSchema>
 export type AgentContextCompactionStatus = z.infer<typeof agentContextCompactionStatusSchema>
+export type AgentContextCompactionRequestResult = z.infer<typeof agentContextCompactionRequestResultSchema>
 export type AgentErrorSource = z.infer<typeof agentErrorSourceSchema>
 export type AgentSkillScope = z.infer<typeof agentSkillScopeSchema>
 export type AgentSkill = z.infer<typeof agentSkillSchema>
@@ -365,6 +491,8 @@ export type AgentEventBase = z.infer<typeof agentEventBaseSchema>
 export type AgentTurnEventBase = z.infer<typeof agentTurnEventBaseSchema>
 export type SessionStartedAgentEvent = z.infer<typeof sessionStartedAgentEventSchema>
 export type SessionConfiguredAgentEvent = z.infer<typeof sessionConfiguredAgentEventSchema>
+export type AgentSettingsAppliesFrom = z.infer<typeof agentSettingsAppliesFromSchema>
+export type SessionSettingsChangedAgentEvent = z.infer<typeof sessionSettingsChangedAgentEventSchema>
 export type SessionSkillsUpdatedAgentEvent = z.infer<typeof sessionSkillsUpdatedAgentEventSchema>
 export type SessionStateChangedAgentEvent = z.infer<typeof sessionStateChangedAgentEventSchema>
 export type SessionEndedAgentEvent = z.infer<typeof sessionEndedAgentEventSchema>
@@ -380,13 +508,22 @@ export type ReasoningEndedAgentEvent = z.infer<typeof reasoningEndedAgentEventSc
 export type ToolCallStartedAgentEvent = z.infer<typeof toolCallStartedAgentEventSchema>
 export type ToolOutputDeltaAgentEvent = z.infer<typeof toolOutputDeltaAgentEventSchema>
 export type ToolCallCompletedAgentEvent = z.infer<typeof toolCallCompletedAgentEventSchema>
+export type ToolOutputUpdatedAgentEvent = z.infer<typeof toolOutputUpdatedAgentEventSchema>
 export type SubagentStartedAgentEvent = z.infer<typeof subagentStartedAgentEventSchema>
 export type SubagentProgressAgentEvent = z.infer<typeof subagentProgressAgentEventSchema>
 export type SubagentEndedAgentEvent = z.infer<typeof subagentEndedAgentEventSchema>
 export type UsageAgentEvent = z.infer<typeof usageAgentEventSchema>
+export type ContextUpdatedAgentEvent = z.infer<typeof contextUpdatedAgentEventSchema>
 export type ContextCompactionStartedAgentEvent = z.infer<typeof contextCompactionStartedAgentEventSchema>
 export type ContextCompactionCompletedAgentEvent = z.infer<typeof contextCompactionCompletedAgentEventSchema>
+export type ContextCompactionRequestCompletedAgentEvent = z.infer<typeof contextCompactionRequestCompletedAgentEventSchema>
 export type UserInputRequestedAgentEvent = z.infer<typeof userInputRequestedAgentEventSchema>
 export type UserInputResolvedAgentEvent = z.infer<typeof userInputResolvedAgentEventSchema>
 export type ErrorAgentEvent = z.infer<typeof errorAgentEventSchema>
 export type AgentEvent = z.infer<typeof agentEventSchema>
+
+export const agentEventTypes: readonly AgentEvent['type'][] = agentEventSchema.options.map(
+    schema => schema.shape.type.value,
+)
+
+export type PromptTurnCorrelatedAgentEvent = z.infer<typeof promptTurnCorrelatedAgentEventSchema>

package/src/protocol/agent-identity.ts

@@ -0,0 +1,29 @@
+import type { AgentEventActor, AgentEventBase } from './agent-event'
+
+export type AgentSubagentIdentity = Pick<Extract<AgentEventActor, { type: 'subagent' }>, 'actorId' | 'subagentId' | 'parentActorId' | 'origin' | 'parentToolCallId'>
+
+export function normalizeAgentSubagentIdentity(identity: AgentSubagentIdentity): AgentSubagentIdentity {
+    return {
+        actorId: identity.actorId,
+        subagentId: identity.subagentId,
+        parentActorId: identity.parentActorId,
+        origin: identity.origin,
+        parentToolCallId: identity.parentToolCallId ?? (identity.origin.type === 'tool_call' ? identity.origin.toolCallId : undefined),
+    }
+}
+
+export function agentSubagentIdentitiesEqual(left: AgentSubagentIdentity, right: AgentSubagentIdentity): boolean {
+    const normalizedLeft = normalizeAgentSubagentIdentity(left)
+    const normalizedRight = normalizeAgentSubagentIdentity(right)
+    return normalizedLeft.actorId === normalizedRight.actorId
+        && normalizedLeft.subagentId === normalizedRight.subagentId
+        && normalizedLeft.parentActorId === normalizedRight.parentActorId
+        && normalizedLeft.parentToolCallId === normalizedRight.parentToolCallId
+        && (normalizedLeft.origin.type === 'tool_call'
+            ? normalizedRight.origin.type === 'tool_call' && normalizedLeft.origin.toolCallId === normalizedRight.origin.toolCallId
+            : normalizedRight.origin.type === 'provider_task' && normalizedLeft.origin.taskId === normalizedRight.origin.taskId)
+}
+
+export function agentRuntimeIdentityKey(event: Pick<AgentEventBase, 'sessionId' | 'providerSessionId'>): string {
+    return `${event.sessionId.length}:${event.sessionId}:${event.providerSessionId.length}:${event.providerSessionId}`
+}