Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
51d41aa
fix(server): cascade parent lifecycle to subagent descendants
Quicksaver Nov 21, 2026
2e155e2
fix(server): preserve cascades through upstream lifecycle changes
Quicksaver Nov 21, 2026
94ab323
fix(server): reject conflicting side-chat cascade receipts
Quicksaver Nov 21, 2026
27d5b43
fix(server): preserve side-chat cascade ancestry
Quicksaver Nov 21, 2026
b188651
fix(server): roll back colliding side-chat effects
Quicksaver Nov 21, 2026
924b04e
fix(server): distinguish unused-only side-chat deletes
Quicksaver Nov 21, 2026
6f4140d
fix(server): keep committed side-chat cascades after no-op close
Quicksaver Nov 21, 2026
8f373ac
fix(server): verify side-chat deletion and archive provenance
Quicksaver Nov 21, 2026
7b6a607
fix(server): protect side-chat delete and restore recovery
Quicksaver Nov 21, 2026
4cd83f0
fix(server): require durable side-chat lifecycle recovery
Quicksaver Nov 21, 2026
641409b
fix(server): preserve side-chat recovery eligibility
Quicksaver Nov 21, 2026
fa79039
fix(server): check side-chat eligibility before scheduling cascades
Quicksaver Nov 21, 2026
372a6f8
fix(server): trace subagent lifecycle reads
Quicksaver Nov 21, 2026
4f0800d
test(server): check descendants after a conditional delete
Quicksaver Nov 21, 2026
90b5e50
fix(server): preserve subagent cascade receipt ownership
Quicksaver Nov 21, 2026
b513d79
docs(user): explain the subagent cascade project boundary
Quicksaver Nov 21, 2026
adc6eb6
fix(server): keep subagent cascade retries on the same path
Quicksaver Nov 21, 2026
9d87f24
fix(server): recover legacy subagent cascade receipts
Quicksaver Nov 21, 2026
15db1bb
fix(server): verify legacy cascade ownership before recovery
Quicksaver Nov 21, 2026
eabb7a0
fix(server): replay committed leaf restores on recovery
Quicksaver Nov 21, 2026
c7d5c75
test(server): consolidate subagent cascade regressions
Quicksaver Nov 21, 2026
363ff75
test(server): cover cascade recovery boundaries in place
Quicksaver Nov 21, 2026
8765bc5
test(server): distinguish cascade recovery from independent archives
Quicksaver Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
217 changes: 206 additions & 11 deletions apps/server/src/orchestration-v2/CommandReceiptStore.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,19 @@ export class CommandReceiptStoreReadError extends Schema.TaggedError<CommandRece
}
}

class CommandReceiptStoreLifecycleError extends Schema.TaggedError<CommandReceiptStoreLifecycleError>()(
"CommandReceiptStoreLifecycleError",
{ threadId: ThreadId, cause: Schema.Defect() },
) {
override get message(): string {
return `Failed to read orchestration V2 lifecycle receipt for thread ${this.threadId}.`;
}
}

export const CommandReceiptStoreV2Error = Schema.Union([
CommandReceiptStoreWriteError,
CommandReceiptStoreReadError,
CommandReceiptStoreLifecycleError,
]);
export type CommandReceiptStoreV2Error = typeof CommandReceiptStoreV2Error.Type;

Expand All @@ -48,6 +58,7 @@ export const CommandReceiptV2 = Schema.Struct({
resultSequence: NonNegativeInt,
status: CommandReceiptV2Status,
error: Schema.NullOr(Schema.String),
archiveSourceCommandId: Schema.optional(CommandId),
});
export type CommandReceiptV2 = typeof CommandReceiptV2.Type;

Expand All @@ -62,15 +73,27 @@ export const ProjectCommandReceiptV2 = Schema.Struct({
});
export type ProjectCommandReceiptV2 = typeof ProjectCommandReceiptV2.Type;

type AnyCommandReceiptV2 = CommandReceiptV2 | ProjectCommandReceiptV2;
export type AnyCommandReceiptV2 = CommandReceiptV2 | ProjectCommandReceiptV2;

