@devries-cameron20 / t3code Mirror · read-only / commits / 68be2f7b32
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 12:00 UTC

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,