@sentry/junior 0.137.0 → 0.138.0

package/dist/chunk-ZBSMCXKV.js

@@ -0,0 +1,710 @@
+import {
+  appendAndEnqueueInboundMessage
+} from "./chunk-5LTJ4ITU.js";
+import {
+  ConversationTurnLifecycleService
+} from "./chunk-Q6QZTTLS.js";
+import {
+  AgentInvocationBusyError,
+  AgentInvocationLimitError,
+  AuthorizationFlowDisabledError,
+  PluginCredentialFailureError,
+  agentBindingSchema,
+  agentInvocationSchema,
+  createAgentInvocationSchema
+} from "./chunk-LPVUNO2W.js";
+import {
+  TurnInputCommitLostError,
+  coerceThreadArtifactsState,
+  failAgentTurnSessionRecord,
+  getAgentTurnSessionRecord,
+  getAssistantReplyText,
+  getConversationTurnBoundaryError,
+  getPersistedSandboxState,
+  getPersistedThreadState,
+  getTerminalAssistantMessages,
+  isTurnInputCommitLostError,
+  openConversationProjection,
+  persistCompletedSessionRecord,
+  persistThreadStateById,
+  persistYieldSessionRecord
+} from "./chunk-TUUDXEXU.js";
+import {
+  getConversationEventStore,
+  getConversationStore,
+  getSqlExecutor
+} from "./chunk-SIPKWSXK.js";
+import {
+  juniorAgentBindings,
+  juniorAgentInvocations
+} from "./chunk-DCLLQGS6.js";
+
+// src/chat/agent-invocations/work.ts
+import { z } from "zod";
+
+// src/chat/agent-invocations/store.ts
+import { createHash } from "crypto";
+import { and, asc, count, eq, inArray } from "drizzle-orm";
+var CREATE_LOCK_PREFIX = "junior:agent_invocation:create";
+var MAX_ACTIVE_AGENT_INVOCATIONS_PER_PARENT = 8;
+var TERMINAL_AGENT_INVOCATION_STATUSES = [
+  "blocked",
+  "completed",
+  "failed"
+];
+var NON_TERMINAL_AGENT_INVOCATION_STATUSES = [
+  "pending",
+  "running",
+  "awaiting_resume"
+];
+function stableId(prefix, ...parts) {
+  const digest = createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 32);
+  return `${prefix}:${digest}`;
+}
+function getAgentInvocationId(parentConversationId, idempotencyKey) {
+  return stableId("agent-invocation", parentConversationId, idempotencyKey);
+}
+function getUnnamedAgentConversationId(invocationId) {
+  return stableId("agent", invocationId);
+}
+function getNamedAgentConversationId(parentConversationId, name) {
+  return stableId("agent", parentConversationId, name);
+}
+function getAgentInvocationTurnId(invocationId) {
+  return `agent-invocation:${invocationId}`;
+}
+function getAgentInvocationMessageId(invocationId) {
+  return `agent-invocation:${invocationId}:input`;
+}
+function bindingFromRow(row) {
+  return agentBindingSchema.parse({
+    childConversationId: row.childConversationId,
+    name: row.name,
+    parentConversationId: row.parentConversationId
+  });
+}
+function invocationFromRow(row) {
+  return agentInvocationSchema.parse({
+    actor: row.actor,
+    ...row.agentName ? { agentName: row.agentName } : {},
+    childConversationId: row.childConversationId,
+    createdAtMs: row.createdAt.getTime(),
+    ...row.credentialContext ? { credentialContext: row.credentialContext } : {},
+    destination: row.destination,
+    ...row.destinationVisibility ? { destinationVisibility: row.destinationVisibility } : {},
+    ...row.errorMessage !== null ? { errorMessage: row.errorMessage } : {},
+    input: row.input,
+    invocationId: row.invocationId,
+    mailboxStatus: row.mailboxStatus,
+    parentConversationId: row.parentConversationId,
+    ...row.reasoningLevel ? { reasoningLevel: row.reasoningLevel } : {},
+    ...row.result !== null ? { result: row.result } : {},
+    source: row.source,
+    status: row.status,
+    ...row.terminalAt ? { terminalAtMs: row.terminalAt.getTime() } : {},
+    updatedAtMs: row.updatedAt.getTime()
+  });
+}
+function sameCreateInput(invocation, input) {
+  return invocation.parentConversationId === input.parentConversationId && invocation.agentName === input.agentName && invocation.input === input.input && invocation.reasoningLevel === input.reasoningLevel && JSON.stringify(invocation.actor) === JSON.stringify(input.actor) && JSON.stringify(invocation.credentialContext) === JSON.stringify(input.credentialContext) && JSON.stringify(invocation.destination) === JSON.stringify(input.destination) && invocation.destinationVisibility === input.destinationVisibility && JSON.stringify(invocation.source) === JSON.stringify(input.source);
+}
+async function getAgentBinding(args) {
+  const rows = await getSqlExecutor().db().select().from(juniorAgentBindings).where(
+    and(
+      eq(juniorAgentBindings.parentConversationId, args.parentConversationId),
+      eq(juniorAgentBindings.name, args.name)
+    )
+  );
+  return rows[0] ? bindingFromRow(rows[0]) : void 0;
+}
+async function getAgentInvocation(invocationId) {
+  const rows = await getSqlExecutor().db().select().from(juniorAgentInvocations).where(eq(juniorAgentInvocations.invocationId, invocationId));
+  return rows[0] ? invocationFromRow(rows[0]) : void 0;
+}
+async function getActiveAgentInvocationForConversation(childConversationId) {
+  const rows = await getSqlExecutor().db().select().from(juniorAgentInvocations).where(
+    and(
+      eq(juniorAgentInvocations.childConversationId, childConversationId),
+      inArray(juniorAgentInvocations.status, ["running", "awaiting_resume"])
+    )
+  ).orderBy(asc(juniorAgentInvocations.createdAt)).limit(2);
+  if (rows.length > 1) {
+    throw new Error(
+      `Child conversation ${childConversationId} has multiple active agent invocations`
+    );
+  }
+  return rows[0] ? invocationFromRow(rows[0]) : void 0;
+}
+async function getNonTerminalAgentInvocationForConversation(childConversationId) {
+  const rows = await getSqlExecutor().db().select().from(juniorAgentInvocations).where(
+    and(
+      eq(juniorAgentInvocations.childConversationId, childConversationId),
+      inArray(
+        juniorAgentInvocations.status,
+        NON_TERMINAL_AGENT_INVOCATION_STATUSES
+      )
+    )
+  ).orderBy(asc(juniorAgentInvocations.createdAt)).limit(1);
+  return rows[0] ? invocationFromRow(rows[0]) : void 0;
+}
+async function countNonTerminalAgentInvocationsForParent(parentConversationId) {
+  const rows = await getSqlExecutor().db().select({ value: count() }).from(juniorAgentInvocations).where(
+    and(
+      eq(juniorAgentInvocations.parentConversationId, parentConversationId),
+      inArray(
+        juniorAgentInvocations.status,
+        NON_TERMINAL_AGENT_INVOCATION_STATUSES
+      )
+    )
+  );
+  return rows[0]?.value ?? 0;
+}
+async function createAgentInvocation(rawInput, nowMs = Date.now()) {
+  const input = createAgentInvocationSchema.parse(rawInput);
+  const invocationId = getAgentInvocationId(
+    input.parentConversationId,
+    input.idempotencyKey
+  );
+  const childConversationId = input.agentName ? getNamedAgentConversationId(input.parentConversationId, input.agentName) : getUnnamedAgentConversationId(invocationId);
+  const lockName = `${CREATE_LOCK_PREFIX}:${input.parentConversationId}`;
+  return await getSqlExecutor().withLock(lockName, async () => {
+    const existing = await getAgentInvocation(invocationId);
+    if (existing) {
+      if (!sameCreateInput(existing, input)) {
+        throw new Error(
+          `Agent invocation idempotency key was reused with different input for ${invocationId}`
+        );
+      }
+      return existing;
+    }
+    const activeCount = await countNonTerminalAgentInvocationsForParent(
+      input.parentConversationId
+    );
+    if (activeCount >= MAX_ACTIVE_AGENT_INVOCATIONS_PER_PARENT) {
+      throw new AgentInvocationLimitError(
+        MAX_ACTIVE_AGENT_INVOCATIONS_PER_PARENT
+      );
+    }
+    await getConversationStore().createChild({
+      childConversationId,
+      parentConversationId: input.parentConversationId,
+      nowMs,
+      source: "internal"
+    });
+    if (input.agentName) {
+      await getSqlExecutor().db().insert(juniorAgentBindings).values({
+        childConversationId,
+        name: input.agentName,
+        parentConversationId: input.parentConversationId
+      }).onConflictDoNothing();
+      const binding = await getAgentBinding({
+        name: input.agentName,
+        parentConversationId: input.parentConversationId
+      });
+      if (!binding || binding.childConversationId !== childConversationId) {
+        throw new Error(
+          `Named agent binding did not resolve to ${childConversationId}`
+        );
+      }
+      if (await getNonTerminalAgentInvocationForConversation(childConversationId)) {
+        throw new AgentInvocationBusyError(input.agentName);
+      }
+    }
+    await getSqlExecutor().db().insert(juniorAgentInvocations).values({
+      invocationId,
+      parentConversationId: input.parentConversationId,
+      childConversationId,
+      agentName: input.agentName ?? null,
+      input: input.input,
+      actor: input.actor,
+      credentialContext: input.credentialContext ?? null,
+      source: input.source,
+      destination: input.destination,
+      destinationVisibility: input.destinationVisibility ?? null,
+      reasoningLevel: input.reasoningLevel ?? null,
+      status: "pending",
+      mailboxStatus: "pending",
+      createdAt: new Date(nowMs),
+      updatedAt: new Date(nowMs),
+      terminalAt: null
+    }).onConflictDoNothing();
+    const invocation = await getAgentInvocation(invocationId);
+    if (!invocation || !sameCreateInput(invocation, input)) {
+      throw new Error(`Agent invocation creation raced for ${invocationId}`);
+    }
+    return invocation;
+  });
+}
+async function listPendingAgentInvocationMailboxAppends(limit = 100) {
+  const rows = await getSqlExecutor().db().select().from(juniorAgentInvocations).where(eq(juniorAgentInvocations.mailboxStatus, "pending")).orderBy(asc(juniorAgentInvocations.createdAt)).limit(limit);
+  return rows.map(invocationFromRow);
+}
+async function markAgentInvocationMailboxAppended(invocationId, nowMs = Date.now()) {
+  await getSqlExecutor().db().update(juniorAgentInvocations).set({ mailboxStatus: "appended", updatedAt: new Date(nowMs) }).where(eq(juniorAgentInvocations.invocationId, invocationId));
+}
+async function markAgentInvocationRunning(invocationId, nowMs = Date.now()) {
+  await getSqlExecutor().db().update(juniorAgentInvocations).set({ status: "running", updatedAt: new Date(nowMs) }).where(
+    and(
+      eq(juniorAgentInvocations.invocationId, invocationId),
+      inArray(
+        juniorAgentInvocations.status,
+        NON_TERMINAL_AGENT_INVOCATION_STATUSES
+      )
+    )
+  );
+  return await getAgentInvocation(invocationId);
+}
+async function markAgentInvocationAwaitingResume(invocationId, nowMs = Date.now()) {
+  await getSqlExecutor().db().update(juniorAgentInvocations).set({ status: "awaiting_resume", updatedAt: new Date(nowMs) }).where(
+    and(
+      eq(juniorAgentInvocations.invocationId, invocationId),
+      inArray(
+        juniorAgentInvocations.status,
+        NON_TERMINAL_AGENT_INVOCATION_STATUSES
+      )
+    )
+  );
+}
+async function completeAgentInvocation(args) {
+  const nowMs = args.nowMs ?? Date.now();
+  await getSqlExecutor().db().update(juniorAgentInvocations).set({
+    status: args.status,
+    result: args.status === "completed" ? args.result : null,
+    errorMessage: args.status === "completed" ? null : args.errorMessage,
+    terminalAt: new Date(nowMs),
+    updatedAt: new Date(nowMs)
+  }).where(
+    and(
+      eq(juniorAgentInvocations.invocationId, args.invocationId),
+      inArray(
+        juniorAgentInvocations.status,
+        NON_TERMINAL_AGENT_INVOCATION_STATUSES
+      )
+    )
+  );
+  return await getAgentInvocation(args.invocationId);
+}
+function isTerminalAgentInvocation(invocation) {
+  return TERMINAL_AGENT_INVOCATION_STATUSES.includes(
+    invocation.status
+  );
+}
+
+// src/chat/agent-invocations/work.ts
+var agentInvocationMailboxMetadataSchema = z.object({
+  agentInvocationId: z.string().min(1),
+  kind: z.literal("agent_invocation")
+}).strict();
+function buildAgentInvocationInboundMessage(invocation, nowMs = Date.now()) {
+  return {
+    conversationId: invocation.childConversationId,
+    createdAtMs: invocation.createdAtMs,
+    delivery: "defer",
+    inboundMessageId: getAgentInvocationMessageId(invocation.invocationId),
+    input: {
+      authorId: invocation.invocationId,
+      text: "[agent invocation]",
+      metadata: {
+        agentInvocationId: invocation.invocationId,
+        kind: "agent_invocation"
+      }
+    },
+    receivedAtMs: nowMs,
+    source: "internal"
+  };
+}
+async function enqueueAgentInvocation(invocation, options) {
+  if (invocation.mailboxStatus === "appended") {
+    return;
+  }
+  const nowMs = options.nowMs ?? Date.now();
+  await appendAndEnqueueInboundMessage({
+    message: buildAgentInvocationInboundMessage(invocation, nowMs),
+    conversationStore: options.conversationStore,
+    nowMs,
+    queue: options.queue,
+    state: options.state
+  });
+  await markAgentInvocationMailboxAppended(invocation.invocationId, nowMs);
+}
+async function createAndEnqueueAgentInvocation(input, options) {
+  const invocation = await createAgentInvocation(input, options.nowMs);
+  await enqueueAgentInvocation(invocation, options);
+  return await getAgentInvocation(invocation.invocationId) ?? invocation;
+}
+function invocationIdFromMessages(messages) {
+  if (messages.length === 0) {
+    return void 0;
+  }
+  const parsed = messages.map(
+    (message) => agentInvocationMailboxMetadataSchema.safeParse(message.input.metadata)
+  );
+  if (parsed.every((result) => !result.success)) {
+    return void 0;
+  }
+  if (parsed.some((result) => !result.success)) {
+    throw new Error(
+      "Conversation mailbox mixes agent invocation and other input"
+    );
+  }
+  const invocationIds = new Set(
+    parsed.map((result) => {
+      if (!result.success) {
+        throw new Error("Agent invocation mailbox metadata failed validation");
+      }
+      return result.data.agentInvocationId;
+    })
+  );
+  if (invocationIds.size !== 1) {
+    throw new Error(
+      "Conversation mailbox contains multiple agent invocations in one attempt"
+    );
+  }
+  return invocationIds.values().next().value;
+}
+async function resolveAgentInvocationId(context) {
+  const mailboxInvocationId = invocationIdFromMessages(
+    context.attempt.messages
+  );
+  if (mailboxInvocationId) {
+    return mailboxInvocationId;
+  }
+  if (context.attempt.messages.length > 0) {
+    return void 0;
+  }
+  return (await getActiveAgentInvocationForConversation(context.conversationId))?.invocationId;
+}
+async function persistTerminalLifecycle(invocation) {
+  const lifecycle = new ConversationTurnLifecycleService(
+    getConversationEventStore()
+  );
+  const common = {
+    conversationId: invocation.childConversationId,
+    createdAtMs: "terminalAtMs" in invocation ? invocation.terminalAtMs : invocation.updatedAtMs,
+    turnId: getAgentInvocationTurnId(invocation.invocationId)
+  };
+  if (invocation.status === "completed") {
+    await lifecycle.complete({
+      ...common,
+      outcome: invocation.result?.trim() ? "success" : "no_reply"
+    });
+  } else if (invocation.status === "blocked" || invocation.status === "failed") {
+    await lifecycle.fail({
+      ...common,
+      failureCode: "model_execution_failed"
+    });
+  }
+}
+async function projectTerminalSession(invocation) {
+  const session = await getAgentTurnSessionRecord(
+    invocation.childConversationId,
+    getAgentInvocationTurnId(invocation.invocationId)
+  );
+  if (!session) {
+    return void 0;
+  }
+  if (session.state === "awaiting_resume" || session.state === "running") {
+    return void 0;
+  }
+  const result = getTerminalAssistantMessages(session.piMessages).map(getAssistantReplyText).filter((text) => text !== void 0).join("\n\n");
+  const failed = session.state !== "completed" || Boolean(session.errorMessage);
+  return await completeAgentInvocation({
+    invocationId: invocation.invocationId,
+    ...failed ? {
+      errorMessage: session.errorMessage ?? "Agent invocation failed",
+      status: "failed"
+    } : {
+      result,
+      status: "completed"
+    }
+  });
+}
+async function recoverRunningSession(invocation) {
+  const session = await getAgentTurnSessionRecord(
+    invocation.childConversationId,
+    getAgentInvocationTurnId(invocation.invocationId)
+  );
+  if (!session || session.state !== "running") {
+    return;
+  }
+  if (!session.modelId) {
+    await failAgentTurnSessionRecord({
+      conversationId: invocation.childConversationId,
+      expectedVersion: session.version,
+      sessionId: session.sessionId,
+      errorMessage: `Running agent invocation session is missing its model for ${invocation.invocationId}`
+    });
+    return;
+  }
+  const parked = await persistYieldSessionRecord({
+    conversationId: invocation.childConversationId,
+    currentSliceId: session.sliceId,
+    errorMessage: "Recovered running agent invocation after worker loss",
+    messages: session.piMessages,
+    modelId: session.modelId,
+    actor: session.actor,
+    reasoningLevel: session.reasoningLevel,
+    sessionId: session.sessionId,
+    surface: session.surface
+  });
+  if (!parked) {
+    await failAgentTurnSessionRecord({
+      conversationId: invocation.childConversationId,
+      expectedVersion: session.version,
+      sessionId: session.sessionId,
+      errorMessage: `Running agent invocation had no resumable boundary for ${invocation.invocationId}`
+    });
+    return;
+  }
+  await markAgentInvocationAwaitingResume(invocation.invocationId);
+}
+function blockingInvocationError(error) {
+  const cause = getConversationTurnBoundaryError(error)?.cause ?? error;
+  return cause instanceof AuthorizationFlowDisabledError || cause instanceof PluginCredentialFailureError ? cause : void 0;
+}
+function isInvocationInputCommitLost(error) {
+  const cause = getConversationTurnBoundaryError(error)?.cause ?? error;
+  return isTurnInputCommitLostError(cause);
+}
+function createAgentInvocationWorker(options) {
+  return async (context, invocationId) => {
+    let invocation = await getAgentInvocation(invocationId);
+    if (!invocation) {
+      throw new Error(`Agent invocation is missing for ${invocationId}`);
+    }
+    let acknowledged = context.attempt.messages.length === 0;
+    const acknowledge = async () => {
+      if (acknowledged) {
+        return;
+      }
+      try {
+        await context.attempt.ack();
+      } catch {
+        throw new TurnInputCommitLostError(
+          `Conversation work lease lost before invocation inbox ack for ${context.conversationId}`
+        );
+      }
+      acknowledged = true;
+    };
+    const turnId = getAgentInvocationTurnId(invocation.invocationId);
+    const lifecycle = new ConversationTurnLifecycleService(
+      getConversationEventStore()
+    );
+    let artifacts;
+    let sandboxRef;
+    let history;
+    try {
+      if (invocation.childConversationId !== context.conversationId) {
+        throw new Error(
+          `Agent invocation ${invocationId} belongs to ${invocation.childConversationId}, not ${context.conversationId}`
+        );
+      }
+      if (context.destination) {
+        throw new Error(
+          `Agent invocation conversation ${context.conversationId} must not own a provider destination`
+        );
+      }
+      if (isTerminalAgentInvocation(invocation)) {
+        await persistTerminalLifecycle(invocation);
+        await acknowledge();
+        return { status: "completed" };
+      }
+      await recoverRunningSession(invocation);
+      const projected = await projectTerminalSession(invocation);
+      if (projected && isTerminalAgentInvocation(projected)) {
+        await persistTerminalLifecycle(projected);
+        await acknowledge();
+        return { status: "completed" };
+      }
+      invocation = await markAgentInvocationRunning(invocation.invocationId) ?? invocation;
+      await lifecycle.start({
+        conversationId: invocation.childConversationId,
+        createdAtMs: invocation.createdAtMs,
+        inputMessageIds: [getAgentInvocationMessageId(invocation.invocationId)],
+        surface: "internal",
+        turnId
+      });
+      const [persisted, projection] = await Promise.all([
+        getPersistedThreadState(invocation.childConversationId),
+        openConversationProjection({
+          conversationId: invocation.childConversationId
+        })
+      ]);
+      artifacts = coerceThreadArtifactsState(persisted);
+      sandboxRef = getPersistedSandboxState(persisted);
+      history = projection.messages;
+    } catch (error) {
+      if (isInvocationInputCommitLost(error)) {
+        return { status: "lost_lease" };
+      }
+      if (!context.attempt.isFinalAttempt) {
+        throw error;
+      }
+      const terminal2 = await completeAgentInvocation({
+        invocationId: invocation.invocationId,
+        errorMessage: error instanceof Error ? error.message : "Agent invocation failed",
+        status: "failed"
+      });
+      if (terminal2) {
+        await persistTerminalLifecycle(terminal2);
+      }
+      await acknowledge();
+      return { status: "completed" };
+    }
+    let outcome;
+    try {
+      outcome = await options.agentRunner.run({
+        conversationId: invocation.childConversationId,
+        turnId,
+        runId: invocation.invocationId,
+        input: {
+          messageText: invocation.input,
+          piMessages: history
+        },
+        routing: {
+          actor: invocation.actor,
+          credentialContext: invocation.credentialContext,
+          destination: invocation.destination,
+          destinationVisibility: invocation.destinationVisibility,
+          source: invocation.source,
+          surface: "internal"
+        },
+        policy: {
+          // TODO(#881, #883): Child runs may still need a path to force
+          // interactive auth when a delegated tool requires credentials the
+          // parent already has authority to request. Today background children
+          // hard-fail instead of pausing for an OAuth link.
+          disabledFeatures: ["handoff", "interactive-auth", "subagents"],
+          reasoningLevel: invocation.reasoningLevel
+        },
+        state: {
+          artifactState: artifacts,
+          sandboxRef
+        },
+        durability: {
+          onInputCommitted: acknowledge,
+          shouldYield: context.shouldYield,
+          onArtifactStateUpdated: async (nextArtifacts) => {
+            artifacts = nextArtifacts;
+            await persistThreadStateById(invocation.childConversationId, {
+              artifacts,
+              sandboxRef
+            });
+          },
+          onSandboxRefChanged: async (nextSandboxRef) => {
+            sandboxRef = nextSandboxRef;
+            await persistThreadStateById(invocation.childConversationId, {
+              artifacts,
+              sandboxRef
+            });
+          }
+        }
+      });
+    } catch (error) {
+      if (isInvocationInputCommitLost(error)) {
+        return { status: "lost_lease" };
+      }
+      const blocking = blockingInvocationError(error);
+      if (blocking) {
+        const terminal3 = await completeAgentInvocation({
+          invocationId: invocation.invocationId,
+          errorMessage: blocking.message,
+          status: "blocked"
+        });
+        if (terminal3) {
+          await persistTerminalLifecycle(terminal3);
+        }
+        await acknowledge();
+        return { status: "completed" };
+      }
+      if (!context.attempt.isFinalAttempt) {
+        throw error;
+      }
+      const terminal2 = await completeAgentInvocation({
+        invocationId: invocation.invocationId,
+        errorMessage: error instanceof Error ? error.message : "Agent invocation failed",
+        status: "failed"
+      });
+      if (terminal2) {
+        await persistTerminalLifecycle(terminal2);
+      }
+      await acknowledge();
+      return { status: "completed" };
+    }
+    if (outcome.status === "suspended") {
+      await markAgentInvocationAwaitingResume(invocation.invocationId);
+      return { status: "yielded" };
+    }
+    if (outcome.status === "awaiting_auth") {
+      const terminal2 = await completeAgentInvocation({
+        invocationId: invocation.invocationId,
+        errorMessage: `Agent invocation requires ${outcome.providerDisplayName} authorization`,
+        status: "blocked"
+      });
+      if (terminal2) {
+        await persistTerminalLifecycle(terminal2);
+      }
+      await acknowledge();
+      return { status: "completed" };
+    }
+    const result = outcome.result;
+    const failed = result.diagnostics.outcome !== "success";
+    await persistThreadStateById(invocation.childConversationId, {
+      artifacts: result.artifactStatePatch ? { ...artifacts, ...result.artifactStatePatch } : artifacts,
+      sandboxRef: result.sandboxRef ?? sandboxRef
+    });
+    if (result.piMessages?.length) {
+      await persistCompletedSessionRecord({
+        conversationId: invocation.childConversationId,
+        currentDurationMs: result.diagnostics.durationMs,
+        currentUsage: result.diagnostics.usage,
+        destination: invocation.destination,
+        destinationVisibility: invocation.destinationVisibility,
+        ...failed ? {
+          errorMessage: result.diagnostics.errorMessage ?? "Agent invocation failed"
+        } : {},
+        sessionId: turnId,
+        allMessages: result.piMessages,
+        modelId: result.diagnostics.modelId,
+        actor: invocation.actor,
+        reasoningLevel: result.diagnostics.reasoningLevel,
+        source: invocation.source,
+        surface: "internal"
+      });
+    }
+    const terminal = await completeAgentInvocation({
+      invocationId: invocation.invocationId,
+      ...failed ? {
+        errorMessage: result.diagnostics.errorMessage ?? "Agent invocation failed",
+        status: "failed"
+      } : {
+        result: result.text,
+        status: "completed"
+      }
+    });
+    if (!terminal) {
+      throw new Error(
+        `Agent invocation disappeared during completion for ${invocation.invocationId}`
+      );
+    }
+    await persistTerminalLifecycle(terminal);
+    await acknowledge();
+    return { status: "completed" };
+  };
+}
+function routeAgentInvocationWork(options) {
+  return async (context) => {
+    const invocationId = await resolveAgentInvocationId(context);
+    return invocationId ? await options.invocationWorker(context, invocationId) : await options.fallbackWorker(context);
+  };
+}
+
+export {
+  listPendingAgentInvocationMailboxAppends,
+  buildAgentInvocationInboundMessage,
+  enqueueAgentInvocation,
+  createAndEnqueueAgentInvocation,
+  resolveAgentInvocationId,
+  createAgentInvocationWorker,
+  routeAgentInvocationWork
+};