Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

refactor(in-app-agent): remove dead foreground runtime support (#15946)

Lysander Kieselc8d86e95656a
diff --git a/packages/shared/AGENTS.md b/packages/shared/AGENTS.md
index cffb3bd36f..636b271a3e 100644
--- a/packages/shared/AGENTS.md
+++ b/packages/shared/AGENTS.md
@@ -55,13 +55,15 @@
signature helpers for secrets and signed payloads.
- `@langfuse/shared/query` via `src/features/query/index.ts`: dashboard query feature.
- `@langfuse/shared/in-app-agent` via `src/in-app-agent/index.ts`:
- client-safe contracts (AG-UI schemas, constants, id helpers) of the
- EE-licensed in-app-agent module. Never re-export server code here.
+ client-safe in-app-agent contracts (AG-UI schemas, constants, id helpers).
+ `AgUiRunAgentInput` is a compile-time-only execution contract; there is no
+ runtime input or browser runtime-state schema. Never re-export server code
+ here.
- `@langfuse/shared/in-app-agent/server` (plus per-module subpaths via the
`./in-app-agent/server/*` wildcard) via `src/in-app-agent/server/`:
- the EE-licensed in-app-agent runtime (Mastra/Bedrock/MCP loop, tools,
- persistence, sandbox), consumed by web's router/watch adapters and the worker
- execution processor.
+ the in-app-agent runtime (Mastra/Bedrock/MCP loop, tools, persistence,
+ sandbox), consumed by web's router/watch adapters and the worker execution
+ processor.
- Narrower exported subpaths also exist for targeted imports:
`@langfuse/shared/src/server/auth/apiKeys`,
`@langfuse/shared/src/server/ee/ingestionMasking`, and
diff --git a/packages/shared/prisma/schema.prisma b/packages/shared/prisma/schema.prisma
index 34e6b5b949..6c4e7105da 100644
--- a/packages/shared/prisma/schema.prisma
+++ b/packages/shared/prisma/schema.prisma
@@ -305,6 +305,8 @@ model InAppAgentRun {
}
model InAppAgentPendingToolApproval {
+ // Background execution never reads or writes this table. Retain it
+ // temporarily so existing rows and relations remain valid.
projectId String @map("project_id")
project Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
conversationId String @map("conversation_id")
diff --git a/packages/shared/src/features/inAppAgent/types.ts b/packages/shared/src/features/inAppAgent/types.ts
index 3c012ec2a7..fd5724e6e7 100644
--- a/packages/shared/src/features/inAppAgent/types.ts
+++ b/packages/shared/src/features/inAppAgent/types.ts
@@ -28,7 +28,7 @@ export const InAppAgentRunStatusSchema = z.enum(InAppAgentRunStatus);
* tolerate unknown strings rather than parse against this enum.
*/
export enum InAppAgentRunErrorCode {
- /** Unfinished run lazily closed because its foreground stream died. */
+ /** Retained so persisted run errors remain readable. */
STALE = "stale",
/** Client aborted the request. */
CANCELLED = "cancelled",
diff --git a/packages/shared/src/in-app-agent/schema.ts b/packages/shared/src/in-app-agent/schema.ts
index 08fc28404f..c07d96ade0 100644
--- a/packages/shared/src/in-app-agent/schema.ts
+++ b/packages/shared/src/in-app-agent/schema.ts
@@ -187,30 +187,28 @@ export type InAppAgentMessageSource = z.infer<
typeof InAppAgentMessageSourceSchema
>;
-const AgUiToolSchema = z.object({
- name: z.string(),
- description: z.string(),
- parameters: z.unknown().optional(),
- metadata: z.record(z.string(), z.unknown()).optional(),
-});
+type AgUiTool = {
+ name: string;
+ description: string;
+ parameters?: unknown;
+ metadata?: Record<string, unknown>;
+};
export const AgUiContextSchema = z.object({
description: z.string(),
value: z.string(),
});
-export const AgUiRunAgentInputSchema = z.object({
- threadId: z.string(),
- runId: z.string(),
- parentRunId: z.string().optional(),
- state: z.unknown().optional(),
- messages: z.array(AgUiMessageSchema),
- tools: z.array(AgUiToolSchema),
- context: z.array(AgUiContextSchema),
- forwardedProps: z.unknown().optional(),
-});
-
-export type AgUiRunAgentInput = z.infer<typeof AgUiRunAgentInputSchema>;
+export type AgUiRunAgentInput = {
+ threadId: string;
+ runId: string;
+ parentRunId?: string;
+ state?: unknown;
+ messages: AgUiMessage[];
+ tools: AgUiTool[];
+ context: Array<z.infer<typeof AgUiContextSchema>>;
+ forwardedProps?: unknown;
+};
export type AgUiEvent = {
type: EventType;
@@ -247,19 +245,3 @@ export const ResumeForwardedPropsSchema = z.object({
});
export type ResumeForwardedProps = z.infer<typeof ResumeForwardedPropsSchema>;
-
-export const InAppAgentRuntimeStateSchema = z.discriminatedUnion("type", [
- z.object({
- type: z.literal("newConversation"),
- projectId: z.string(),
- }),
- z.object({
- type: z.literal("existingConversation"),
- projectId: z.string(),
- conversationId: z.string(),
- }),
-]);
-
-export type InAppAgentRuntimeState = z.infer<
- typeof InAppAgentRuntimeStateSchema
->;
diff --git a/packages/shared/src/in-app-agent/server/human-in-the-loop.ts b/packages/shared/src/in-app-agent/server/human-in-the-loop.ts
index dd9672a054..bdc7004743 100644
--- a/packages/shared/src/in-app-agent/server/human-in-the-loop.ts
+++ b/packages/shared/src/in-app-agent/server/human-in-the-loop.ts
@@ -1,14 +1,12 @@
import { EventType } from "@ag-ui/core";
import { z } from "zod";
-import { InvalidRequestError } from "../../index";
-import { prisma } from "../../db";
import { IN_APP_AGENT_TOOL_REJECTION_ERROR_CODE } from "../constants";
import {
IN_APP_AGENT_LANGFUSE_MCP_TOOL_NAMES,
type InAppAgentLangfuseMcpToolName,
} from "./tools";
-import { safeJsonParse, stableJsonStringify } from "../../utils/json";
+import { safeJsonParse } from "../../utils/json";
import {
type AgUiEvent,
type AgUiMessage,
@@ -26,15 +24,6 @@ const MANUAL_TOOL_APPROVAL_REJECTION_ERROR = JSON.stringify({
type DeveloperGuidanceMessage = Extract<AgUiMessage, { role: "developer" }>;
-export const IN_APP_AGENT_PENDING_TOOL_APPROVAL_TTL_SECONDS = 60 * 60;
-
-const PendingToolApprovalSchema = z.object({
- toolCallId: z.string().min(1),
- toolName: z.string().min(1),
- runId: z.string().min(1),
- argsFingerprint: z.string(),
-});
-
const InAppAgentLangfuseMcpToolNameSchema =
z.custom<InAppAgentLangfuseMcpToolName>(
(value) =>
@@ -57,89 +46,6 @@ const MastraSuspendEventSchema = z.object({
runId: z.string().min(1),
});
-export async function storePendingToolApproval(params: {
- projectId: string;
- conversationId: string;
- approvalRequest: InAppAgentToolApprovalRequest;
-}) {
- const approvalFingerprint = createPendingToolApprovalFingerprint(
- params.approvalRequest,
- );
- const expiresAt = new Date(
- Date.now() + IN_APP_AGENT_PENDING_TOOL_APPROVAL_TTL_SECONDS * 1000,
- );
-
- await prisma.inAppAgentPendingToolApproval.upsert({
- where: {
- projectId_conversationId_toolCallId: {
- projectId: params.projectId,
- conversationId: params.conversationId,
- toolCallId: params.approvalRequest.toolCallId,
- },
- },
- create: {
- projectId: params.projectId,
- conversationId: params.conversationId,
- toolCallId: params.approvalRequest.toolCallId,
- approvalFingerprint,
- expiresAt,
- },
- update: {
- approvalFingerprint,
- expiresAt,
- },
- });
-}
-
-// Check early, before stream setup, so malformed or forged resume payloads fail
-// without starting another model/tool execution attempt.
-export async function validatePendingToolApproval(params: {
- projectId: string;
- conversationId: string;
- forwardedProps: ResumeForwardedProps;
-}) {
- const approvalRequest = params.forwardedProps.command.resume.approvalRequest;
- const pendingApproval = await prisma.inAppAgentPendingToolApproval.findFirst({
- where: {
- projectId: params.projectId,
- conversationId: params.conversationId,
- toolCallId: approvalRequest.toolCallId,
- approvalFingerprint:
- createPendingToolApprovalFingerprint(approvalRequest),
- expiresAt: { gt: new Date() },
- },
- select: { toolCallId: true },
- });
-
- if (!pendingApproval) {
- throw new InvalidRequestError("Invalid forwarded props");
- }
-}
-
-// Atomically consume before stream setup so a pending approval can start at most
-// one resumed tool call attempt.
-export async function consumeAndValidatePendingToolApproval(params: {
- projectId: string;
- conversationId: string;
- forwardedProps: ResumeForwardedProps;
-}) {
- const approvalRequest = params.forwardedProps.command.resume.approvalRequest;
- const consumeResult = await prisma.inAppAgentPendingToolApproval.deleteMany({
- where: {
- projectId: params.projectId,
- conversationId: params.conversationId,
- toolCallId: approvalRequest.toolCallId,
- approvalFingerprint:
- createPendingToolApprovalFingerprint(approvalRequest),
- expiresAt: { gt: new Date() },
- },
- });
-
- if (consumeResult.count !== 1) {
- throw new InvalidRequestError("Invalid forwarded props");
- }
-}
-
export async function createInAppAgentMcpRunOverride(params: {
toolName: InAppAgentLangfuseMcpToolName;
}) {
@@ -440,18 +346,3 @@ function serializeToolResultContent(value: unknown) {
return String(value);
}
}
-
-function createPendingToolApprovalFingerprint(
- approvalRequest: InAppAgentToolApprovalRequest,
-): string {
- // Persist only the stable approval identity, including a sorted-JSON argument
- // fingerprint, so approved calls cannot be replayed with changed arguments.
- return JSON.stringify(
- PendingToolApprovalSchema.parse({
- toolCallId: approvalRequest.toolCallId,
- toolName: approvalRequest.toolName,
- runId: approvalRequest.runId,
- argsFingerprint: stableJsonStringify(approvalRequest.args),
- }),
- );
-}
diff --git a/packages/shared/src/in-app-agent/server/persistence.ts b/packages/shared/src/in-app-agent/server/persistence.ts
index 6a21ab15f8..87c16dfcab 100644
--- a/packages/shared/src/in-app-agent/server/persistence.ts
+++ b/packages/shared/src/in-app-agent/server/persistence.ts
@@ -4,7 +4,6 @@ import { EventType } from "@ag-ui/core";
import {
InAppAgentRunErrorCode,
InAppAgentRunStatus,
- LangfuseConflictError,
LangfuseNotFoundError,
} from "../../index";
import {
@@ -171,99 +170,6 @@ export async function ensureOwnedConversation(params: {
});
}
-export async function createRun(params: {
- prisma: PrismaClient;
- runId: string;
- projectId: string;
- conversationId: string;
- triggeredByUserId: string;
- model?: string;
- mcpApiKeyId?: string;
-}) {
- return params.prisma.$transaction(async (tx) => {
- await lockConversation(tx, params.projectId, params.conversationId);
-
- const activeRun = await tx.inAppAgentRun.findFirst({
- where: {
- projectId: params.projectId,
- conversationId: params.conversationId,
- finishedAt: null,
- },
- select: { id: true },
- });
-
- if (activeRun) {
- throw new LangfuseConflictError(ACTIVE_RUN_CONFLICT_MESSAGE);
- }
-
- try {
- return await tx.inAppAgentRun.create({
- data: {
- id: params.runId,
- projectId: params.projectId,
- conversationId: params.conversationId,
- triggeredByUserId: params.triggeredByUserId,
- model: params.model,
- mcpApiKeyId: params.mcpApiKeyId,
- status: InAppAgentRunStatus.RUNNING,
- },
- });
- } catch (error) {
- // Backstop: the partial unique index on active runs. The conversation
- // lock above should make this unreachable; surface it as the same
- // conflict as the primary check instead of a 500. The insert can also
- // violate the (id, project_id) primary key (a replayed runId), so only
- // map the active-run index — Prisma reports it via its column names.
- if (
- error instanceof Prisma.PrismaClientKnownRequestError &&
- error.code === "P2002" &&
- Array.isArray(error.meta?.target) &&
- error.meta.target.includes("conversation_id")
- ) {
- throw new LangfuseConflictError(ACTIVE_RUN_CONFLICT_MESSAGE);
- }
- throw error;
- }
- });
-}
-
-export async function finishRun(params: {
- prisma: PrismaClient;
- runId: string;
- projectId: string;
- errorCode?: InAppAgentRunErrorCode | null;
- errorMessage?: string | null;
-}) {
- const errorCode = params.errorCode ?? null;
- const status =
- errorCode == null
- ? InAppAgentRunStatus.SUCCEEDED
- : errorCode === InAppAgentRunErrorCode.CANCELLED
- ? InAppAgentRunStatus.CANCELLED
- : InAppAgentRunStatus.FAILED;
- await params.prisma.inAppAgentRun
- .updateMany({
- where: {
- id: params.runId,
- projectId: params.projectId,
- finishedAt: null,
- },
- data: {
- status,
- finishedAt: new Date(),
- errorCode,
- errorMessage: params.errorMessage ?? null,
- },
- })
- .catch((error: unknown) =>
- logger.error("Failed to finish in-app agent run", {
- error,
- runId: params.runId,
- projectId: params.projectId,
- }),
- );
-}
-
export async function appendRunEvents(params: {
prisma: PrismaClient;
projectId: string;
diff --git a/web/AGENTS.md b/web/AGENTS.md
index 120a4ea120..c690babe6b 100644
--- a/web/AGENTS.md
+++ b/web/AGENTS.md
@@ -42,6 +42,7 @@
dependency.
- The in-app-agent runtime lives in shared:
`@langfuse/shared/in-app-agent` is the client-safe contracts entry;
+ its `AgUiRunAgentInput` is a compile-time-only execution contract;
`@langfuse/shared/in-app-agent/server` (and per-module subpaths) is
server-only. Web keeps only the thin adapters in
`src/features/in-app-agent/` (router and UI), plus the authenticated watch
diff --git a/web/src/__tests__/server/in-app-agent-persistence.servertest.ts b/web/src/__tests__/server/in-app-agent-persistence.servertest.ts
index ced650908a..b47234d85c 100644
--- a/web/src/__tests__/server/in-app-agent-persistence.servertest.ts
+++ b/web/src/__tests__/server/in-app-agent-persistence.servertest.ts
@@ -18,7 +18,6 @@ import {
type Plan,
} from "@langfuse/shared";
import { prisma } from "@langfuse/shared/src/db";
-import type { Prisma } from "@langfuse/shared/src/db";
import {
createOrgProjectAndApiKey,
generateLLMText,
@@ -40,10 +39,8 @@ import {
} from "@/src/features/in-app-agent/lib/display";
import { inAppAgentRouter } from "@/src/features/in-app-agent/server/router";
import {
- createRun,
ensureOwnedConversation,
getConversationEvents,
- finishRun,
getConversationMessagesForReplay,
maybeInferAndPersistConversationTitle,
appendRunEvents,
@@ -51,6 +48,7 @@ import {
shouldFlushPersistedEvent,
toPersistableAgentEvent,
} from "@langfuse/shared/in-app-agent/server/persistence";
+import { finishClaimedRun } from "@langfuse/shared/in-app-agent/server/runLifecycle";
import { watchConversationFrames } from "@langfuse/shared/in-app-agent/server/watch";
import { createInnerTRPCContext } from "@/src/server/api/trpc";
import { IN_APP_AGENT_REDIRECT_TOOL_NAME } from "@langfuse/shared/in-app-agent";
@@ -149,21 +147,95 @@ describe("in-app agent persistence", () => {
userId: params.userId,
});
- const createConversationRun = async (params: {
+ // Create only the claimed run record so persistence tests can control their
+ // exact event rows while exercising transitions through lifecycle APIs.
+ const createClaimedRunFixture = async (params: {
projectId: string;
conversationId: string;
userId: string;
runId?: string;
+ }) => {
+ const now = new Date();
+
+ return prisma.inAppAgentRun.create({
+ data: {
+ id: params.runId ?? createInAppAgentRunId(),
+ projectId: params.projectId,
+ conversationId: params.conversationId,
+ triggeredByUserId: params.userId,
+ model: "haiku",
+ mcpApiKeyId: "api-key-id-1",
+ status: InAppAgentRunStatus.RUNNING,
+ claimedAt: now,
+ heartbeatAt: now,
+ },
+ });
+ };
+
+ const finishConversationRun = (params: {
+ projectId: string;
+ runId: string;
+ errorCode?: InAppAgentRunErrorCode;
+ errorMessage?: string;
}) =>
- createRun({
+ finishClaimedRun({
prisma,
- runId: params.runId ?? createInAppAgentRunId(),
- projectId: params.projectId,
- conversationId: params.conversationId,
- triggeredByUserId: params.userId,
- model: "haiku",
- mcpApiKeyId: "api-key-id-1",
+ ...params,
+ status:
+ params.errorCode == null
+ ? InAppAgentRunStatus.SUCCEEDED
+ : params.errorCode === InAppAgentRunErrorCode.CANCELLED
+ ? InAppAgentRunStatus.CANCELLED
+ : InAppAgentRunStatus.FAILED,
+ });
+
+ it("finishes claimed runs once and preserves the first terminal error", async () => {
+ const { projectId, userId } = await createCaller();
+ const conversation = await createConversation({ projectId, userId });
+ const run = await createClaimedRunFixture({
+ projectId,
+ conversationId: conversation.id,
+ userId,
+ });
+
+ await expect(
+ finishClaimedRun({
+ prisma,
+ projectId,
+ runId: run.id,
+ status: InAppAgentRunStatus.FAILED,
+ errorCode: InAppAgentRunErrorCode.AGENT_ERROR,
+ errorMessage: "Original agent error",
+ }),
+ ).resolves.toBe(true);
+ await expect(
+ finishClaimedRun({
+ prisma,
+ projectId,
+ runId: run.id,
+ status: InAppAgentRunStatus.CANCELLED,
+ errorCode: InAppAgentRunErrorCode.CANCELLED,
+ errorMessage: "Client aborted request",
+ }),
+ ).resolves.toBe(false);
+
+ await expect(
+ prisma.inAppAgentRun.findUniqueOrThrow({
+ where: { id_projectId: { id: run.id, projectId } },
+ select: {
+ status: true,
+ finishedAt: true,
+ errorCode: true,
+ errorMessage: true,
+ },
+ }),
+ ).resolves.toEqual({
+ status: InAppAgentRunStatus.FAILED,
+ finishedAt: expect.any(Date),
+ errorCode: InAppAgentRunErrorCode.AGENT_ERROR,
+ errorMessage: "Original agent error",
});
+ });
it("rejects users without the in-app agent entitlement", async () => {
const { caller, projectId } = await createCaller(
@@ -287,7 +359,7 @@ describe("in-app agent persistence", () => {
it("stores compacted events and restores multi-turn messages", async () => {
const { caller, projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run1 = await createConversationRun({
+ const run1 = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -322,13 +394,12 @@ describe("in-app agent persistence", () => {
messageId: "assistant-message-1",
chunks: ["I will inspect recent traces", " and look for outliers."],
});
- await finishRun({
- prisma,
+ await finishConversationRun({
runId: run1.id,
projectId,
});
- const run2 = await createConversationRun({
+ const run2 = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -479,113 +550,6 @@ describe("in-app agent persistence", () => {
);
});
- // Behavior: append-written multi-run history remains replayable after the latest run is rewritten by the legacy writer.
- // Crucial: the unflagged rollout must be safely reversible without corrupting event order or changing model context.
- // Necessary: existing append and fencing tests do not exercise the mixed-version writer transition created by a rollback.
- it("preserves replay when the latest append-written run is rewritten by the legacy writer", async () => {
- const { projectId, userId } = await createCaller();
- const conversation = await createConversation({ projectId, userId });
- const run1 = await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
- const events1 = await startCompactRun({
- projectId,
- conversationId: conversation.id,
- runId: run1.id,
- messageId: "rollback-user-1",
- content: "Inspect the first trace",
- });
- await appendAssistantText({
- projectId,
- conversationId: conversation.id,
- runId: run1.id,
- events: events1,
- messageId: "rollback-assistant-1",
- chunks: ["First trace inspected."],
- });
- await finishRun({ prisma, runId: run1.id, projectId });
-
- const run2 = await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
- const events2 = await startCompactRun({
- projectId,
- conversationId: conversation.id,
- runId: run2.id,
- messageId: "rollback-user-2",
- content: "Inspect the second trace",
- });
- await appendAssistantText({
- projectId,
- conversationId: conversation.id,
- runId: run2.id,
- events: events2,
- messageId: "rollback-assistant-2",
- chunks: ["Second trace inspected."],
- });
-
- const replayBeforeRollback = await getConversationMessagesForReplay({
- prisma,
- projectId,
- conversationId: conversation.id,
- });
- const latestRunEvents = await prisma.inAppAgentEvent.findMany({
- where: {
- projectId,
- conversationId: conversation.id,
- runId: run2.id,
- },
- orderBy: { sequenceNumber: "asc" },
- select: { type: true, event: true },
- });
-
- await prisma.$transaction(async (tx) => {
- await tx.inAppAgentEvent.deleteMany({
- where: {
- projectId,
- conversationId: conversation.id,
- runId: run2.id,
- },
- });
- const latestRemainingEvent = await tx.inAppAgentEvent.findFirst({
- where: { projectId, conversationId: conversation.id },
- orderBy: { sequenceNumber: "desc" },
- select: { sequenceNumber: true },
- });
- await tx.inAppAgentEvent.createMany({
- data: latestRunEvents.map((event, index) => ({
- projectId,
- conversationId: conversation.id,
- runId: run2.id,
- sequenceNumber:
- (latestRemainingEvent?.sequenceNumber ?? -1) + index + 1,
- type: event.type,
- event: event.event as Prisma.InputJsonValue,
- })),
- });
- });
-
- const rewrittenEvents = await prisma.inAppAgentEvent.findMany({
- where: { projectId, conversationId: conversation.id },
- orderBy: { sequenceNumber: "asc" },
- select: { sequenceNumber: true },
- });
- expect(rewrittenEvents.map((event) => event.sequenceNumber)).toEqual(
- rewrittenEvents.map((_, index) => index),
- );
- await expect(
- getConversationMessagesForReplay({
- prisma,
- projectId,
- conversationId: conversation.id,
- }),
- ).resolves.toEqual(replayBeforeRollback);
- });
-
it("does not overwrite user-renamed conversation titles", async () => {
const originalBedrockSmallModel = env.LANGFUSE_AWS_BEDROCK_SMALL_MODEL;
const { caller, projectId, userId } = await createCaller();
@@ -628,7 +592,7 @@ describe("in-app agent persistence", () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
const originalTitle = conversation.title;
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -669,7 +633,7 @@ describe("in-app agent persistence", () => {
it("requires feedback run ids to match persisted assistant messages", async () => {
const { caller, projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -718,7 +682,7 @@ describe("in-app agent persistence", () => {
it("does not reduce partial assistant content before the end event", async () => {
const { caller, projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -775,7 +739,7 @@ describe("in-app agent persistence", () => {
it("hydrates visible reasoning without including it in model replay", async () => {
const { projectId, userId, caller } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1014,7 +978,7 @@ describe("in-app agent persistence", () => {
it("preserves reasoning order when hydrating an assistant message that continues afterward", async () => {
const { projectId, userId, caller } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1150,7 +1114,7 @@ describe("in-app agent persistence", () => {
it("stores only compact events and skips raw adapter payloads", async () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1240,7 +1204,7 @@ describe("in-app agent persistence", () => {
it("does not persist adapter message snapshots", async () => {
const { caller, projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1292,7 +1256,7 @@ describe("in-app agent persistence", () => {
it("drops trailing user-only turns before replay", async () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const completedRun = await createConversationRun({
+ const completedRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1327,13 +1291,12 @@ describe("in-app agent persistence", () => {
runId: completedRun.id,
},
});
- await finishRun({
- prisma,
+ await finishConversationRun({
runId: completedRun.id,
projectId,
});
- const abandonedRun = await createConversationRun({
+ const abandonedRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1362,7 +1325,7 @@ describe("in-app agent persistence", () => {
it("drops assistant tool calls that have no matching tool result", async () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1467,7 +1430,7 @@ describe("in-app agent persistence", () => {
it("redacts silent MCP output from replayed conversation history", async () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1545,7 +1508,7 @@ describe("in-app agent persistence", () => {
it("drops assistant tool calls without results from loaded conversation history", async () => {
const { caller, projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1667,7 +1630,7 @@ describe("in-app agent persistence", () => {
it("flushes sibling tools while retaining only successful redirect actions for display", async () => {
const { caller, projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1848,7 +1811,7 @@ describe("in-app agent persistence", () => {
it("drops empty assistant messages after removing orphan tool calls before replay", async () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
+ const run = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1903,7 +1866,7 @@ describe("in-app agent persistence", () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const orphanToolRun = await createConversationRun({
+ const orphanToolRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1939,15 +1902,14 @@ describe("in-app agent persistence", () => {
type: EventType.TOOL_CALL_END,
toolCallId: "orphan-tool-call",
});
- await finishRun({
- prisma,
+ await finishConversationRun({
runId: orphanToolRun.id,
projectId,
errorCode: InAppAgentRunErrorCode.CANCELLED,
errorMessage: "Aborted before tool result",
});
- const completedRun = await createConversationRun({
+ const completedRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1985,7 +1947,7 @@ describe("in-app agent persistence", () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const failedRun = await createConversationRun({
+ const failedRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -1997,15 +1959,14 @@ describe("in-app agent persistence", () => {
messageId: "user-1",
content: "failed before output",
});
- await finishRun({
- prisma,
+ await finishConversationRun({
runId: failedRun.id,
projectId,
errorCode: InAppAgentRunErrorCode.AGENT_ERROR,
errorMessage: "Failed before output",
});
- const completedRun = await createConversationRun({
+ const completedRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -2106,14 +2067,14 @@ describe("in-app agent persistence", () => {
});
const runId = createInAppAgentRunId();
- await createConversationRun({
+ await createClaimedRunFixture({
projectId: owner.projectId,
conversationId: conversation.id,
userId: owner.userId,
runId,
});
await expect(
- createConversationRun({
+ createClaimedRunFixture({
projectId: other.projectId,
conversationId: otherConversation.id,
userId: other.userId,
@@ -2125,47 +2086,10 @@ describe("in-app agent persistence", () => {
});
});
- it("finishes runs once and preserves the first terminal error", async () => {
- const { projectId, userId } = await createCaller();
- const conversation = await createConversation({ projectId, userId });
- const run = await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
-
- expect(run.mcpApiKeyId).toBe("api-key-id-1");
- expect(run.finishedAt).toBeNull();
-
- await finishRun({
- prisma,
- runId: run.id,
- projectId,
- errorCode: InAppAgentRunErrorCode.AGENT_ERROR,
- errorMessage: "Original agent error",
- });
- await finishRun({
- prisma,
- runId: run.id,
- projectId,
- errorCode: InAppAgentRunErrorCode.CANCELLED,
- errorMessage: "Client aborted request",
- });
-
- await expect(
- prisma.inAppAgentRun.findUniqueOrThrow({
- where: { id_projectId: { id: run.id, projectId } },
- }),
- ).resolves.toMatchObject({
- errorCode: "agent_error",
- errorMessage: "Original agent error",
- });
- });
-
it("ignores event flushes from already-finished runs", async () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const run1 = await createConversationRun({
+ const run1 = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -2178,9 +2102,9 @@ describe("in-app agent persistence", () => {
content: "First",
});
- await finishRun({ prisma, runId: run1.id, projectId });
+ await finishConversationRun({ runId: run1.id, projectId });
- const run2 = await createConversationRun({
+ const run2 = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -2222,7 +2146,7 @@ describe("in-app agent persistence", () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- const firstRun = await createConversationRun({
+ const firstRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -2263,7 +2187,7 @@ describe("in-app agent persistence", () => {
finish: { status: InAppAgentRunStatus.SUCCEEDED },
});
- const secondRun = await createConversationRun({
+ const secondRun = await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
@@ -2347,119 +2271,19 @@ describe("in-app agent persistence", () => {
expect(frames.at(-1)).toEqual({ type: "done" });
});
- it("blocks a second active run in the same conversation", async () => {
- const { projectId, userId } = await createCaller();
- const conversation = await createConversation({ projectId, userId });
-
- await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
-
- await expect(
- createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- }),
- ).rejects.toThrow("Assistant is already responding in this conversation");
- });
-
- it("rethrows a replayed run id instead of reporting an active-run conflict", async () => {
- const { projectId, userId } = await createCaller();
- const conversation = await createConversation({ projectId, userId });
-
- const finished = await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
- await finishRun({ prisma, runId: finished.id, projectId });
-
- // Replaying the id of a finished run violates the (id, project_id) primary
- // key, not the active-run backstop index — the caller must not be told the
- // assistant is still responding. Asserting on meta.target pins the shape
- // the createRun catch discriminates on.
- await expect(
- createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- runId: finished.id,
- }),
- ).rejects.toMatchObject({
- code: "P2002",
- meta: { target: ["id", "project_id"] },
- });
- });
-
- it("writes run lifecycle status on the foreground path", async () => {
- const { projectId, userId } = await createCaller();
- const conversation = await createConversation({ projectId, userId });
-
- const succeeded = await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
- expect(succeeded.status).toBe("RUNNING");
- await finishRun({ prisma, runId: succeeded.id, projectId });
-
- const failed = await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
- await finishRun({
- prisma,
- runId: failed.id,
- projectId,
- errorCode: InAppAgentRunErrorCode.AGENT_ERROR,
- errorMessage: "boom",
- });
-
- const cancelled = await createConversationRun({
- projectId,
- conversationId: conversation.id,
- userId,
- });
- await finishRun({
- prisma,
- runId: cancelled.id,
- projectId,
- errorCode: InAppAgentRunErrorCode.CANCELLED,
- errorMessage: "Client aborted request",
- });
-
- const runs = await prisma.inAppAgentRun.findMany({
- where: { projectId, conversationId: conversation.id },
- select: { id: true, status: true },
- });
- expect(new Map(runs.map((run) => [run.id, run.status]))).toEqual(
- new Map([
- [succeeded.id, "SUCCEEDED"],
- [failed.id, "FAILED"],
- [cancelled.id, "CANCELLED"],
- ]),
- );
- });
-
it("enforces the single-active-run backstop index at the database level", async () => {
const { projectId, userId } = await createCaller();
const conversation = await createConversation({ projectId, userId });
- await createConversationRun({
+ await createClaimedRunFixture({
projectId,
conversationId: conversation.id,
userId,
});
- // Bypass createRun's conversation lock and conflict check: the partial
- // unique index is the DB-level invariant against two unfinished runs in
- // one conversation. Asserting on meta.target pins the shape the createRun
- // catch discriminates on (Prisma resolves the raw-SQL index to its
- // column names).
+ // The partial unique index is the database-level invariant against two
+ // unfinished runs in one conversation. Prisma resolves the raw-SQL index
+ // to its column names in the conflict metadata.
await expect(
prisma.inAppAgentRun.create({
data: {
diff --git a/web/src/features/in-app-agent/README.md b/web/src/features/in-app-agent/README.md
index fcd3821b90..7ec8a0a553 100644
--- a/web/src/features/in-app-agent/README.md
+++ b/web/src/features/in-app-agent/README.md
@@ -26,10 +26,10 @@ Closing the drawer detaches observation without cancelling the worker run.
- `schema.ts`: runtime-neutral AG-UI schemas and types shared by browser, server, persistence, replay, and rendering, including Langfuse-owned human-in-the-loop wire contracts.
- `server/agent.ts`: Mastra/Bedrock/MCP runtime setup, custom tool wiring, human-in-the-loop approval gates, AG-UI event normalization, and cleanup.
- `server/human-in-the-loop.ts`: interrupt parsing and worker continuation
- compatibility, plus unused request-scoped pending-approval helpers retained
- until the shared-runtime cleanup.
+ compatibility.
- `server/tools.ts`: custom agent tools with strict schemas and scoped, user-visible behavior.
-- `server/persistence.ts`: conversations, runs, events, canonical accumulation, replay, active-run locking, and stale-run recovery. Knows nothing about rendering.
+- `server/persistence.ts`: conversations, events, canonical accumulation, and replay. Knows nothing about rendering.
+- `server/runLifecycle.ts`: durable run creation, claiming, cancellation, terminal transitions, active-run locking, and reconciliation.
- `lib/display.ts`: display-state recording, the render-time projection, and its
wire serialization. Web-only; used by the browser and by the web server when
it builds a conversation snapshot.
@@ -212,9 +212,8 @@ Human approval is separate from the MCP tool override. Shared `server/tools.ts`
`IN_APP_AGENT_AUTO_APPROVED_TOOL_NAMES` is generated from that map by prefixing Langfuse MCP tools with `langfuse_` and adding local tools such as `IN_APP_AGENT_REDIRECT_TOOL_NAME`; docs MCP tools are auto-approved by the `langfuseDocs_` prefix. `server/agent.ts` marks every other tool with Mastra `requireApproval: true`. Mastra emits an interrupt, the browser asks the user, and the router records the decision for a durable worker continuation. `server/human-in-the-loop.ts` adapts Mastra's runtime interrupt payload into the Langfuse-owned `tool_approval_request` contract from `schema.ts`; the browser stores and forwards only that runtime-neutral shape.
-The request-scoped pending-approval persistence helpers and their table are not
-used by background execution. The helpers remain temporarily for the following
-shared-runtime cleanup; the table remains for historical data compatibility.
+The `InAppAgentPendingToolApproval` table is not used by background execution.
+It remains temporarily so existing rows and Prisma relations stay valid.
Sandbox tools are separate from MCP authorization. When a sandbox provider is enabled, `server/tools.ts` adds local `read`, `write`, `edit`, and `bash` tools backed by the sandbox provider contract rather than the MCP registry.