@evalops/maestro 0.10.17 → 0.10.20

package/dist/platform/a2a-client.js

@@ -0,0 +1,589 @@
+import { EVALOPS_ORGANIZATION_ID_ENV_VARS, EVALOPS_WORKSPACE_ID_ENV_VARS, } from "../evalops/env-aliases.js";
+import { fetchDownstream } from "../utils/downstream-http.js";
+import { buildPlatformJsonHeaders, getEnvValue, resolvePlatformServiceConfig, trimString, } from "./client.js";
+const DEFAULT_TIMEOUT_MS = 2_500;
+const DEFAULT_MAX_ATTEMPTS = 2;
+const A2A_BASE_URL_ENV_VARS = [
+    "MAESTRO_PLATFORM_A2A_URL",
+    "MAESTRO_A2A_URL",
+    "MAESTRO_AGENT_RUNTIME_SERVICE_URL",
+    "PLATFORM_AGENT_RUNTIME_URL",
+    "AGENT_RUNTIME_SERVICE_URL",
+    "MAESTRO_PLATFORM_BASE_URL",
+    "MAESTRO_EVALOPS_BASE_URL",
+    "EVALOPS_BASE_URL",
+];
+const A2A_TOKEN_ENV_VARS = [
+    "MAESTRO_PLATFORM_A2A_TOKEN",
+    "MAESTRO_A2A_TOKEN",
+    "MAESTRO_AGENT_RUNTIME_SERVICE_TOKEN",
+    "AGENT_RUNTIME_SERVICE_TOKEN",
+];
+const A2A_ORGANIZATION_ENV_VARS = [
+    "MAESTRO_PLATFORM_A2A_ORG_ID",
+    "MAESTRO_A2A_ORG_ID",
+    "MAESTRO_AGENT_RUNTIME_ORG_ID",
+    "AGENT_RUNTIME_ORGANIZATION_ID",
+    ...EVALOPS_ORGANIZATION_ID_ENV_VARS,
+];
+const A2A_WORKSPACE_ENV_VARS = [
+    "MAESTRO_PLATFORM_A2A_WORKSPACE_ID",
+    "MAESTRO_A2A_WORKSPACE_ID",
+    "MAESTRO_AGENT_RUNTIME_WORKSPACE_ID",
+    "AGENT_RUNTIME_WORKSPACE_ID",
+    ...EVALOPS_WORKSPACE_ID_ENV_VARS,
+];
+const A2A_TIMEOUT_ENV_VARS = [
+    "MAESTRO_PLATFORM_A2A_TIMEOUT_MS",
+    "MAESTRO_A2A_TIMEOUT_MS",
+    "MAESTRO_AGENT_RUNTIME_TIMEOUT_MS",
+    "AGENT_RUNTIME_SERVICE_TIMEOUT_MS",
+];
+const A2A_MAX_ATTEMPTS_ENV_VARS = [
+    "MAESTRO_PLATFORM_A2A_MAX_ATTEMPTS",
+    "MAESTRO_A2A_MAX_ATTEMPTS",
+    "MAESTRO_AGENT_RUNTIME_MAX_ATTEMPTS",
+    "AGENT_RUNTIME_SERVICE_MAX_ATTEMPTS",
+];
+const A2A_EXTENSIONS_ENV_VARS = [
+    "MAESTRO_PLATFORM_A2A_EXTENSIONS",
+    "MAESTRO_A2A_EXTENSIONS",
+];
+const A2A_BASE_URL_SUFFIXES = [
+    "/.well-known/agent-card.json",
+    "/message:send",
+    "/message:stream",
+    "/agentruntime.v1.AgentRuntimeService/HandleTrigger",
+    "/agentruntime.v1.AgentRuntimeService",
+];
+export function normalizeA2ABaseUrl(baseUrl) {
+    let normalized = baseUrl.trim().replace(/\/+$/u, "");
+    for (const suffix of A2A_BASE_URL_SUFFIXES) {
+        if (normalized.endsWith(suffix)) {
+            normalized = normalized.slice(0, -suffix.length).replace(/\/+$/u, "");
+        }
+    }
+    return normalized;
+}
+export async function resolveA2AServiceConfig(overrides = {}) {
+    const config = await resolvePlatformServiceConfig({
+        baseUrlEnvVars: A2A_BASE_URL_ENV_VARS,
+        tokenEnvVars: A2A_TOKEN_ENV_VARS,
+        organizationEnvVars: A2A_ORGANIZATION_ENV_VARS,
+        workspaceEnvVars: A2A_WORKSPACE_ENV_VARS,
+        timeoutEnvVars: A2A_TIMEOUT_ENV_VARS,
+        maxAttemptsEnvVars: A2A_MAX_ATTEMPTS_ENV_VARS,
+        baseUrlSuffixes: A2A_BASE_URL_SUFFIXES,
+        defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+        defaultMaxAttempts: DEFAULT_MAX_ATTEMPTS,
+        requireBaseUrl: false,
+        requireOrganizationId: false,
+        requireToken: false,
+        allowOAuthTokenFallback: false,
+    });
+    const baseUrl = trimString(overrides.baseUrl ?? config?.baseUrl);
+    const workspaceId = trimString(overrides.workspaceId ?? config?.workspaceId);
+    if (!baseUrl || !workspaceId) {
+        return null;
+    }
+    return {
+        ...(config ?? {
+            baseUrl,
+            timeoutMs: DEFAULT_TIMEOUT_MS,
+            maxAttempts: DEFAULT_MAX_ATTEMPTS,
+        }),
+        baseUrl: normalizeA2ABaseUrl(baseUrl),
+        organizationId: trimString(overrides.organizationId ?? config?.organizationId) ??
+            config?.organizationId,
+        workspaceId,
+        token: trimString(overrides.token ?? config?.token) ?? config?.token,
+        timeoutMs: overrides.timeoutMs ?? config?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxAttempts: overrides.maxAttempts ?? config?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+        agentId: trimString(overrides.agentId) ??
+            getEnvValue(["MAESTRO_AGENT_ID", "MAESTRO_EVALOPS_AGENT_ID"]) ??
+            "maestro",
+        sessionId: trimString(overrides.sessionId) ?? getEnvValue(["MAESTRO_SESSION_ID"]),
+        actorId: trimString(overrides.actorId) ??
+            getEnvValue(["MAESTRO_USER_ID", "MAESTRO_ACTOR_ID"]),
+        extensions: resolveConfiguredA2AExtensions(overrides.extensions),
+    };
+}
+export function buildA2AUserMessage(input) {
+    return {
+        messageId: input.messageId,
+        contextId: input.contextId,
+        taskId: input.taskId,
+        role: "ROLE_USER",
+        parts: [{ text: input.text, mediaType: "text/plain" }],
+        metadata: input.metadata,
+        extensions: input.extensions,
+    };
+}
+export async function discoverA2AAgentCard(config, options = {}) {
+    const response = await fetchDownstream(`${config.baseUrl}/.well-known/agent-card.json`, {
+        method: "GET",
+        headers: buildA2AHeaders(config),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "discover agent card");
+    return (await response.json());
+}
+export async function sendA2AMessage(config, input, options = {}) {
+    const { body, traceContext } = buildA2AMessageRequestBody(config, input);
+    const extensions = resolveA2AExtensions(config, input.message.extensions);
+    const response = await fetchDownstream(`${config.baseUrl}/message:send`, {
+        method: "POST",
+        headers: buildA2AHeaders(config, traceContext, extensions),
+        body: JSON.stringify(body),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "send message");
+    return (await response.json());
+}
+export async function* streamA2AMessage(config, input, options = {}) {
+    const { body, traceContext } = buildA2AMessageRequestBody(config, input);
+    const extensions = resolveA2AExtensions(config, input.message.extensions);
+    const response = await fetchDownstream(`${config.baseUrl}/message:stream`, {
+        method: "POST",
+        headers: {
+            ...buildA2AHeaders(config, traceContext, extensions),
+            Accept: "text/event-stream",
+        },
+        body: JSON.stringify(body),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "stream message");
+    yield* parseA2AStreamEvents(response);
+}
+export async function* subscribeA2ATask(config, taskId, options = {}) {
+    const trimmedTaskId = trimString(taskId);
+    if (!trimmedTaskId) {
+        throw new Error("A2A task id is required");
+    }
+    const response = await fetchDownstream(`${config.baseUrl}/tasks/${encodeURIComponent(trimmedTaskId)}:subscribe`, {
+        method: "POST",
+        headers: {
+            ...buildA2AHeaders(config, options.traceContext, resolveA2AExtensions(config, options.extensions)),
+            Accept: "text/event-stream",
+        },
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "subscribe task");
+    yield* parseA2AStreamEvents(response);
+}
+export async function createA2ATaskPushNotificationConfig(config, taskId, pushConfig, options = {}) {
+    const trimmedTaskId = requireA2ATaskId(taskId);
+    const response = await fetchDownstream(`${config.baseUrl}/tasks/${encodeURIComponent(trimmedTaskId)}/pushNotificationConfigs`, {
+        method: "POST",
+        headers: buildA2AHeaders(config, options.traceContext),
+        body: JSON.stringify(pushConfig),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "create task push notification config");
+    return (await response.json());
+}
+export async function listA2ATaskPushNotificationConfigs(config, taskId, options = {}) {
+    const trimmedTaskId = requireA2ATaskId(taskId);
+    const response = await fetchDownstream(`${config.baseUrl}/tasks/${encodeURIComponent(trimmedTaskId)}/pushNotificationConfigs`, {
+        method: "GET",
+        headers: buildA2AHeaders(config, options.traceContext),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "list task push notification configs");
+    return (await response.json());
+}
+export async function getA2ATaskPushNotificationConfig(config, taskId, configId, options = {}) {
+    const trimmedTaskId = requireA2ATaskId(taskId);
+    const trimmedConfigId = requireA2APushConfigId(configId);
+    const response = await fetchDownstream(`${config.baseUrl}/tasks/${encodeURIComponent(trimmedTaskId)}/pushNotificationConfigs/${encodeURIComponent(trimmedConfigId)}`, {
+        method: "GET",
+        headers: buildA2AHeaders(config, options.traceContext),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "get task push notification config");
+    return (await response.json());
+}
+export async function deleteA2ATaskPushNotificationConfig(config, taskId, configId, options = {}) {
+    const trimmedTaskId = requireA2ATaskId(taskId);
+    const trimmedConfigId = requireA2APushConfigId(configId);
+    const response = await fetchDownstream(`${config.baseUrl}/tasks/${encodeURIComponent(trimmedTaskId)}/pushNotificationConfigs/${encodeURIComponent(trimmedConfigId)}`, {
+        method: "DELETE",
+        headers: buildA2AHeaders(config, options.traceContext),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "delete task push notification config");
+}
+function buildA2AMessageRequestBody(config, input) {
+    // `traceContext` is caller control data, not part of the A2A request body.
+    // Project it into headers and message metadata so Platform can join
+    // the task to traces without receiving a Maestro-private wrapper field.
+    const { traceContext: inputTraceContext, ...messageInput } = input;
+    const traceContext = resolveA2ATraceContext(inputTraceContext ?? config, {
+        envFallback: !inputTraceContext,
+    });
+    const body = {
+        ...messageInput,
+        message: {
+            ...input.message,
+            metadata: {
+                ...(input.message.metadata ?? {}),
+                workspaceId: config.workspaceId,
+                agentId: config.agentId,
+                sessionId: config.sessionId,
+                actorId: config.actorId,
+                ...(traceContext?.traceparent
+                    ? { traceparent: traceContext.traceparent }
+                    : {}),
+                ...(traceContext?.tracestate
+                    ? { tracestate: traceContext.tracestate }
+                    : {}),
+            },
+        },
+    };
+    return { body, traceContext };
+}
+export function resolveA2ATraceContext(input, options = {}) {
+    const envFallback = options.envFallback ?? true;
+    // Explicit trace input wins as a unit. A caller-provided traceparent with no
+    // tracestate should not inherit a stale process-level TRACESTATE value.
+    const traceparent = trimString(input?.traceparent) ??
+        (envFallback
+            ? getEnvValue(["TRACEPARENT", "TRACE_PARENT", "MAESTRO_TRACEPARENT"])
+            : undefined);
+    const tracestate = trimString(input?.tracestate) ??
+        (envFallback
+            ? getEnvValue(["TRACESTATE", "TRACE_STATE", "MAESTRO_TRACESTATE"])
+            : undefined);
+    if (!traceparent) {
+        return undefined;
+    }
+    return {
+        traceparent,
+        ...(tracestate ? { tracestate } : {}),
+    };
+}
+export async function getA2ATask(config, taskId, options = {}) {
+    const trimmedTaskId = requireA2ATaskId(taskId);
+    const response = await fetchDownstream(`${config.baseUrl}/tasks/${encodeURIComponent(trimmedTaskId)}`, {
+        method: "GET",
+        headers: buildA2AHeaders(config, options.traceContext),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "get task");
+    return (await response.json());
+}
+export async function cancelA2ATask(config, taskId, options = {}) {
+    const trimmedTaskId = requireA2ATaskId(taskId);
+    const response = await fetchDownstream(`${config.baseUrl}/tasks/${encodeURIComponent(trimmedTaskId)}:cancel`, {
+        method: "POST",
+        headers: buildA2AHeaders(config, options.traceContext),
+        signal: options.signal,
+    }, {
+        serviceName: "platform-a2a",
+        failureMode: "required",
+        timeoutMs: config.timeoutMs,
+        maxAttempts: config.maxAttempts,
+    });
+    await throwForA2AError(response, "cancel task");
+    return (await response.json());
+}
+async function* parseA2AStreamEvents(response) {
+    if (!response.body) {
+        return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let completed = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                completed = true;
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            const parsed = splitCompleteServerSentEvents(buffer);
+            buffer = parsed.remainder;
+            for (const frame of parsed.frames) {
+                const event = parseA2AStreamEventFrame(frame);
+                if (event) {
+                    yield event;
+                }
+            }
+        }
+        buffer += decoder.decode();
+        if (buffer.trim()) {
+            const event = parseA2AStreamEventFrame(buffer);
+            if (event) {
+                yield event;
+            }
+        }
+    }
+    finally {
+        if (!completed) {
+            await reader.cancel().catch(() => undefined);
+        }
+        reader.releaseLock();
+    }
+}
+function splitCompleteServerSentEvents(input) {
+    const frames = [];
+    let cursor = 0;
+    while (cursor < input.length) {
+        const lineBreakIndex = findServerSentEventBoundary(input, cursor);
+        if (lineBreakIndex === -1) {
+            break;
+        }
+        frames.push(input.slice(cursor, lineBreakIndex.start));
+        cursor = lineBreakIndex.end;
+    }
+    return { frames, remainder: input.slice(cursor) };
+}
+function findServerSentEventBoundary(input, startIndex) {
+    for (let index = startIndex; index < input.length; index += 1) {
+        const firstLineEndingLength = getServerSentEventLineEndingLength(input, index);
+        if (firstLineEndingLength === 0) {
+            continue;
+        }
+        const secondLineEndingLength = getServerSentEventLineEndingLength(input, index + firstLineEndingLength);
+        if (secondLineEndingLength > 0) {
+            return {
+                start: index,
+                end: index + firstLineEndingLength + secondLineEndingLength,
+            };
+        }
+    }
+    return -1;
+}
+function getServerSentEventLineEndingLength(input, index) {
+    if (input[index] === "\r") {
+        return input[index + 1] === "\n" ? 2 : 1;
+    }
+    return input[index] === "\n" ? 1 : 0;
+}
+function parseA2AStreamEventFrame(frame) {
+    let eventType;
+    const dataLines = [];
+    for (const line of frame.split(/\r\n|\n|\r/u)) {
+        if (!line || line.startsWith(":")) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(":");
+        const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);
+        const rawValue = separatorIndex === -1 ? "" : line.slice(separatorIndex + 1);
+        const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
+        if (field === "event") {
+            eventType = parseA2AStreamEventType(value);
+        }
+        if (field === "data") {
+            dataLines.push(value);
+        }
+    }
+    if (dataLines.length === 0) {
+        return undefined;
+    }
+    let payload;
+    try {
+        const parsed = JSON.parse(dataLines.join("\n"));
+        if (!isRecord(parsed)) {
+            return undefined;
+        }
+        payload = parsed;
+    }
+    catch {
+        return undefined;
+    }
+    payload = unwrapA2AStreamPayload(payload);
+    eventType ??= inferA2AStreamEventType(payload);
+    if (!eventType) {
+        return undefined;
+    }
+    return normalizeA2AStreamEvent(eventType, payload);
+}
+function parseA2AStreamEventType(value) {
+    if (value === "task" ||
+        value === "message" ||
+        value === "statusUpdate" ||
+        value === "artifactUpdate") {
+        return value;
+    }
+    return undefined;
+}
+function inferA2AStreamEventType(payload) {
+    if (isRecord(payload.task)) {
+        return "task";
+    }
+    if (isRecord(payload.message)) {
+        return "message";
+    }
+    if (isRecord(payload.statusUpdate)) {
+        return "statusUpdate";
+    }
+    if (isRecord(payload.artifactUpdate) || isRecord(payload.artifact)) {
+        return "artifactUpdate";
+    }
+    if (isRecord(payload.status) && typeof payload.id === "string") {
+        return "task";
+    }
+    if (isRecord(payload.status)) {
+        return "statusUpdate";
+    }
+    if (typeof payload.messageId === "string" &&
+        typeof payload.role === "string") {
+        return "message";
+    }
+    return undefined;
+}
+function unwrapA2AStreamPayload(payload) {
+    return payload.jsonrpc === "2.0" && isRecord(payload.result)
+        ? payload.result
+        : payload;
+}
+function normalizeA2AStreamEvent(eventType, payload) {
+    if (eventType === "task") {
+        return {
+            type: "task",
+            task: (payload.task ?? payload),
+        };
+    }
+    if (eventType === "message") {
+        return {
+            type: "message",
+            message: (payload.message ?? payload),
+        };
+    }
+    if (eventType === "statusUpdate") {
+        const statusUpdatePayload = isRecord(payload.statusUpdate)
+            ? payload.statusUpdate
+            : payload;
+        return {
+            ...statusUpdatePayload,
+            status: statusUpdatePayload.status,
+            type: "statusUpdate",
+        };
+    }
+    const artifactUpdatePayload = isRecord(payload.artifactUpdate)
+        ? payload.artifactUpdate
+        : payload;
+    return {
+        ...artifactUpdatePayload,
+        artifact: artifactUpdatePayload.artifact,
+        type: "artifactUpdate",
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireA2ATaskId(taskId) {
+    const trimmedTaskId = trimString(taskId);
+    if (!trimmedTaskId) {
+        throw new Error("A2A task id is required");
+    }
+    return trimmedTaskId;
+}
+function requireA2APushConfigId(configId) {
+    const trimmedConfigId = trimString(configId);
+    if (!trimmedConfigId) {
+        throw new Error("A2A push notification config id is required");
+    }
+    return trimmedConfigId;
+}
+function resolveA2AExtensions(config, requestExtensions) {
+    const extensions = new Set();
+    for (const extension of [
+        ...(config.extensions ?? []),
+        ...(requestExtensions ?? []),
+    ]) {
+        const value = trimString(extension);
+        if (value) {
+            extensions.add(value);
+        }
+    }
+    return [...extensions];
+}
+function resolveConfiguredA2AExtensions(overrides) {
+    const values = overrides ??
+        getEnvValue([...A2A_EXTENSIONS_ENV_VARS])
+            ?.split(",")
+            .map((value) => value.trim())
+            .filter(Boolean);
+    return values && values.length > 0 ? [...new Set(values)] : undefined;
+}
+function buildA2AHeaders(config, traceContext, extensions = []) {
+    // Header projection mirrors message metadata projection: intermediaries can
+    // route and trace the HTTP request, while the task itself keeps durable
+    // correlation metadata for later lookup.
+    const resolvedTraceContext = resolveA2ATraceContext(traceContext ?? config, {
+        envFallback: !traceContext,
+    });
+    return buildPlatformJsonHeaders(config, {
+        "X-EvalOps-Workspace-Id": config.workspaceId,
+        "X-EvalOps-Agent-Id": config.agentId,
+        "X-EvalOps-Session-Id": config.sessionId,
+        "X-EvalOps-Actor-Id": config.actorId,
+        traceparent: resolvedTraceContext?.traceparent,
+        tracestate: resolvedTraceContext?.tracestate,
+        "A2A-Extensions": extensions.length > 0 ? extensions.join(",") : undefined,
+    });
+}
+async function throwForA2AError(response, operation) {
+    if (response.ok) {
+        return;
+    }
+    let detail = "";
+    try {
+        const payload = (await response.json());
+        detail = payload.error?.message ?? payload.error?.code ?? "";
+    }
+    catch {
+        detail = await response.text().catch(() => "");
+    }
+    throw new Error(`Platform A2A ${operation} failed with ${response.status}${detail ? `: ${detail}` : ""}`);
+}
+//# sourceMappingURL=a2a-client.js.map