Skip to content

Commit 877ef38

Browse files
committed
feat(orchestration-v2): add subagent observability data model
Introduces the schema, storage, and migration for richer subagent tracking. Nothing produces the new data yet — adapters populate neutral defaults so every subagent row remains valid — which keeps this change reviewable as a pure data-model step. Contracts gain a reusable subagent identity: per-activation records (SubagentActivationId, OrchestrationV2SubagentActivation), cumulative usage, a role, recent activity, and workflow grouping. A subagent may now also rest at "idle" between activations. Because a subagent status is not a turn item status, the two are bridged by an explicit mapping rather than a copy. The Record type makes that total: adding a subagent status without giving it a timeline meaning is a compile error. Without it, a producer can emit a turn item whose own schema cannot decode it, which is unrecoverable — the projection rebuild then fails on every subsequent startup and the server cannot boot. Migration 043 backfills existing rows so old events stay readable. Its riskiest path is a partially-migrated row, where already-present JSON is round-tripped through COALESCE; a test pins that structured values keep their JSON subtype rather than being rewritten as quoted strings. Also narrows event-envelope attribution in ProviderEventIngestor: a payload carrying an explicit null run or node id now keeps that null instead of inheriting the ambient run. Activations legitimately have no run id, and the envelope is persistence metadata only — routing reads payload fields — but this does change stored metadata for existing event types that already pass explicit nulls.
1 parent 408efa6 commit 877ef38

29 files changed

Lines changed: 1031 additions & 10 deletions

‎apps/server/src/orchestration-v2/Adapters/AcpAdapterV2.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1942,6 +1942,14 @@ export function makeAcpAdapterV2(options: AcpAdapterV2Options): ProviderAdapterV
19421942
prompt: update.prompt,
19431943
title: update.title,
19441944
model: update.model,
1945+
kind: "subagent",
1946+
role: { name: "general-purpose", source: "app_default" },
1947+
usage: null,
1948+
currentActivationId: null,
1949+
activationCount: 1,
1950+
workflow: null,
1951+
workflowMembership: null,
1952+
recentActivity: [],
19451953
result: null,
19461954
startedAt: now,
19471955
}),

‎apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2321,6 +2321,14 @@ export function makeClaudeAdapterV2(
23212321
prompt: input.prompt ?? "",
23222322
title: input.title ?? null,
23232323
model: input.context.input.modelSelection.model,
2324+
kind: "subagent" as const,
2325+
role: { name: "general-purpose", source: "app_default" as const },
2326+
usage: null,
2327+
currentActivationId: null,
2328+
activationCount: 1,
2329+
workflow: null,
2330+
workflowMembership: null,
2331+
recentActivity: [],
23242332
result: null,
23252333
startedAt: now,
23262334
}),

‎apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1-
import { CodexSettings, defaultInstanceIdForDriver, ProviderDriverKind } from "@t3tools/contracts";
1+
import {
2+
CodexSettings,
3+
defaultInstanceIdForDriver,
4+
orchestrationV2SubagentStatusAsTurnItemStatus,
5+
ProviderDriverKind,
6+
} from "@t3tools/contracts";
27
import { HostProcessEnvironment } from "@t3tools/shared/hostProcess";
38
import { getModelSelectionStringOptionValue } from "@t3tools/shared/model";
49
import { resolveSpawnCommand } from "@t3tools/shared/shell";
@@ -100,6 +105,7 @@ import {
100105
makeSubagentConversationArtifacts,
101106
subagentThreadTitle,
102107
} from "../SubagentProjection.ts";
108+
import { defaultSubagentRole } from "../SubagentObservability.ts";
103109

104110
const CODEX_PROVIDER = ProviderDriverKind.make("codex");
105111
export const CODEX_DRIVER_KIND = CODEX_PROVIDER;
@@ -1721,7 +1727,7 @@ export function makeCodexAdapterV2(adapterOptions: CodexAdapterV2Options): Provi
17211727
nativeItemRef: task.nativeTaskRef,
17221728
parentItemId: null,
17231729
ordinal: input.subagent.turnItemOrdinal,
1724-
status: task.status,
1730+
status: orchestrationV2SubagentStatusAsTurnItemStatus[task.status],
17251731
title: task.title,
17261732
startedAt: task.startedAt,
17271733
completedAt: task.completedAt,
@@ -1968,8 +1974,16 @@ export function makeCodexAdapterV2(adapterOptions: CodexAdapterV2Options): Provi
19681974
prompt: input.prompt,
19691975
title: input.title,
19701976
model: input.model,
1977+
kind: "subagent",
1978+
role: defaultSubagentRole(),
19711979
status: "running",
19721980
result: null,
1981+
usage: null,
1982+
currentActivationId: null,
1983+
activationCount: 1,
1984+
workflow: null,
1985+
workflowMembership: null,
1986+
recentActivity: [],
19731987
startedAt: now,
19741988
completedAt: null,
19751989
updatedAt: now,

