create-windy 0.6.18 → 0.6.20

package/template/packages/server-sdk/src/agent-runtime-compatibility.ts

@@ -0,0 +1,284 @@
+import { createHash } from "node:crypto";
+
+export const AGENT_RUNTIME_COMPATIBILITY_SCHEMA_VERSION = 1 as const;
+export const AGENT_RUNTIME_PROTOCOL_VERSION_V1 = 1 as const;
+export const AGENT_RUNTIME_KIND_V1 = "agent" as const;
+export const AGENT_RUNTIME_COMPATIBILITY_PATH_V1 =
+  "/api/agent/runtime/compatibility" as const;
+export const AGENT_RUNTIME_PROTOCOL_HEADER_V1 =
+  "X-Windy-Agent-Runtime-Protocol" as const;
+export const AGENT_RUNTIME_OFFER_DIGEST_HEADER_V1 =
+  "X-Windy-Agent-Runtime-Offer-Digest" as const;
+export const AGENT_RUNTIME_TOOL_CALLBACK_CONTRACT_VERSION_V1 = 1 as const;
+export const AGENT_RUNTIME_INTERNAL_CALLBACK_AUTH_V1 =
+  "windy-internal-bearer-v1" as const;
+
+export const AGENT_RUNTIME_PROTOCOL_FEATURES_V1 = Object.freeze([
+  "canonical-sse-replay.v1",
+  "execution-grant-forwarding.v1",
+  "operation-release-attestation.v1",
+  "run-cancel.v1",
+  "run-lifecycle.v1",
+  "runtime-reporting.v1",
+  "tool-callback.v1",
+] as const);
+
+export type AgentRuntimeCompatibilityDigestV1 = `sha256:${string}`;
+
+export interface AgentRuntimeCompatibilityOfferV1 {
+  readonly schemaVersion: typeof AGENT_RUNTIME_COMPATIBILITY_SCHEMA_VERSION;
+  readonly runtimeKind: typeof AGENT_RUNTIME_KIND_V1;
+  readonly engineId: string;
+  readonly protocolVersions: readonly number[];
+  readonly protocolFeatures: readonly string[];
+  readonly toolCallback: {
+    readonly contractVersion: typeof AGENT_RUNTIME_TOOL_CALLBACK_CONTRACT_VERSION_V1;
+    readonly authentication: string;
+  };
+  readonly releaseDigest: AgentRuntimeCompatibilityDigestV1;
+  readonly capabilitiesDigest: AgentRuntimeCompatibilityDigestV1;
+  readonly offerDigest: AgentRuntimeCompatibilityDigestV1;
+}
+
+export interface AgentRuntimeCompatibilityRequirementsV1 {
+  readonly protocolVersions: readonly number[];
+  readonly requiredProtocolFeatures: readonly string[];
+  readonly requiredToolCallbackAuthentication: string;
+  readonly expectedReleaseDigest?: AgentRuntimeCompatibilityDigestV1;
+}
+
+export type AgentRuntimeCompatibilityNegotiationV1 =
+  | {
+      readonly ok: true;
+      readonly protocolVersion: number;
+      readonly offer: AgentRuntimeCompatibilityOfferV1;
+    }
+  | {
+      readonly ok: false;
+      readonly code:
+        | "CONTRACT_INVALID"
+        | "CONTRACT_UNSUPPORTED"
+        | "CAPABILITY_MISSING"
+        | "CALLBACK_AUTH_UNSUPPORTED"
+        | "RELEASE_DIGEST_MISMATCH";
+      readonly subject?: string;
+    };
+
+const stableValuePattern = /^[a-z0-9][a-z0-9._-]{0,159}$/;
+
+export function createAgentRuntimeCompatibilityOfferV1(
+  engineId: string,
+): AgentRuntimeCompatibilityOfferV1 {
+  const normalizedEngineId = stableValue(engineId);
+  if (!normalizedEngineId) {
+    throw new TypeError("Agent Runtime engineId invalid");
+  }
+  return buildOffer({
+    engineId: normalizedEngineId,
+    protocolVersions: [AGENT_RUNTIME_PROTOCOL_VERSION_V1],
+    protocolFeatures: AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+    toolCallback: {
+      contractVersion: AGENT_RUNTIME_TOOL_CALLBACK_CONTRACT_VERSION_V1,
+      authentication: AGENT_RUNTIME_INTERNAL_CALLBACK_AUTH_V1,
+    },
+  });
+}
+
+export function parseAgentRuntimeCompatibilityOfferV1(
+  raw: unknown,
+): AgentRuntimeCompatibilityOfferV1 | null {
+  try {
+    return parseCapturedOffer(raw);
+  } catch {
+    return null;
+  }
+}
+
+function parseCapturedOffer(
+  raw: unknown,
+): AgentRuntimeCompatibilityOfferV1 | null {
+  if (!isRecord(raw)) return null;
+  if (
+    raw.schemaVersion !== AGENT_RUNTIME_COMPATIBILITY_SCHEMA_VERSION ||
+    raw.runtimeKind !== AGENT_RUNTIME_KIND_V1
+  ) {
+    return null;
+  }
+  const engineId = stableValue(raw.engineId);
+  const protocolVersions = versions(raw.protocolVersions);
+  const protocolFeatures = stableValues(raw.protocolFeatures, 64);
+  const toolCallback = parseToolCallback(raw.toolCallback);
+  if (!engineId || !protocolVersions || !protocolFeatures || !toolCallback) {
+    return null;
+  }
+  const expected = buildOffer({
+    engineId,
+    protocolVersions,
+    protocolFeatures,
+    toolCallback,
+  });
+  return raw.releaseDigest === expected.releaseDigest &&
+    raw.capabilitiesDigest === expected.capabilitiesDigest &&
+    raw.offerDigest === expected.offerDigest
+    ? expected
+    : null;
+}
+
+export function negotiateAgentRuntimeCompatibilityV1(
+  raw: unknown,
+  requirements: AgentRuntimeCompatibilityRequirementsV1,
+): AgentRuntimeCompatibilityNegotiationV1 {
+  const schemaVersion = observedSchemaVersion(raw);
+  if (
+    schemaVersion !== undefined &&
+    schemaVersion !== AGENT_RUNTIME_COMPATIBILITY_SCHEMA_VERSION
+  ) {
+    return { ok: false, code: "CONTRACT_UNSUPPORTED" };
+  }
+  const offer = parseAgentRuntimeCompatibilityOfferV1(raw);
+  if (!offer) return { ok: false, code: "CONTRACT_INVALID" };
+  const requiredVersions = versions(requirements.protocolVersions);
+  const requiredFeatures = stableValues(
+    requirements.requiredProtocolFeatures,
+    64,
+  );
+  const callbackAuthentication = stableValue(
+    requirements.requiredToolCallbackAuthentication,
+  );
+  if (!requiredVersions || !requiredFeatures || !callbackAuthentication) {
+    throw new TypeError("Agent Runtime compatibility requirements invalid");
+  }
+  const protocolVersion = [...offer.protocolVersions]
+    .filter((version) => requiredVersions.includes(version))
+    .sort((left, right) => right - left)[0];
+  if (protocolVersion === undefined) {
+    return { ok: false, code: "CONTRACT_UNSUPPORTED" };
+  }
+  const missing = requiredFeatures.find(
+    (feature) => !offer.protocolFeatures.includes(feature),
+  );
+  if (missing) {
+    return { ok: false, code: "CAPABILITY_MISSING", subject: missing };
+  }
+  if (offer.toolCallback.authentication !== callbackAuthentication) {
+    return {
+      ok: false,
+      code: "CALLBACK_AUTH_UNSUPPORTED",
+      subject: callbackAuthentication,
+    };
+  }
+  if (
+    requirements.expectedReleaseDigest &&
+    requirements.expectedReleaseDigest !== offer.releaseDigest
+  ) {
+    return { ok: false, code: "RELEASE_DIGEST_MISMATCH" };
+  }
+  return { ok: true, protocolVersion, offer };
+}
+
+export function localAgentRuntimeCompatibilityRequirementsV1(): AgentRuntimeCompatibilityRequirementsV1 {
+  return {
+    protocolVersions: [AGENT_RUNTIME_PROTOCOL_VERSION_V1],
+    requiredProtocolFeatures: AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+    requiredToolCallbackAuthentication: AGENT_RUNTIME_INTERNAL_CALLBACK_AUTH_V1,
+  };
+}
+
+function buildOffer(input: {
+  readonly engineId: string;
+  readonly protocolVersions: readonly number[];
+  readonly protocolFeatures: readonly string[];
+  readonly toolCallback: AgentRuntimeCompatibilityOfferV1["toolCallback"];
+}): AgentRuntimeCompatibilityOfferV1 {
+  const protocolVersions = sortedNumbers(input.protocolVersions);
+  const protocolFeatures = sortedStrings(input.protocolFeatures);
+  const releaseDigest = digest({
+    runtimeKind: AGENT_RUNTIME_KIND_V1,
+    engineId: input.engineId,
+    protocolVersions,
+  });
+  const capabilitiesDigest = digest({
+    protocolFeatures,
+    toolCallback: input.toolCallback,
+  });
+  const body = {
+    schemaVersion: AGENT_RUNTIME_COMPATIBILITY_SCHEMA_VERSION,
+    runtimeKind: AGENT_RUNTIME_KIND_V1,
+    engineId: input.engineId,
+    protocolVersions,
+    protocolFeatures,
+    toolCallback: { ...input.toolCallback },
+    releaseDigest,
+    capabilitiesDigest,
+  };
+  return { ...body, offerDigest: digest(body) };
+}
+
+function digest(value: unknown): AgentRuntimeCompatibilityDigestV1 {
+  return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+
+function parseToolCallback(
+  raw: unknown,
+): AgentRuntimeCompatibilityOfferV1["toolCallback"] | null {
+  if (!isRecord(raw)) return null;
+  const authentication = stableValue(raw.authentication);
+  return raw.contractVersion ===
+    AGENT_RUNTIME_TOOL_CALLBACK_CONTRACT_VERSION_V1 && authentication
+    ? {
+        contractVersion: AGENT_RUNTIME_TOOL_CALLBACK_CONTRACT_VERSION_V1,
+        authentication,
+      }
+    : null;
+}
+
+function versions(raw: unknown): readonly number[] | null {
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > 16) return null;
+  if (
+    raw.some(
+      (value) =>
+        !Number.isSafeInteger(value) ||
+        Number(value) < 1 ||
+        Number(value) > 255,
+    )
+  ) {
+    return null;
+  }
+  const result = sortedNumbers(raw as number[]);
+  return result.length === raw.length ? result : null;
+}
+
+function stableValues(raw: unknown, limit: number): readonly string[] | null {
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > limit)
+    return null;
+  const values = raw.map(stableValue);
+  if (values.some((value) => !value)) return null;
+  const result = sortedStrings(values as string[]);
+  return result.length === raw.length ? result : null;
+}
+
+function stableValue(raw: unknown): string | null {
+  return typeof raw === "string" && stableValuePattern.test(raw) ? raw : null;
+}
+
+function sortedNumbers(values: readonly number[]): readonly number[] {
+  return [...new Set(values)].sort((left, right) => left - right);
+}
+
+function sortedStrings(values: readonly string[]): readonly string[] {
+  return [...new Set(values)].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function observedSchemaVersion(raw: unknown): unknown {
+  try {
+    return isRecord(raw) ? raw.schemaVersion : undefined;
+  } catch {
+    return undefined;
+  }
+}