export interface CommandReceiptStoreV2Shape {
readonly getLatestLifecycle: (
threadId: ThreadId,
commandTypes?: ReadonlyArray<OrchestrationCommandReceipts.LifecycleCommandType>,
) => Effect.Effect<CommandReceiptV2 | null, CommandReceiptStoreV2Error>;
readonly insertIfAbsent: (
receipt: AnyCommandReceiptV2,
) => Effect.Effect<boolean, CommandReceiptStoreV2Error>;
readonly upsert: (
receipt: AnyCommandReceiptV2,
) => Effect.Effect<void, CommandReceiptStoreV2Error>;
readonly setArchiveSourceIfMissing: (
input: Parameters<
OrchestrationCommandReceipts.OrchestrationCommandReceiptRepository["Service"]["setArchiveSourceIfMissing"]
>[0],
) => Effect.Effect<boolean, CommandReceiptStoreV2Error>;
readonly getAnyByCommandId: (
commandId: CommandId,
) => Effect.Effect<Option.Option<AnyCommandReceiptV2>, CommandReceiptStoreV2Error>;
/** None for project command ids. */
readonly getByCommandId: (
commandId: CommandId,
Expand Down Expand Up @@ -108,6 +131,23 @@ function fromApplicationReceipt(receipt: OrchestrationCommandReceipts.Orchestrat
resultSequence: receipt.resultSequence,
status: receipt.status,
error: receipt.error,
...(receipt.archiveSourceCommandId == null
? {}
: { archiveSourceCommandId: receipt.archiveSourceCommandId }),
});
}

function fromProjectApplicationReceipt(
receipt: OrchestrationCommandReceipts.OrchestrationCommandReceipt,
) {
return decodeProjectReceipt({
commandId: receipt.commandId,
projectId: receipt.aggregateId,
commandType: receipt.commandType,
acceptedAt: receipt.acceptedAt,
resultSequence: receipt.resultSequence,
status: receipt.status,
error: receipt.error,
});
}

Expand All @@ -118,7 +158,11 @@ function toApplicationReceipt(
commandId: receipt.commandId,
...("projectId" in receipt
? { aggregateKind: "project" as const, aggregateId: receipt.projectId }
: { aggregateKind: "thread" as const, aggregateId: receipt.threadId }),
: {
aggregateKind: "thread" as const,
aggregateId: receipt.threadId,
archiveSourceCommandId: receipt.archiveSourceCommandId,
}),
commandType: receipt.commandType,
acceptedAt: DateTime.formatIso(receipt.acceptedAt),
resultSequence: receipt.resultSequence,
Expand All @@ -137,6 +181,15 @@ const layerBase: Layer.Layer<
const receipts = yield* OrchestrationCommandReceipts.OrchestrationCommandReceiptRepository;

