@axiom-lattice/protocols 4.1.0 → 4.1.2

package/src/__tests__/TrustedRunContextProtocol.test.ts

@@ -0,0 +1,265 @@
+import { parseTrustedRunContext } from "../TrustedRunContextProtocol";
+import vm from "node:vm";
+
+function validProjectRoom(): Record<string, unknown> {
+  return {
+    tenantId: "tenant", workspaceId: "workspace", projectId: "project", roomId: "room",
+    sourceRoomMessageId: "source", membershipId: "membership", assistantId: "assistant",
+    inputMessageId: "input", role: "coordinator", title: "Coordinator",
+  };
+}
+
+function validProjectTask(): Record<string, unknown> {
+  return {
+    tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1",
+    roomId: "room-1", membershipId: "member-1", assistantId: "agent-1",
+    taskId: "task-1", threadId: "thread-1", inputMessageId: "input-1",
+  };
+}
+
+describe("parseTrustedRunContext", () => {
+  it("returns a canonical clone and accepts null-prototype records", () => {
+    const projectRoom = Object.assign(Object.create(null) as Record<string, unknown>, validProjectRoom());
+    const context = Object.assign(Object.create(null) as Record<string, unknown>, { projectRoom });
+
+    const parsed = parseTrustedRunContext(context);
+
+    expect(parsed).toEqual({ projectRoom: validProjectRoom() });
+    expect(Object.getPrototypeOf(parsed)).toBe(Object.prototype);
+    expect(Object.getPrototypeOf(parsed.projectRoom)).toBe(Object.prototype);
+  });
+
+  it("accepts exact cross-realm records and returns a canonical local clone", () => {
+    const context = vm.runInNewContext(`({ projectRoom: ${JSON.stringify(validProjectRoom())} })`) as unknown;
+
+    const parsed = parseTrustedRunContext(context);
+
+    expect(parsed).toEqual({ projectRoom: validProjectRoom() });
+    expect(Object.getPrototypeOf(parsed)).toBe(Object.prototype);
+    expect(Object.getPrototypeOf(parsed.projectRoom)).toBe(Object.prototype);
+  });
+
+  it("accepts custom prototypes while ignoring inherited values", () => {
+    let inheritedReads = 0;
+    const inherited = Object.defineProperty({}, "responsibility", {
+      enumerable: true,
+      get: () => {
+        inheritedReads += 1;
+        return "malicious";
+      },
+    });
+    const projectRoom = Object.assign(Object.create(inherited) as Record<string, unknown>, validProjectRoom());
+    const context = Object.assign(Object.create({ extra: true }) as Record<string, unknown>, { projectRoom });
+
+    const parsed = parseTrustedRunContext(context);
+
+    expect(parsed).toEqual({ projectRoom: validProjectRoom() });
+    expect(inheritedReads).toBe(0);
+  });
+
+  it("rejects symbol and non-enumerable extra keys", () => {
+    const stringExtra = { projectRoom: validProjectRoom(), extra: true };
+    const symbolExtra = { projectRoom: validProjectRoom(), [Symbol("extra")]: true };
+    const hiddenExtra = { projectRoom: validProjectRoom() };
+    Object.defineProperty(hiddenExtra, "extra", { value: true, enumerable: false });
+
+    expect(() => parseTrustedRunContext(stringExtra)).toThrow("Invalid trusted agent run context");
+    expect(() => parseTrustedRunContext(symbolExtra)).toThrow("Invalid trusted agent run context");
+    expect(() => parseTrustedRunContext(hiddenExtra)).toThrow("Invalid trusted agent run context");
+  });
+
+  it("rejects a top-level projectRoom getter without invoking it", () => {
+    let calls = 0;
+    const context = Object.defineProperty({}, "projectRoom", {
+      enumerable: true,
+      get: () => {
+        calls += 1;
+        return validProjectRoom();
+      },
+    });
+
+    expect(() => parseTrustedRunContext(context)).toThrow("Invalid trusted agent run context");
+    expect(calls).toBe(0);
+  });
+
+  it.each(["tenantId", "responsibility"])(
+    "rejects a nested %s getter without invoking it",
+    (field) => {
+      let calls = 0;
+      const projectRoom = validProjectRoom();
+      Object.defineProperty(projectRoom, field, {
+        enumerable: true,
+        get: () => {
+          calls += 1;
+          return field === "responsibility" ? "Lead" : "tenant";
+        },
+      });
+
+      expect(() => parseTrustedRunContext({ projectRoom })).toThrow("Invalid trusted agent run context");
+      expect(calls).toBe(0);
+    },
+  );
+
+  it("returns a canonical clone of an exact project task branch", () => {
+    const projectTask = Object.assign(Object.create(null) as Record<string, unknown>, validProjectTask());
+    const context = Object.assign(Object.create(null) as Record<string, unknown>, { projectTask });
+
+    const parsed = parseTrustedRunContext(context);
+
+    expect(parsed).toEqual({ projectTask: validProjectTask() });
+    expect(parsed.projectTask).not.toBe(projectTask);
+    expect(Object.getPrototypeOf(parsed)).toBe(Object.prototype);
+    expect(Object.getPrototypeOf(parsed.projectTask)).toBe(Object.prototype);
+  });
+
+  it("accepts an exact cross-realm project task branch", () => {
+    const context = vm.runInNewContext(`({ projectTask: ${JSON.stringify(validProjectTask())} })`) as unknown;
+
+    const parsed = parseTrustedRunContext(context);
+
+    expect(parsed).toEqual({ projectTask: validProjectTask() });
+    expect(Object.getPrototypeOf(parsed)).toBe(Object.prototype);
+    expect(Object.getPrototypeOf(parsed.projectTask)).toBe(Object.prototype);
+  });
+
+  it("accepts custom prototypes and ignores inherited project task values", () => {
+    let inheritedReads = 0;
+    const inherited = Object.defineProperty({}, "extra", {
+      enumerable: true,
+      get: () => {
+        inheritedReads += 1;
+        return "malicious";
+      },
+    });
+    const projectTask = Object.assign(Object.create(inherited) as Record<string, unknown>, validProjectTask());
+    const context = Object.assign(Object.create({ extra: true }) as Record<string, unknown>, { projectTask });
+
+    expect(parseTrustedRunContext(context)).toEqual({ projectTask: validProjectTask() });
+    expect(inheritedReads).toBe(0);
+  });
+
+  it("requires exactly one trusted context branch", () => {
+    expect(() => parseTrustedRunContext({})).toThrow("Invalid trusted agent run context");
+    expect(() => parseTrustedRunContext({ projectRoom: validProjectRoom(), projectTask: validProjectTask() }))
+      .toThrow("Invalid trusted agent run context");
+    expect(() => parseTrustedRunContext({ projectTask: undefined }))
+      .toThrow("Invalid trusted agent run context");
+  });
+
+  it.each(Object.keys(validProjectTask()))("rejects an empty project task %s", (field) => {
+    expect(() => parseTrustedRunContext({
+      projectTask: { ...validProjectTask(), [field]: "" },
+    })).toThrow("Invalid trusted agent run context");
+  });
+
+  it.each(Object.keys(validProjectTask()))("rejects a missing project task %s", (field) => {
+    const projectTask = validProjectTask();
+    delete projectTask[field];
+
+    expect(() => parseTrustedRunContext({ projectTask })).toThrow("Invalid trusted agent run context");
+  });
+
+  it("rejects project task string, symbol, and non-enumerable extra keys", () => {
+    const stringExtra = { ...validProjectTask(), extra: true };
+    const symbolExtra = { ...validProjectTask(), [Symbol("extra")]: true };
+    const hiddenExtra = validProjectTask();
+    Object.defineProperty(hiddenExtra, "extra", { value: true, enumerable: false });
+
+    expect(() => parseTrustedRunContext({ projectTask: stringExtra })).toThrow("Invalid trusted agent run context");
+    expect(() => parseTrustedRunContext({ projectTask: symbolExtra })).toThrow("Invalid trusted agent run context");
+    expect(() => parseTrustedRunContext({ projectTask: hiddenExtra })).toThrow("Invalid trusted agent run context");
+  });
+
+  it("rejects projectTask root symbol and non-enumerable extra keys", () => {
+    const symbolExtra = { projectTask: validProjectTask(), [Symbol("extra")]: true };
+    const hiddenExtra = { projectTask: validProjectTask() };
+    Object.defineProperty(hiddenExtra, "extra", { value: true, enumerable: false });
+
+    expect(() => parseTrustedRunContext(symbolExtra)).toThrow("Invalid trusted agent run context");
+    expect(() => parseTrustedRunContext(hiddenExtra)).toThrow("Invalid trusted agent run context");
+  });
+
+  it("rejects a top-level projectTask getter without invoking it", () => {
+    let calls = 0;
+    const context = Object.defineProperty({}, "projectTask", {
+      enumerable: true,
+      get: () => {
+        calls += 1;
+        return validProjectTask();
+      },
+    });
+
+    expect(() => parseTrustedRunContext(context)).toThrow("Invalid trusted agent run context");
+    expect(calls).toBe(0);
+  });
+
+  it.each(Object.keys(validProjectTask()))(
+    "rejects a nested project task %s getter without invoking it",
+    (field) => {
+      let calls = 0;
+      const projectTask = validProjectTask();
+      Object.defineProperty(projectTask, field, {
+        enumerable: true,
+        get: () => {
+          calls += 1;
+          return "malicious";
+        },
+      });
+
+      expect(() => parseTrustedRunContext({ projectTask })).toThrow("Invalid trusted agent run context");
+      expect(calls).toBe(0);
+    },
+  );
+
+  it("rejects inherited required project task fields without invoking getters", () => {
+    let calls = 0;
+    const inherited = Object.defineProperty({}, "tenantId", {
+      enumerable: true,
+      get: () => {
+        calls += 1;
+        return "tenant-1";
+      },
+    });
+    const projectTask = validProjectTask();
+    delete projectTask.tenantId;
+    Object.setPrototypeOf(projectTask, inherited);
+
+    expect(() => parseTrustedRunContext({ projectTask })).toThrow("Invalid trusted agent run context");
+    expect(calls).toBe(0);
+  });
+
+  it("rejects task accessors without reading polluted descriptor prototypes", () => {
+    const originalValue = Object.getOwnPropertyDescriptor(Object.prototype, "value");
+    const originalEnumerable = Object.getOwnPropertyDescriptor(Object.prototype, "enumerable");
+    let inheritedReads = 0;
+    const projectTask = validProjectTask();
+    Object.defineProperty(projectTask, "tenantId", {
+      enumerable: true,
+      get: () => "tenant-1",
+    });
+    try {
+      Object.defineProperty(Object.prototype, "value", {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return "tenant-1";
+        },
+      });
+      Object.defineProperty(Object.prototype, "enumerable", Object.assign(Object.create(null), {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return true;
+        },
+      }));
+
+      expect(() => parseTrustedRunContext({ projectTask })).toThrow("Invalid trusted agent run context");
+      expect(inheritedReads).toBe(0);
+    } finally {
+      if (originalValue) Object.defineProperty(Object.prototype, "value", originalValue);
+      else delete (Object.prototype as { value?: unknown }).value;
+      if (originalEnumerable) Object.defineProperty(Object.prototype, "enumerable", originalEnumerable);
+      else delete (Object.prototype as { enumerable?: unknown }).enumerable;
+    }
+  });
+});

