create-windy 0.6.17 → 0.6.19

package/template/apps/web/src/pages/system/components/user-account/UserAccountForm.vue

@@ -1,7 +1,11 @@
 <script setup lang="ts">
 import { onMounted, shallowRef, watch } from "vue";
 import { PlusIcon } from "@lucide/vue";
-import { PASSWORD_POLICY, type PasswordPolicy } from "@southwind-ai/shared";
+import {
+  PASSWORD_POLICY,
+  type PasswordPolicy,
+  type PermissionDefinition,
+} from "@southwind-ai/shared";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import {
@@ -11,13 +15,9 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
-import {
-  createSystemResource,
-  listSystemResource,
-  quickCreateDepartment,
-  type SystemRecord,
-} from "@/services/system-api";
+import { listSystemResource, type SystemRecord } from "@/services/system-api";
 import { loadPasswordPolicy } from "@/services/auth-api";
+import CreateDepartmentDialog from "./CreateDepartmentDialog.vue";
 import UserRoleSelector from "./UserRoleSelector.vue";
 
 interface DepartmentOption {
@@ -30,6 +30,7 @@ interface DepartmentOption {
 const props = defineProps<{
   item?: SystemRecord;
   defaults: Record<string, unknown>;
+  permissions: PermissionDefinition[];
   departmentCreateMode?: "create" | "manage";
 }>();
 
@@ -40,12 +41,8 @@ const emit = defineEmits<{
 const form = shallowRef<Record<string, unknown>>({});
 const departments = shallowRef<DepartmentOption[]>([]);
 const loading = shallowRef(false);
-const creating = shallowRef(false);
 const error = shallowRef("");
-const quickOpen = shallowRef(false);
-const quickName = shallowRef("");
-const quickCode = shallowRef("");
-const quickParentId = shallowRef<string | undefined>();
+const departmentDialogOpen = shallowRef(false);
 const governedTouched = shallowRef<Record<string, boolean>>({});
 const passwordPolicy = shallowRef<PasswordPolicy>(PASSWORD_POLICY);
 
@@ -114,32 +111,9 @@ function selectedRoleIds(): string[] {
     : [];
 }
 
-async function createDepartment() {
-  if (!props.departmentCreateMode || creating.value) return;
-  creating.value = true;
-  error.value = "";
-  try {
-    const payload = {
-      code: quickCode.value,
-      name: quickName.value,
-      parentId: quickParentId.value,
-      order: 100,
-    };
-    const created =
-      props.departmentCreateMode === "create"
-        ? await quickCreateDepartment(payload)
-        : await createSystemResource("departments", payload);
-    await loadDepartments();
-    update("departmentId", created.id);
-    quickOpen.value = false;
-    quickName.value = "";
-    quickCode.value = "";
-    quickParentId.value = undefined;
-  } catch (currentError) {
-    error.value = readError(currentError);
-  } finally {
-    creating.value = false;
-  }
+async function selectCreatedDepartment(department: DepartmentOption) {
+  await loadDepartments();
+  update("departmentId", department.id);
 }
 
 function submit() {
@@ -218,7 +192,7 @@ defineExpose({ submit });
           type="button"
           size="sm"
           variant="ghost"
-          @click="quickOpen = !quickOpen"
+          @click="departmentDialogOpen = true"
         >
           <PlusIcon data-icon="inline-start" />新建部门
         </Button>
@@ -246,6 +220,7 @@ defineExpose({ submit });
     </div>
     <UserRoleSelector
       :model-value="selectedRoleIds()"
+      :permissions="permissions"
       @update:model-value="update('roleIds', $event)"
     />
     <div class="grid gap-4 sm:grid-cols-2">
@@ -283,38 +258,13 @@ defineExpose({ submit });
         </span>
       </label>
     </div>
-    <section
-      v-if="quickOpen"
-      class="space-y-3 rounded-lg border bg-muted/20 p-4"
-    >
-      <p class="text-sm font-medium">新建并选中部门</p>
-      <div class="grid gap-3 sm:grid-cols-2">
-        <Input v-model="quickName" placeholder="部门名称" />
-        <Input v-model="quickCode" placeholder="部门编码，例如 sales" />
-      </div>
-      <Select v-model="quickParentId">
-        <SelectTrigger class="w-full" aria-label="上级部门">
-          <SelectValue placeholder="请选择上级部门" />
-        </SelectTrigger>
-        <SelectContent>
-          <SelectItem
-            v-for="department in departments"
-            :key="department.id"
-            :value="department.id"
-          >
-            {{ department.name }}
-          </SelectItem>
-        </SelectContent>
-      </Select>
-      <Button
-        type="button"
-        size="sm"
-        :disabled="creating || !quickParentId"
-        @click="createDepartment"
-      >
-        {{ creating ? "创建中…" : "创建并选中" }}
-      </Button>
-    </section>
     <p v-if="error" class="text-sm text-destructive">{{ error }}</p>
+    <CreateDepartmentDialog
+      v-if="departmentCreateMode"
+      v-model:open="departmentDialogOpen"
+      :mode="departmentCreateMode"
+      :departments="departments"
+      @created="selectCreatedDepartment"
+    />
   </div>
 </template>

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

@@ -0,0 +1,71 @@
+import { defineComponent } from "vue";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { flushPromises, mount } from "@vue/test-utils";
+import UserAccountForm from "./UserAccountForm.vue";
+
+const api = vi.hoisted(() => ({
+  list: vi.fn(),
+  loadPasswordPolicy: vi.fn(),
+}));
+
+vi.mock("@/services/system-api", async () => {
+  const actual = await vi.importActual<typeof import("@/services/system-api")>(
+    "@/services/system-api",
+  );
+  return { ...actual, listSystemResource: api.list };
+});
+
+vi.mock("@/services/auth-api", () => ({
+  loadPasswordPolicy: api.loadPasswordPolicy,
+}));
+
+afterEach(() => vi.clearAllMocks());
+
+describe("UserAccountForm", () => {
+  test("新建部门使用独立 Modal，不在用户表单底部追加内容", async () => {
+    api.list.mockResolvedValue({
+      items: [{ id: "dept_root", code: "root", name: "总部" }],
+      total: 1,
+      page: 1,
+      pageSize: 100,
+    });
+    api.loadPasswordPolicy.mockResolvedValue({
+      minLength: 12,
+      maxLength: 128,
+      requireUppercase: true,
+      requireLowercase: true,
+      requireNumber: true,
+      requireSpecial: false,
+    });
+    const dialogStub = defineComponent({
+      name: "CreateDepartmentDialog",
+      props: { open: Boolean },
+      emits: ["update:open", "created"],
+      template: '<div data-testid="department-dialog" />',
+    });
+    const wrapper = mount(UserAccountForm, {
+      props: {
+        defaults: { roleIds: [], status: "active" },
+        permissions: [],
+        departmentCreateMode: "create",
+      },
+      global: {
+        stubs: {
+          CreateDepartmentDialog: dialogStub,
+          UserRoleSelector: { template: "<div />" },
+        },
+      },
+    });
+    await flushPromises();
+
+    const dialog = wrapper.getComponent(dialogStub);
+    expect(dialog.props("open")).toBe(false);
+    const openButton = wrapper
+      .findAll("button")
+      .find((button) => button.text() === "新建部门");
+    await openButton?.trigger("click");
+
+    expect(dialog.props("open")).toBe(true);
+    expect(wrapper.text()).not.toContain("新建并选中部门");
+  });
+});

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

@@ -1,16 +1,22 @@
 <script setup lang="ts">
+import type { PermissionDefinition } from "@southwind-ai/shared";
 import { onMounted, shallowRef } from "vue";
 import { Checkbox } from "@/components/ui/checkbox";
 import { listSystemResource } from "@/services/system-api";
+import RolePermissionSummary from "./RolePermissionSummary.vue";
 
 interface RoleOption {
   id: string;
   code: string;
   name: string;
   dataScope: string;
+  permissionKeys: string[];
 }
 
-const props = defineProps<{ modelValue: string[] }>();
+const props = defineProps<{
+  modelValue: string[];
+  permissions: PermissionDefinition[];
+}>();
 const emit = defineEmits<{ "update:modelValue": [value: string[]] }>();
 const roles = shallowRef<RoleOption[]>([]);
 const loading = shallowRef(false);
@@ -37,6 +43,11 @@ async function loadRoles() {
               name: item.name,
               dataScope:
                 typeof item.dataScope === "string" ? item.dataScope : "self",
+              permissionKeys: Array.isArray(item.permissionKeys)
+                ? item.permissionKeys.filter(
+                    (key): key is string => typeof key === "string",
+                  )
+                : [],
             },
           ]
         : [],
@@ -78,34 +89,44 @@ function dataScopeLabel(scope: string): string {
       <label class="text-sm font-medium">账号角色</label>
       <span class="text-xs text-muted-foreground">至少选择一个</span>
     </div>
-    <div
-      class="grid gap-2 rounded-lg border p-3 sm:grid-cols-2"
-      aria-label="账号角色"
-    >
-      <p v-if="loading" class="text-sm text-muted-foreground sm:col-span-2">
-        正在加载角色…
-      </p>
-      <p v-else-if="error" class="text-sm text-destructive sm:col-span-2">
+    <div class="grid gap-3 rounded-lg border p-3" aria-label="账号角色">
+      <p v-if="loading" class="text-sm text-muted-foreground">正在加载角色…</p>
+      <p v-else-if="error" class="text-sm text-destructive">
         {{ error }}
       </p>
-      <label
-        v-for="role in roles"
-        v-else
-        :key="role.id"
-        class="flex cursor-pointer items-start gap-3 rounded-md p-2 hover:bg-muted/60"
-      >
-        <Checkbox
-          :model-value="modelValue.includes(role.id)"
-          :aria-label="role.name"
-          @update:model-value="toggle(role.id, $event)"
-        />
-        <span class="grid gap-0.5 text-sm">
-          <span class="font-medium">{{ role.name }}</span>
-          <span class="text-xs text-muted-foreground">
-            {{ role.code }} · {{ dataScopeLabel(role.dataScope) }}
-          </span>
-        </span>
-      </label>
+      <template v-else>
+        <article
+          v-for="role in roles"
+          :key="role.id"
+          class="rounded-lg border p-3 transition-colors"
+          :class="
+            modelValue.includes(role.id)
+              ? 'border-primary/50 bg-primary/5'
+              : 'hover:bg-muted/40'
+          "
+        >
+          <label class="flex cursor-pointer items-start gap-3">
+            <Checkbox
+              :model-value="modelValue.includes(role.id)"
+              :aria-label="role.name"
+              @update:model-value="toggle(role.id, $event)"
+            />
+            <span class="grid gap-0.5 text-sm">
+              <span class="font-medium">{{ role.name }}</span>
+              <span class="text-xs text-muted-foreground">
+                {{ role.code }} · {{ dataScopeLabel(role.dataScope) }}
+              </span>
+            </span>
+          </label>
+          <RolePermissionSummary
+            :permission-keys="role.permissionKeys"
+            :permissions="permissions"
+          />
+        </article>
+        <p v-if="!roles.length" class="text-sm text-muted-foreground">
+          暂无可选角色。
+        </p>
+      </template>
     </div>
   </div>
 </template>

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