@axiom-lattice/protocols 4.0.1 → 4.1.1

package/src/PluginProtocol.ts

@@ -65,19 +65,63 @@ export interface PluginConnection {
 
 /**
  * 工具元信息（用于前端 allowedTools 筛选）
+ *
+ * New connection-backed plugin tools that select one connection must accept
+ * the selected key as `args.connectionKey`. Existing legacy tools retain their
+ * established resource argument names.
  */
 export interface PluginToolMeta {
   name: string;
   description: string;
 }
 
+/**
+ * A text file included in a plugin skill bundle.
+ *
+ * @property content - Text content written to the skill resource file.
+ * @property mimeType - Optional MIME type for consumers that need it.
+ */
+export interface PluginSkillResource {
+  content: string;
+  mimeType?: string;
+}
+
+/**
+ * Versioned definition of a plugin-provided skill.
+ *
+ * @property version - Bundle version used to detect resource updates.
+ * @property content - Complete SKILL.md markdown content.
+ * @property resources - Optional text resources keyed by safe relative paths.
+ */
+export interface PluginSkillDefinition {
+  version: string;
+  content: string;
+  resources?: Record<string, PluginSkillResource>;
+}
+
+/**
+ * Standard configuration for a new connection-backed plugin.
+ *
+ * `PluginMeta.type` is also the Connection Store type. `connections` selects
+ * connection keys of that type; `connectAll` opts into using all available
+ * connections of that type. Do not add a separate connection or resource type
+ * or selector field to this configuration.
+ */
+export type PluginStandardConnectionConfig = {
+  connections: string[];
+  connectAll?: boolean;
+};
+
 /**
  * 插件元数据（开发者声明）
  *
  * connectionSchema 不在此类型中——由 serializePluginMeta 自动推导后注入 PluginMetaOutput。
  */
 export interface PluginMeta {
-  /** 插件唯一标识，如 "erp" */
+  /**
+   * 插件唯一标识，如 "erp"; for connection-backed plugins this is also the
+   * Connection Store type.
+   */
   type: string;
   /** 显示名称 */
   name: string;
@@ -91,9 +135,13 @@ export interface PluginMeta {
   icon?: string;
   /** 工具清单（可选，middleware 能自动提取时不需要写） */
   tools?: PluginToolMeta[];
-  /** 中间件配置 schema（用于 agent 配置面板） */
+  /**
+   * 中间件配置 schema（用于 agent 配置面板）。新的 connection-backed
+   * plugins use `connections: string[]` and optional `connectAll?: boolean`.
+   * Do not introduce connectionType, resourceType, or resourceSelector fields.
+   */
   configSchema?: Record<string, unknown>;
-  /** 默认配置 */
+  /** 默认配置；connection-backed plugins use PluginStandardConnectionConfig. */
   defaultConfig?: Record<string, unknown>;
   /** 推荐配置的 companion 插件 */
   recommends?: string[];
@@ -103,6 +151,8 @@ export interface PluginMeta {
    * 第三方插件可自定义分类名，前端会原样显示；未提供时归入 "Other"。
    */
   category?: string;
+  /** Whether this plugin's middleware may be included in capability bundles. */
+  capabilityBundleEligible?: boolean;
 }
 
 /**
@@ -133,7 +183,7 @@ export interface PluginMetaOutput extends PluginMeta {
  * const myPlugin: Plugin = {
  *   meta: { ... },
  *   middleware: (config, context) => {
- *     const skills = context?.pluginSkillContents ?? {};
+ *     const skills = context?.pluginSkills ?? {};
  *     return createMyMiddleware({ ...config, pluginSkills: skills });
  *   },
  * };
@@ -141,12 +191,14 @@ export interface PluginMetaOutput extends PluginMeta {
  */
 export interface PluginContext {
   /**
-   * Cross-plugin aggregated skill contents (SKILL.md, keyed by skill name).
+   * Cross-plugin aggregated skill bundles, keyed by skill name.
    * Collected from all enabled plugins before the main middleware loop.
    * Most plugins should ignore this; only cross-plugin coordination
    * middleware (e.g. skillMiddleware) consumes it.
    */
-  pluginSkillContents?: Record<string, string>;
+  pluginSkills?: Record<string, PluginSkillDefinition>;
+  /** Owning plugin type for each enabled plugin skill bundle. */
+  pluginSkillOwners?: Record<string, string>;
 }
 
 /**
@@ -197,7 +249,7 @@ export interface Plugin {
    * 名称必须以 "{pluginType}-" 为前缀，注册时校验。
    * Builder 在构建中间件之前从所有启用的插件中收集。
    */
-  skills?: Record<string, string>;
+  skills?: Record<string, PluginSkillDefinition>;
   /**
    * 插件贡献的 Agent 定义（以 agent key 为键）。
    * 在租户首次访问时通过 ensurePluginAgentsForTenant 按租户注册到

package/src/SkillStoreProtocol.ts

@@ -59,6 +59,36 @@ export interface Skill {
    */
   subSkills?: string[];
 
+  /**
+   * Source of the skill (optional)
+   * e.g. "builtin-plugin" for read-only plugin-provided skills
+   */
+  source?: string;
+
+  /**
+   * Owning plugin type (optional)
+   * Set for skills contributed by a registered plugin
+   */
+  pluginType?: string;
+
+  /**
+   * Plugin skill bundle version (optional)
+   * Set for skills contributed by a registered plugin
+   */
+  version?: string;
+
+  /**
+   * Resource catalog (optional)
+   * Safe relative paths of a plugin skill's bundled resources with their MIME types
+   */
+  resourcePaths?: Array<{ path: string; mimeType?: string }>;
+
+  /**
+   * Read-only flag (optional)
+   * True for immutable sources (e.g. plugin-provided skills) that cannot be created/updated/deleted
+   */
+  readOnly?: boolean;
+
   /**
    * Skill creation timestamp
    */

package/src/TaskBeliefProtocol.ts

@@ -1,4 +1,9 @@
-/** A single canonical belief recorded in a task description. */
+/**
+ * A single canonical belief recorded in a task description.
+ *
+ * `probability` is retained as the persisted field name, but task guidance uses
+ * it as an evidence-support percentage rather than a calibrated probability.
+ */
 export interface TaskBeliefEntry {
   key: string;
   probability: number;

package/src/TaskWorkItemProtocol.ts

@@ -56,10 +56,62 @@ export interface TaskWorkItemListFilter {
   offset?: number;
 }
 
+/** Canonical prefix for public task execution-result event identities. */
+export const EXECUTION_RESULT_EVENT_KEY_PREFIX = "execution-result:";
+
+/**
+ * Portable regular-expression source for canonical execution-result event keys.
+ *
+ * The entire key is the literal `execution-result:` prefix followed by a nonempty
+ * suffix containing only ASCII letters, digits, period, underscore, colon, or hyphen.
+ * Colon is intentionally allowed so callers can compose structured suffixes.
+ */
+export const EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE =
+  "^execution-result:[A-Za-z0-9._:-]+$";
+
+/** Compiled runtime expression for canonical execution-result event keys. */
+export const EXECUTION_RESULT_EVENT_KEY_PATTERN =
+  new RegExp(EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE);
+
+/** Maximum pending execution-result rows accepted by one store query. */
+export const MAX_PENDING_EXECUTION_RESULTS_LIMIT = 1_000;
+
+/**
+ * Determines whether a runtime value is a canonical execution-result event key.
+ *
+ * @param value Runtime value to validate.
+ * @returns True only for the portable canonical ASCII grammar.
+ */
+export function isExecutionResultEventKey(value: unknown): value is string {
+  return typeof value === "string" && EXECUTION_RESULT_EVENT_KEY_PATTERN.test(value);
+}
+
 export interface TaskWorkItemStore {
   create(params: CreateWorkItemRequest): Promise<TaskWorkItem>;
   list(filter: TaskWorkItemListFilter): Promise<TaskWorkItem[]>;
 
+  /**
+   * List the newest bounded set of execution results awaiting reconciliation.
+   *
+   * Only `execution_result` items with a canonical ASCII
+   * `execution-result:[A-Za-z0-9._:-]+` event key are returned. An item is excluded when
+   * a task-scoped `execution_reconciled` item has a
+   * `detail.executionResultId` equal to that event key. Results are ordered by
+   * `createdAt` descending and then `id` descending for deterministic ties.
+   *
+   * @param params Tenant/task scope and required maximum number of rows.
+   * @returns At most `limit` pending execution-result work items, newest first.
+   * @throws RangeError with code `INVALID_LIMIT` unless limit is a safe integer from zero through
+   * {@link MAX_PENDING_EXECUTION_RESULTS_LIMIT}.
+   * @remarks Optional optimization. Stores that omit it remain compatible; callers may use a
+   * bounded, non-authoritative fallback through the pre-existing list and event-key methods.
+   */
+  listPendingExecutionResults?(params: {
+    tenantId: string;
+    taskId: string;
+    limit: number;
+  }): Promise<TaskWorkItem[]>;
+
   /**
    * Find an event by deterministic identity without list pagination.
    *

package/src/WorkspaceStoreProtocol.ts

@@ -102,6 +102,25 @@ export interface UpdateProjectRequest {
   kind?: ProjectKind;
 }
 
+/** Error raised when generic project writes attempt to change capability Bundle references. */
+export class InvalidProjectCapabilityBundleConfigError extends Error {
+  /** Stable machine-readable error code. */
+  readonly code = "INVALID_BUNDLE_CONFIG" as const;
+
+  /** Creates the reserved-config error returned by generic Project writes. */
+  constructor() {
+    super("Use the project capability-bundles endpoint to update capability bundle IDs");
+    this.name = "InvalidProjectCapabilityBundleConfigError";
+  }
+}
+
+/** Rejects capability Bundle references supplied through generic Project config writes. */
+export function assertGenericProjectConfig(config: Record<string, unknown> | undefined): void {
+  if (config !== undefined && Object.prototype.hasOwnProperty.call(config, "capabilityBundleIds")) {
+    throw new InvalidProjectCapabilityBundleConfigError();
+  }
+}
+
 /**
  * Filter options for listing projects within a workspace
  */
@@ -109,6 +128,16 @@ export interface ProjectFilter {
   kind?: ProjectKind;
 }
 
+/** Atomic result of replacing a Project's capability Bundle IDs. */
+export type UpdateProjectCapabilityBundlesResult =
+  | { status: "updated"; project: Project }
+  | { status: "project_not_found" }
+  | { status: "bundle_not_found" }
+  | { status: "bundle_conflict" };
+
+/** Revision preconditions for the bundles reviewed before project assignment. */
+export type ExpectedCapabilityBundleRevisions = Record<string, string>;
+
 /**
  * ProjectStore interface
  * Provides CRUD operations for project data
@@ -118,5 +147,9 @@ export interface ProjectStore {
   getProjectById(tenantId: string, id: string): Promise<Project | null>;
   createProject(tenantId: string, workspaceId: string, id: string, data: CreateProjectRequest): Promise<Project>;
   updateProject(tenantId: string, id: string, updates: UpdateProjectRequest): Promise<Project | null>;
+  /** Omitted expectedRevisions is reserved for internal maintenance callers. */
+  updateCapabilityBundleIds(tenantId: string, projectId: string, bundleIds: string[], expectedRevisions?: ExpectedCapabilityBundleRevisions): Promise<UpdateProjectCapabilityBundlesResult>;
   deleteProject(tenantId: string, id: string): Promise<boolean>;
+  /** Returns whether a tenant project references the given capability bundle. */
+  isCapabilityBundleReferenced(tenantId: string, bundleId: string): Promise<boolean>;
 }

package/src/__tests__/TaskWorkItemProtocol.test.ts

@@ -0,0 +1,69 @@
+import {
+  EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE,
+  isExecutionResultEventKey,
+} from "../TaskWorkItemProtocol";
+import { readFileSync } from "node:fs";
+import type {
+  TaskWorkItem,
+  TaskWorkItemStore,
+} from "../TaskWorkItemProtocol";
+
+class LegacyTaskWorkItemStore implements TaskWorkItemStore {
+  async create(): Promise<TaskWorkItem> {
+    throw new Error("fixture only");
+  }
+
+  async list(): Promise<TaskWorkItem[]> {
+    return [];
+  }
+
+  async findByEventKey(): Promise<TaskWorkItem | null> {
+    return null;
+  }
+
+  async createIfAbsentByEventKey(): Promise<TaskWorkItem> {
+    throw new Error("fixture only");
+  }
+}
+
+const legacyStore: TaskWorkItemStore = new LegacyTaskWorkItemStore();
+
+describe("execution result event keys", () => {
+  it("runs the legacy-store compatibility fixture during normal package tests", () => {
+    const packageJson = JSON.parse(readFileSync("package.json", "utf8")) as {
+      scripts?: Record<string, string>;
+    };
+
+    expect(packageJson.scripts?.["typecheck:compat"]).toBe(
+      "tsc -p tsconfig.type-tests.json",
+    );
+    expect(packageJson.scripts?.test).toBe("jest && pnpm typecheck:compat");
+  });
+
+  it("keeps stores without the optimized pending query protocol-compatible", () => {
+    expect(legacyStore).toBeInstanceOf(LegacyTaskWorkItemStore);
+  });
+
+  it.each([
+    "execution-result:550e8400-e29b-41d4-a716-446655440000",
+    "execution-result:thread.segment_1:attempt-2",
+  ])("accepts canonical ASCII key %s", (value) => {
+    expect(isExecutionResultEventKey(value)).toBe(true);
+    expect(new RegExp(EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE).test(value)).toBe(true);
+  });
+
+  it.each([
+    undefined,
+    1,
+    "execution-result:",
+    "wrong-prefix:value",
+    "execution-result:internal space",
+    "execution-result:non-breaking\u00a0space",
+    "execution-result:next-line\u0085",
+    "execution-result:em-space\u2003",
+    "execution-result:invalid/punctuation",
+    "execution-result:query?value",
+  ])("rejects non-canonical key %p", (value) => {
+    expect(isExecutionResultEventKey(value)).toBe(false);
+  });
+});

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,8 @@ export * from "./A2AApiKeyStoreProtocol";
 export * from "./ConversationStoreProtocol";
 export * from "./AgentWebAppStoreProtocol";
 export * from "./AgentWebAppRuntimeProtocol";
+export * from "./CapabilityBundleStoreProtocol";
+export * from "./CapabilityRuntimeProtocol";
 
 // Workflow DSL (concise, public API)
 export * from "./WorkflowDSL";
@@ -68,6 +70,9 @@ export type {
   PluginDiscoveredResource,
   PluginContext,
   PluginToolMeta,
+  PluginSkillResource,
+  PluginSkillDefinition,
+  PluginStandardConnectionConfig,
   PluginMiddlewareFactory,
 } from "./PluginProtocol";
 

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,25 @@
+import type {
+  TaskWorkItem,
+  TaskWorkItemStore,
+} 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 store: TaskWorkItemStore = new LegacyTaskWorkItemStore();
+void store;