The best way to control Claude Code, Codex and more from any computer or phone
fix(server): record ACP prompt response turn usage (#19958)
Co-authored-by: Ben Smith <ben.smith@boardbots.com> Co-authored-by: GLM-5.3 (Z.ai ACP) <noreply@z.ai> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: maria-rcks <254055478+maria-rcks@users.noreply.github.com>
Ben Smith committed
Oct 30, 2026 at 14:25 UTC
68be2f7b3273a642f3d48dc9fd723310f3fb5eef
3 files changed
+882
-5
apps/server/src/orchestration-v2/Adapters/AcpAdapterV2.test.ts
+809
@@ -76,6 +76,7 @@ import { makeTurnInput } from "./AcpAdapterV2.testkit.ts";
76
import type * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
77
import {
78
AcpProviderCapabilitiesV2,
79
+ acpPerTurnPromptUsage,
80
acpScopedNativeId,
81
acpPostSettleContinuationOfferEvidence,
82
acpPostSettleWakeEvidence,
@@ -110,6 +111,124 @@ const layerTest = Layer.mergeAll(
111
const ACP_TEST_DRIVER = ProviderDriverKind.make("acp-test");
112
const decodeUnknownJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown));
113
114
+describe("acpPerTurnPromptUsage", () => {
115
+ it("maps a per-turn sample straight onto TurnTokenUsage", () => {
116
+ assert.deepEqual(
117
+ acpPerTurnPromptUsage(
118
+ {
119
+ inputTokens: 2453,
120
+ outputTokens: 4,
121
+ totalTokens: 2457,
122
+ cachedReadTokens: 512,
123
+ cachedWriteTokens: 32,
124
+ thoughtTokens: 3,
125
+ },
126
+ false,
127
+ "completed",
128
+ ),
129
+ {
130
+ usageScope: "main_agent",
131
+ usageStatus: "complete",
132
+ hasSubagents: false,
133
+ inputTokens: 2453,
134
+ outputTokens: 4,
135
+ cachedInputTokens: 512,
136
+ cacheCreationTokens: 32,
137
+ reasoningTokens: 3,
138
+ },
139
+ );
140
+ });
141
+
142
+ it("clamps subsets that exceed their parents and drops unset counters", () => {
143
+ assert.deepEqual(
144
+ acpPerTurnPromptUsage(
145
+ {
146
+ inputTokens: 100,
147
+ outputTokens: 10,
148
+ totalTokens: 110,
149
+ cachedReadTokens: 150,
150
+ cachedWriteTokens: 120,
151
+ thoughtTokens: 30,
152
+ },
153
+ false,
154
+ "completed",
155
+ ),
156
+ {
157
+ usageScope: "main_agent",
158
+ usageStatus: "complete",
159
+ hasSubagents: false,
160
+ inputTokens: 100,
161
+ outputTokens: 10,
162
+ cachedInputTokens: 100,
163
+ cacheCreationTokens: 0,
164
+ reasoningTokens: 10,
165
+ },
166
+ );
167
+ assert.deepEqual(
168
+ acpPerTurnPromptUsage(
169
+ { inputTokens: 100, outputTokens: 10, totalTokens: 110 },
170
+ false,
171
+ "completed",
172
+ ),
173
+ {
174
+ usageScope: "main_agent",
175
+ usageStatus: "complete",
176
+ hasSubagents: false,
177
+ inputTokens: 100,
178
+ outputTokens: 10,
179
+ },
180
+ );
181
+ });
182
+
183
+ it("caps cache writes at the input left over after cache reads", () => {
184
+ // Each counter fits under input alone, but together they exceed it.
185
+ assert.deepEqual(
186
+ acpPerTurnPromptUsage(
187
+ {
188
+ inputTokens: 100,
189
+ outputTokens: 10,
190
+ totalTokens: 110,
191
+ cachedReadTokens: 80,
192
+ cachedWriteTokens: 80,
193
+ },
194
+ false,
195
+ "completed",
196
+ ),
197
+ {
198
+ usageScope: "main_agent",
199
+ usageStatus: "complete",
200
+ hasSubagents: false,
201
+ inputTokens: 100,
202
+ outputTokens: 10,
203
+ cachedInputTokens: 80,
204
+ cacheCreationTokens: 20,
205
+ },
206
+ );
207
+ });
208
+
209
+ it("marks present usage partial on a non-completed terminal and missing usage unavailable", () => {
210
+ assert.deepEqual(
211
+ acpPerTurnPromptUsage(
212
+ { inputTokens: 100, outputTokens: 10, totalTokens: 110 },
213
+ true,
214
+ "interrupted",
215
+ ),
216
+ {
217
+ usageScope: "main_agent",
218
+ usageStatus: "partial",
219
+ hasSubagents: true,
220
+ inputTokens: 100,
221
+ outputTokens: 10,
222
+ },
223
+ );
224
+ assert.deepEqual(acpPerTurnPromptUsage(undefined, false, "completed"), {
225
+ usageScope: "main_agent",
226
+ usageStatus: "unavailable",
227
+ hasSubagents: false,
228
+ });
229
+ });
230
+});
231
+
232
describe("acpToolCallDiffPatch", () => {
233
it("builds per-file patches from ACP hunks and recorded old/new text", () => {
234
for (const operation of ["add", "delete"]) {
@@ -419,6 +538,696 @@ function assertReinjectedInstructions(
538
}
539
540
describe("AcpAdapterV2", () => {
541
+ it.live("reports per-turn usage unavailable on a continuation turn that never prompts", () =>
542
+ Effect.gen(function* () {
543
+ const path = yield* Path.Path;
544
+ const instanceId = ProviderInstanceId.make("acp-test-usage-continuation");
545
+ const threadId = ThreadId.make("thread-acp-usage-continuation");
546
+ let promptOrdinal = 0;
547
+ const promptUsages = [
548
+ { inputTokens: 60, outputTokens: 15, totalTokens: 75 },
549
+ { inputTokens: 130, outputTokens: 30, totalTokens: 160 },
550
+ ];
551
+ const adapter = yield* makeAcpAdapterV2({
552
+ instanceId,
553
+ selfInvocation: yield* resolveSelfInvocation(),
554
+ continuationRequests: { offer: () => Effect.void },
555
+ flavor: {
556
+ driver: ACP_TEST_DRIVER,
557
+ capabilities: AcpProviderCapabilitiesV2,
558
+ reportsPerTurnPromptUsage: true,
559
+ enablePostSettleContinuation: true,
560
+ makeRuntime: makeMockRuntime({
561
+ childProcessSpawner: yield* ChildProcessSpawner.ChildProcessSpawner,
562
+ mockAgentPath: yield* path.fromFileUrl(
563
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
564
+ ),
565
+ wrapRuntime: (runtime) => ({
566
+ ...runtime,
567
+ prompt: () => {
568
+ promptOrdinal += 1;
569
+ const usage = promptUsages[promptOrdinal - 1];
570
+ if (usage === undefined) return Effect.die("Unexpected prompt");
571
+ return Effect.succeed({ stopReason: "end_turn" as const, usage });
572
+ },
573
+ }),
574
+ }),
575
+ },
576
+ });
577
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
578
+ runtimeMode: "full-access",
579
+ interactionMode: "default",
580
+ cwd: process.cwd(),
581
+ });
582
+ const modelSelection = { instanceId, model: "default" } as const;
583
+ const runtime = yield* adapter.openSession({
584
+ threadId,
585
+ providerSessionId: ProviderSessionId.make("provider-session-acp-usage-continuation"),
586
+ modelSelection,
587
+ runtimePolicy,
588
+ });
589
+ const providerThread = yield* runtime.ensureThread({
590
+ threadId,
591
+ modelSelection,
592
+ runtimePolicy,
593
+ });
594
+ const now = yield* DateTime.now;
595
+ const completedUsage = (ordinal: number) =>
596
+ Effect.gen(function* () {
597
+ yield* runtime.startTurn(
598
+ makeTurnInput({ threadId, providerThread, instanceId, runtimePolicy, now, ordinal }),
599
+ );
600
+ const events = Array.from(
601
+ yield* runtime.events.pipe(
602
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
603
+ Stream.runCollect,
604
+ ),
605
+ );
606
+ const completed = events.find(
607
+ (event) =>
608
+ event.type === "provider_turn.updated" && event.providerTurn.status === "completed",
609
+ );
610
+ return completed?.type === "provider_turn.updated"
611
+ ? completed.providerTurn.turnTokenUsage
612
+ : null;
613
+ });
614
+ assert.deepEqual(yield* completedUsage(1), {
615
+ usageScope: "main_agent",
616
+ usageStatus: "complete",
617
+ hasSubagents: false,
618
+ inputTokens: 60,
619
+ outputTokens: 15,
620
+ });
621
+ // Continuation attach: drains wake traffic and finalizes without ever
622
+ // dispatching session/prompt, so it must report unavailable usage.
623
+ yield* runtime.startTurn(
624
+ makeTurnInput({
625
+ threadId,
626
+ providerThread,
627
+ instanceId,
628
+ runtimePolicy,
629
+ now,
630
+ ordinal: 2,
631
+ messageCreatedBy: "agent",
632
+ messageCreationSource: "provider",
633
+ messageText: "Background task completed.",
634
+ }),
635
+ );
636
+ const continuationEvents = Array.from(
637
+ yield* runtime.events.pipe(
638
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
639
+ Stream.runCollect,
640
+ ),
641
+ );
642
+ const continuation = continuationEvents.find(
643
+ (event) =>
644
+ event.type === "provider_turn.updated" && event.providerTurn.status === "completed",
645
+ );
646
+ assert.deepEqual(
647
+ continuation?.type === "provider_turn.updated"
648
+ ? continuation.providerTurn.turnTokenUsage
649
+ : null,
650
+ { usageScope: "main_agent", usageStatus: "unavailable", hasSubagents: false },
651
+ );
652
+ // The continuation must not disturb the next real prompt's sample.
653
+ assert.deepEqual(yield* completedUsage(3), {
654
+ usageScope: "main_agent",
655
+ usageStatus: "complete",
656
+ hasSubagents: false,
657
+ inputTokens: 130,
658
+ outputTokens: 30,
659
+ });
660
+ assert.equal(promptOrdinal, 2, "continuation turn must not dispatch session/prompt");
661
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
662
+ );
663
+ it.live("retains returned usage when Stop finalizes before the prompt callback", () =>
664
+ Effect.gen(function* () {
665
+ const path = yield* Path.Path;
666
+ const instanceId = ProviderInstanceId.make("acp-test-prompt-usage-stop");
667
+ const threadId = ThreadId.make("thread-acp-prompt-usage-stop");
668
+ const wireSettled = yield* Deferred.make<void>();
669
+ const releaseCompletion = yield* Deferred.make<void>();
670
+ const idAllocator = yield* IdAllocator.IdAllocatorV2;
671
+ const adapter = yield* makeAcpAdapterV2({
672
+ instanceId,
673
+ selfInvocation: yield* resolveSelfInvocation(),
674
+ testHooks: {
675
+ afterPromptWireSettled: () =>
676
+ Deferred.succeed(wireSettled, undefined).pipe(
677
+ Effect.andThen(Deferred.await(releaseCompletion)),
678
+ ),
679
+ },
680
+ flavor: {
681
+ driver: ACP_TEST_DRIVER,
682
+ capabilities: AcpProviderCapabilitiesV2,
683
+ reportsPerTurnPromptUsage: true,
684
+ preserveRuntimeOnSettledInterrupt: true,
685
+ makeRuntime: makeMockRuntime({
686
+ childProcessSpawner: yield* ChildProcessSpawner.ChildProcessSpawner,
687
+ mockAgentPath: yield* path.fromFileUrl(
688
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
689
+ ),
690
+ wrapRuntime: (runtime) => ({
691
+ ...runtime,
692
+ prompt: () =>
693
+ Effect.succeed({
694
+ stopReason: "end_turn" as const,
695
+ usage: { inputTokens: 60, outputTokens: 15, totalTokens: 75 },
696
+ }),
697
+ }),
698
+ }),
699
+ },
700
+ });
701
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
702
+ runtimeMode: "full-access",
703
+ interactionMode: "default",
704
+ cwd: process.cwd(),
705
+ });
706
+ const modelSelection = { instanceId, model: "default" } as const;
707
+ const runtime = yield* adapter.openSession({
708
+ threadId,
709
+ providerSessionId: ProviderSessionId.make("provider-session-acp-prompt-usage-stop"),
710
+ modelSelection,
711
+ runtimePolicy,
712
+ });
713
+ const providerThread = yield* runtime.ensureThread({
714
+ threadId,
715
+ modelSelection,
716
+ runtimePolicy,
717
+ });
718
+ yield* runtime.startTurn(
719
+ makeTurnInput({
720
+ threadId,
721
+ providerThread,
722
+ instanceId,
723
+ runtimePolicy,
724
+ now: yield* DateTime.now,
725
+ }),
726
+ );
727
+ yield* Deferred.await(wireSettled);
728
+ const providerTurnId = idAllocator.derive.providerTurn({
729
+ driver: ACP_TEST_DRIVER,
730
+ nativeTurnId: acpScopedNativeId(instanceId, "mock-session-1:turn:1"),
731
+ });
732
+ yield* runtime.interruptTurn({ providerThread, providerTurnId });
733
+ const completed = Array.from(
734
+ yield* runtime.events.pipe(
735
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
736
+ Stream.runCollect,
737
+ ),
738
+ ).find(
739
+ (event) =>
740
+ event.type === "provider_turn.updated" && event.providerTurn.status === "interrupted",
741
+ );
742
+ assert.deepEqual(
743
+ completed?.type === "provider_turn.updated" ? completed.providerTurn.turnTokenUsage : null,
744
+ {
745
+ usageScope: "main_agent",
746
+ usageStatus: "partial",
747
+ hasSubagents: false,
748
+ inputTokens: 60,
749
+ outputTokens: 15,
750
+ },
751
+ );
752
+ yield* Deferred.succeed(releaseCompletion, undefined);
753
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
754
+ );
755
+
756
+ it.live("drops a late prompt response that lands after the turn finalized", () =>
757
+ Effect.gen(function* () {
758
+ const path = yield* Path.Path;
759
+ const instanceId = ProviderInstanceId.make("acp-test-prompt-usage-late");
760
+ const threadId = ThreadId.make("thread-acp-prompt-usage-late");
761
+ const dispatched = yield* Deferred.make<void>();
762
+ const gate = yield* Deferred.make<void>();
763
+ const wireSettled = yield* Deferred.make<void>();
764
+ const idAllocator = yield* IdAllocator.IdAllocatorV2;
765
+ const adapter = yield* makeAcpAdapterV2({
766
+ instanceId,
767
+ selfInvocation: yield* resolveSelfInvocation(),
768
+ testHooks: {
769
+ afterPromptWireSettled: () =>
770
+ Deferred.succeed(wireSettled, undefined).pipe(Effect.asVoid),
771
+ },
772
+ flavor: {
773
+ driver: ACP_TEST_DRIVER,
774
+ capabilities: AcpProviderCapabilitiesV2,
775
+ reportsPerTurnPromptUsage: true,
776
+ terminateRuntimeProcessGroupOnInterrupt: true,
777
+ makeRuntime: makeMockRuntime({
778
+ childProcessSpawner: yield* ChildProcessSpawner.ChildProcessSpawner,
779
+ mockAgentPath: yield* path.fromFileUrl(
780
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
781
+ ),
782
+ ownDetachedProcessGroup: true,
783
+ processGroupTerminationGrace: 0,
784
+ wrapRuntime: (runtime) => ({
785
+ ...runtime,
786
+ // The response only leaves the agent after the turn has been
787
+ // force stopped and finalized: teardown does not interrupt this fiber.
788
+ prompt: () =>
789
+ Deferred.succeed(dispatched, undefined).pipe(
790
+ Effect.andThen(Deferred.await(gate)),
791
+ Effect.andThen(
792
+ Effect.succeed({
793
+ stopReason: "cancelled" as const,
794
+ usage: { inputTokens: 60, outputTokens: 15, totalTokens: 75 },
795
+ }),
796
+ ),
797
+ ),
798
+ }),
799
+ }),
800
+ },
801
+ });
802
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
803
+ runtimeMode: "full-access",
804
+ interactionMode: "default",
805
+ cwd: process.cwd(),
806
+ });
807
+ const modelSelection = { instanceId, model: "default" } as const;
808
+ const runtime = yield* adapter.openSession({
809
+ threadId,
810
+ providerSessionId: ProviderSessionId.make("provider-session-acp-prompt-usage-late"),
811
+ modelSelection,
812
+ runtimePolicy,
813
+ });
814
+ const providerThread = yield* runtime.ensureThread({
815
+ threadId,
816
+ modelSelection,
817
+ runtimePolicy,
818
+ });
819
+ let stopCollector = false;
820
+ const events: Array<Record<string, unknown>> = [];
821
+ const usageRecorded = yield* Deferred.make<void>();
822
+ const collector = yield* Stream.runForEach(
823
+ runtime.events.pipe(Stream.takeUntil(() => stopCollector)),
824
+ (event) =>
825
+ Effect.suspend(() => {
826
+ const record = event as Record<string, unknown>;
827
+ events.push(record);
828
+ return record.type === "provider_turn.updated" &&
829
+ (record.providerTurn as Record<string, unknown>).turnTokenUsage !== undefined
830
+ ? Deferred.succeed(usageRecorded, undefined)
831
+ : Effect.void;
832
+ }),
833
+ ).pipe(Effect.forkScoped);
834
+ yield* runtime.startTurn(
835
+ makeTurnInput({
836
+ threadId,
837
+ providerThread,
838
+ instanceId,
839
+ runtimePolicy,
840
+ now: yield* DateTime.now,
841
+ messageText: "Say hi.",
842
+ }),
843
+ );
844
+ yield* Deferred.await(dispatched);
845
+ const providerTurnId = idAllocator.derive.providerTurn({
846
+ driver: ACP_TEST_DRIVER,
847
+ nativeTurnId: acpScopedNativeId(instanceId, "mock-session-1:turn:1"),
848
+ });
849
+ // Force stop finalizes the turn without waiting for the gated prompt response.
850
+ yield* runtime.interruptTurn({
851
+ providerThread,
852
+ providerTurnId,
853
+ requestRuntimeRestart: true,
854
+ });
855
+ yield* Deferred.await(usageRecorded);
856
+ const usageAt = () => {
857
+ const turns = events.filter(
858
+ (event) =>
859
+ event.type === "provider_turn.updated" &&
860
+ (event.providerTurn as Record<string, unknown>).turnTokenUsage !== undefined,
861
+ );
862
+ const last = turns[turns.length - 1] as
863
+ | { providerTurn: Record<string, unknown> }
864
+ | undefined;
865
+ return last?.providerTurn.turnTokenUsage as Record<string, unknown>;
866
+ };
867
+ assert.deepEqual(usageAt(), {
868
+ usageScope: "main_agent",
869
+ usageStatus: "unavailable",
870
+ hasSubagents: false,
871
+ });
872
+ // The response lands now; the finalized turn must not adopt its counters.
873
+ yield* Deferred.succeed(gate, undefined);
874
+ yield* Deferred.await(wireSettled);
875
+ assert.deepEqual(usageAt(), {
876
+ usageScope: "main_agent",
877
+ usageStatus: "unavailable",
878
+ hasSubagents: false,
879
+ });
880
+ stopCollector = true;
881
+ yield* Fiber.interrupt(collector);
882
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
883
+ );
884
+
885
+ it.live("passes per-turn usage samples through", () =>
886
+ Effect.gen(function* () {
887
+ const path = yield* Path.Path;
888
+ const instanceId = ProviderInstanceId.make("acp-test-per-turn-usage");
889
+ const threadId = ThreadId.make("thread-acp-per-turn-usage");
890
+ let promptOrdinal = 0;
891
+ // Fixture shaped after the live glm-acp-agent probe: three sequential
892
+ // prompts whose inputTokens grow by tens, not by a context per turn.
893
+ // GLM never sends cachedWriteTokens; those values are added here to
894
+ // exercise the clamp path.
895
+ const promptUsages = [
896
+ {
897
+ inputTokens: 2432,
898
+ outputTokens: 3,
899
+ totalTokens: 2435,
900
+ cachedReadTokens: 1024,
901
+ cachedWriteTokens: 64,
902
+ thoughtTokens: 2,
903
+ },
904
+ {
905
+ inputTokens: 2453,
906
+ outputTokens: 4,
907
+ totalTokens: 2457,
908
+ cachedReadTokens: 1045,
909
+ cachedWriteTokens: 85,
910
+ thoughtTokens: 3,
911
+ },
912
+ {
913
+ inputTokens: 2475,
914
+ outputTokens: 25,
915
+ totalTokens: 2500,
916
+ cachedReadTokens: 1067,
917
+ cachedWriteTokens: 107,
918
+ thoughtTokens: 20,
919
+ },
920
+ ];
921
+ const adapter = yield* makeAcpAdapterV2({
922
+ instanceId,
923
+ selfInvocation: yield* resolveSelfInvocation(),
924
+ flavor: {
925
+ driver: ACP_TEST_DRIVER,
926
+ capabilities: AcpProviderCapabilitiesV2,
927
+ reportsPerTurnPromptUsage: true,
928
+ makeRuntime: makeMockRuntime({
929
+ childProcessSpawner: yield* ChildProcessSpawner.ChildProcessSpawner,
930
+ mockAgentPath: yield* path.fromFileUrl(
931
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
932
+ ),
933
+ wrapRuntime: (runtime) => ({
934
+ ...runtime,
935
+ prompt: () => {
936
+ const usage = promptUsages[promptOrdinal++];
937
+ if (usage === undefined) return Effect.die("Unexpected prompt");
938
+ return Effect.succeed({ stopReason: "end_turn" as const, usage });
939
+ },
940
+ }),
941
+ }),
942
+ },
943
+ });
944
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
945
+ runtimeMode: "full-access",
946
+ interactionMode: "default",
947
+ cwd: process.cwd(),
948
+ });
949
+ const modelSelection = { instanceId, model: "default" } as const;
950
+ const runtime = yield* adapter.openSession({
951
+ threadId,
952
+ providerSessionId: ProviderSessionId.make("provider-session-acp-per-turn-usage"),
953
+ modelSelection,
954
+ runtimePolicy,
955
+ });
956
+ const providerThread = yield* runtime.ensureThread({
957
+ threadId,
958
+ modelSelection,
959
+ runtimePolicy,
960
+ });
961
+ const now = yield* DateTime.now;
962
+ for (const [index, sample] of promptUsages.entries()) {
963
+ yield* runtime.startTurn(
964
+ makeTurnInput({
965
+ threadId,
966
+ providerThread,
967
+ instanceId,
968
+ runtimePolicy,
969
+ now,
970
+ ordinal: index + 1,
971
+ }),
972
+ );
973
+ const events = Array.from(
974
+ yield* runtime.events.pipe(
975
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
976
+ Stream.runCollect,
977
+ ),
978
+ );
979
+ const completed = events.find(
980
+ (event) =>
981
+ event.type === "provider_turn.updated" && event.providerTurn.status === "completed",
982
+ );
983
+ // Per-turn: each response's own sample maps straight onto its turn.
984
+ assert.deepEqual(
985
+ completed?.type === "provider_turn.updated"
986
+ ? completed.providerTurn.turnTokenUsage
987
+ : null,
988
+ {
989
+ usageScope: "main_agent",
990
+ usageStatus: "complete",
991
+ hasSubagents: false,
992
+ inputTokens: sample.inputTokens,
993
+ outputTokens: sample.outputTokens,
994
+ cachedInputTokens: sample.cachedReadTokens,
995
+ cacheCreationTokens: sample.cachedWriteTokens,
996
+ reasoningTokens: sample.thoughtTokens,
997
+ },
998
+ );
999
+ }
1000
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
1001
+ );
1002
+
1003
+ it.live("clamps per-turn subsets that exceed their parent counters", () =>
1004
+ Effect.gen(function* () {
1005
+ const path = yield* Path.Path;
1006
+ const instanceId = ProviderInstanceId.make("acp-test-per-turn-clamp");
1007
+ const threadId = ThreadId.make("thread-acp-per-turn-clamp");
1008
+ const adapter = yield* makeAcpAdapterV2({
1009
+ instanceId,
1010
+ selfInvocation: yield* resolveSelfInvocation(),
1011
+ flavor: {
1012
+ driver: ACP_TEST_DRIVER,
1013
+ capabilities: AcpProviderCapabilitiesV2,
1014
+ reportsPerTurnPromptUsage: true,
1015
+ makeRuntime: makeMockRuntime({
1016
+ childProcessSpawner: yield* ChildProcessSpawner.ChildProcessSpawner,
1017
+ mockAgentPath: yield* path.fromFileUrl(
1018
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
1019
+ ),
1020
+ wrapRuntime: (runtime) => ({
1021
+ ...runtime,
1022
+ prompt: () =>
1023
+ Effect.succeed({
1024
+ stopReason: "end_turn" as const,
1025
+ usage: {
1026
+ inputTokens: 100,
1027
+ outputTokens: 10,
1028
+ totalTokens: 110,
1029
+ cachedReadTokens: 150,
1030
+ cachedWriteTokens: 120,
1031
+ thoughtTokens: 30,
1032
+ },
1033
+ }),
1034
+ }),
1035
+ }),
1036
+ },
1037
+ });
1038
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
1039
+ runtimeMode: "full-access",
1040
+ interactionMode: "default",
1041
+ cwd: process.cwd(),
1042
+ });
1043
+ const modelSelection = { instanceId, model: "default" } as const;
1044
+ const runtime = yield* adapter.openSession({
1045
+ threadId,
1046
+ providerSessionId: ProviderSessionId.make("provider-session-acp-per-turn-clamp"),
1047
+ modelSelection,
1048
+ runtimePolicy,
1049
+ });
1050
+ const providerThread = yield* runtime.ensureThread({
1051
+ threadId,
1052
+ modelSelection,
1053
+ runtimePolicy,
1054
+ });
1055
+ yield* runtime.startTurn(
1056
+ makeTurnInput({
1057
+ threadId,
1058
+ providerThread,
1059
+ instanceId,
1060
+ runtimePolicy,
1061
+ now: yield* DateTime.now,
1062
+ }),
1063
+ );
1064
+ const events = Array.from(
1065
+ yield* runtime.events.pipe(
1066
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
1067
+ Stream.runCollect,
1068
+ ),
1069
+ );
1070
+ const completed = events.find(
1071
+ (event) =>
1072
+ event.type === "provider_turn.updated" && event.providerTurn.status === "completed",
1073
+ );
1074
+ // TurnTokenUsage contract: input includes cache read + write and
1075
+ // reasoning is a subset of output. Reads clamp to input, writes clamp
1076
+ // to what reads leave of it (100 - 100 = 0 here).
1077
+ assert.deepEqual(
1078
+ completed?.type === "provider_turn.updated" ? completed.providerTurn.turnTokenUsage : null,
1079
+ {
1080
+ usageScope: "main_agent",
1081
+ usageStatus: "complete",
1082
+ hasSubagents: false,
1083
+ inputTokens: 100,
1084
+ outputTokens: 10,
1085
+ cachedInputTokens: 100,
1086
+ cacheCreationTokens: 0,
1087
+ reasoningTokens: 10,
1088
+ },
1089
+ );
1090
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
1091
+ );
1092
+
1093
+ it.live("reports per-turn usage unavailable when the agent omits usage", () =>
1094
+ Effect.gen(function* () {
1095
+ const path = yield* Path.Path;
1096
+ const instanceId = ProviderInstanceId.make("acp-test-per-turn-missing");
1097
+ const threadId = ThreadId.make("thread-acp-per-turn-missing");
1098
+ const adapter = yield* makeAcpAdapterV2({
1099
+ instanceId,
1100
+ selfInvocation: yield* resolveSelfInvocation(),
1101
+ flavor: {
1102
+ driver: ACP_TEST_DRIVER,
1103
+ capabilities: AcpProviderCapabilitiesV2,
1104
+ reportsPerTurnPromptUsage: true,
1105
+ makeRuntime: makeMockRuntime({
1106
+ childProcessSpawner: yield* ChildProcessSpawner.ChildProcessSpawner,
1107
+ mockAgentPath: yield* path.fromFileUrl(
1108
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
1109
+ ),
1110
+ wrapRuntime: (runtime) => ({
1111
+ ...runtime,
1112
+ prompt: () => Effect.succeed({ stopReason: "end_turn" as const }),
1113
+ }),
1114
+ }),
1115
+ },
1116
+ });
1117
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
1118
+ runtimeMode: "full-access",
1119
+ interactionMode: "default",
1120
+ cwd: process.cwd(),
1121
+ });
1122
+ const modelSelection = { instanceId, model: "default" } as const;
1123
+ const runtime = yield* adapter.openSession({
1124
+ threadId,
1125
+ providerSessionId: ProviderSessionId.make("provider-session-acp-per-turn-missing"),
1126
+ modelSelection,
1127
+ runtimePolicy,
1128
+ });
1129
+ const providerThread = yield* runtime.ensureThread({
1130
+ threadId,
1131
+ modelSelection,
1132
+ runtimePolicy,
1133
+ });
1134
+ yield* runtime.startTurn(
1135
+ makeTurnInput({
1136
+ threadId,
1137
+ providerThread,
1138
+ instanceId,
1139
+ runtimePolicy,
1140
+ now: yield* DateTime.now,
1141
+ }),
1142
+ );
1143
+ const events = Array.from(
1144
+ yield* runtime.events.pipe(
1145
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
1146
+ Stream.runCollect,
1147
+ ),
1148
+ );
1149
+ const completed = events.find(
1150
+ (event) =>
1151
+ event.type === "provider_turn.updated" && event.providerTurn.status === "completed",
1152
+ );
1153
+ assert.deepEqual(
1154
+ completed?.type === "provider_turn.updated" ? completed.providerTurn.turnTokenUsage : null,
1155
+ { usageScope: "main_agent", usageStatus: "unavailable", hasSubagents: false },
1156
+ );
1157
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
1158
+ );
1159
+
1160
+ it.live("keeps usage unavailable for undeclared agents even when they report usage", () =>
1161
+ Effect.gen(function* () {
1162
+ const path = yield* Path.Path;
1163
+ const instanceId = ProviderInstanceId.make("acp-test-usage-undeclared");
1164
+ const threadId = ThreadId.make("thread-acp-usage-undeclared");
1165
+ const adapter = yield* makeAcpAdapterV2({
1166
+ instanceId,
1167
+ selfInvocation: yield* resolveSelfInvocation(),
1168
+ flavor: {
1169
+ driver: ACP_TEST_DRIVER,
1170
+ capabilities: AcpProviderCapabilitiesV2,
1171
+ makeRuntime: makeMockRuntime({
1172
+ childProcessSpawner: yield* ChildProcessSpawner.ChildProcessSpawner,
1173
+ mockAgentPath: yield* path.fromFileUrl(
1174
+ new URL("../../../scripts/acp-mock-agent.ts", import.meta.url),
1175
+ ),
1176
+ wrapRuntime: (runtime) => ({
1177
+ ...runtime,
1178
+ prompt: () =>
1179
+ Effect.succeed({
1180
+ stopReason: "end_turn" as const,
1181
+ usage: { inputTokens: 60, outputTokens: 15, totalTokens: 75 },
1182
+ }),
1183
+ }),
1184
+ }),
1185
+ },
1186
+ });
1187
+ const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({
1188
+ runtimeMode: "full-access",
1189
+ interactionMode: "default",
1190
+ cwd: process.cwd(),
1191
+ });
1192
+ const modelSelection = { instanceId, model: "default" } as const;
1193
+ const runtime = yield* adapter.openSession({
1194
+ threadId,
1195
+ providerSessionId: ProviderSessionId.make("provider-session-acp-usage-undeclared"),
1196
+ modelSelection,
1197
+ runtimePolicy,
1198
+ });
1199
+ const providerThread = yield* runtime.ensureThread({
1200
+ threadId,
1201
+ modelSelection,
1202
+ runtimePolicy,
1203
+ });
1204
+ const now = yield* DateTime.now;
1205
+ for (const ordinal of [1, 2]) {
1206
+ yield* runtime.startTurn(
1207
+ makeTurnInput({ threadId, providerThread, instanceId, runtimePolicy, now, ordinal }),
1208
+ );
1209
+ const events = Array.from(
1210
+ yield* runtime.events.pipe(
1211
+ Stream.takeUntil((event) => event.type === "turn.terminal"),
1212
+ Stream.runCollect,
1213
+ ),
1214
+ );
1215
+ const completed = events.find(
1216
+ (event) =>
1217
+ event.type === "provider_turn.updated" && event.providerTurn.status === "completed",
1218
+ );
1219
+ // Usage semantics are unverified for an undeclared agent, so its
1220
+ // counters are never trusted, on any turn.
1221
+ assert.deepEqual(
1222
+ completed?.type === "provider_turn.updated"
1223
+ ? completed.providerTurn.turnTokenUsage
1224
+ : null,
1225
+ { usageScope: "main_agent", usageStatus: "unavailable", hasSubagents: false },
1226
+ );
1227
+ }
1228
+ }).pipe(Effect.provide(layerTest), Effect.scoped),
1229
+ );
1230
+
1231
it.live.each(["details", "none"] as const)(
1232
"fails the turn on an ACP v2 idle error with %s, settles its open tool, and accepts the next prompt",
1233
(details) =>
packages/provider-acp-registry/src/server/adapter.ts
+2
@@ -222,6 +222,8 @@ export const makeAcpRegistryAdapterV2 = Effect.fn("makeAcpRegistryAdapterV2")(fu
222
...(registryAgentId === "factory-droid"
223
? { extractElicitationForm: extractDroidElicitationForm }
224
: {}),
225
+ // glm-acp-agent is the one agent whose per-turn usage a live probe has verified.
226
+ ...(registryAgentId === "glm-acp-agent" ? { reportsPerTurnPromptUsage: true } : {}),
227
...(registryAgentId === "mistral-vibe"
228
? { registerExtensions: registerMistralVibeAcpExtensions }
229
: {}),
packages/provider-acp/src/server/adapter.ts
+71
-5
@@ -30,6 +30,7 @@ import {
30
type RuntimeRequestId,
31
type ThreadTokenUsageSnapshot,
32
type ThreadId,
33
+ type TurnTokenUsage,
34
} from "@t3tools/contracts";
35
import { AgentScope, AgentScopeThreadId } from "@t3tools/shared/AgentScope";
36
import { HTML_RENDER_TOOL_NAME } from "@t3tools/shared/htmlRender";
@@ -217,6 +218,43 @@ class AcpModelSelectionError extends Schema.TaggedError<AcpModelSelectionError>(
218
}
219
}
220
221
+/**
222
+ * Maps one per-turn usage sample (flavors with reportsPerTurnPromptUsage)
223
+ * directly onto TurnTokenUsage: the response's counters already cover exactly
224
+ * this prompt.
225
+ */
226
+export function acpPerTurnPromptUsage(
227
+ usage: EffectAcpSchema.Usage | null | undefined,
228
+ hasSubagents: boolean,
229
+ terminalStatus: OrchestrationV2ProviderTurn["status"],
230
+): TurnTokenUsage {
231
+ if (usage == null) {
232
+ return { usageScope: "main_agent", usageStatus: "unavailable", hasSubagents };
233
+ }
234
+ // TurnTokenUsage contract: input includes cache read + write and reasoning
235
+ // is a subset of output, so clamp counters that exceed their parent and
236
+ // drop the ones the agent left unset. Cache writes are capped at whatever
237
+ // cache reads leave of input, so the pair cannot exceed it.
238
+ const clampSubset = (value: number | null | undefined, parent: number) =>
239
+ value == null ? undefined : Math.min(value, parent);
240
+ const cachedInputTokens = clampSubset(usage.cachedReadTokens, usage.inputTokens);
241
+ const cacheCreationTokens = clampSubset(
242
+ usage.cachedWriteTokens,
243
+ usage.inputTokens - (cachedInputTokens ?? 0),
244
+ );
245
+ const reasoningTokens = clampSubset(usage.thoughtTokens, usage.outputTokens);
246
+ return {
247
+ usageScope: "main_agent",
248
+ usageStatus: terminalStatus === "completed" ? "complete" : "partial",
249
+ hasSubagents,
250
+ inputTokens: usage.inputTokens,
251
+ outputTokens: usage.outputTokens,
252
+ ...(cachedInputTokens === undefined ? {} : { cachedInputTokens }),
253
+ ...(cacheCreationTokens === undefined ? {} : { cacheCreationTokens }),
254
+ ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
255
+ };
256
+}
257
+
258
export interface AcpAdapterV2Flavor {
259
readonly buildPrompt?: (input: {
260
readonly text: string;
@@ -355,6 +393,11 @@ export interface AcpAdapterV2Flavor {
393
readonly assertComplete?: Effect.Effect<void, EffectAcpErrors.AcpError>;
394
/** Interrupt the local prompt fiber before `session/cancel` (Grok wedged prompts). */
395
readonly interruptPromptOnCancel?: boolean;
396
+ /**
397
+ * The agent's PromptResponse.usage counters read per-turn. The ACP spec
398
+ * leaves usage semantics open, so this stays unset until proven live.
399
+ */
400
+ readonly reportsPerTurnPromptUsage?: boolean;
401
/** Grok can retain task_already_running until process exit. */
402
readonly restartRuntimeAfterInterrupt?: boolean;
403
readonly restartRuntimeOnEveryInterrupt?: boolean;
@@ -442,6 +485,7 @@ export interface AcpAdapterV2Options {
485
};
486
readonly testHooks?: {
487
readonly onDeferredFinalizeScheduled?: (debounce: Duration.Input) => Effect.Effect<void>;
488
+ readonly afterPromptWireSettled?: () => Effect.Effect<void>;
489
readonly afterPromptSettledWithBackgroundWork?: () => Effect.Effect<void>;
490
readonly onNativeResponseLifecycle?: (event: {
491
readonly generation?: number;
@@ -1091,6 +1135,7 @@ interface ActiveAcpTurn {
1135
promptSettledStatus: "completed" | "interrupted" | "failed" | "cancelled" | null;
1136
workAccepted: boolean;
1137
readonly promptWireSettled: Deferred.Deferred<void, never>;
1138
+ promptUsage: EffectAcpSchema.Usage | undefined;
1139
backgroundFinalizeGeneration: number;
1140
}
1141
@@ -6918,6 +6963,17 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
6963
status,
6964
startedAt: context.startedAt,
6965
completedAt,
6966
+ ...(status === "running" || status === "pending"
6967
+ ? {}
6968
+ : {
6969
+ // The prompt tap only captures usage for flavors that declared
6970
+ // per-turn counters, so undeclared agents stay unavailable here.
6971
+ turnTokenUsage: acpPerTurnPromptUsage(
6972
+ context.promptUsage,
6973
+ context.subagents.size > 0,
6974
+ status,
6975
+ ),
6976
+ }),
6977
});
6978
6979
const terminalizeOpenRunOwnedItems = Effect.fnUntraced(function* (
@@ -7461,6 +7517,7 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
7517
promptSettledStatus: null,
7518
workAccepted: false,
7519
promptWireSettled,
7520
+ promptUsage: undefined,
7521
backgroundFinalizeGeneration: 0,
7522
};
7523
const carryover = yield* Ref.getAndSet(carryoverSubagents, null);
@@ -7620,12 +7677,21 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
7677
return updated;
7678
}),
7679
),
7623
- // Wire settlement precedes the completion callback's permit request so
7624
- // settled-soft classification can observe the native return even when
7625
- // the completion fiber has not yet set promptSettled under the permit.
7626
- Effect.tap(() =>
7627
- Deferred.succeed(context.promptWireSettled, undefined).pipe(Effect.asVoid),
7680
+ // Settle the wire before the completion callback's permit so a settled-soft
7681
+ // Stop sees the native return. Capture usage only before finalize: a late
7682
+ // response must not flip a settled turn.
7683
+ Effect.tap((result) =>
7684
+ Effect.sync(() => {
7685
+ if (flavor.reportsPerTurnPromptUsage === true && !context.finalized) {
7686
+ context.promptUsage = result.usage ?? undefined;
7687
+ }
7688
+ }).pipe(
7689
+ Effect.andThen(
7690
+ Deferred.succeed(context.promptWireSettled, undefined).pipe(Effect.asVoid),
7691
+ ),
7692
+ ),
7693
),
7694
+ Effect.tap(() => options.testHooks?.afterPromptWireSettled?.() ?? Effect.void),
7695
Effect.flatMap((result) =>
7696
runRuntimeCallbackAtGeneration(
7697
promptGeneration,