create-windy 0.6.18 → 0.6.19

package/template/apps/web/src/pages/system/components/user-account/UserRoleSelector.webtest.ts

@@ -22,13 +22,38 @@ describe("UserRoleSelector", () => {
           code: "department-manager",
           name: "部门负责人",
           dataScope: "department-and-children",
+          permissionKeys: ["system.user.read", "system.user.manage"],
         },
       ],
       total: 1,
       page: 1,
       pageSize: 100,
     });
-    const wrapper = mount(UserRoleSelector, { props: { modelValue: [] } });
+    const wrapper = mount(UserRoleSelector, {
+      props: {
+        modelValue: [],
+        permissions: [
+          {
+            key: "system.user.read",
+            label: "查看用户",
+            module: "system",
+            moduleLabel: "系统管理",
+            resource: "user",
+            resourceLabel: "用户账号",
+            action: "read",
+          },
+          {
+            key: "system.user.manage",
+            label: "管理用户",
+            module: "system",
+            moduleLabel: "系统管理",
+            resource: "user",
+            resourceLabel: "用户账号",
+            action: "manage",
+          },
+        ],
+      },
+    });
     await flushPromises();
 
     expect(api.list).toHaveBeenCalledWith(
@@ -37,6 +62,10 @@ describe("UserRoleSelector", () => {
     );
     expect(wrapper.text()).toContain("部门负责人");
     expect(wrapper.text()).toContain("本部门及下级");
+    expect(wrapper.text()).toContain("查看 2 项功能权限");
+    await wrapper.get("summary").trigger("click");
+    expect(wrapper.text()).toContain("用户账号");
+    expect(wrapper.text()).toContain("查看用户、管理用户");
     await wrapper.get('[role="checkbox"]').trigger("click");
     expect(wrapper.emitted("update:modelValue")?.at(-1)).toEqual([
       ["role_manager"],

package/template/docs/architecture/ai-runtime.md

@@ -1,20 +1,13 @@
 # Windy AI Runtime 架构
 
-更新时间：2026-08-27。
-
-状态：架构已确认，文本 Agent、Document AI、批量 Speech/ASR 与受控 Vision Artifact
-切片已实现。当前包含 Module AI Operation
-注册、Guarded Run facade、短时 Execution Grant、受限 Tool Host、OpenAI-compatible
-Provider、canonical HTTP/SSE、取消、cursor 重放和单副本有界 SQLite Store。未配置
-Provider 时仍安全拒绝。真实业务 Run 由 Windy Direct OpenAI-compatible Engine 执行，
-并直接产生 canonical signal。持久 Session/Workflow、LiteLLM 多 Provider 路由和
-PostgreSQL 多副本 Store 尚未实现。Document AI 已提供独立
-Server、授权 ArtifactRef、结构化页级结果、本地/内网 Adapter 契约，以及搜索型 PDF
-等派生文件的受治理 Output Artifact producer 协议；项目 composition 尚未接线，不能
-视为生产可用。Speech 已提供批量转写、归一化、VAD/时间戳契约、稳定分段和结果
-Artifact，但未提供实时 ASR、TTS 或 Dictation。不能据此宣称完整 AI Runtime 已交付。
-Vision 已提供 `agent.vision` 的多图片受控输入、像素限制、逐次发送审计和 JSON Schema
-终态校验；视频帧输入与实时视觉不在当前切片。
+更新时间：2026-09-02。
+
+状态：文本 Agent、Document、Embedding、批量 Speech/ASR、受控 Vision Artifact、PostgreSQL
+Run Store、持久 Session/Memory 与 Workflow/委派切片均已实现。WAI-1 已为 Windy Server 到
+Agent Server 增加 additive 的 V1 兼容 Offer、release/capability digest 和 Run 创建 pin；详见
+[Remote Agent Runtime 兼容契约](./agent-runtime-compatibility.md)。当前 Provider 仍是单一 Direct
+OpenAI-compatible Adapter；LiteLLM 多 Provider 路由、完整 RAG、外部业务 Host callback 认证与
+Sharp S-Word 接线均未实现。未配置任一可选 Runtime 时继续安全拒绝对应 Operation，不阻止普通业务。
 
 ## 目标
 

package/template/docs/platform/agent-runtime.md

@@ -18,6 +18,11 @@ POST /api/agent/runs/:runId/cancel
 创建 Run 必须携带幂等键；SSE 支持 cursor 重放和 heartbeat。Engine 切换不改变 Run DTO、
 canonical Event、唯一终态、取消或 Tool 授权语义。
 
+Windy Server 与 Agent Server 之间已经提供 additive 的 V1 兼容 Offer、release/capability digest
+和 Run 创建请求头 pin。当前同部署 Adapter 使用滚动兼容的 `prefer-v1`；任何外部业务 Host Adapter
+必须使用 `require-v1`，且在独立 callback 认证 profile 落地前不得投入生产。完整职责与失败语义见
+[Remote Agent Runtime 兼容契约](../architecture/agent-runtime-compatibility.md)。
+
 ## 能力与治理边界
 
 Direct Engine 已覆盖：

package/template/packages/server-sdk/contracts/agent-runtime-compatibility/v1/offer.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "runtimeKind": "agent",
+  "engineId": "windy.direct.openai-compatible.v1",
+  "protocolVersions": [1],
+  "protocolFeatures": [
+    "canonical-sse-replay.v1",
+    "execution-grant-forwarding.v1",
+    "operation-release-attestation.v1",
+    "run-cancel.v1",
+    "run-lifecycle.v1",
+    "runtime-reporting.v1",
+    "tool-callback.v1"
+  ],
+  "toolCallback": {
+    "contractVersion": 1,
+    "authentication": "windy-internal-bearer-v1"
+  },
+  "releaseDigest": "sha256:410c49040a4e4de40dd2fed60877b2b08e9bbcb23198f10a7cbb3cf7d1135ce0",
+  "capabilitiesDigest": "sha256:bcdd3822f9077ac6d1cd42f8a53dbdb46d9a5bc908821e92bd6fb28e2ec6ab65",
+  "offerDigest": "sha256:1375cd3a1511f2d5fdde3cac123d9d6bc603f80ad746758508d0a3da67ed8fad"
+}

package/template/packages/server-sdk/index.ts

@@ -1,4 +1,23 @@
 export type { ModuleActor } from "./src/actor.js";
+export {
+  AGENT_RUNTIME_COMPATIBILITY_PATH_V1,
+  AGENT_RUNTIME_COMPATIBILITY_SCHEMA_VERSION,
+  AGENT_RUNTIME_INTERNAL_CALLBACK_AUTH_V1,
+  AGENT_RUNTIME_KIND_V1,
+  AGENT_RUNTIME_OFFER_DIGEST_HEADER_V1,
+  AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+  AGENT_RUNTIME_PROTOCOL_HEADER_V1,
+  AGENT_RUNTIME_PROTOCOL_VERSION_V1,
+  AGENT_RUNTIME_TOOL_CALLBACK_CONTRACT_VERSION_V1,
+  createAgentRuntimeCompatibilityOfferV1,
+  localAgentRuntimeCompatibilityRequirementsV1,
+  negotiateAgentRuntimeCompatibilityV1,
+  parseAgentRuntimeCompatibilityOfferV1,
+  type AgentRuntimeCompatibilityDigestV1,
+  type AgentRuntimeCompatibilityNegotiationV1,
+  type AgentRuntimeCompatibilityOfferV1,
+  type AgentRuntimeCompatibilityRequirementsV1,
+} from "./src/agent-runtime-compatibility.js";
 export { pageAgentClientRunCapability } from "./src/client-agent-session.js";
 export type {
   ModuleClientAgentHostAuthAdapter,

package/template/packages/server-sdk/package.json

@@ -26,6 +26,7 @@
     "src/ai-runtime-readiness-validation.ts",
     "src/ai-runtime-readiness-validation-values.ts",
     "src/ai-runtime-readiness-values.ts",
+    "src/agent-runtime-compatibility.ts",
     "src/agent-session-memory-port.ts",
     "src/agent-session-provider.ts",
     "src/agent-source-invalidation-port.ts",
@@ -71,6 +72,7 @@
   },
   "exports": {
     ".": "./index.ts",
+    "./contracts/agent-runtime-compatibility/v1/*": "./contracts/agent-runtime-compatibility/v1/*",
     "./contracts/ai-runtime-readiness/v1/*": "./contracts/ai-runtime-readiness/v1/*"
   },
   "publishConfig": {

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

@@ -0,0 +1,143 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, test } from "bun:test";
+import {
+  AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+  type AgentRuntimeCompatibilityOfferV1,
+  createAgentRuntimeCompatibilityOfferV1,
+  localAgentRuntimeCompatibilityRequirementsV1,
+  negotiateAgentRuntimeCompatibilityV1,
+  parseAgentRuntimeCompatibilityOfferV1,
+} from "./agent-runtime-compatibility.js";
+
+const fixture = await loadFixture();
+
+describe("Remote Agent Runtime compatibility V1", () => {
+  test("公共 builder 与跨语言 fixture 字节语义一致", () => {
+    expect(
+      createAgentRuntimeCompatibilityOfferV1(
+        "windy.direct.openai-compatible.v1",
+      ),
+    ).toEqual(fixture);
+    expect(parseAgentRuntimeCompatibilityOfferV1(fixture)).toEqual(fixture);
+  });
+
+  test("协商最高共同版本并要求完整协议能力与 callback 认证", () => {
+    const result = negotiateAgentRuntimeCompatibilityV1(
+      fixture,
+      localAgentRuntimeCompatibilityRequirementsV1(),
+    );
+
+    expect(result).toEqual({ ok: true, protocolVersion: 1, offer: fixture });
+  });
+
+  test("未知 schema、缺失能力和 callback 认证漂移均失败关闭", () => {
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(
+        { ...fixture, schemaVersion: 2 },
+        localAgentRuntimeCompatibilityRequirementsV1(),
+      ),
+    ).toEqual({ ok: false, code: "CONTRACT_UNSUPPORTED" });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        requiredProtocolFeatures: [
+          ...AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+          "future-required.v1",
+        ],
+      }),
+    ).toEqual({
+      ok: false,
+      code: "CAPABILITY_MISSING",
+      subject: "future-required.v1",
+    });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        requiredToolCallbackAuthentication: "signed-callback-v1",
+      }),
+    ).toEqual({
+      ok: false,
+      code: "CALLBACK_AUTH_UNSUPPORTED",
+      subject: "signed-callback-v1",
+    });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        protocolVersions: [2],
+      }),
+    ).toEqual({ ok: false, code: "CONTRACT_UNSUPPORTED" });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        expectedReleaseDigest: `sha256:${"0".repeat(64)}`,
+      }),
+    ).toEqual({ ok: false, code: "RELEASE_DIGEST_MISMATCH" });
+  });
+
+  test("任一受摘要保护字段漂移都不能沿用旧 Offer", () => {
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        protocolFeatures: [...fixture.protocolFeatures, "tampered.v1"],
+      }),
+    ).toBeNull();
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        engineId: "windy.other-engine.v1",
+      }),
+    ).toBeNull();
+  });
+
+  test("重复或超界集合与非稳定 identity 被拒绝", () => {
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        protocolVersions: [1, 1],
+      }),
+    ).toBeNull();
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        protocolFeatures: Array.from(
+          { length: 65 },
+          (_, index) => `feature-${index}.v1`,
+        ),
+      }),
+    ).toBeNull();
+    expect(() =>
+      createAgentRuntimeCompatibilityOfferV1("https://provider.invalid"),
+    ).toThrow("engineId invalid");
+  });
+
+  test("恶意 getter 或循环对象只形成安全的契约拒绝", () => {
+    const throwing = Object.defineProperty({}, "schemaVersion", {
+      get() {
+        throw new Error("secret getter body");
+      },
+    });
+    const cyclic: Record<string, unknown> = { ...fixture };
+    cyclic.toolCallback = cyclic;
+
+    expect(parseAgentRuntimeCompatibilityOfferV1(throwing)).toBeNull();
+    expect(parseAgentRuntimeCompatibilityOfferV1(cyclic)).toBeNull();
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(
+        throwing,
+        localAgentRuntimeCompatibilityRequirementsV1(),
+      ),
+    ).toEqual({ ok: false, code: "CONTRACT_INVALID" });
+  });
+});
+
+async function loadFixture(): Promise<AgentRuntimeCompatibilityOfferV1> {
+  return JSON.parse(
+    await readFile(
+      new URL(
+        "../contracts/agent-runtime-compatibility/v1/offer.json",
+        import.meta.url,
+      ),
+      "utf8",
+    ),
+  ) as AgentRuntimeCompatibilityOfferV1;
+}

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

@@ -0,0 +1,19 @@
+import { expect, test } from "bun:test";
+import {
+  createAgentRuntimeCompatibilityOfferV1,
+  localAgentRuntimeCompatibilityRequirementsV1,
+  negotiateAgentRuntimeCompatibilityV1,
+} from "../index.js";
+
+test("@southwind-ai/server-sdk 根入口公开 Remote Agent Runtime V1 协商", () => {
+  const offer = createAgentRuntimeCompatibilityOfferV1(
+    "windy.direct.openai-compatible.v1",
+  );
+
+  expect(
+    negotiateAgentRuntimeCompatibilityV1(
+      offer,
+      localAgentRuntimeCompatibilityRequirementsV1(),
+    ),
+  ).toMatchObject({ ok: true, protocolVersion: 1 });
+});

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;
+  }
+}