create-windy 0.8.2 → 0.9.1

package/template/apps/server/src/agent-skills/access.ts

@@ -0,0 +1,88 @@
+import type {
+  AgentSkillRequirement,
+  AgentSkillVersion,
+} from "@southwind-ai/shared";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import { AgentSkillError } from "./contracts.js";
+export function skillActor(context: RequestGuardContext) {
+  const scope = context.actor.scopeContext;
+  if (
+    context.actor.type !== "user" ||
+    !isServerScopeContext(scope) ||
+    scope.actorId !== context.actor.id ||
+    (context.actor.credentialState !== undefined &&
+      context.actor.credentialState !== "active")
+  )
+    throw new AgentSkillError(
+      "SKILL_FORBIDDEN",
+      "当前身份缺少技能治理范围",
+      403,
+    );
+  return {
+    actorId: context.actor.id,
+    tenantId: scope.tenantId,
+    departmentId: scope.departmentId,
+    tenantWide: scope.grants.some(
+      (grant) => grant.scope === "all" || grant.scope === "tenant",
+    ),
+  };
+}
+export function skillReadable(
+  skill: AgentSkillVersion,
+  context: RequestGuardContext,
+) {
+  const actor = skillActor(context);
+  return (
+    skill.tenantId === actor.tenantId &&
+    (skill.ownerActorId === actor.actorId ||
+      skill.scope === "tenant" ||
+      (skill.scope === "department" &&
+        !!actor.departmentId &&
+        skill.departmentId === actor.departmentId))
+  );
+}
+export function skillGovernable(
+  skill: AgentSkillVersion,
+  context: RequestGuardContext,
+) {
+  const actor = skillActor(context);
+  return (
+    skill.tenantId === actor.tenantId &&
+    (skill.ownerActorId === actor.actorId ||
+      (skill.scope !== "personal" && actor.tenantWide))
+  );
+}
+export interface AgentSkillAccess {
+  authorize(
+    context: RequestGuardContext,
+    action: "read" | "manage" | "execute",
+  ): Promise<boolean>;
+  requirement(
+    context: RequestGuardContext,
+    requirement: AgentSkillRequirement,
+  ): Promise<boolean>;
+}
+export async function requireSkillAccess(
+  access: AgentSkillAccess,
+  context: RequestGuardContext,
+  action: "read" | "manage" | "execute",
+) {
+  skillActor(context);
+  if (!(await access.authorize(context, action)))
+    throw new AgentSkillError(
+      "SKILL_FORBIDDEN",
+      "当前身份不能执行此技能操作",
+      403,
+    );
+}
+
+export async function skillRequirementsAvailable(
+  access: AgentSkillAccess,
+  skill: AgentSkillVersion,
+  context: RequestGuardContext,
+) {
+  for (const requirement of skill.requirements)
+    if (!(await access.requirement(context, requirement))) return false;
+  return true;
+}

package/template/apps/server/src/agent-skills/bootstrap.ts

@@ -0,0 +1,49 @@
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { createServerRuntime } from "../runtime.js";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import { AgentSkillService } from "./service.js";
+import { DrizzleAgentSkillRepository } from "./drizzle-repository.js";
+import { InMemoryAgentSkillRepository } from "./repository.js";
+export { registerAgentSkillRoutes } from "./routes.js";
+export function bootstrapAgentSkills(input: {
+  db?: NodePgDatabase;
+  runtime: ReturnType<typeof createServerRuntime>;
+  modules: readonly ModuleManifest[];
+  tools?: GovernedToolRegistry | (() => GovernedToolRegistry | undefined);
+}) {
+  const feature = input.modules
+    .flatMap((module) => module.features)
+    .find((value) => value.key === "system.agent-skill");
+  return new AgentSkillService(
+    input.db
+      ? new DrizzleAgentSkillRepository(input.db)
+      : new InMemoryAgentSkillRepository(),
+    {
+      async authorize(context, action) {
+        if (!feature) return false;
+        return (
+          await evaluateAccessGuards(input.runtime, context, {
+            feature,
+            permission: { permissionKey: `system.agent-skill.${action}` },
+          })
+        ).decision.allowed;
+      },
+      async requirement(context, requirement) {
+        const tools =
+          typeof input.tools === "function" ? input.tools() : input.tools;
+        const definition = tools?.definition(requirement.toolKey);
+        if (
+          !definition ||
+          definition.featureKey !== requirement.featureKey ||
+          definition.permissionKey !== requirement.permissionKey
+        )
+          return false;
+        return (await tools!.availability(requirement.toolKey, context))
+          .allowed;
+      },
+    },
+    (event) => input.runtime.auditSink.recordCriticalEvent(event),
+  );
+}

