create-windy 0.2.8 → 0.2.10

package/template/packages/agent-contracts/src/events.ts

@@ -0,0 +1,161 @@
+import { parseAgentError, type AgentError } from "./errors.js";
+import { parseAgentUsage, type AgentUsage } from "./usage.js";
+import {
+  AgentContractParseError,
+  positiveIntegerAt,
+  recordAt,
+  stringAt,
+} from "./validation.js";
+
+export interface AgentEventBase {
+  runId: string;
+  sequence: number;
+}
+
+export interface AgentRunStartedEvent extends AgentEventBase {
+  type: "run.started";
+}
+
+export interface AgentOutputDeltaEvent extends AgentEventBase {
+  type: "output.delta";
+  text: string;
+}
+
+export interface AgentToolRequestedEvent extends AgentEventBase {
+  type: "tool.requested";
+  toolCallId: string;
+  toolKey: string;
+}
+
+export interface AgentApprovalRequiredEvent extends AgentEventBase {
+  type: "approval.required";
+  workItemId: string;
+}
+
+export interface AgentToolCompletedEvent extends AgentEventBase {
+  type: "tool.completed";
+  toolCallId: string;
+}
+
+export interface AgentUsageReportedEvent extends AgentEventBase {
+  type: "usage.reported";
+  usage: AgentUsage;
+}
+
+export interface AgentRunCompletedEvent extends AgentEventBase {
+  type: "run.completed";
+}
+
+export interface AgentRunFailedEvent extends AgentEventBase {
+  type: "run.failed";
+  error: AgentError;
+}
+
+export interface AgentRunCancelledEvent extends AgentEventBase {
+  type: "run.cancelled";
+}
+
+export type AgentEvent =
+  | AgentRunStartedEvent
+  | AgentOutputDeltaEvent
+  | AgentToolRequestedEvent
+  | AgentApprovalRequiredEvent
+  | AgentToolCompletedEvent
+  | AgentUsageReportedEvent
+  | AgentRunCompletedEvent
+  | AgentRunFailedEvent
+  | AgentRunCancelledEvent;
+
+export type AgentEventType = AgentEvent["type"];
+export type TerminalAgentEvent =
+  | AgentRunCompletedEvent
+  | AgentRunFailedEvent
+  | AgentRunCancelledEvent;
+
+const eventTypes: ReadonlySet<string> = new Set<AgentEventType>([
+  "run.started",
+  "output.delta",
+  "tool.requested",
+  "approval.required",
+  "tool.completed",
+  "usage.reported",
+  "run.completed",
+  "run.failed",
+  "run.cancelled",
+]);
+
+export function parseAgentEvent(input: unknown): AgentEvent {
+  const record = recordAt(input, "event");
+  const type = stringAt(record, "type", "event");
+  if (!eventTypes.has(type)) {
+    throw new AgentContractParseError("event.type", "事件类型无效");
+  }
+  const eventType = type as AgentEventType;
+  const base = {
+    runId: stringAt(record, "runId", "event"),
+    sequence: positiveIntegerAt(record, "sequence", "event"),
+  };
+
+  switch (eventType) {
+    case "run.started":
+    case "run.completed":
+    case "run.cancelled":
+      return { type: eventType, ...base };
+    case "output.delta":
+      return {
+        type: eventType,
+        ...base,
+        text: stringAt(record, "text", "event"),
+      };
+    case "tool.requested":
+      return {
+        type: eventType,
+        ...base,
+        toolCallId: stringAt(record, "toolCallId", "event"),
+        toolKey: stringAt(record, "toolKey", "event"),
+      };
+    case "approval.required":
+      return {
+        type: eventType,
+        ...base,
+        workItemId: stringAt(record, "workItemId", "event"),
+      };
+    case "tool.completed":
+      return {
+        type: eventType,
+        ...base,
+        toolCallId: stringAt(record, "toolCallId", "event"),
+      };
+    case "usage.reported":
+      return {
+        type: eventType,
+        ...base,
+        usage: parseAgentUsage(record.usage),
+      };
+    case "run.failed":
+      return {
+        type: eventType,
+        ...base,
+        error: parseAgentError(record.error),
+      };
+  }
+}
+
+export function isAgentEvent(input: unknown): input is AgentEvent {
+  try {
+    parseAgentEvent(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isTerminalAgentEvent(
+  event: AgentEvent,
+): event is TerminalAgentEvent {
+  return (
+    event.type === "run.completed" ||
+    event.type === "run.failed" ||
+    event.type === "run.cancelled"
+  );
+}

package/template/packages/agent-contracts/src/operation.ts

@@ -0,0 +1,28 @@
+declare const operationTypes: unique symbol;
+
+/**
+ * 业务侧稳定的 Agent Operation 引用。
+ *
+ * 输入类型只在编译期存在；远端输出必须通过运行时 parser 收窄。
+ */
+export interface AgentOperation<Input, Output> {
+  readonly key: string;
+  readonly parseOutput: (value: unknown) => Output;
+  readonly [operationTypes]?: {
+    readonly input: Input;
+  };
+}
+
+export type AgentOperationInput<T> =
+  T extends AgentOperation<infer Input, unknown> ? Input : never;
+
+export type AgentOperationOutput<T> =
+  T extends AgentOperation<unknown, infer Output> ? Output : never;
+
+export function defineAgentOperation<Input, Output>(
+  key: string,
+  parseOutput: (value: unknown) => Output,
+): AgentOperation<Input, Output> {
+  if (!key.trim()) throw new TypeError("Agent Operation key 不能为空");
+  return Object.freeze({ key, parseOutput });
+}

package/template/packages/agent-contracts/src/runs.ts

@@ -0,0 +1,58 @@
+import { AgentContractParseError, recordAt, stringAt } from "./validation.js";
+
+export type AgentRunStatus =
+  | "accepted"
+  | "running"
+  | "awaiting-approval"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export interface StartAgentRunRequest<Input> {
+  operationKey: string;
+  input: Input;
+}
+
+export interface StartAgentRunResponse {
+  runId: string;
+  status: AgentRunStatus;
+  eventsUrl: string;
+}
+
+const terminalStatuses: ReadonlySet<AgentRunStatus> = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+]);
+const runStatuses: ReadonlySet<string> = new Set<AgentRunStatus>([
+  "accepted",
+  "running",
+  "awaiting-approval",
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+export function parseStartAgentRunResponse(
+  input: unknown,
+): StartAgentRunResponse {
+  const record = recordAt(input, "startAgentRunResponse");
+  const status = stringAt(record, "status", "startAgentRunResponse");
+  if (!runStatuses.has(status)) {
+    throw new AgentContractParseError(
+      "startAgentRunResponse.status",
+      "Run 状态无效",
+    );
+  }
+  return {
+    runId: stringAt(record, "runId", "startAgentRunResponse"),
+    status: status as AgentRunStatus,
+    eventsUrl: stringAt(record, "eventsUrl", "startAgentRunResponse"),
+  };
+}
+
+export function isTerminalAgentRunStatus(
+  status: AgentRunStatus,
+): status is Extract<AgentRunStatus, "completed" | "failed" | "cancelled"> {
+  return terminalStatuses.has(status);
+}

package/template/packages/agent-contracts/src/sse.ts

@@ -0,0 +1,95 @@
+import { parseAgentEvent, type AgentEvent } from "./events.js";
+import { AgentContractParseError } from "./validation.js";
+
+export interface DecodedAgentSseEventFrame {
+  kind: "event";
+  id: number;
+  event: AgentEvent;
+}
+
+export interface DecodedAgentSseCommentFrame {
+  kind: "comment";
+  comment: string;
+}
+
+export type DecodedAgentSseFrame =
+  | DecodedAgentSseEventFrame
+  | DecodedAgentSseCommentFrame;
+
+export interface SplitAgentSseFramesResult {
+  frames: string[];
+  remainder: string;
+}
+
+export function splitAgentSseFrames(buffer: string): SplitAgentSseFramesResult {
+  const frames: string[] = [];
+  const separator = /\r?\n\r?\n/g;
+  let start = 0;
+  for (const match of buffer.matchAll(separator)) {
+    const index = match.index;
+    frames.push(buffer.slice(start, index));
+    start = index + match[0].length;
+  }
+  return { frames, remainder: buffer.slice(start) };
+}
+
+export function decodeAgentSseFrame(frame: string): DecodedAgentSseFrame {
+  const lines = frame.replace(/\r\n/g, "\n").split("\n");
+  const fields = new Map<string, string>();
+  const comments: string[] = [];
+
+  for (const line of lines) {
+    if (!line) continue;
+    if (line.startsWith(":")) {
+      comments.push(line.slice(1).trimStart());
+      continue;
+    }
+    const colon = line.indexOf(":");
+    const field = colon < 0 ? line : line.slice(0, colon);
+    const rawValue = colon < 0 ? "" : line.slice(colon + 1);
+    const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
+    if (!["id", "event", "data"].includes(field)) {
+      throw new AgentContractParseError("sse", `不支持字段 ${field}`);
+    }
+    if (fields.has(field)) {
+      throw new AgentContractParseError("sse", `字段 ${field} 重复`);
+    }
+    fields.set(field, value);
+  }
+
+  if (fields.size === 0 && comments.length > 0) {
+    return { kind: "comment", comment: comments.join("\n") };
+  }
+  if (comments.length > 0) {
+    throw new AgentContractParseError("sse", "事件帧不能混入 comment");
+  }
+
+  const idValue = fields.get("id");
+  const eventType = fields.get("event");
+  const data = fields.get("data");
+  if (idValue === undefined || eventType === undefined || data === undefined) {
+    throw new AgentContractParseError(
+      "sse",
+      "事件帧必须包含 id、event 和 data",
+    );
+  }
+  if (!/^[1-9]\d*$/.test(idValue) || !Number.isSafeInteger(Number(idValue))) {
+    throw new AgentContractParseError("sse.id", "必须是正安全整数");
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    throw new AgentContractParseError("sse.data", "必须是单行 JSON");
+  }
+  const event = parseAgentEvent(parsed);
+  const id = Number(idValue);
+  if (event.type !== eventType) {
+    throw new AgentContractParseError("sse.event", "与 data.type 不一致");
+  }
+  if (event.sequence !== id) {
+    throw new AgentContractParseError("sse.id", "与 data.sequence 不一致");
+  }
+  return { kind: "event", id, event };
+}

package/template/packages/agent-contracts/src/usage.ts

@@ -0,0 +1,62 @@
+import {
+  AgentContractParseError,
+  nonNegativeIntegerAt,
+  recordAt,
+} from "./validation.js";
+
+export interface AgentUsageMeasurements {
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedInputTokens?: number;
+  reasoningTokens?: number;
+  totalTokens?: number;
+  firstTokenLatencyMs?: number;
+}
+
+type AtLeastOne<T> = {
+  [Key in keyof T]-?: Required<Pick<T, Key>> & Partial<Omit<T, Key>>;
+}[keyof T];
+
+export type AgentUsage =
+  | ({
+      source: "provider-reported" | "estimated";
+    } & AtLeastOne<AgentUsageMeasurements>)
+  | {
+      source: "unknown";
+    };
+
+const measurementKeys = [
+  "inputTokens",
+  "outputTokens",
+  "cachedInputTokens",
+  "reasoningTokens",
+  "totalTokens",
+  "firstTokenLatencyMs",
+] as const satisfies readonly (keyof AgentUsageMeasurements)[];
+
+export function parseAgentUsage(input: unknown): AgentUsage {
+  const record = recordAt(input, "usage");
+  const source = record.source;
+  if (source === "unknown") {
+    if (measurementKeys.some((key) => record[key] !== undefined)) {
+      throw new AgentContractParseError(
+        "usage",
+        "unknown 用量不能携带伪造的数值",
+      );
+    }
+    return { source };
+  }
+  if (source !== "provider-reported" && source !== "estimated") {
+    throw new AgentContractParseError("usage.source", "用量来源无效");
+  }
+
+  const measurements: AgentUsageMeasurements = {};
+  for (const key of measurementKeys) {
+    const value = nonNegativeIntegerAt(record, key, "usage");
+    if (value !== undefined) measurements[key] = value;
+  }
+  if (Object.keys(measurements).length === 0) {
+    throw new AgentContractParseError("usage", "已知来源至少需要一个用量数值");
+  }
+  return { source, ...measurements } as AgentUsage;
+}

package/template/packages/agent-contracts/src/validation.ts

@@ -0,0 +1,68 @@
+export class AgentContractParseError extends Error {
+  constructor(
+    readonly path: string,
+    message: string,
+  ) {
+    super(`${path}: ${message}`);
+    this.name = "AgentContractParseError";
+  }
+}
+
+export function recordAt(
+  input: unknown,
+  path: string,
+): Record<string, unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new AgentContractParseError(path, "必须是对象");
+  }
+  return input as Record<string, unknown>;
+}
+
+export function stringAt(
+  input: Record<string, unknown>,
+  key: string,
+  path: string,
+): string {
+  const value = input[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new AgentContractParseError(`${path}.${key}`, "必须是非空字符串");
+  }
+  return value;
+}
+
+export function booleanAt(
+  input: Record<string, unknown>,
+  key: string,
+  path: string,
+): boolean {
+  const value = input[key];
+  if (typeof value !== "boolean") {
+    throw new AgentContractParseError(`${path}.${key}`, "必须是布尔值");
+  }
+  return value;
+}
+
+export function nonNegativeIntegerAt(
+  input: Record<string, unknown>,
+  key: string,
+  path: string,
+): number | undefined {
+  const value = input[key];
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new AgentContractParseError(`${path}.${key}`, "必须是非负安全整数");
+  }
+  return Number(value);
+}
+
+export function positiveIntegerAt(
+  input: Record<string, unknown>,
+  key: string,
+  path: string,
+): number {
+  const value = nonNegativeIntegerAt(input, key, path);
+  if (value === undefined || value === 0) {
+    throw new AgentContractParseError(`${path}.${key}`, "必须是正安全整数");
+  }
+  return value;
+}

