diff --git a/packages/paperclip-runner/src/contracts/control-plane-port.ts b/packages/paperclip-runner/src/contracts/control-plane-port.ts index 1e7b5664a7f..98cd2aeb117 100644 --- a/packages/paperclip-runner/src/contracts/control-plane-port.ts +++ b/packages/paperclip-runner/src/contracts/control-plane-port.ts @@ -36,7 +36,8 @@ export interface AppendControlPlaneEventOptions { */ deferPostCommitObservers?: true; /** - * For an `item.delta` only, on a port with `pipelinesStreamingEvents`: the + * For an event type in the port's `pipelinedEventTypes` (only `item.delta` + * when the port does not name them), on a port with `pipelinesStreamingEvents`: the * caller does not wait for this receipt before its next append, so the port * may hold the delta briefly to commit it with later ones. */ @@ -95,6 +96,7 @@ export interface ControlPlanePort { * commits. */ readonly pipelinesStreamingEvents?: boolean; + readonly pipelinedEventTypes?: ReadonlySet; /** Commits the queued streaming deltas now, without waiting for the batch timer. */ flushStreamingEvents?(): void; normalizeReplayPayload?(payload: PrpEvent["payload"]): PrpEvent["payload"]; diff --git a/packages/paperclip-runner/src/native-session-runtime.test.ts b/packages/paperclip-runner/src/native-session-runtime.test.ts index 93813aab14b..c5a8842fc5f 100644 --- a/packages/paperclip-runner/src/native-session-runtime.test.ts +++ b/packages/paperclip-runner/src/native-session-runtime.test.ts @@ -312,7 +312,8 @@ describe("executeNativeSession recovery", () => { }); /** A batching port whose queued deltas commit only when flushed: it has no timer. */ - const batchingDeltaFixture = (events: () => AsyncGenerator, commitDelta: (sourceSeq: number) => Promise = async () => {}) => { + const batchingDeltaFixture = (events: () => AsyncGenerator, commitDelta: (sourceSeq: number) => Promise = async () => {}, + pipelinedEventTypes?: ReadonlySet) => { const capabilities = { resume: true, typedEvents: true, steering: false, interruption: true, structuredResult: true }; const session: NativeSession = { identity: () => identity, @@ -335,6 +336,7 @@ describe("executeNativeSession recovery", () => { let queued: Array<() => void> = []; const port: ControlPlanePort = { pipelinesStreamingEvents: true, + ...(pipelinedEventTypes ? { pipelinedEventTypes } : {}), flushStreamingEvents() { log.push("flush"); const flushed = queued; @@ -345,7 +347,7 @@ describe("executeNativeSession recovery", () => { async appendEvent(event: PrpEvent, options) { if (event.sourceKind !== "runner") return { cursor: 0, highestContiguousSourceSeq: event.sourceSeq, disposition: "committed" }; log.push(`append:${event.sourceSeq}`); - if (event.eventType === "item.delta") { + if ((pipelinedEventTypes ?? new Set(["item.delta"])).has(event.eventType)) { expect(options?.streaming).toBe(true); await new Promise(resolve => queued.push(resolve)); await commitDelta(event.sourceSeq); @@ -375,6 +377,26 @@ describe("executeNativeSession recovery", () => { expect(execution).toMatchObject({ nativeEventCount: 7, highestContiguousSourceSeq: 5 }); }); + it.each([true, false])("starts progress appends without waiting only when the port pipelines them (pipelined=%s)", async pipelined => { + const progress = (sourceSeq: number) => runnerEvent(sourceSeq, "tool.execution.progressed", { name: "build", status: "running" }); + const f = batchingDeltaFixture(async function* () { + for (const sourceSeq of [1, 2]) yield progress(sourceSeq); + yield streamedDelta(3); + yield runnerEvent(4, "run.result.proposed", result); + yield runnerEvent(5, "turn.completed"); + }, async () => {}, pipelined ? new Set(["item.delta", "tool.execution.progressed"]) : undefined); + const execution = await executeNativeSession({ input: preparedInput(), backend: f.backend, controlPlane: f.port, + runnerInstanceId: "runner-recovery", controlPlaneInstanceId: "control-recovery" }); + expect(f.log.slice(0, 4)).toEqual(["append:1", "append:2", "append:3", "flush"]); + if (pipelined) { + expect(f.log.indexOf("append:2")).toBeLessThan(f.log.indexOf("committed:1")); + expect(f.log.indexOf("append:4")).toBeGreaterThan(Math.max(...[1, 2, 3].map(seq => f.log.indexOf(`committed:${seq}`)))); + } else { + expect(f.log).not.toContain("committed:1"); + } + expect(execution).toMatchObject({ highestContiguousSourceSeq: 5 }); + }); + it("joins pending delta appends before a failed turn settles", async () => { let releaseCommit = () => {}; const commitReleased = new Promise(resolve => { releaseCommit = resolve; }); diff --git a/packages/paperclip-runner/src/native-session-runtime.ts b/packages/paperclip-runner/src/native-session-runtime.ts index 218f2ab52dc..e5aa6c1a5f0 100644 --- a/packages/paperclip-runner/src/native-session-runtime.ts +++ b/packages/paperclip-runner/src/native-session-runtime.ts @@ -1265,6 +1265,7 @@ async function consumeTurn( // delta's receipt settles. Every other event, and every result, waits for // the receipts of the deltas before it. const pipelinesDeltas = controlPlane.pipelinesStreamingEvents === true; + const pipelinedEventTypes: ReadonlySet = controlPlane.pipelinedEventTypes ?? new Set(["item.delta"]); let pendingDeltas: Promise[] = []; let deltaFailure = null as { error: unknown } | null; const settlePendingDeltas = async () => { @@ -1450,7 +1451,7 @@ async function consumeTurn( // A failed delta stops the turn before any later event is appended. if (deltaFailure) throw deltaFailure.error; let receipt: AppendedEventReceipt | null = null; - if (pipelinesDeltas && event.eventType === "item.delta") { + if (pipelinesDeltas && pipelinedEventTypes.has(event.eventType)) { const pending = controlPlane.appendEvent(event, { signal: appendAbort.signal, streaming: true }); const settled = pending.then(() => undefined, (error: unknown) => { deltaFailure ??= { error }; }); outstandingDeltas.add(settled); diff --git a/server/src/services/native-runtime/paperclip-control-plane-port.test.ts b/server/src/services/native-runtime/paperclip-control-plane-port.test.ts index 2975c229823..406070043ad 100644 --- a/server/src/services/native-runtime/paperclip-control-plane-port.test.ts +++ b/server/src/services/native-runtime/paperclip-control-plane-port.test.ts @@ -3,7 +3,7 @@ import { resolveExternalTestDatabaseUrl } from "../../__tests__/helpers/external import { plugins } from "@paperclipai/db"; import { readTaskPanelActivations } from "../plugin-task-panels.js"; import { startServerMetrics, stopServerMetrics } from "../server-metrics.js"; -import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; import { and, asc, eq, sql } from "drizzle-orm"; import { createHash, generateKeyPairSync, randomUUID } from "node:crypto"; import { mkdtemp, rm } from "node:fs/promises"; @@ -1096,6 +1096,31 @@ describe("PaperclipControlPlanePort conformance", () => { await expect(f.port.appendEvent(f.event(12), f.streamed)).resolves.toMatchObject({ cursor: 12 }); }); + it("commits progress events that arrive while a batch commits in the next single batch", async () => { + let release!: () => void; + const gate = new Promise(resolve => { release = resolve; }); + const f = await streamingFixture({ streamingBatchMs: 600_000, onCommittedEvent: async (event) => { + if (event.sourceSeq === 1) await gate; + } }); + const first = f.port.appendEvent(f.event(1, "tool.execution.progressed"), f.streamed); + await vi.waitFor(async () => expect(await f.stored()).toHaveLength(1)); + const options = db.$client.options as { debug?: unknown }; + const statements: string[] = []; + options.debug = (_connection: number, text: string) => { statements.push(text.trim().replace(/\s+/g, " ")); }; + try { + const later = [2, 3, 4].map(sourceSeq => f.port.appendEvent(f.event(sourceSeq, "tool.execution.progressed"), f.streamed)); + await new Promise(resolve => setTimeout(resolve, 50)); + expect(statements.filter(text => /^begin/i.test(text))).toHaveLength(0); + release(); + await expect(first).resolves.toMatchObject({ cursor: 1, disposition: "committed" }); + expect((await Promise.all(later)).map(receipt => receipt.cursor)).toEqual([2, 3, 4]); + expect(statements.filter(text => /^begin/i.test(text))).toHaveLength(1); + } finally { options.debug = undefined; } + const boundary = await f.port.appendEvent(f.event(5, "tool.execution.started")); + expect(boundary).toMatchObject({ cursor: 5, disposition: "committed" }); + expect(await f.stored()).toEqual([1, 2, 3, 4, 5].map(seq => ({ seq, sourceSeq: seq }))); + }); + it("observes every committed delta of a batch when one observer fails", async () => { const observed: number[] = []; const f = await streamingFixture({ streamingBatchMs: 600_000, onCommittedEvent: async (event) => { diff --git a/server/src/services/native-runtime/paperclip-control-plane-port.ts b/server/src/services/native-runtime/paperclip-control-plane-port.ts index 7afee85af21..578b82bd420 100644 --- a/server/src/services/native-runtime/paperclip-control-plane-port.ts +++ b/server/src/services/native-runtime/paperclip-control-plane-port.ts @@ -125,6 +125,7 @@ export class PaperclipControlPlanePort implements ControlPlanePort { * a delta's receipt settles; the receipt settles after its batch commits. */ readonly pipelinesStreamingEvents = true; + readonly pipelinedEventTypes: ReadonlySet = new Set(["item.delta", "tool.execution.progressed"]); readonly #streamingBatchMs: number; #streamingBatch: PendingStreamingEvent[] = []; #streamingTimer: ReturnType | null = null; @@ -133,7 +134,7 @@ export class PaperclipControlPlanePort implements ControlPlanePort { /** Deltas queued or committing. Other operations wait only when some are; otherwise they start at once. */ #streamingEventsPending = 0; /** - * False until a delta with text commits after the latest other event. Until + * False until a delta with text is appended after the latest other event. Until * then each delta commits at once, so the first text of an item, and the * time to first token, never wait for the batch timer. */ @@ -467,7 +468,7 @@ export class PaperclipControlPlanePort implements ControlPlanePort { }, assertWritable: () => this.#assertActive(options), }; - if (event.eventType === "item.delta" && !options?.deferPostCommitObservers) { + if (this.pipelinedEventTypes.has(event.eventType) && !options?.deferPostCommitObservers) { return this.#appendStreamingEvent({ event, input, options, startedAtMs: persistenceStartedAt, startedClock: persistenceClock }, options?.streaming === true); } @@ -547,7 +548,12 @@ export class PaperclipControlPlanePort implements ControlPlanePort { return new Promise((resolve, reject) => { this.#streamingBatch.push({ ...pending, resolve, reject }); this.#streamingEventsPending += 1; - if (!streaming || !this.#streamedSinceBoundary || this.#streamingBatch.length >= STREAMING_EVENT_BATCH_MAX) { + if (pending.event.eventType !== "item.delta") this.#streamedSinceBoundary = false; + const flushNow = !streaming || !this.#streamedSinceBoundary || this.#streamingBatch.length >= STREAMING_EVENT_BATCH_MAX; + if (typeof pending.event.payload.text === "string" && pending.event.payload.text.length > 0) { + this.#streamedSinceBoundary = true; + } + if (flushNow) { void this.#flushStreamingEvents(); } else { this.#streamingTimer ??= setTimeout(() => { void this.#flushStreamingEvents(); }, this.#streamingBatchMs); @@ -569,9 +575,6 @@ export class PaperclipControlPlanePort implements ControlPlanePort { this.#streamingFlushQueued = false; const batch = this.#streamingBatch; this.#streamingBatch = []; - if (batch.some(pending => typeof pending.event.payload.text === "string" && pending.event.payload.text.length > 0)) { - this.#streamedSinceBoundary = true; - } try { await this.#commitStreamingEvents(batch); } finally { this.#streamingEventsPending -= batch.length; } });