package/template/apps/server/src/agent-skills/builtin-registration.ts

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import type {
+  AgentSkillRequirement,
+  AgentSkillVersion,
+  AuditEvent,
+} from "@southwind-ai/shared";
+import type { AgentSkillRepository } from "./contracts.js";
+import { parseSkillBundle, hashSkillValue } from "./bundle.js";
+export interface BuiltinAgentSkill {
+  readonly markdown: string;
+  readonly source: string;
+  readonly requirements?: readonly AgentSkillRequirement[];
+}
+export async function registerBuiltinSkillBundles(
+  skills: readonly BuiltinAgentSkill[],
+  input: {
+    readonly tenantId: string;
+    readonly repository: AgentSkillRepository;
+    readonly audit: (event: AuditEvent) => Promise<void>;
+  },
+) {
+  if (!input.tenantId || input.tenantId.length > 64)
+    throw new Error("Builtin skill tenant is required");
+  const tenantId = input.tenantId;
+  for (const definition of skills) {
+    const bundle = parseSkillBundle({
+      format: "markdown",
+      content: definition.markdown,
+    });
+    const existing = await input.repository.versions(tenantId, bundle.name);
+    if (
+      existing.some((record) => record.auditCommitted) ||
+      (existing.length && existing[0]?.metadata.origin !== "builtin")
+    )
+      continue;
+    const metadata: AgentSkillVersion = {
+      key: bundle.name,
+      version: 1,
+      tenantId,
+      ownerActorId: "windy-platform",
+      scope: "tenant",
+      origin: "builtin",
+      status: "published",
+      name: bundle.displayName,
+      description: bundle.description,
+      digest: bundle.digest,
+      requirements: definition.requirements ?? [],
+      safetyConstraints: [],
+      createdAt: new Date().toISOString(),
+      createdBy: "windy-platform",
+      source: definition.source,
+    };
+    const receipt = await input.repository.mutate(
+      {
+        tenantId,
+        actorId: "windy-platform",
+        idempotencyKey: `builtin:${bundle.name}`,
+        requestDigest: hashSkillValue([bundle.digest, definition]),
+        key: bundle.name,
+        expectedVersion: 0,
+      },
+      async () => ({
+        record: { metadata, bundle, auditCommitted: false },
+        audit: {
+          id: randomUUID(),
+          action: "agent.skill.publish",
+          actor: {
+            id: "windy-platform",
+            type: "service",
+            name: "Windy 技能初始化",
+            roleCodes: [],
+          },
+          outcome: "success",
+          target: { type: "agent-skill", id: bundle.name },
+          occurredAt: metadata.createdAt,
+          metadata: { version: 1, digest: bundle.digest },
+        },
+      }),
+    );
+    await input.audit(receipt.audit);
+    await input.repository.acknowledge(receipt);
+  }
+}

package/template/apps/server/src/agent-skills/builtins.ts

