Function dispatchCallTool

server/src/training-agent/task-handlers.ts:3587–3893

(
    request: { params: { name: string; arguments?: unknown; task?: { ttl?: number } } },
    _extra: unknown,
  )

  });

  async function dispatchCallTool(
    request: { params: { name: string; arguments?: unknown; task?: { ttl?: number } } },
    _extra: unknown,
  ): Promise<{ result: object; flushable: boolean }> {
    const { name, arguments: args } = request.params;

    // Extract and strip context before passing args to handlers (AdCP requirement:
    // echo caller's context object back unchanged in every response).
    const rawArgs = (args as Record<string, unknown> | undefined) ?? {};
    const { context: callerContext, ...handlerArgs } = rawArgs;

    const handler = HANDLER_MAP[name];

    if (!handler) {
      // Pre-handler validation failures don't touch session state, so flushing
      // is a no-op; leaving flushable=true keeps behaviour consistent for
      // requests whose handlers DO legitimately mutate before failing.
      return { result: adcpError('INVALID_REQUEST', { message: `Unknown tool: ${name}` }, callerContext), flushable: true };
    }

    const requestedVersion = (handlerArgs as { adcp_major_version?: unknown }).adcp_major_version;
    if (
      requestedVersion !== undefined
      && !(SUPPORTED_MAJOR_VERSIONS as readonly number[]).includes(requestedVersion as number)
    ) {
      return {
        result: adcpError('VERSION_UNSUPPORTED', {
          message: `AdCP major version ${String(requestedVersion)} is not supported`,
          details: { supported_major_versions: SUPPORTED_MAJOR_VERSIONS },
          field: 'adcp_major_version',
        }, callerContext),
        flushable: true,
      };
    }

    // Check for task-augmented request (explicit `task` field in params).
    // Dry-run requests always return synchronously — there's no reason to
    // async a dry-run operation, and clients expect immediate results.
    const taskField = (request.params as { task?: { ttl?: number } }).task;
    const isDryRun = rawArgs.dry_run === true;
    const isTaskRequest = taskField !== undefined && !isDryRun;
    if (isTaskRequest && !toolSupportsTask(name)) {
      throw new Error(`Tool "${name}" does not support task augmentation`);
    }

    // Idempotency enforcement for mutating tools (#2315, #2346).
    // Key presence + format are schema-level requirements; we check them
    // before the handler so a malformed key never touches the cache
    // (prevents key-format-accepting cache misses from leaking timing).
    const authPrincipal = ctx.principal ?? 'anonymous';
    // Partition the idempotency cache by caller-stated account scope so the
    // shared public sandbox token doesn't pool every buyer into one oracle
    // (security.mdx §"three-state response"). An attacker on the same auth
    // principal using a different account ref can still cross-probe, but
    // callers can already enumerate their own account's keys — so the
    // scoping adds no useful probing surface while closing the cross-caller
    // leak.
    const accountScope = deriveAccountScope(handlerArgs);