‎apps/server/src/orchestration-v2/Adapters/CursorAdapterV2.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1497,6 +1497,14 @@ export function makeCursorAdapterV2(
14971497
prompt: args.prompt,
14981498
title: args.description,
14991499
model: args.model ?? input.context.input.modelSelection.model,
1500+
kind: "subagent",
1501+
role: { name: "general-purpose", source: "app_default" },
1502+
usage: null,
1503+
currentActivationId: null,
1504+
activationCount: 1,
1505+
workflow: null,
1506+
workflowMembership: null,
1507+
recentActivity: [],
15001508
result: null,
15011509
startedAt: now,
15021510
}),

‎apps/server/src/orchestration-v2/Adapters/OpenCodeAdapterV2.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1210,6 +1210,14 @@ export function makeOpenCodeAdapterV2(options: OpenCodeAdapterV2Options): Provid
12101210
prompt,
12111211
title,
12121212
model: context.model,
1213+
kind: "subagent",
1214+
role: { name: "general-purpose", source: "app_default" },
1215+
usage: null,
1216+
currentActivationId: null,
1217+
activationCount: 1,
1218+
workflow: null,
1219+
workflowMembership: null,
1220+
recentActivity: [],
12131221
status: subagentStatus,
12141222
result: context.result,
12151223
startedAt: context.startedAt,

‎apps/server/src/orchestration-v2/FoundationPersistence.test.ts‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
ProviderThreadId,
2020
RunAttemptId,
2121
RunId,
22+
SubagentActivationId,
2223
ThreadId,
2324
TurnItemId,
2425
} from "@t3tools/contracts";
@@ -266,13 +267,17 @@ it.layer(TestLayer)("orchestration V2 foundation persistence", (it) => {
266267
const eventSink = yield* EventSinkV2;
267268
const projectionStore = yield* ProjectionStoreV2;
268269
const maintenance = yield* ProjectionMaintenanceV2;
270+
const sql = yield* SqlClient.SqlClient;
269271
const now = yield* DateTime.now;
270272
const parentThreadId = ThreadId.make("thread:foundation-cross-thread:parent");
271273
const childThreadId = ThreadId.make("thread:foundation-cross-thread:child");
272274
const childProviderThreadId = ProviderThreadId.make(
273275
"provider-thread:foundation-cross-thread:child",
274276
);
275277
const subagentId = NodeId.make("subagent:foundation-cross-thread");
278+
const activationId = SubagentActivationId.make(
279+
"subagent:foundation-cross-thread:activation:1",
280+
);
276281
const spawnTransferId = ContextTransferId.make("transfer:foundation-cross-thread:spawn");
277282
const resultTransferId = ContextTransferId.make("transfer:foundation-cross-thread:result");
278283
const parentThread = makeThread(parentThreadId, now);
@@ -321,8 +326,37 @@ it.layer(TestLayer)("orchestration V2 foundation persistence", (it) => {
321326
prompt: "Inspect the child flow",
322327
title: "Cross-thread child",
323328
model: modelSelection.model,
329+
kind: "subagent",
330+
role: { name: "general-purpose", source: "app_default" },
324331
status: "completed",
325332
result: "done",
333+
usage: null,
334+
currentActivationId: null,
335+
activationCount: 1,
336+
workflow: null,
337+
workflowMembership: null,
338+
recentActivity: [],
339+
startedAt: now,
340+
completedAt: now,
341+
updatedAt: now,
342+
},
343+
},
344+
{
345+
id: EventId.make("event:foundation-cross-thread:subagent-activation"),
346+
type: "subagent-activation.updated",
347+
threadId: parentThreadId,
348+
nodeId: subagentId,
349+
providerInstanceId,
350+
occurredAt: now,
351+
payload: {
352+
id: activationId,
353+
threadId: parentThreadId,
354+
subagentId,
355+
runId: null,
356+
providerTurnId: null,
357+
ordinal: 1,
358+
status: "completed",
359+
usage: { totalTokens: 240, toolUses: 2 },
326360
startedAt: now,
327361
completedAt: now,
328362
updatedAt: now,
@@ -423,11 +457,57 @@ it.layer(TestLayer)("orchestration V2 foundation persistence", (it) => {
423457
[childProviderThreadId],
424458
);
425459
assert.equal(child.thread.activeProviderThreadId, childProviderThreadId);
460+
assert.deepEqual(
461+
parent.subagentActivations.map((activation) => ({
462+
id: activation.id,
463+
totalTokens: activation.usage?.totalTokens,
464+
})),
465+
[
466+
{
467+
id: activationId,
468+
totalTokens: 240,
469+
},
470+
],
471+
);
426472
});
427473

428474
yield* assertCrossThreadProjection;
429475
assert.isTrue((yield* maintenance.verify).valid);
476+
yield* sql`
477+
INSERT INTO orchestration_v2_projection_subagent_activations (
478+
activation_id,
479+
thread_id,
480+
subagent_id,
481+
run_id,
482+
provider_turn_id,
483+
ordinal,
484+
status,
485+
started_at,
486+
completed_at,
487+
updated_at,
488+
payload_json
489+
)
490+
VALUES (
491+
'activation:foundation-cross-thread:stale',
492+
${parentThreadId},
493+
${subagentId},
494+
NULL,
495+
NULL,
496+
99,
497+
'completed',
498+
NULL,
499+
NULL,
500+
'2026-07-26T00:00:00.000Z',
501+
'{}'
502+
)
503+
`;
430504
assert.isTrue((yield* maintenance.rebuild).valid);
505+
const staleActivationRows = yield* sql<{ readonly count: number }>`
506+
SELECT COUNT(*) AS count
507+
FROM orchestration_v2_projection_subagent_activations
508+
WHERE activation_id = 'activation:foundation-cross-thread:stale'
509+
`;
510+
assert.equal(staleActivationRows[0]?.count, 0);
431511
yield* assertCrossThreadProjection;
432512
}),
433513
);