@@ -0,0 +1,19 @@
+import type { BuiltinAgentSkill } from "./service.js";
+export const platformBuiltinAgentSkills: readonly BuiltinAgentSkill[] = [
+  {
+    source: "windy-platform/builtin/windy-tool-query@1",
+    markdown: `---
+name: windy-tool-query
+description: 在当前身份授权范围内发现工具、只读查询并解释来源。
+metadata:
+  displayName: 平台工具查询
+---
+
+先读取当前会话实际可见的工具目录，使用与问题相关的简短关键词发现工具。
+仅调用当前身份已授权的只读查询工具，按真实参数 Schema 提交有界条件与分页。
+不得猜测工具名、身份、权限或内部地址；没有工具或权限时明确说明缺口。
+结果区分原始来源、计算结果与待核实推断，不将总结自动当作正式业务事实。
+用户要求修改时，解释需要的正式业务入口和审批；本技能不授予写入权限。
+`,
+  },
+];

package/template/apps/server/src/agent-skills/bundle-zip.ts

@@ -0,0 +1,163 @@
+import { Unzip, UnzipInflate } from "fflate";
+import { AgentSkillError } from "./contracts.js";
+export const SKILL_LIMITS = {
+  archive: 4 * 1024 * 1024,
+  total: 16 * 1024 * 1024,
+  file: 4 * 1024 * 1024,
+  markdown: 128 * 1024,
+  entries: 128,
+};
+function invalid(message: string, status = 400): never {
+  throw new AgentSkillError("SKILL_PACKAGE_INVALID", message, status);
+}
+export function skillPath(value: string): string {
+  if (
+    !value ||
+    value.length > 240 ||
+    value.includes("\\") ||
+    value.startsWith("/") ||
+    [...value].some(
+      (char) =>
+        char === ":" || char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+    )
+  )
+    invalid("技能包包含非法路径");
+  const parts = value.replace(/\/$/, "").split("/");
+  if (parts.some((part) => !part || part.startsWith(".") || part.length > 100))
+    invalid("技能包不能包含隐藏路径、父目录或空路径");
+  return value;
+}
+function inspectZip(bytes: Uint8Array) {
+  if (bytes.length > SKILL_LIMITS.archive || bytes.length < 22)
+    invalid("ZIP 超过 4 MiB 或格式无效", 413);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let end = bytes.length - 22;
+  while (
+    end >= Math.max(0, bytes.length - 65557) &&
+    view.getUint32(end, true) !== 0x06054b50
+  )
+    end--;
+  if (end < 0 || end < bytes.length - 65557) invalid("ZIP 目录无效");
+  const count = view.getUint16(end + 10, true),
+    start = view.getUint32(end + 16, true);
+  if (
+    view.getUint16(end + 4, true) ||
+    view.getUint16(end + 6, true) ||
+    count !== view.getUint16(end + 8, true) ||
+    !count ||
+    count > SKILL_LIMITS.entries ||
+    start + view.getUint32(end + 12, true) !== end ||
+    end + 22 + view.getUint16(end + 20, true) !== bytes.length
+  )
+    invalid("ZIP 文件数量或分卷格式不支持");
+  let cursor = start,
+    total = 0;
+  const names = new Map<string, { name: string; size: number }>();
+  for (let i = 0; i < count; i++) {
+    if (cursor + 46 > end || view.getUint32(cursor, true) !== 0x02014b50)
+      invalid("ZIP 目录损坏");
+    const size = view.getUint32(cursor + 24, true),
+      length = view.getUint16(cursor + 28, true),
+      extra = view.getUint16(cursor + 30, true),
+      comment = view.getUint16(cursor + 32, true);
+    const mode = (view.getUint32(cursor + 38, true) >>> 16) & 0xf000;
+    if (
+      cursor + 46 + length + extra + comment > end ||
+      view.getUint16(cursor + 8, true) & 1 ||
+      ![0, 8].includes(view.getUint16(cursor + 10, true)) ||
+      ![0, 0x8000, 0x4000].includes(mode)
+    )
+      invalid("ZIP 包含加密、特殊文件或不支持的压缩方式");
+    const name = skillPath(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        bytes.subarray(cursor + 46, cursor + 46 + length),
+      ),
+    );
+    const key = name.replace(/\/$/, "").toLowerCase();
+    if (
+      names.has(key) ||
+      size > SKILL_LIMITS.file ||
+      (total += size) > SKILL_LIMITS.total
+    )
+      invalid("ZIP 路径重复或展开体积过大", 413);
+    names.set(key, { name, size });
+    cursor += 46 + length + extra + comment;
+  }
+  if (cursor !== end) invalid("ZIP 目录不完整");
+  return names;
+}
+export function decodeSkillZip(bytes: Uint8Array): Record<string, Uint8Array> {
+  const advertised = inspectZip(bytes),
+    files: Record<string, Uint8Array> = Object.create(null),
+    seen = new Set<string>();
+  let expanded = 0,
+    failure: Error | undefined;
+  const archive = new Unzip((entry) => {
+    const name = skillPath(entry.name),
+      known = advertised.get(name.replace(/\/$/, "").toLowerCase());
+    if (!known || known.name !== name || seen.has(name))
+      invalid("ZIP 本地目录与中央目录不一致");
+    seen.add(name);
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    entry.ondata = (error, chunk, final) => {
+      if (error) {
+        failure = error;
+        entry.terminate();
+        return;
+      }
+      size += chunk.length;
+      expanded += chunk.length;
+      if (
+        size > known.size ||
+        size > SKILL_LIMITS.file ||
+        expanded > SKILL_LIMITS.total
+      ) {
+        failure = new AgentSkillError(
+          "SKILL_PACKAGE_INVALID",
+          "ZIP 展开体积超限",
+          413,
+        );
+        entry.terminate();
+        return;
+      }
+      chunks.push(chunk);
+      if (final && !name.endsWith("/")) {
+        if (size !== known.size) {
+          failure = new Error("ZIP 文件长度不一致");
+          return;
+        }
+        const output = new Uint8Array(size);
+        let offset = 0;
+        for (const part of chunks) {
+          output.set(part, offset);
+          offset += part.length;
+        }
+        files[name] = output;
+      }
+    };
+    entry.start();
+  });
+  archive.register(UnzipInflate);
+  for (let offset = 0; offset < bytes.length; offset += 1024) {
+    archive.push(
+      bytes.subarray(offset, offset + 1024),
+      offset + 1024 >= bytes.length,
+    );
+    if (failure) throw failure;
+  }
+  if (seen.size !== advertised.size) invalid("ZIP 文件目录不完整");
+  const keys = Object.keys(files),
+    markdown = keys.filter(
+      (name) => name === "SKILL.md" || /^[^/]+\/SKILL\.md$/.test(name),
+    );
+  if (markdown.length !== 1) invalid("ZIP 必须只包含一个技能目录及其 SKILL.md");
+  const prefix = markdown[0]!.slice(0, -8),
+    result: Record<string, Uint8Array> = Object.create(null);
+  for (const key of keys) {
+    if (!key.startsWith(prefix) || key === prefix)
+      invalid("ZIP 含技能目录之外的文件");
+    result[skillPath(key.slice(prefix.length))] = files[key]!;
+  }
+  return result;
+}