return CommandReceiptStoreV2.of({
getLatestLifecycle: Effect.fn("CommandReceiptStore.getLatestLifecycle")(
(threadId, commandTypes) =>
receipts.getLatestLifecycle({ threadId, commandTypes }).pipe(
Effect.flatMap((receipt) =>
Option.isSome(receipt) ? fromApplicationReceipt(receipt.value) : Effect.succeed(null),
),
Effect.mapError((cause) => new CommandReceiptStoreLifecycleError({ threadId, cause })),
),
),
insertIfAbsent: (receipt) =>
receipts.insertIfAbsent(toApplicationReceipt(receipt)).pipe(
Effect.mapError(
Expand All @@ -157,6 +210,29 @@ const layerBase: Layer.Layer<
}),
),
),
setArchiveSourceIfMissing: Effect.fn("CommandReceiptStore.setArchiveSourceIfMissing")(
(input) =>
receipts
.setArchiveSourceIfMissing(input)
.pipe(
Effect.mapError(
(cause) => new CommandReceiptStoreWriteError({ commandId: input.commandId, cause }),
),
),
),
getAnyByCommandId: Effect.fn("CommandReceiptStore.getAnyByCommandId")((commandId) =>
receipts.getByCommandId({ commandId }).pipe(
Effect.flatMap((receipt) => {
if (Option.isNone(receipt)) return Effect.succeedNone;
const decode: Effect.Effect<AnyCommandReceiptV2, Schema.SchemaError> =
receipt.value.aggregateKind === "project"
? fromProjectApplicationReceipt(receipt.value)
: fromApplicationReceipt(receipt.value);
return decode.pipe(Effect.asSome);
}),
Effect.mapError((cause) => new CommandReceiptStoreReadError({ commandId, cause })),
),
),
getByCommandId: (commandId) =>
receipts.getByCommandId({ commandId }).pipe(
Effect.flatMap(
Expand All @@ -181,15 +257,7 @@ const layerBase: Layer.Layer<
Effect.flatMap((receipt) =>
Option.isNone(receipt) || receipt.value.aggregateKind !== "project"
? Effect.succeedNone
: decodeProjectReceipt({
commandId: receipt.value.commandId,
projectId: receipt.value.aggregateId,
commandType: receipt.value.commandType,
acceptedAt: receipt.value.acceptedAt,
resultSequence: receipt.value.resultSequence,
status: receipt.value.status,
error: receipt.value.error,
}).pipe(Effect.asSome),
: fromProjectApplicationReceipt(receipt.value).pipe(Effect.asSome),
),
Effect.mapError((cause) => new CommandReceiptStoreReadError({ commandId, cause })),
),
Expand All @@ -200,3 +268,130 @@ const layerBase: Layer.Layer<
export const layer = layerBase.pipe(Layer.provide(OrchestrationCommandReceipts.layer));

export const layerFromApplicationReceipts = layerBase;

export const cascadeCommandIdLimit = 32;

export const cascadeCommandIdAt = (base: CommandId, retry: number) =>
retry === 0 ? base : CommandId.make(`${base}:retry:${retry}`);

/** Older receipts encode cascade ownership in the command ID. */
export const legacyCascadeCommandId = Effect.fn("CommandReceiptStore.cascadeCommandId")(function* (
receipts: CommandReceiptStoreV2Shape,
base: CommandId,
) {
for (let retry = 0; retry < cascadeCommandIdLimit; retry++) {
const id = cascadeCommandIdAt(base, retry);
const receipt = yield* receipts.getByCommandId(id);
if (Option.isNone(receipt) || receipt.value.status === "accepted") return id;
}
return undefined;
});

export const matchesLegacyCascadePath = Effect.fn("CommandReceiptStore.matchesLegacyCascadePath")(
function* (
receipts: CommandReceiptStoreV2Shape,
anchorId: CommandId,
path: ReadonlyArray<ThreadId>,
completedId: CommandId,
occupiesDispatchedId: (receipt: AnyCommandReceiptV2) => boolean,
) {
const retries: Array<{ baseId: CommandId; retry: number; dispatched: boolean }> = [];
let id: string = completedId;
for (const [offset, threadId] of path.toReversed().entries()) {
const segment = `:subagent:${threadId}`;
if (!id.endsWith(segment)) {
const suffix = /:retry:([1-9][0-9]*)$/.exec(id);
if (suffix === null) return false;
const retry = Number(suffix[1]);
if (retry >= cascadeCommandIdLimit) return false;
id = id.slice(0, suffix.index);
retries.push({ baseId: CommandId.make(id), retry, dispatched: offset === 0 });
}
if (!id.endsWith(segment)) return false;
id = id.slice(0, -segment.length);
}
if (id !== anchorId) return false;

for (const { baseId, retry, dispatched } of retries) {
for (let previous = 0; previous < retry; previous++) {
const commandId = cascadeCommandIdAt(baseId, previous);
const receipt = yield* dispatched
? receipts.getAnyByCommandId(commandId)
: receipts.getByCommandId(commandId);
if (
Option.isNone(receipt) ||
(dispatched ? !occupiesDispatchedId(receipt.value) : receipt.value.status !== "rejected")
)
return false;
}
}
return true;
},
);

/** A lifecycle choice made after the cascade's source command, other than `ownCommandId`. */
export const supersedesCascade = (
latest: CommandReceiptV2 | null,
cutoff: number,
ownCommandId?: CommandId,
) => latest !== null && latest.resultSequence > cutoff && latest.commandId !== ownCommandId;

/** Whether a cascade from an archive of `rootThreadId`, along `path`, archived this thread. */
export const archivedByCascade = Effect.fn("CommandReceiptStore.archivedByCascade")(function* (
receipts: CommandReceiptStoreV2Shape,
latest: CommandReceiptV2 | null,
rootThreadId: ThreadId,
path: ReadonlyArray<ThreadId>,
expectedArchiveCommandId?: CommandId,
) {
if (latest?.commandType !== "thread.archive") return false;
let archive = latest;
let depth = path.length;
while (depth > 0 && archive.archiveSourceCommandId !== undefined) {
if (archive.archiveSourceCommandId === archive.commandId) return false;
const source = Option.getOrUndefined(
yield* receipts.getByCommandId(archive.archiveSourceCommandId),
);
if (
source?.status !== "accepted" ||
source.commandType !== "thread.archive" ||
source.resultSequence > archive.resultSequence
)
return false;
// A cascade can pass through an already archived thread without claiming its archive.
const ancestor =
source.threadId === rootThreadId
? 0
: depth < 2
? -1
: path.lastIndexOf(source.threadId, depth - 2) + 1;
if (ancestor <= 0 && source.threadId !== rootThreadId) return false;
depth = ancestor;
archive = source;
}
if (depth === 0)
return expectedArchiveCommandId === undefined || archive.commandId === expectedArchiveCommandId;

const legacyPath = path.slice(0, depth);
let rootCommandId: string = archive.commandId;
for (const threadId of legacyPath.toReversed()) {
const segment = `:subagent:${threadId}`;
if (!rootCommandId.endsWith(segment)) rootCommandId = rootCommandId.replace(/:retry:\d+$/, "");
if (!rootCommandId.endsWith(segment)) return false;
rootCommandId = rootCommandId.slice(0, -segment.length);
}
if (expectedArchiveCommandId !== undefined && rootCommandId !== expectedArchiveCommandId)
return false;
const root = Option.getOrNull(yield* receipts.getByCommandId(CommandId.make(rootCommandId)));
const valid = root?.status === "accepted" && root.threadId === rootThreadId;
// Derive the IDs again, so a user ID only shaped like a cascade retry is not counted.
let derived = valid && root.commandType === "thread.archive" ? root.commandId : undefined;
for (const threadId of legacyPath) {
if (derived === undefined) return false;
derived = yield* legacyCascadeCommandId(
receipts,
CommandId.make(`${derived}:subagent:${threadId}`),
);
}
return derived === archive.commandId && (root?.resultSequence ?? 0) <= archive.resultSequence;
});
58 changes: 57 additions & 1 deletion apps/server/src/orchestration-v2/EffectOutbox.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,10 @@ import {
ProviderUserInputAnswers,
ProviderThreadId,
ProviderTurnId,
ProviderInteractionMode,
ProjectId,
RunId,
RuntimeMode,
RuntimeRequestId,
ThreadId,
} from "@t3tools/contracts";
Expand All @@ -32,6 +35,37 @@ import * as SqlClient from "effect/sql/SqlClient";

import { forkParked } from "../serverActivation.ts";

const EmbeddedSideChatCascade = Schema.Struct({
parentThreadId: ThreadId,
projectId: ProjectId,
cutoff: Schema.optional(NonNegativeInt),
archiveCommandId: Schema.optional(CommandId),
});
export type EmbeddedSideChatCascade = typeof EmbeddedSideChatCascade.Type;

/** Set while a cascade dispatches a descendant's lifecycle command; delete needs no source. */
export const SubagentCascade = Context.Reference<
| {
readonly source:
| {
readonly threadId: ThreadId;
readonly cutoff: number;
readonly archiveCommandId?: CommandId | undefined;
}
| undefined;
readonly path: ReadonlyArray<ThreadId>;
readonly parentArchiveCommandId: CommandId;
readonly legacyPath?:
| {
readonly anchorId: CommandId;
readonly depth: number;
readonly verified?: true;
}
| undefined;
}
| undefined
>("t3/orchestration-v2/SubagentCascade", { defaultValue: () => undefined });

export const OrchestrationEffectRequestV2 = Schema.Union([
Schema.Struct({
type: Schema.Literal("provider-runtime.continue"),
Expand Down Expand Up @@ -127,6 +161,16 @@ export const OrchestrationEffectRequestV2 = Schema.Union([
attachmentIds: Schema.Array(Schema.String),
skipReferenced: Schema.optional(Schema.Boolean),
}),
Schema.Struct({
type: Schema.Literal("subagent-threads.cascade"),
operation: Schema.Literals(["thread.archive", "thread.unarchive", "thread.delete"]),
sideChat: Schema.optional(EmbeddedSideChatCascade),
directDelete: Schema.optional(Schema.Literal(true)),
stableSkipPrefix: Schema.optional(Schema.Literal(true)),
limit: Schema.optional(
Schema.Struct({ runtimeMode: RuntimeMode, interactionMode: ProviderInteractionMode }),
),
}),
Schema.Struct({
type: Schema.Literal("thread-title.generate"),
kind: Schema.Union([
Expand All @@ -150,6 +194,7 @@ export const REPLAY_SAFE_EFFECT_TYPES_AFTER_PROCESS_LOSS = [
"terminal.cleanup",
"preview.cleanup",
"attachment.cleanup",
"subagent-threads.cascade",
"thread-title.generate",
"delegated-tasks.stop",
] as const satisfies ReadonlyArray<OrchestrationEffectRequestV2["type"]>;
Expand Down Expand Up @@ -200,6 +245,13 @@ export interface PendingOrchestrationEffectV2 {
readonly availableAt?: DateTime.Utc;
}

export type SubagentCascadeEffect = PendingOrchestrationEffectV2 & {
readonly request: Extract<
OrchestrationEffectRequestV2,
{ readonly type: "subagent-threads.cascade" }
>;
};

export class EffectOutboxError extends Schema.TaggedError<EffectOutboxError>()(
"EffectOutboxError",
{
Expand Down Expand Up @@ -440,7 +492,11 @@ export const layer: Layer.Layer<EffectOutboxV2, never, SqlClient.SqlClient> = La
${nowIso},
${nowIso}
)
ON CONFLICT(effect_id) DO NOTHING
${
effect.request.type === "subagent-threads.cascade"
? sql``
: sql`ON CONFLICT(effect_id) DO NOTHING`
}
`,
{ concurrency: 1, discard: true },
);
Expand Down
Loading
Loading