‎apps/server/src/orchestration-v2/Orchestrator.ts‎

Lines changed: 89 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
type OrchestrationV2ThreadShellSnapshot,
1919
type OrchestrationV2StoredEvent,
2020
type OrchestrationV2Subagent,
21+
type OrchestrationV2SubagentActivation,
2122
type OrchestrationV2ThreadProjection,
2223
type OrchestrationV2TurnItem,
2324
ProviderInstanceId,
@@ -53,6 +54,7 @@ import {
5354
subagentResultForRun,
5455
subagentThreadTitle,
5556
} from "./SubagentProjection.ts";
57+
import { defaultSubagentRole, subagentActivationId } from "./SubagentObservability.ts";
5658
import { ThreadForkServiceV2 } from "./ThreadForkService.ts";
5759

5860
export class OrchestratorDispatchError extends Schema.TaggedErrorClass<OrchestratorDispatchError>()(
@@ -222,7 +224,10 @@ function isBlockingRun(run: OrchestrationV2Run): boolean {
222224

223225
function delegatedTaskTerminalStatus(
224226
status: OrchestrationV2Run["status"],
225-
): OrchestrationV2Subagent["status"] | null {
227+
): Extract<
228+
OrchestrationV2Subagent["status"],
229+
"completed" | "failed" | "cancelled" | "interrupted"
230+
> | null {
226231
switch (status) {
227232
case "completed":
228233
case "failed":
@@ -240,6 +245,12 @@ function delegatedTaskTerminalStatus(
240245
}
241246
}
242247

248+
const isTerminalSubagentActivation = (activation: OrchestrationV2SubagentActivation) =>
249+
activation.status === "completed" ||
250+
activation.status === "failed" ||
251+
activation.status === "cancelled" ||
252+
activation.status === "interrupted";
253+
243254
function nextQueuedRun(
244255
projection: OrchestrationV2ThreadProjection,
245256
): OrchestrationV2Run | undefined {
@@ -3687,6 +3698,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
36873698
runtimeMode: command.runtimeMode,
36883699
interactionMode: command.interactionMode,
36893700
};
3701+
const activationId = subagentActivationId(taskNodeId, 1);
36903702
const task: OrchestrationV2Subagent = {
36913703
id: taskNodeId,
36923704
threadId: command.parentThreadId,
@@ -3702,8 +3714,16 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
37023714
prompt: command.task,
37033715
title: command.title ?? null,
37043716
model: command.modelSelection.model,
3717+
kind: "subagent",
3718+
role: defaultSubagentRole("delegated-worker"),
37053719
status: "running",
37063720
result: null,
3721+
usage: null,
3722+
currentActivationId: activationId,
3723+
activationCount: 1,
3724+
workflow: null,
3725+
workflowMembership: null,
3726+
recentActivity: [],
37073727
startedAt: now,
37083728
completedAt: null,
37093729
updatedAt: now,
@@ -3726,6 +3746,19 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
37263746
completedAt: null,
37273747
};
37283748
const parentProviderTurn = providerTurnForRun(parentProjection, parentRun);
3749+
const activation = {
3750+
id: activationId,
3751+
threadId: command.parentThreadId,
3752+
subagentId: taskNodeId,
3753+
runId: parentRun.id,
3754+
providerTurnId: parentProviderTurn?.id ?? null,
3755+
ordinal: 1,
3756+
status: "running",
3757+
usage: null,
3758+
startedAt: now,
3759+
completedAt: null,
3760+
updatedAt: now,
3761+
} satisfies OrchestrationV2SubagentActivation;
37293762
const taskTurnItem: OrchestrationV2TurnItem = {
37303763
id: taskTurnItemId,
37313764
threadId: command.parentThreadId,
@@ -3780,6 +3813,16 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
37803813
occurredAt: now,
37813814
payload: task,
37823815
});
3816+
yield* emitEvent({
3817+
type: "subagent-activation.updated",
3818+
threadId: command.parentThreadId,
3819+
runId: parentRun.id,
3820+
nodeId: taskNodeId,
3821+
driver: targetAdapter.driver,
3822+
providerInstanceId: command.modelSelection.instanceId,
3823+
occurredAt: now,
3824+
payload: activation,
3825+
});
37833826
yield* emitEvent({
37843827
type: "turn-item.updated",
37853828
threadId: command.parentThreadId,
@@ -4949,9 +4992,41 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
49494992
providerThreadId: childRun.providerThreadId,
49504993
status: terminalStatus,
49514994
result: result.text,
4995+
currentActivationId: null,
49524996
completedAt: now,
49534997
updatedAt: now,
49544998
};
4999+
const currentActivation =
5000+
task.currentActivationId === null
5001+
? undefined
5002+
: parentProjection.subagentActivations.find(
5003+
(activation) => activation.id === task.currentActivationId,
5004+
);
5005+
const terminalActivation =
5006+
task.currentActivationId === null || currentActivation?.status === terminalStatus
5007+
? null
5008+
: currentActivation === undefined
5009+
? ({
5010+
id: task.currentActivationId,
5011+
threadId: task.threadId,
5012+
subagentId: task.id,
5013+
runId: task.runId,
5014+
providerTurnId: null,
5015+
ordinal: Math.max(1, task.activationCount),
5016+
status: terminalStatus,
5017+
usage: task.usage,
5018+
startedAt: task.startedAt,
5019+
completedAt: now,
5020+
updatedAt: now,
5021+
} satisfies OrchestrationV2SubagentActivation)
5022+
: isTerminalSubagentActivation(currentActivation)
5023+
? null
5024+
: ({
5025+
...currentActivation,
5026+
status: terminalStatus,
5027+
completedAt: now,
5028+
updatedAt: now,
5029+
} satisfies OrchestrationV2SubagentActivation);
49555030
const resultTransferId = yield* idAllocator.allocate.contextTransfer({
49565031
sourceThreadId: childThreadId,
49575032
targetThreadId: parentThreadId,
@@ -5036,6 +5111,19 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
50365111
occurredAt: now,
50375112
payload: updatedTask,
50385113
},
5114+
...(terminalActivation === null
5115+
? []
5116+
: [
5117+
{
5118+
type: "subagent-activation.updated" as const,
5119+
threadId: parentThreadId,
5120+
...(task.runId === null ? {} : { runId: task.runId }),
5121+
nodeId: task.id,
5122+
driver: task.driver,
5123+
occurredAt: now,
5124+
payload: terminalActivation,
5125+
},
5126+
]),
50395127
...(parentNode === undefined
50405128
? []
50415129
: [

‎apps/server/src/orchestration-v2/ProjectionMaintenance.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,7 @@ export const layer: Layer.Layer<
152152
yield* sql`DELETE FROM orchestration_v2_projection_provider_threads`;
153153
yield* sql`DELETE FROM orchestration_v2_projection_provider_session_bindings`;
154154
yield* sql`DELETE FROM orchestration_v2_projection_provider_sessions`;
155+
yield* sql`DELETE FROM orchestration_v2_projection_subagent_activations`;
155156
yield* sql`DELETE FROM orchestration_v2_projection_subagents`;
156157
yield* sql`DELETE FROM orchestration_v2_projection_nodes`;
157158
yield* sql`DELETE FROM orchestration_v2_projection_run_attempts`;

0 commit comments

Comments
 (0)