package/src/__tests__/capability-bundle-types.test.ts

@@ -0,0 +1,177 @@
+import type {
+  AgentMiddlewareConfig,
+  CapabilityBundle,
+  CapabilityBundleStore,
+  CapabilityFieldSource,
+  CapabilityOverride,
+  CapabilityPreview,
+  CapabilityPreviewIssue,
+  CapabilityRuntime,
+  CreateCapabilityBundleInput,
+  PluginMetaOutput,
+  Plugin,
+  PluginStandardConnectionConfig,
+  ProjectCapabilityConfig,
+  ProjectStore,
+  UpdateCapabilityBundleInput,
+} from "../index";
+
+const standardConnectionConfig: PluginStandardConnectionConfig = {
+  connections: ["crm-prod"],
+  connectAll: false,
+};
+
+const standardConnectionPlugin: Plugin = {
+  meta: {
+    type: "crm",
+    name: "CRM",
+    description: "CRM plugin",
+    capabilityBundleEligible: true,
+    configSchema: {
+      connections: { type: "array", items: { type: "string" } },
+      connectAll: { type: "boolean" },
+    },
+    defaultConfig: standardConnectionConfig,
+  },
+  connection: {
+    fields: [{ key: "apiKey", type: "password", title: "API key" }],
+  },
+};
+
+const middleware: AgentMiddlewareConfig = {
+  id: "filesystem",
+  type: "filesystem",
+  name: "Filesystem",
+  description: "Read project files",
+  enabled: true,
+  config: {},
+};
+
+const createInput: CreateCapabilityBundleInput = {
+  name: "Research",
+  description: "Research capabilities",
+  capabilities: [middleware],
+};
+
+const updateInput: UpdateCapabilityBundleInput = {
+  name: "Updated research",
+  expectedUpdatedAt: "2026-08-27T00:00:00.000Z",
+};
+
+const bundle: CapabilityBundle = {
+  id: "bundle-1",
+  tenantId: "tenant-1",
+  key: "research",
+  ...createInput,
+  createdAt: "2026-08-27T00:00:00.000Z",
+  updatedAt: "2026-08-27T00:00:00.000Z",
+};
+
+const source: CapabilityFieldSource = {
+  capabilityType: "filesystem",
+  fieldPath: "config.root",
+  sourceBundleId: bundle.id,
+  value: "/workspace",
+};
+
+const override: CapabilityOverride = {
+  capabilityType: "filesystem",
+  fieldPath: "config.root",
+  previousValue: "/project",
+  nextValue: "/workspace",
+  sourceBundleId: bundle.id,
+};
+
+const warning: CapabilityPreviewIssue = {
+  code: "DUPLICATE_FIELD",
+  message: "A later bundle overrides this field",
+  bundleId: bundle.id,
+  capabilityType: "filesystem",
+  fieldPath: "config.root",
+};
+
+const preview: CapabilityPreview = {
+  bundleIds: [bundle.id],
+  capabilities: [middleware],
+  overrides: [override],
+  sources: [source],
+  warnings: [warning],
+  errors: [],
+  revision: "revision-1",
+};
+
+const runtime: CapabilityRuntime = {
+  revision: preview.revision,
+  middleware: { [middleware.id]: middleware },
+};
+
+const projectConfig: ProjectCapabilityConfig = {
+  capabilityBundleIds: bundle.id ? [bundle.id] : [],
+};
+
+const pluginMeta: PluginMetaOutput = {
+  type: "research",
+  name: "Research",
+  description: "Research plugin",
+  capabilityBundleEligible: true,
+};
+
+const bundleStore: CapabilityBundleStore = {
+  async listByTenant() {
+    return [bundle];
+  },
+  async getById() {
+    return bundle;
+  },
+  async getManyByIds() {
+    return [bundle];
+  },
+  async create(tenantId, input) {
+    return { ...bundle, tenantId, ...input };
+  },
+  async update() {
+    return bundle;
+  },
+  async deleteIfUnreferenced() {
+    return "deleted";
+  },
+};
+
+const projectStore: ProjectStore = {
+  getProjectsByWorkspace: async () => [],
+  getProjectById: async () => null,
+  createProject: async () => {
+    throw new Error("not used");
+  },
+  updateProject: async () => null,
+  deleteProject: async () => false,
+  isCapabilityBundleReferenced: async () => projectConfig.capabilityBundleIds.includes(bundle.id),
+  updateCapabilityBundleIds: async () => ({ status: "project_not_found" }),
+};
+
+describe("capability bundle protocol types", () => {
+  it("represents bundle storage, runtime, preview provenance, and eligibility", async () => {
+    expect(bundle.capabilities).toEqual([middleware]);
+    expect(runtime.middleware[middleware.id]).toBe(middleware);
+    expect(preview.sources[0]).toEqual(source);
+    expect(preview.overrides[0]).toEqual(override);
+    expect(pluginMeta.capabilityBundleEligible).toBe(true);
+    await expect(projectStore.isCapabilityBundleReferenced("tenant-1", bundle.id)).resolves.toBe(true);
+  });
+
+  it("defines standard connection-backed plugins without duplicate resource fields", () => {
+    expect(standardConnectionPlugin.meta.type).toBe("crm");
+    expect(standardConnectionPlugin.meta.capabilityBundleEligible).toBe(true);
+    expect(standardConnectionPlugin.connection).toBeDefined();
+    expect(standardConnectionPlugin.meta.defaultConfig).toEqual(standardConnectionConfig);
+    expect(standardConnectionPlugin.meta.configSchema).not.toHaveProperty("connectionType");
+    expect(standardConnectionPlugin.meta.configSchema).not.toHaveProperty("resourceType");
+    expect(standardConnectionPlugin.meta.configSchema).not.toHaveProperty("resourceSelector");
+    expect(standardConnectionPlugin.meta.defaultConfig).not.toHaveProperty("connectionType");
+    expect(standardConnectionPlugin.meta.defaultConfig).not.toHaveProperty("resourceType");
+    expect(standardConnectionPlugin.meta.defaultConfig).not.toHaveProperty("resourceSelector");
+  });
+});
+
+void updateInput;
+void bundleStore;