package/template/apps/server/src/agent-skills/bundle.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { zipSync, strToU8 } from "fflate";
+import { parseSkillBundle } from "./bundle.js";
+const markdown =
+  "---\nname: safe-query\ndescription: 安全查询\n---\n仅使用已授权工具。\n";
+function archive(files: Record<string, Uint8Array>) {
+  return {
+    format: "zip" as const,
+    content: Buffer.from(zipSync(files)).toString("base64"),
+  };
+}
+describe("shared DSH skill import", () => {
+  test("imports one directory with binary attachments and a stable digest", () => {
+    const imported = parseSkillBundle(
+      archive({
+        "safe-query/SKILL.md": strToU8(markdown),
+        "safe-query/assets/sample.bin": Uint8Array.from([0, 1, 255]),
+      }),
+    );
+    expect(imported.name).toBe("safe-query");
+    expect(imported.files).toHaveLength(2);
+    expect(
+      imported.files.find((file) => file.path === "assets/sample.bin")
+        ?.contentBase64,
+    ).toBe("AAH/");
+    expect(
+      parseSkillBundle(
+        archive({
+          "safe-query/assets/sample.bin": Uint8Array.from([0, 1, 255]),
+          "safe-query/SKILL.md": strToU8(markdown),
+        }),
+      ).digest,
+    ).toBe(imported.digest);
+  });
+  test("rejects traversal, multiple skills and unrelated root files", () => {
+    const invalidBundles: Record<string, Uint8Array>[] = [
+      { "../SKILL.md": strToU8(markdown) },
+      { "a/SKILL.md": strToU8(markdown), "b/SKILL.md": strToU8(markdown) },
+      {
+        "safe-query/SKILL.md": strToU8(markdown),
+        "unrelated.txt": strToU8("x"),
+      },
+    ];
+    for (const files of invalidBundles)
+      expect(() => parseSkillBundle(archive(files))).toThrow();
+  });
+  test("rejects duplicate YAML, malformed flags, invalid UTF-8 and oversized markdown", () => {
+    for (const content of [
+      markdown.replace("description:", "name: duplicate\ndescription:"),
+      markdown.replace("---\n仅", "user-invocable: yes\n---\n仅"),
+      `---\nname: safe-query\ndescription: 安全\n---\n${"x".repeat(128 * 1024)}`,
+    ])
+      expect(() => parseSkillBundle({ format: "markdown", content })).toThrow();
+    expect(() =>
+      parseSkillBundle(archive({ "SKILL.md": Uint8Array.from([255, 255]) })),
+    ).toThrow();
+  });
+  test("rejects Unix symlinks and advertised expanded-size bombs before decompression", () => {
+    const bytes = zipSync({ "SKILL.md": strToU8(markdown) });
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let cursor = 0;
+    while (view.getUint32(cursor, true) !== 0x02014b50) cursor++;
+    view.setUint32(cursor + 38, 0xa1ff << 16, true);
+    expect(() =>
+      parseSkillBundle({
+        format: "zip",
+        content: Buffer.from(bytes).toString("base64"),
+      }),
+    ).toThrow();
+    view.setUint32(cursor + 38, 0x81a4 << 16, true);
+    view.setUint32(cursor + 24, 0x7fffffff, true);
+    expect(() =>
+      parseSkillBundle({
+        format: "zip",
+        content: Buffer.from(bytes).toString("base64"),
+      }),
+    ).toThrow();
+  });
+});

