@sentry/junior 0.261.0 → 0.263.0

package/dist/store-TKg1HVKx.js

@@ -0,0 +1,697 @@
+import { l as TURN_REASONING_LEVELS, s as modelProfileSchema } from "./model-profile-Bg8EoCKD.js";
+import { f as getSqlExecutor, u as getConversationStore } from "./viewer-DmNRM88V.js";
+import { a as juniorAgentInvocations, i as juniorAgentBindings, n as AGENT_INVOCATION_PARENT_MAILBOX_STATUSES, t as AGENT_INVOCATION_MAILBOX_STATUSES } from "./agent-invocations-CxKldAeB.js";
+import "./executor-J9k2sp9m.js";
+import { p as credentialContextSchema } from "./registry-BFzQFV_y.js";
+import { z } from "zod";
+import { createHash } from "node:crypto";
+import { and, asc, count, countDistinct, desc, eq, inArray, lt, ne, or, sql } from "drizzle-orm";
+import { actorSchema, destinationSchema, sourceSchema } from "@sentry/junior-plugin-api";
+// src/chat/runtime/turn.ts
+/** Classified Slack turn failure carrying the owning Sentry capture outward. */
+var ConversationTurnBoundaryError = class extends Error {
+	eventId;
+	failureCode;
+	constructor(args) {
+		super(args.cause instanceof Error ? args.cause.message : String(args.cause), { cause: args.cause });
+		this.name = "ConversationTurnBoundaryError";
+		this.eventId = args.eventId;
+		this.failureCode = args.failureCode;
+	}
+};
+/** Return a classified Slack boundary failure without erasing its cause. */
+function getConversationTurnBoundaryError(error) {
+	return error instanceof ConversationTurnBoundaryError ? error : void 0;
+}
+/**
+* Queue-worker yield routing: respond.ts returns a suspended AgentRunOutcome
+* and the Slack executor raises this at the worker boundary so the lease owner
+* requeues the conversation.
+*/
+var CooperativeTurnYieldError = class extends Error {
+	code = "cooperative_turn_yield";
+	constructor(message = "Agent turn yielded at a safe boundary") {
+		super(message);
+		this.name = "CooperativeTurnYieldError";
+	}
+};
+function isCooperativeTurnYieldError(error) {
+	return error instanceof CooperativeTurnYieldError;
+}
+/** Error indicating durable turn input could not be committed by the worker owner. */
+var TurnInputCommitLostError = class extends Error {
+	code = "turn_input_commit_lost";
+	constructor(message = "Turn input commit lost its durable owner") {
+		super(message);
+		this.name = "TurnInputCommitLostError";
+	}
+};
+/** Return whether an error means the durable worker lost input ownership. */
+function isTurnInputCommitLostError(error) {
+	return error instanceof TurnInputCommitLostError;
+}
+/** Error indicating durable turn input should stay pending for a later worker. */
+var TurnInputDeferredError = class extends Error {
+	code = "turn_input_deferred";
+	constructor(message = "Turn input is deferred until the active resume ends") {
+		super(message);
+		this.name = "TurnInputDeferredError";
+	}
+};
+/** Return whether an error means the durable worker should redeliver input later. */
+function isTurnInputDeferredError(error) {
+	return error instanceof TurnInputDeferredError;
+}
+/** Mark a turn as the active turn in conversation state. */
+function startActiveTurn(args) {
+	args.conversation.processing.activeTurnId = args.nextTurnId;
+}
+function clearActiveTurn(conversation, sessionId) {
+	if (!sessionId || conversation.processing.activeTurnId === sessionId) conversation.processing.activeTurnId = void 0;
+}
+/**
+* Close the active turn without marking a Pi session reusable for future
+* history. Use this for auth handoffs and recovery replies that end the live
+* turn but do not produce a completed Pi session.
+*/
+function markTurnClosed(args) {
+	clearActiveTurn(args.conversation, args.sessionId);
+	args.conversation.processing.lastCompletedAtMs = args.nowMs;
+}
+/**
+* Mark a turn as completed after its assistant output has been handled.
+*/
+function markTurnCompleted(args) {
+	clearActiveTurn(args.conversation, args.sessionId);
+	args.conversation.processing.lastCompletedAtMs = args.nowMs;
+}
+/**
+* Mark a turn as failed when execution or final user-visible reply delivery
+* cannot be completed. If `sessionId` is provided, `activeTurnId` is only
+* cleared when it still matches the failing turn.
+*/
+function markTurnFailed(args) {
+	clearActiveTurn(args.conversation, args.sessionId);
+	args.conversation.processing.lastCompletedAtMs = args.nowMs;
+	args.markConversationMessage(args.conversation, args.userMessageId, {
+		replied: false,
+		skippedReason: "reply failed"
+	});
+}
+// src/chat/agent-invocations/agent-types.ts
+/**
+* Child agent types. A type is plain data: when to pick it, whether the child
+* starts with its parent's history, and what it reads with its task. Runtime
+* code reads only these fields, never a type name, so types can later come
+* from configuration. Types do not limit tools: Guardian reviews each child
+* action against the root user's messages, as for any child. A child keeps its
+* type for later agent invocations, the same as its profile. A child without
+* a type starts fresh.
+*/
+const AGENT_TYPES = [
+	"fork",
+	"explore",
+	"reviewer"
+];
+/**
+* Stored name of a child agent type. Like a model profile, a stored name stays
+* readable after its type is removed; the runtime then treats the child as a
+* child without a type.
+*/
+const agentTypeSchema = z.string().regex(/^[a-z][a-z0-9_-]*$/);
+const AGENT_TYPE_DEFINITIONS = {
+	fork: {
+		whenToUse: "A copy of you. Use it when the brief would need most of what you already know, or when the intermediate tool output is not worth keeping in your context. The task is a directive: say what to do and what is in or out of scope; do not re-explain the background.",
+		startsWithParentHistory: true,
+		instructions: "You are a fork of your parent agent. The messages before your first parent task are copied from the parent's conversation so you have its context. They are not your job: your job is the parent task below. Sandbox files, approvals, and credentials of the parent were not copied, and your sandbox is separate. Verify files in your own sandbox before you use them."
+	},
+	explore: {
+		whenToUse: "Investigation across code, docs, logs, telemetry, or the web. Use it when an answer needs reading across many files or sources and you need the conclusion with evidence, not the raw output.",
+		startsWithParentHistory: false,
+		instructions: "You are an explore agent. Your job is to investigate and report, so do not change anything outside your sandbox unless the task asks for it. Report what you found with exact evidence, such as paths, lines, links, and ids, and say what you could not verify."
+	},
+	reviewer: {
+		whenToUse: "An independent second opinion on a change, plan, or claim. Give it the evidence to judge, not your conclusion.",
+		startsWithParentHistory: false,
+		instructions: "You are a reviewer agent. Give an independent assessment. Do not assume that the parent's framing is correct: verify each claim against the evidence. Do not change anything outside your own sandbox. Report concrete problems ranked by severity, each with its evidence, and say clearly when you found none."
+	}
+};
+function agentTypeDefinition(type) {
+	return type && Object.hasOwn(AGENT_TYPE_DEFINITIONS, type) ? AGENT_TYPE_DEFINITIONS[type] : void 0;
+}
+/** Model-facing list of child agent types, with how each child starts. */
+function formatAgentTypes() {
+	return AGENT_TYPES.map((type) => {
+		const definition = AGENT_TYPE_DEFINITIONS[type];
+		return `- "${type}"${definition.startsWithParentHistory ? " (starts with this conversation's history)" : ""}: ${definition.whenToUse}`;
+	}).join("\n");
+}
+/** Return whether a child of this type starts with its parent's history. */
+function agentTypeStartsWithParentHistory(type) {
+	return agentTypeDefinition(type)?.startsWithParentHistory ?? false;
+}
+/** Return the instructions that a child of this type reads with its task. */
+function agentTypeInstructions(type) {
+	return agentTypeDefinition(type)?.instructions;
+}
+// src/chat/agent-invocations/types.ts
+const exactStringSchema = z.string().min(1).refine((value) => value === value.trim());
+const agentNameSchema = exactStringSchema.max(64);
+/** `messageAgent` target for the parent of a child agent. */
+const PARENT_AGENT_TARGET = "parent";
+const agentInvocationMailboxStatusSchema = z.enum(AGENT_INVOCATION_MAILBOX_STATUSES);
+const agentInvocationParentMailboxStatusSchema = z.enum(AGENT_INVOCATION_PARENT_MAILBOX_STATUSES);
+const agentBindingSchema = z.object({
+	childConversationId: exactStringSchema,
+	name: agentNameSchema,
+	parentConversationId: exactStringSchema
+}).strict();
+const agentInvocationBaseSchema = z.object({
+	actor: actorSchema,
+	agentName: agentNameSchema.optional(),
+	childConversationId: exactStringSchema,
+	createdAtMs: z.number().finite(),
+	credentialContext: credentialContextSchema.optional(),
+	destination: destinationSchema,
+	input: exactStringSchema,
+	invocationId: exactStringSchema,
+	mailboxStatus: agentInvocationMailboxStatusSchema,
+	parentConversationId: exactStringSchema,
+	parentToolCallId: exactStringSchema.optional(),
+	agentType: agentTypeSchema.optional(),
+	modelProfile: modelProfileSchema.optional(),
+	reasoningLevel: z.enum(TURN_REASONING_LEVELS).optional(),
+	source: sourceSchema,
+	title: exactStringSchema.optional(),
+	updatedAtMs: z.number().finite()
+}).strict();
+const agentInvocationSchema = z.discriminatedUnion("status", [
+	agentInvocationBaseSchema.extend({ status: z.enum([
+		"pending",
+		"running",
+		"paused"
+	]) }),
+	agentInvocationBaseSchema.extend({
+		parentMailboxStatus: agentInvocationParentMailboxStatusSchema,
+		result: z.string(),
+		status: z.literal("completed"),
+		terminalAtMs: z.number().finite()
+	}),
+	agentInvocationBaseSchema.extend({
+		errorMessage: z.string(),
+		parentMailboxStatus: agentInvocationParentMailboxStatusSchema,
+		status: z.enum([
+			"blocked",
+			"failed",
+			"stopped"
+		]),
+		terminalAtMs: z.number().finite()
+	})
+]);
+const createAgentInvocationSchema = z.object({
+	actor: actorSchema,
+	agentName: agentNameSchema.optional(),
+	credentialContext: credentialContextSchema.optional(),
+	destination: destinationSchema,
+	idempotencyKey: exactStringSchema,
+	input: exactStringSchema,
+	parentConversationId: exactStringSchema,
+	parentToolCallId: exactStringSchema.optional(),
+	agentType: agentTypeSchema.optional(),
+	modelProfile: modelProfileSchema.optional(),
+	reasoningLevel: z.enum(TURN_REASONING_LEVELS).optional(),
+	title: exactStringSchema.optional()
+}).strict();
+/** How a finished task of a child agent ended. A stop is not a result. */
+const CHILD_AGENT_RESULTS = [
+	"completed",
+	"blocked",
+	"failed"
+];
+// src/chat/agent-invocations/errors.ts
+/** A child agent already uses this name in the parent Conversation. */
+var AgentNameInUseError = class extends Error {
+	constructor(name) {
+		super(`A child agent named "${name}" already exists`);
+		this.name = "AgentNameInUseError";
+	}
+};
+/** Parent already has the maximum number of non-terminal child invocations. */
+var AgentInvocationLimitError = class extends Error {
+	constructor(limit) {
+		super(`Parent already has ${limit} active child agent invocations (limit ${limit})`);
+		this.name = "AgentInvocationLimitError";
+	}
+};
+/** A child agent already has the maximum number of open tasks. */
+var AgentMessageQueueFullError = class extends Error {
+	constructor(limit) {
+		super(`The child agent already has ${limit} open tasks`);
+		this.name = "AgentMessageQueueFullError";
+	}
+};
+/** A messageAgent target is not the parent or a child of the sender. */
+var AgentMessageTargetError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AgentMessageTargetError";
+	}
+};
+// src/chat/agent-invocations/store.ts
+const CREATE_LOCK_PREFIX = "junior:agent_invocation:create";
+/**
+* Return the SQL lock that one parent Conversation takes to start, message,
+* or stop its child agents.
+*/
+function getChildAgentLockName(parentConversationId) {
+	return `${CREATE_LOCK_PREFIX}:${parentConversationId}`;
+}
+const TERMINAL_AGENT_INVOCATION_STATUSES = [
+	"blocked",
+	"completed",
+	"failed",
+	"stopped"
+];
+/** Statuses of an agent invocation that has not finished. */
+const NON_TERMINAL_AGENT_INVOCATION_STATUSES = [
+	"pending",
+	"running",
+	"paused"
+];
+function stableId(prefix, ...parts) {
+	return `${prefix}:${createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 32)}`;
+}
+/** Return the stable identity for one retry-safe delegated task. */
+function getAgentInvocationId(parentConversationId, idempotencyKey) {
+	return stableId("agent-invocation", parentConversationId, idempotencyKey);
+}
+/** Return the stable child identity for one invocation without a named binding. */
+function getUnnamedAgentConversationId(invocationId) {
+	return stableId("agent", invocationId);
+}
+/** Return the stable child identity for one named binding. */
+function getNamedAgentConversationId(parentConversationId, name) {
+	return stableId("agent", parentConversationId, name);
+}
+/**
+* Return the stable identity of the agent invocation that gives one child
+* agent result to the child Conversation that started that child agent.
+*/
+function getAgentInvocationIdForResult(resultInvocationId) {
+	return stableId("agent-invocation", "result", resultInvocationId);
+}
+/**
+* Return the stable identity of the agent invocation that gives one message
+* from a child agent to the child Conversation that started that child agent.
+*/
+function getAgentInvocationIdForMessage(messageId) {
+	return stableId("agent-invocation", "message", messageId);
+}
+/**
+* Return the stable identity of the agent invocation that gives one batch of
+* watch events to a child Conversation. The first message of the batch names
+* it.
+*/
+function getAgentInvocationIdForEvents(messageId) {
+	return stableId("agent-invocation", "events", messageId);
+}
+/** Return the stable turn identity advanced by one agent invocation. */
+function getAgentInvocationTurnId(invocationId) {
+	return `agent-invocation:${invocationId}`;
+}
+/** Return the stable mailbox identity for one agent invocation. */
+function getAgentInvocationMessageId(invocationId) {
+	return `agent-invocation:${invocationId}:input`;
+}
+const RESULT_MESSAGE_PREFIX = "agent-invocation:";
+const RESULT_MESSAGE_SUFFIX = ":result";
+/** Return the stable parent mailbox identity for one terminal result. */
+function getAgentInvocationResultMessageId(invocationId) {
+	return `${RESULT_MESSAGE_PREFIX}${invocationId}${RESULT_MESSAGE_SUFFIX}`;
+}
+/** Read the invocation identity from one parent result mailbox identity. */
+function parseAgentInvocationResultMessageId(messageId) {
+	if (!messageId.startsWith(RESULT_MESSAGE_PREFIX) || !messageId.endsWith(RESULT_MESSAGE_SUFFIX)) return;
+	return messageId.slice(17, -7) || void 0;
+}
+function bindingFromRow(row) {
+	return agentBindingSchema.parse({
+		childConversationId: row.childConversationId,
+		name: row.name,
+		parentConversationId: row.parentConversationId
+	});
+}
+/** Parse one agent invocation row. */
+function invocationFromRow(row) {
+	return agentInvocationSchema.parse({
+		actor: row.actor,
+		...row.agentName ? { agentName: row.agentName } : void 0,
+		childConversationId: row.childConversationId,
+		createdAtMs: row.createdAt.getTime(),
+		...row.credentialContext ? { credentialContext: row.credentialContext } : void 0,
+		destination: row.destination,
+		...row.errorMessage !== null ? { errorMessage: row.errorMessage } : void 0,
+		input: row.input,
+		invocationId: row.invocationId,
+		mailboxStatus: row.mailboxStatus,
+		parentConversationId: row.parentConversationId,
+		...row.parentMailboxStatus ? { parentMailboxStatus: row.parentMailboxStatus } : void 0,
+		...row.parentToolCallId ? { parentToolCallId: row.parentToolCallId } : void 0,
+		...row.agentType ? { agentType: row.agentType } : void 0,
+		...row.modelProfile ? { modelProfile: row.modelProfile } : void 0,
+		...row.reasoningLevel ? { reasoningLevel: row.reasoningLevel } : void 0,
+		...row.result !== null ? { result: row.result } : void 0,
+		source: row.source,
+		status: row.status,
+		...row.terminalAt ? { terminalAtMs: row.terminalAt.getTime() } : void 0,
+		...row.title ? { title: row.title } : void 0,
+		updatedAtMs: row.updatedAt.getTime()
+	});
+}
+/**
+* Require every durable creation input to match before replaying one key.
+* The title is not compared: a retry can generate a different one, and the
+* stored title wins.
+*/
+function sameCreateInput(invocation, input) {
+	return invocation.parentConversationId === input.parentConversationId && invocation.agentName === input.agentName && invocation.input === input.input && invocation.agentType === input.agentType && invocation.modelProfile === input.modelProfile && 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);
+}
+/** Read one named child binding in its parent-agent scope. */
+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;
+}
+/** Read one durable agent invocation. */
+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;
+}
+/** Resolve the single invocation that may resume for one child conversation. */
+async function getActiveAgentInvocationForConversation(childConversationId) {
+	const rows = await getSqlExecutor().db().select().from(juniorAgentInvocations).where(and(eq(juniorAgentInvocations.childConversationId, childConversationId), inArray(juniorAgentInvocations.status, ["running", "paused"]))).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;
+}
+/** Read the newest agent invocation of one child Conversation. */
+async function getLatestAgentInvocationForConversation(childConversationId) {
+	const rows = await getSqlExecutor().db().select().from(juniorAgentInvocations).where(eq(juniorAgentInvocations.childConversationId, childConversationId)).orderBy(desc(juniorAgentInvocations.createdAt)).limit(1);
+	return rows[0] ? invocationFromRow(rows[0]) : void 0;
+}
+/**
+* Read the name and the newest task title of one child Conversation, for
+* labels. Agent invocations that give a nested result to the child have no
+* title, so an agent invocation with a title comes first.
+*/
+async function getChildAgentLabel(childConversationId) {
+	const [row] = await getSqlExecutor().db().select({
+		agentName: juniorAgentInvocations.agentName,
+		title: juniorAgentInvocations.title
+	}).from(juniorAgentInvocations).where(eq(juniorAgentInvocations.childConversationId, childConversationId)).orderBy(sql`${juniorAgentInvocations.title} is null`, desc(juniorAgentInvocations.createdAt)).limit(1);
+	return row;
+}
+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 countNonTerminalAgentInvocationsForChild(childConversationId) {
+	return (await getSqlExecutor().db().select({ value: count() }).from(juniorAgentInvocations).where(and(eq(juniorAgentInvocations.childConversationId, childConversationId), inArray(juniorAgentInvocations.status, NON_TERMINAL_AGENT_INVOCATION_STATUSES))))[0]?.value ?? 0;
+}
+/**
+* A child agent can only start or give work to child agents while it has
+* open work. A stopped child has none. A root Conversation has no agent
+* invocation, so it always passes.
+*/
+async function assertCanGiveChildWork(parentConversationId) {
+	if (await getLatestAgentInvocationForConversation(parentConversationId) && !await getNonTerminalAgentInvocationForConversation(parentConversationId)) throw new Error(`Agent conversation ${parentConversationId} has no open work and cannot give work to child agents`);
+}
+/**
+* Count the child agents of one parent that have open work. Messages queued
+* for a busy child do not count again.
+*/
+async function countActiveChildAgentsForParent(parentConversationId) {
+	return (await getSqlExecutor().db().select({ value: countDistinct(juniorAgentInvocations.childConversationId) }).from(juniorAgentInvocations).where(and(eq(juniorAgentInvocations.parentConversationId, parentConversationId), inArray(juniorAgentInvocations.status, NON_TERMINAL_AGENT_INVOCATION_STATUSES))))[0]?.value ?? 0;
+}
+/**
+* Create or replay the first invocation of one new child agent. A name gives
+* the child a stable Conversation id that later messages can address. A name
+* that is already used throws: later work for that child goes through
+* `createAgentInvocationForMessage`.
+*/
+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 = getChildAgentLockName(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;
+		}
+		await assertCanGiveChildWork(input.parentConversationId);
+		if (input.agentName && await getAgentBinding({
+			name: input.agentName,
+			parentConversationId: input.parentConversationId
+		})) throw new AgentNameInUseError(input.agentName);
+		if (await countActiveChildAgentsForParent(input.parentConversationId) >= 8) throw new AgentInvocationLimitError(8);
+		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
+		});
+		await getSqlExecutor().db().insert(juniorAgentInvocations).values({
+			invocationId,
+			parentConversationId: input.parentConversationId,
+			childConversationId,
+			agentName: input.agentName ?? null,
+			input: input.input,
+			title: input.title ?? null,
+			actor: input.actor,
+			credentialContext: input.credentialContext ?? null,
+			source: { kind: "agent_invocation" },
+			destination: input.destination,
+			agentType: input.agentType ?? null,
+			modelProfile: input.modelProfile ?? null,
+			reasoningLevel: input.reasoningLevel ?? null,
+			parentToolCallId: input.parentToolCallId ?? 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;
+	});
+}
+/**
+* Create or replay the agent invocation that gives one input to a child
+* Conversation: a result or message from its own child agent, or its own
+* watch events. It continues that Conversation for the same parent as
+* `latest`, and for the same Actor and credentials unless `runAs` sets them.
+* It skips the queue and active-count checks because it continues work that
+* already passed them.
+*/
+async function createAgentInvocationFromLatest(args, nowMs = Date.now()) {
+	const { invocationId } = args;
+	await getSqlExecutor().db().insert(juniorAgentInvocations).values({
+		invocationId,
+		parentConversationId: args.latest.parentConversationId,
+		childConversationId: args.latest.childConversationId,
+		agentName: args.latest.agentName ?? null,
+		input: args.input,
+		actor: (args.runAs ?? args.latest).actor,
+		credentialContext: (args.runAs ?? args.latest).credentialContext ?? null,
+		source: args.runAs?.source ?? { kind: "agent_invocation" },
+		destination: args.latest.destination,
+		agentType: args.latest.agentType ?? null,
+		modelProfile: args.latest.modelProfile ?? null,
+		reasoningLevel: args.latest.reasoningLevel ?? null,
+		status: "pending",
+		mailboxStatus: "pending",
+		createdAt: new Date(nowMs),
+		updatedAt: new Date(nowMs),
+		terminalAt: null
+	}).onConflictDoNothing();
+	const invocation = await getAgentInvocation(invocationId);
+	if (!invocation || invocation.childConversationId !== args.latest.childConversationId) throw new Error(`Agent invocation creation raced for ${invocationId}`);
+	return invocation;
+}
+/** Find a direct child agent of one parent by name or child Conversation id. */
+async function findChildAgentConversationId(args) {
+	const binding = await getAgentBinding({
+		name: args.target,
+		parentConversationId: args.parentConversationId
+	});
+	if (binding) return binding.childConversationId;
+	return (await getSqlExecutor().db().select({ childConversationId: juniorAgentInvocations.childConversationId }).from(juniorAgentInvocations).where(and(eq(juniorAgentInvocations.parentConversationId, args.parentConversationId), eq(juniorAgentInvocations.childConversationId, args.target))).limit(1))[0]?.childConversationId;
+}
+/**
+* Return whether a pending agent invocation still waits for older open work
+* on its child.
+*/
+async function isQueuedBehindOpenWork(invocation) {
+	if (invocation.status !== "pending") return false;
+	return (await getSqlExecutor().db().select({ invocationId: juniorAgentInvocations.invocationId }).from(juniorAgentInvocations).where(and(eq(juniorAgentInvocations.childConversationId, invocation.childConversationId), lt(juniorAgentInvocations.createdAt, new Date(invocation.createdAtMs)), inArray(juniorAgentInvocations.status, NON_TERMINAL_AGENT_INVOCATION_STATUSES))).limit(1)).length > 0;
+}
+/**
+* Create or replay the agent invocation for one message from a parent to one
+* of its child agents. The child continues its history. If the child already
+* has open work, the new agent invocation waits for that work and the parent
+* gets one report for both. A stopped child starts again.
+*/
+async function createAgentInvocationForMessage(input, nowMs = Date.now()) {
+	const invocationId = getAgentInvocationId(input.parentConversationId, input.idempotencyKey);
+	return await getSqlExecutor().withLock(getChildAgentLockName(input.parentConversationId), async () => {
+		const existing = await getAgentInvocation(invocationId);
+		if (existing) {
+			if (existing.childConversationId !== input.childConversationId || existing.input !== input.input) throw new Error(`Agent invocation idempotency key was reused with different input for ${invocationId}`);
+			return {
+				invocation: existing,
+				queued: await isQueuedBehindOpenWork(existing)
+			};
+		}
+		const latest = await getLatestAgentInvocationForConversation(input.childConversationId);
+		if (!latest || latest.parentConversationId !== input.parentConversationId) throw new Error(`${input.childConversationId} is not a child agent of ${input.parentConversationId}`);
+		await assertCanGiveChildWork(input.parentConversationId);
+		const openCount = await countNonTerminalAgentInvocationsForChild(input.childConversationId);
+		if (openCount >= 4) throw new AgentMessageQueueFullError(4);
+		if (openCount === 0 && await countActiveChildAgentsForParent(input.parentConversationId) >= 8) throw new AgentInvocationLimitError(8);
+		await getSqlExecutor().db().insert(juniorAgentInvocations).values({
+			invocationId,
+			parentConversationId: input.parentConversationId,
+			childConversationId: input.childConversationId,
+			agentName: latest.agentName ?? null,
+			input: input.input,
+			title: null,
+			actor: input.actor,
+			credentialContext: input.credentialContext ?? null,
+			source: { kind: "agent_invocation" },
+			destination: input.destination,
+			agentType: latest.agentType ?? null,
+			modelProfile: latest.modelProfile ?? null,
+			reasoningLevel: latest.reasoningLevel ?? null,
+			parentToolCallId: input.parentToolCallId,
+			status: "pending",
+			mailboxStatus: "pending",
+			createdAt: new Date(nowMs),
+			updatedAt: new Date(nowMs),
+			terminalAt: null
+		}).onConflictDoNothing();
+		const invocation = await getAgentInvocation(invocationId);
+		if (!invocation) throw new Error(`Agent invocation creation raced for ${invocationId}`);
+		return {
+			invocation,
+			queued: openCount > 0
+		};
+	});
+}
+/**
+* Return whether a child Conversation has work that will start another agent
+* invocation on it: another open agent invocation, an open child agent, or a
+* sent child agent result that no agent invocation has received yet.
+*/
+async function hasOpenChildWork(invocation) {
+	const db = getSqlExecutor().db();
+	const conversationId = invocation.childConversationId;
+	if ((await db.select({ invocationId: juniorAgentInvocations.invocationId }).from(juniorAgentInvocations).where(and(or(eq(juniorAgentInvocations.childConversationId, conversationId), eq(juniorAgentInvocations.parentConversationId, conversationId)), ne(juniorAgentInvocations.invocationId, invocation.invocationId), inArray(juniorAgentInvocations.status, NON_TERMINAL_AGENT_INVOCATION_STATUSES))).limit(1)).length > 0) return true;
+	const sent = await db.select({ invocationId: juniorAgentInvocations.invocationId }).from(juniorAgentInvocations).where(and(eq(juniorAgentInvocations.parentConversationId, conversationId), inArray(juniorAgentInvocations.parentMailboxStatus, ["pending", "appended"])));
+	if (sent.length === 0) return false;
+	return (await db.select({ invocationId: juniorAgentInvocations.invocationId }).from(juniorAgentInvocations).where(inArray(juniorAgentInvocations.invocationId, sent.map((row) => getAgentInvocationIdForResult(row.invocationId))))).length < sent.length;
+}
+/** List bounded invocation records whose mailbox append still needs repair. */
+async function listPendingAgentInvocationMailboxAppends(limit = 100) {
+	return (await getSqlExecutor().db().select().from(juniorAgentInvocations).where(and(eq(juniorAgentInvocations.mailboxStatus, "pending"), inArray(juniorAgentInvocations.status, NON_TERMINAL_AGENT_INVOCATION_STATUSES))).orderBy(asc(juniorAgentInvocations.createdAt)).limit(limit)).map(invocationFromRow);
+}
+/** List terminal agent invocation results that still need a parent mailbox append. */
+async function listPendingAgentInvocationResults(limit = 100) {
+	return (await getSqlExecutor().db().select().from(juniorAgentInvocations).where(eq(juniorAgentInvocations.parentMailboxStatus, "pending")).orderBy(asc(juniorAgentInvocations.terminalAt)).limit(limit)).map(invocationFromRow).filter(isTerminalAgentInvocation);
+}
+/**
+* Send a `replaced` result to the parent now. A stop ended the open work of
+* the child, so no later agent invocation sends the report.
+*/
+async function reportReplacedAgentInvocation(invocationId, nowMs = Date.now()) {
+	await getSqlExecutor().db().update(juniorAgentInvocations).set({
+		parentMailboxStatus: "pending",
+		updatedAt: new Date(nowMs)
+	}).where(and(eq(juniorAgentInvocations.invocationId, invocationId), eq(juniorAgentInvocations.parentMailboxStatus, "replaced")));
+	return await getAgentInvocation(invocationId);
+}
+/** Record that one terminal result is in its parent mailbox. */
+async function markAgentInvocationParentMailboxAppended(invocationId, nowMs = Date.now()) {
+	await getSqlExecutor().db().update(juniorAgentInvocations).set({
+		parentMailboxStatus: "appended",
+		updatedAt: new Date(nowMs)
+	}).where(and(eq(juniorAgentInvocations.invocationId, invocationId), eq(juniorAgentInvocations.parentMailboxStatus, "pending")));
+}
+/** Record that the invocation's idempotent mailbox append completed. */
+async function markAgentInvocationMailboxAppended(invocationId, nowMs = Date.now()) {
+	await getSqlExecutor().db().update(juniorAgentInvocations).set({
+		mailboxStatus: "appended",
+		updatedAt: new Date(nowMs)
+	}).where(eq(juniorAgentInvocations.invocationId, invocationId));
+}
+/** Mark one non-terminal invocation as actively executing. */
+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);
+}
+/** Mark one invocation as waiting for another shared execution slice. */
+async function markAgentInvocationPaused(invocationId, nowMs = Date.now()) {
+	await getSqlExecutor().db().update(juniorAgentInvocations).set({
+		status: "paused",
+		updatedAt: new Date(nowMs)
+	}).where(and(eq(juniorAgentInvocations.invocationId, invocationId), inArray(juniorAgentInvocations.status, NON_TERMINAL_AGENT_INVOCATION_STATUSES)));
+}
+/**
+* Persist one terminal invocation result without overwriting an earlier
+* result. The same write marks the result for the parent mailbox. If the
+* child still has open work, the result is `replaced`: the parent gets one
+* report, from the agent invocation that finishes the child's work.
+*/
+async function completeAgentInvocation(args) {
+	const nowMs = args.nowMs ?? Date.now();
+	const current = await getAgentInvocation(args.invocationId);
+	if (!current || isTerminalAgentInvocation(current)) return current;
+	const parentMailboxStatus = args.status !== "stopped" && await hasOpenChildWork(current) ? "replaced" : "pending";
+	await getSqlExecutor().db().update(juniorAgentInvocations).set({
+		status: args.status,
+		result: args.status === "completed" ? args.result : null,
+		errorMessage: args.status === "completed" ? null : args.errorMessage,
+		parentMailboxStatus,
+		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);
+}
+/**
+* End a pending agent invocation whose input the running agent invocation of
+* the same child read as a steering message. The running agent invocation
+* reports for both, so this one is never sent to the parent.
+*/
+async function markAgentInvocationSteered(invocationId, nowMs = Date.now()) {
+	await getSqlExecutor().db().update(juniorAgentInvocations).set({
+		status: "completed",
+		result: "",
+		parentMailboxStatus: "steered",
+		terminalAt: new Date(nowMs),
+		updatedAt: new Date(nowMs)
+	}).where(and(eq(juniorAgentInvocations.invocationId, invocationId), eq(juniorAgentInvocations.status, "pending")));
+	return await getAgentInvocation(invocationId);
+}
+/** Return whether an agent invocation has finished. */
+function isTerminalAgentInvocation(invocation) {
+	return TERMINAL_AGENT_INVOCATION_STATUSES.includes(invocation.status);
+}
+export { AgentMessageQueueFullError as A, ConversationTurnBoundaryError as B, markAgentInvocationParentMailboxAppended as C, parseAgentInvocationResultMessageId as D, markAgentInvocationSteered as E, agentNameSchema as F, isCooperativeTurnYieldError as G, TurnInputCommitLostError as H, AGENT_TYPES as I, markTurnClosed as J, isTurnInputCommitLostError as K, agentTypeInstructions as L, AgentNameInUseError as M, CHILD_AGENT_RESULTS as N, reportReplacedAgentInvocation as O, PARENT_AGENT_TARGET as P, agentTypeStartsWithParentHistory as R, markAgentInvocationMailboxAppended as S, markAgentInvocationRunning as T, TurnInputDeferredError as U, CooperativeTurnYieldError as V, getConversationTurnBoundaryError as W, markTurnFailed as X, markTurnCompleted as Y, startActiveTurn as Z, getLatestAgentInvocationForConversation as _, createAgentInvocationFromLatest as a, listPendingAgentInvocationMailboxAppends as b, getAgentInvocation as c, getAgentInvocationIdForResult as d, getAgentInvocationMessageId as f, getChildAgentLockName as g, getChildAgentLabel as h, createAgentInvocationForMessage as i, AgentMessageTargetError as j, AgentInvocationLimitError as k, getAgentInvocationIdForEvents as l, getAgentInvocationTurnId as m, completeAgentInvocation as n, findChildAgentConversationId as o, getAgentInvocationResultMessageId as p, isTurnInputDeferredError as q, createAgentInvocation as r, getActiveAgentInvocationForConversation as s, NON_TERMINAL_AGENT_INVOCATION_STATUSES as t, getAgentInvocationIdForMessage as u, invocationFromRow as v, markAgentInvocationPaused as w, listPendingAgentInvocationResults as x, isTerminalAgentInvocation as y, formatAgentTypes as z };