package/src/index.ts

@@ -48,6 +48,15 @@ export * from "./A2AApiKeyStoreProtocol";
 export * from "./ConversationStoreProtocol";
 export * from "./AgentWebAppStoreProtocol";
 export * from "./AgentWebAppRuntimeProtocol";
+export * from "./CapabilityBundleStoreProtocol";
+export * from "./CapabilityRuntimeProtocol";
+export * from "./ProjectRoomProtocol";
+export * from "./ProjectRoomStoreProtocol";
+export * from "./ProjectMembershipStoreProtocol";
+export * from "./ProjectBotMembershipStoreProtocol";
+export * from "./ProjectRoomMessageStoreProtocol";
+export * from "./ExactDataSnapshot";
+export * from "./ProjectRoomRealtimeProtocol";
 
 // Workflow DSL (concise, public API)
 export * from "./WorkflowDSL";
@@ -68,8 +77,12 @@ export type {
   PluginDiscoveredResource,
   PluginContext,
   PluginToolMeta,
+  PluginSkillResource,
+  PluginSkillDefinition,
+  PluginStandardConnectionConfig,
   PluginMiddlewareFactory,
 } from "./PluginProtocol";
 
 // 导出通用类型
 export * from "./types";
+export * from "./TrustedRunContextProtocol";

