@@ -13,14 +13,28 @@ import * as Stream from "effect/Stream";
1313import type * as Types from "effect/Types" ;
1414import { AiError , McpProtocol , McpSchema , McpServer , Tool , Toolkit } from "effect/ai" ;
1515import { HttpRouter , HttpServerRequest , HttpServerResponse } from "effect/http" ;
16- import { OrchestratorMcpFailure , PreviewAutomationError } from "@t3tools/contracts" ;
16+ import {
17+ OrchestratorMcpFailure ,
18+ PreviewAutomationError ,
19+ type RunId ,
20+ ThreadId ,
21+ } from "@t3tools/contracts" ;
1722
1823import packageJson from "../../package.json" with { type : "json" } ;
1924import * as ServerConfig from "../config.ts" ;
2025import * as DeviceService from "../device/DeviceService.ts" ;
2126import * as HtmlRender from "../htmlRender/HtmlRender.ts" ;
2227import * as ThreadCommandExecutor from "../orchestration-v2/ThreadCommandExecutor.ts" ;
2328import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts" ;
29+ import * as ProviderRegistry from "../provider/ProviderRegistry.ts" ;
30+ import * as AnalyticsService from "../telemetry/AnalyticsService.ts" ;
31+ import {
32+ type AgentThread ,
33+ agentToolProperties ,
34+ handoffSettings ,
35+ MAX_REPORTED_DEPTH ,
36+ toolOutcome ,
37+ } from "../telemetry/ProviderDimensions.ts" ;
2438import * as McpInvocationContext from "./McpInvocationContext.ts" ;
2539import * as McpToolAccess from "./McpToolAccess.ts" ;
2640import * as OrchestratorMcpService from "./OrchestratorMcpService.ts" ;
@@ -746,6 +760,186 @@ const registerHtmlPreview = Effect.fn("McpHttpServer.registerHtmlPreview")(funct
746760 ) ;
747761} ) ;
748762
763+ /**
764+ * Tools that hand work to another thread's agent: they create it, message it,
765+ * steer it, or move context into it. Their events name the receiving agent too.
766+ */
767+ const HANDOFF_TOOLS : ReadonlySet < string > = new Set ( [
768+ "delegate_task" ,
769+ "create_threads" ,
770+ "t3_thread_launch" ,
771+ "t3_thread_send" ,
772+ "t3_thread_send_attachments" ,
773+ "t3_thread_fork" ,
774+ "t3_thread_merge_back" ,
775+ "t3_queue_edit" ,
776+ "t3_queue_promote_to_steer" ,
777+ "t3_pending_request_respond" ,
778+ "schedule_task" ,
779+ "run_scheduled_task_now" ,
780+ ] ) ;
781+
782+ /** Handoff tools whose result is only `{ sequence }`; their input names the receiving thread. */
783+ const INPUT_TARGET_TOOLS : ReadonlySet < string > = new Set ( [
784+ "t3_queue_edit" ,
785+ "t3_queue_promote_to_steer" ,
786+ "t3_pending_request_respond" ,
787+ ] ) ;
788+
789+ const resultThreadKeys = [ "childThreadId" , "targetThreadId" , "boundThreadId" , "threadId" ] as const ;
790+
791+ /** Thread ids a handoff tool result names: the thread that received the work. */
792+ const resultThreadIds = ( content : unknown ) : ReadonlyArray < string > => {
793+ if ( typeof content !== "object" || content === null ) return [ ] ;
794+ const record = content as Readonly < Record < string , unknown > > ;
795+ if ( Array . isArray ( record . threads ) ) return record . threads . flatMap ( resultThreadIds ) ;
796+ const key = resultThreadKeys . find ( ( candidate ) => typeof record [ candidate ] === "string" ) ;
797+ return key === undefined ? [ ] : [ record [ key ] as string ] ;
798+ } ;
799+
800+ /**
801+ * Thread ids that received a handoff. The input's `threadId` is used only after
802+ * the call succeeded, so it is one the handler already resolved and authorized.
803+ */
804+ const handoffTargetIds = (
805+ tool : string ,
806+ args : unknown ,
807+ result : McpSchema . CallToolResult | undefined ,
808+ ) : ReadonlyArray < string > => {
809+ if ( ! INPUT_TARGET_TOOLS . has ( tool ) ) return resultThreadIds ( result ?. structuredContent ) ;
810+ if ( result === undefined || toolOutcome ( result ) . outcome !== "ok" ) return [ ] ;
811+ const threadId = ( args as { readonly threadId ?: unknown } | null | undefined ) ?. threadId ;
812+ return typeof threadId === "string" ? [ threadId ] : [ ] ;
813+ } ;
814+
815+ /**
816+ * Runs a tool registration against a server that records one anonymous
817+ * `mcp.tool.invoked` event per call: the tool, the calling agent's provider,
818+ * the outcome with its failure code, and the duration. A handoff tool also
819+ * reports the caller's model, origin, and delegation depth, the settings the
820+ * agent chose, and the provider, model, and modes of each thread that received
821+ * the work. Ids, prompts, and free text are never recorded.
822+ */
823+ const withToolAnalytics = < A , E , R > ( registration : Effect . Effect < A , E , R > ) =>
824+ Effect . gen ( function * ( ) {
825+ const server = yield * McpServer . McpServer ;
826+ const analytics = yield * Effect . serviceOption ( AnalyticsService . AnalyticsService ) ;
827+ if ( Option . isNone ( analytics ) ) return yield * registration ;
828+ const registry = yield * Effect . serviceOption ( ProviderRegistry . ProviderRegistry ) ;
829+ const threads = yield * Effect . serviceOption ( ThreadManagementService . ThreadManagementService ) ;
830+ const shellOf = ( threadId : string ) =>
831+ Option . isNone ( threads )
832+ ? Effect . succeed ( null )
833+ : threads . value
834+ . getThreadShell ( ThreadId . make ( threadId ) )
835+ . pipe ( Effect . orElseSucceed ( ( ) => null ) ) ;
836+ // Delegation depth: parents walked from the caller, capped.
837+ const depthOf = ( thread : AgentThread ) =>
838+ Effect . gen ( function * ( ) {
839+ let depth = 0 ;
840+ let parentId =
841+ thread . lineage . relationshipToParent === "subagent" ? thread . lineage . parentThreadId : null ;
842+ while ( parentId !== null && depth < MAX_REPORTED_DEPTH ) {
843+ depth += 1 ;
844+ const parent = yield * shellOf ( parentId ) ;
845+ parentId =
846+ parent ?. lineage . relationshipToParent === "subagent"
847+ ? parent . lineage . parentThreadId
848+ : null ;
849+ }
850+ return depth ;
851+ } ) ;
852+ // Whether the caller's active run was started by a scheduled task.
853+ const scheduledRunOf = ( threadId : string , runId : RunId | null ) =>
854+ Option . isNone ( threads ) || runId === null
855+ ? Effect . succeed ( false )
856+ : threads . value
857+ . getThreadRecords ( ThreadId . make ( threadId ) , [ "runs" , "messages" ] , {
858+ runIds : [ runId ] ,
859+ messageRoles : [ "user" ] ,
860+ } )
861+ . pipe (
862+ Effect . map ( ( records ) => {
863+ const run = records . runs . find ( ( candidate ) => candidate . id === runId ) ;
864+ return records . messages . some (
865+ ( message ) =>
866+ message . id === run ?. userMessageId && message . scheduledTaskId !== undefined ,
867+ ) ;
868+ } ) ,
869+ Effect . orElseSucceed ( ( ) => false ) ,
870+ ) ;
871+ const record = (
872+ tool : string ,
873+ args : unknown ,
874+ result : McpSchema . CallToolResult | undefined ,
875+ durationMs : number ,
876+ ) =>
877+ Effect . gen ( function * ( ) {
878+ // Client credentials (no calling thread) report an unknown caller.
879+ const invocation = Option . getOrUndefined (
880+ yield * Effect . serviceOption ( McpInvocationContext . McpInvocationContext ) ,
881+ ) ?. thread ;
882+ const providers = Option . isSome ( registry ) ? yield * registry . value . getProviders : [ ] ;
883+ // Only handoff tools pay for thread lookups; the rest report the
884+ // caller's provider from the credential.
885+ const handoff = HANDOFF_TOOLS . has ( tool ) ;
886+ const caller =
887+ handoff && invocation !== undefined
888+ ? ( ( yield * shellOf ( invocation . threadId ) ) ?? undefined )
889+ : undefined ;
890+ const targetIds = handoff
891+ ? [ ...new Set ( handoffTargetIds ( tool , args , result ) ) ] . filter (
892+ ( threadId ) => threadId !== invocation ?. threadId ,
893+ )
894+ : [ ] ;
895+ const targets = yield * Effect . forEach ( targetIds , shellOf ) ;
896+ for ( const properties of agentToolProperties ( {
897+ tool,
898+ providers,
899+ caller,
900+ ...( invocation === undefined
901+ ? { }
902+ : { callerProviderInstanceId : invocation . providerInstanceId } ) ,
903+ ...( caller === undefined || invocation === undefined
904+ ? { }
905+ : {
906+ callerDepth : yield * depthOf ( caller ) ,
907+ callerScheduledRun : yield * scheduledRunOf ( invocation . threadId , caller . activeRunId ) ,
908+ } ) ,
909+ targets : targets . filter ( ( thread ) => thread !== null ) ,
910+ outcome : toolOutcome ( result ) ,
911+ ...( handoff ? { settings : handoffSettings ( tool , args , result ?. structuredContent ) } : { } ) ,
912+ durationMs,
913+ } ) ) {
914+ yield * analytics . value . record ( "mcp.tool.invoked" , properties ) ;
915+ }
916+ } ) . pipe ( Effect . ignoreCause ) ;
917+ const recordingServer = McpServer . McpServer . of ( {
918+ ...server ,
919+ addTool : ( options ) =>
920+ server . addTool ( {
921+ ...options ,
922+ handle : ( payload ) =>
923+ Effect . gen ( function * ( ) {
924+ const startedAt = yield * Clock . currentTimeMillis ;
925+ return yield * options . handle ( payload ) . pipe (
926+ Effect . onExit ( ( exit ) => {
927+ const result = exit . _tag === "Success" ? exit . value : undefined ;
928+ // A call that asks for input is retried with it, and that call is the one counted.
929+ if ( result instanceof McpSchema . InputRequired ) return Effect . void ;
930+ return Clock . currentTimeMillis . pipe (
931+ Effect . flatMap ( ( endedAt ) =>
932+ record ( options . tool . name , payload , result , endedAt - startedAt ) ,
933+ ) ,
934+ ) ;
935+ } ) ,
936+ ) ;
937+ } ) ,
938+ } ) ,
939+ } ) ;
940+ return yield * registration . pipe ( Effect . provideService ( McpServer . McpServer , recordingServer ) ) ;
941+ } ) ;
942+
749943/**
750944 * `McpServer.toolkit` asks for every service its tools declare when it
751945 * registers them, but the auth middleware provides `McpInvocationContext` to
@@ -756,7 +950,9 @@ export const toolkitRegistration = <Tools extends Record<string, Tool.Any>, EX,
756950 toolkit : Toolkit . Toolkit < Tools > ,
757951 handlers : McpToolAccess . HandlersLayer < Tools , EX , RX > ,
758952) => {
759- const registration = McpServer . toolkit ( decodeAsAdvertised ( toolkit ) ) ;
953+ const registration = Layer . effectDiscard (
954+ withToolAnalytics ( McpServer . registerToolkit ( decodeAsAdvertised ( toolkit ) ) ) ,
955+ ) . pipe ( Layer . provide ( McpServer . McpServer . layer ) ) ;
760956 // @effect -diagnostics-next-line unsafeEffectTypeAssertion:off - the auth middleware provides it per request.
761957 const registered = registration as Layer . Layer <
762958 never ,
@@ -769,7 +965,10 @@ export const toolkitRegistration = <Tools extends Record<string, Tool.Any>, EX,
769965const imageToolRegistration = < Tools extends Record < string , Tool . Any > , A , E , R , EX , RX > (
770966 register : Effect . Effect < A , E , R > ,
771967 handlers : McpToolAccess . HandlersLayer < Tools , EX , RX > ,
772- ) => Layer . effectDiscard ( register ) . pipe ( Layer . provide ( McpToolAccess . HandlersLayer . layer ( handlers ) ) ) ;
968+ ) =>
969+ Layer . effectDiscard ( withToolAnalytics ( register ) ) . pipe (
970+ Layer . provide ( McpToolAccess . HandlersLayer . layer ( handlers ) ) ,
971+ ) ;
773972
774973export const layerHtmlToolkit = Layer . mergeAll (
775974 toolkitRegistration ( HtmlRenderToolkit , HtmlHandlers . layerRender ) ,
0 commit comments