package/template/packages/agent-contracts/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "lib": ["esnext", "dom"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*", "index.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/packages/modules/src/ai-operation-composition.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "./manifest.js";
+import { validateModuleComposition } from "./composition.js";
+
+describe("AI Operation Composition", () => {
+  test("统一注册 Agent、Document 与 Speech Operation 并绑定实现", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      operation("business.agent", "agent", ["business.tool"]),
+      operation("business.document", "document"),
+      operation("business.speech", "speech"),
+    ];
+
+    expect(() =>
+      validateModuleComposition([module], {
+        aiOperations: module.aiOperations.map(({ key }) => key),
+      }),
+    ).not.toThrow();
+  });
+
+  test("Operation Key 全局唯一且必须使用所属模块命名空间", () => {
+    const first = fixture("first");
+    const second = fixture("second");
+    first.aiOperations = [operation("first.generate")];
+    second.aiOperations = [operation("first.generate")];
+
+    expect(() => validateModuleComposition([first, second])).toThrow(
+      "AI Operation Key 重复：first.generate",
+    );
+
+    second.aiOperations = [operation("foreign.generate")];
+    expect(() => validateModuleComposition([second])).toThrow(
+      "必须使用模块命名空间 second",
+    );
+  });
+
+  test.each([
+    ["permissionKey", "missing.permission", "未注册权限"],
+    ["featureKey", "missing.feature", "未注册Feature"],
+    ["auditAction", "missing.audit", "未注册审计动作"],
+  ] as const)("拒绝未知 %s 引用", (field, value, message) => {
+    const module = fixture("business");
+    const definition = operation("business.generate");
+    module.aiOperations = [{ ...definition, [field]: value }];
+    expect(() => validateModuleComposition([module])).toThrow(message);
+  });
+
+  test("拒绝未知 Tool、空 capability 和非法限制", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      operation("business.generate", "agent", ["missing.tool"]),
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "未注册Agent Tool",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      requiredCapabilities: [],
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "至少需要一个 capability",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      limits: { ...operation("business.generate").limits, maxInputBytes: 0 },
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "上限必须是正整数",
+    );
+  });
+
+  test("拒绝空 schema、capability 和 Tool Key", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      { ...operation("business.generate"), inputSchemaKey: " " },
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "Key 与引用字段不能为空",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      requiredCapabilities: [" "],
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "capability 不能为空",
+    );
+
+    module.aiOperations[0] = {
+      ...operation("business.generate"),
+      allowedToolKeys: [" "],
+    };
+    expect(() => validateModuleComposition([module])).toThrow("Tool 不能为空");
+  });
+
+  test("Operation Handler 必须与 Manifest 声明一一对应", () => {
+    const module = fixture("business");
+    module.aiOperations = [operation("business.generate")];
+
+    expect(() =>
+      validateModuleComposition([module], { aiOperations: [] }),
+    ).toThrow("AI Operation business.generate 缺少 Handler");
+    expect(() =>
+      validateModuleComposition([module], {
+        aiOperations: ["business.generate", "business.undeclared"],
+      }),
+    ).toThrow("AI Operation Handler business.undeclared 缺少 Manifest 声明");
+  });
+});
+
+function operation(
+  key: string,
+  kind: ModuleAiOperationDefinition["kind"] = "agent",
+  allowedToolKeys: readonly string[] = [],
+): ModuleAiOperationDefinition {
+  const namespace = key.split(".")[0]!;
+  return {
+    key,
+    kind,
+    featureKey: `${namespace}.ai`,
+    permissionKey: `${namespace}.ai.execute`,
+    auditAction: `${namespace}.ai.execute`,
+    inputSchemaKey: `${namespace}.ai.input.v1`,
+    outputSchemaKey: `${namespace}.ai.output.v1`,
+    requiredCapabilities: ["text-generation"],
+    allowedToolKeys,
+    dataClassification: "internal",
+    execution: kind === "speech" ? "live" : "streaming",
+    publicNetworkAccess: "forbidden",
+    limits: {
+      maxDurationSeconds: 60,
+      maxInputBytes: 1_048_576,
+      maxOutputBytes: 1_048_576,
+    },
+  };
+}
+
+function fixture(name: string): ModuleManifest {
+  const permissionKey = `${name}.ai.execute`;
+  const featureKey = `${name}.ai`;
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: name,
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: permissionKey,
+        label: "执行 AI",
+        module: name,
+        resource: "ai",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey,
+        label: "AI",
+        module: name,
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [
+      {
+        key: `${name}.tool`,
+        label: "业务工具",
+        description: "AI Operation 测试工具。",
+        permissionKey,
+        featureKey,
+        auditAction: `${name}.ai.execute`,
+      },
+    ],
+    providers: [],
+    auditActions: [
+      {
+        key: `${name}.ai.execute`,
+        label: "执行 AI",
+        description: "执行 AI Operation。",
+      },
+    ],
+  };
+}