package/tsconfig.type-tests.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "incremental": false,
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["type-tests/**/*.ts"]
+}

package/type-tests/task-work-item-store-compatibility.ts

@@ -0,0 +1,37 @@
+import type {
+  ProjectTaskWorkItemStore,
+  TaskWorkItem,
+  TaskWorkItemStore,
+} from "../src/TaskWorkItemProtocol";
+import { requireProjectTaskWorkItemStore } from "../src/TaskWorkItemProtocol";
+
+class LegacyTaskWorkItemStore implements TaskWorkItemStore {
+  async create(): Promise<TaskWorkItem> {
+    throw new Error("compile fixture");
+  }
+
+  async list(): Promise<TaskWorkItem[]> {
+    return [];
+  }
+
+  async findByEventKey(): Promise<TaskWorkItem | null> {
+    return null;
+  }
+
+  async createIfAbsentByEventKey(): Promise<TaskWorkItem> {
+    throw new Error("compile fixture");
+  }
+}
+
+const legacyStore: TaskWorkItemStore = new LegacyTaskWorkItemStore();
+const completeStore = Object.assign(new LegacyTaskWorkItemStore(), {
+  createIfTaskSnapshot: async () => null,
+  listProjectLifecycleEvents: async () => [],
+});
+const baseStore: TaskWorkItemStore = completeStore;
+const projectStore: ProjectTaskWorkItemStore = completeStore;
+const refinedStore: ProjectTaskWorkItemStore = requireProjectTaskWorkItemStore(baseStore);
+
+void legacyStore;
+void projectStore;
+void refinedStore;