package/template/apps/server/src/agent-skills/bundle.ts

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import { parseDocument } from "yaml";
+import type {
+  AgentSkillBundle,
+  ImportAgentSkillRequest,
+} from "@southwind-ai/shared";
+import { AgentSkillError } from "./contracts.js";
+import { decodeSkillZip, SKILL_LIMITS } from "./bundle-zip.js";
+export function skillKey(value: unknown): string {
+  if (
+    typeof value !== "string" ||
+    value.length > 64 ||
+    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)
+  )
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "技能标识须为小写英文、数字和连字符，最长 64 字符",
+    );
+  return value;
+}
+export function parseSkillBundle(
+  input: Pick<ImportAgentSkillRequest, "format" | "content">,
+): AgentSkillBundle {
+  if (typeof input.content !== "string")
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "请选择 SKILL.md 或 ZIP 文件",
+    );
+  let files: Record<string, Uint8Array>;
+  if (input.format === "markdown")
+    files = { "SKILL.md": new TextEncoder().encode(input.content) };
+  else if (input.format === "zip") {
+    if (
+      input.content.length > Math.ceil(SKILL_LIMITS.archive / 3) * 4 ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        input.content,
+      )
+    )
+      throw new AgentSkillError(
+        "SKILL_PACKAGE_INVALID",
+        "ZIP 编码或体积无效",
+        413,
+      );
+    files = decodeSkillZip(Buffer.from(input.content, "base64"));
+  } else
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "仅支持 SKILL.md 或 ZIP",
+    );
+  const markdown = files["SKILL.md"];
+  if (!markdown || markdown.length > SKILL_LIMITS.markdown)
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "SKILL.md 超过 128 KiB",
+      413,
+    );
+  let raw: string;
+  try {
+    raw = new TextDecoder("utf-8", { fatal: true }).decode(markdown);
+  } catch {
+    throw new AgentSkillError("SKILL_PACKAGE_INVALID", "SKILL.md 必须为 UTF-8");
+  }
+  const metadata = skillDocument(raw);
+  const encoded = Object.keys(files)
+    .sort()
+    .map((path) => ({
+      path,
+      contentBase64: Buffer.from(files[path]!).toString("base64"),
+    }));
+  return { ...metadata, digest: hashSkillValue(encoded), files: encoded };
+}
+export function hashSkillValue(value: unknown): string {
+  return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+function skillDocument(raw: string) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(raw);
+  if (!match || !match[2]!.trim() || raw.includes("\0"))
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "SKILL.md 需要 YAML 头部（name、description）及正文",
+    );
+  const doc = parseDocument(match[1]!, { uniqueKeys: true });
+  if (doc.errors.length)
+    throw new AgentSkillError("SKILL_PACKAGE_INVALID", "技能 YAML 格式无效");
+  let value: unknown;
+  try {
+    value = doc.toJS({ maxAliasCount: 20 }) as unknown;
+  } catch {
+    throw new AgentSkillError("SKILL_PACKAGE_INVALID", "技能 YAML 引用过多");
+  }
+  const meta = record(value),
+    name = skillKey(meta.name),
+    description = meta.description;
+  if (
+    typeof description !== "string" ||
+    !description.trim() ||
+    description.length > 2048
+  )
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "请填写不超过 2048 字符的技能说明",
+    );
+  for (const field of ["user-invocable", "disable-model-invocation"])
+    if (meta[field] !== undefined && typeof meta[field] !== "boolean")
+      throw new AgentSkillError(
+        "SKILL_PACKAGE_INVALID",
+        `${field} 必须为布尔值`,
+      );
+  const displayName = record(meta.metadata).displayName;
+  if (
+    displayName !== undefined &&
+    (typeof displayName !== "string" ||
+      !displayName.trim() ||
+      displayName.length > 60 ||
+      [...displayName].some(
+        (char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+      ))
+  )
+    throw new AgentSkillError(
+      "SKILL_PACKAGE_INVALID",
+      "技能中文名称须为 1–60 字符的单行文字",
+    );
+  return {
+    name,
+    displayName: typeof displayName === "string" ? displayName.trim() : name,
+    description: description.trim(),
+  };
+}
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}

package/template/apps/server/src/agent-skills/contracts.ts

@@ -0,0 +1,46 @@
+import type {
+  AgentSkillBundle,
+  AgentSkillVersion,
+  AuditEvent,
+} from "@southwind-ai/shared";
+
+export class AgentSkillError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status = 400,
+  ) {
+    super(message);
+  }
+}
+export interface StoredAgentSkill {
+  readonly metadata: AgentSkillVersion;
+  readonly bundle: AgentSkillBundle;
+  readonly auditCommitted: boolean;
+}
+export interface SkillMutationIdentity {
+  readonly tenantId: string;
+  readonly actorId: string;
+  readonly idempotencyKey: string;
+  readonly requestDigest: string;
+}
+export interface SkillMutationReceipt extends SkillMutationIdentity {
+  readonly result: AgentSkillVersion;
+  readonly audit: AuditEvent;
+  readonly auditCommitted: boolean;
+}
+export interface AgentSkillRepository {
+  versions(
+    tenantId: string,
+    key?: string,
+  ): Promise<readonly StoredAgentSkill[]>;
+  mutate(
+    input: SkillMutationIdentity & { key: string; expectedVersion: number },
+    change: (
+      current: StoredAgentSkill | undefined,
+      versions: readonly StoredAgentSkill[],
+    ) => Promise<{ record: StoredAgentSkill; audit: AuditEvent }>,
+  ): Promise<SkillMutationReceipt>;
+  pendingAudits(): Promise<readonly SkillMutationReceipt[]>;
+  acknowledge(receipt: SkillMutationReceipt): Promise<void>;
+}