create-windy 0.4.1 → 0.5.0

package/template/apps/server/src/ai-runtime-report/actor-handle.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { AiRuntimeActorHandleCodec } from "./actor-handle.js";
+
+describe("AI Runtime Actor handle", () => {
+  test("签发的 handle 不包含主键且可由同一密钥验证", () => {
+    const codec = new AiRuntimeActorHandleCodec("internal-token-for-tests");
+    const first = codec.issue("user-sensitive-id");
+    const second = codec.issue("user-sensitive-id");
+
+    expect(first).toStartWith("actor_");
+    expect(first).not.toContain("user-sensitive-id");
+    expect(first).not.toBe(second);
+    expect(codec.verify(first)).toBe("user-sensitive-id");
+    expect(codec.verify(second)).toBe("user-sensitive-id");
+  });
+
+  test("篡改或更换密钥后 fail closed", () => {
+    const codec = new AiRuntimeActorHandleCodec("internal-token-for-tests");
+    const handle = codec.issue("user-1");
+
+    expect(codec.verify(`${handle.slice(0, -1)}A`)).toBeUndefined();
+    expect(
+      new AiRuntimeActorHandleCodec("different-internal-token").verify(handle),
+    ).toBeUndefined();
+    expect(codec.verify("user-1")).toBeUndefined();
+  });
+});

package/template/apps/server/src/ai-runtime-report/actor-handle.ts

@@ -0,0 +1,81 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHmac,
+  randomBytes,
+} from "node:crypto";
+
+const VERSION = 1;
+const PREFIX = "actor_";
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const AAD = Buffer.from("windy.ai-runtime.actor-handle.v1", "utf8");
+const MAX_ACTOR_ID_BYTES = 128;
+
+export class AiRuntimeActorHandleCodec {
+  readonly #key: Buffer;
+
+  constructor(secret: string) {
+    if (secret.trim().length < 16) {
+      throw new Error("AI Runtime Actor handle secret 至少需要 16 个字符");
+    }
+    this.#key = createHmac("sha256", secret)
+      .update("windy.ai-runtime.actor-handle.key.v1")
+      .digest();
+  }
+
+  issue(actorId: string): string {
+    const plaintext = Buffer.from(actorId, "utf8");
+    if (plaintext.length === 0 || plaintext.length > MAX_ACTOR_ID_BYTES) {
+      throw new Error("AI Runtime Actor ID 长度无效");
+    }
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", this.#key, iv);
+    cipher.setAAD(AAD);
+    const ciphertext = Buffer.concat([
+      cipher.update(plaintext),
+      cipher.final(),
+    ]);
+    return `${PREFIX}${Buffer.concat([
+      Buffer.from([VERSION]),
+      iv,
+      cipher.getAuthTag(),
+      ciphertext,
+    ]).toString("base64url")}`;
+  }
+
+  verify(handle: string): string | undefined {
+    if (!handle.startsWith(PREFIX)) return undefined;
+    try {
+      const encoded = handle.slice(PREFIX.length);
+      const payload = Buffer.from(encoded, "base64url");
+      if (payload.toString("base64url") !== encoded) return undefined;
+      if (
+        payload.length <= 1 + IV_BYTES + TAG_BYTES ||
+        payload[0] !== VERSION
+      ) {
+        return undefined;
+      }
+      const ivStart = 1;
+      const tagStart = ivStart + IV_BYTES;
+      const ciphertextStart = tagStart + TAG_BYTES;
+      const decipher = createDecipheriv(
+        "aes-256-gcm",
+        this.#key,
+        payload.subarray(ivStart, tagStart),
+      );
+      decipher.setAAD(AAD);
+      decipher.setAuthTag(payload.subarray(tagStart, ciphertextStart));
+      const plaintext = Buffer.concat([
+        decipher.update(payload.subarray(ciphertextStart)),
+        decipher.final(),
+      ]);
+      if (plaintext.length === 0 || plaintext.length > MAX_ACTOR_ID_BYTES) {
+        return undefined;
+      }
+      return plaintext.toString("utf8");
+    } catch {
+      return undefined;
+    }
+  }
+}

package/template/apps/server/src/ai-runtime-report/contracts.ts

@@ -0,0 +1,91 @@
+import type {
+  AiRuntimeActorPage,
+  AiRuntimeActorSummary,
+  AiRuntimeReportRange,
+  AiRuntimeReportSummary,
+  AiRuntimeRunDetail,
+  AiRuntimeRunListItem,
+  AiRuntimeRunPage,
+} from "@southwind-ai/shared";
+import type { RequestActor } from "../guards.js";
+
+export interface AiRuntimeReportQuery {
+  range: AiRuntimeReportRange;
+  actorId?: string;
+}
+
+export interface PublicAiRuntimeReportQuery {
+  range: AiRuntimeReportRange;
+  actorHandle?: string;
+}
+
+export interface AiRuntimeReportScope {
+  mode: "all" | "bounded" | "none";
+  actorIds: readonly string[];
+  departmentIds: readonly string[];
+}
+
+export interface InternalAiRuntimeRunListItem extends Omit<
+  AiRuntimeRunListItem,
+  "actor"
+> {
+  actorId: string | null;
+  departmentId: string | null;
+}
+
+export interface InternalAiRuntimeRunDetail extends Omit<
+  AiRuntimeRunDetail,
+  "actor"
+> {
+  actorId: string | null;
+  departmentId: string | null;
+}
+
+export interface InternalAiRuntimeRunPage {
+  items: InternalAiRuntimeRunListItem[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export interface AiRuntimeReportRemotePort {
+  summary(
+    query: AiRuntimeReportQuery,
+    scope: AiRuntimeReportScope,
+    signal?: AbortSignal,
+  ): Promise<AiRuntimeReportSummary>;
+  runs(
+    query: AiRuntimeReportQuery & { page: number; pageSize: number },
+    scope: AiRuntimeReportScope,
+    signal?: AbortSignal,
+  ): Promise<InternalAiRuntimeRunPage>;
+  run(
+    runId: string,
+    signal?: AbortSignal,
+  ): Promise<InternalAiRuntimeRunDetail | undefined>;
+}
+
+export interface AiRuntimeActorDirectory {
+  list(
+    query: { q?: string; page: number; pageSize: number },
+    actor: RequestActor,
+  ): Promise<AiRuntimeActorPage>;
+  resolve(
+    actorIds: readonly string[],
+    actor: RequestActor,
+  ): Promise<Map<string, AiRuntimeActorSummary>>;
+  resolveHandle(
+    handle: string,
+    actor: RequestActor,
+  ): Promise<string | undefined>;
+}
+
+export type {
+  AiRuntimeActorPage,
+  AiRuntimeActorSummary,
+  AiRuntimeReportRange,
+  AiRuntimeReportSummary,
+  AiRuntimeRunDetail,
+  AiRuntimeRunListItem,
+  AiRuntimeRunPage,
+};

package/template/apps/server/src/ai-runtime-report/remote-parser.ts

@@ -0,0 +1,212 @@
+import type {
+  AiRuntimeAttemptDetail,
+  AiRuntimeReportSummary,
+  AiRuntimeRunUsage,
+} from "@southwind-ai/shared";
+import type {
+  InternalAiRuntimeRunDetail,
+  InternalAiRuntimeRunListItem,
+  InternalAiRuntimeRunPage,
+} from "./contracts.js";
+
+export function parseReportSummary(value: unknown): AiRuntimeReportSummary {
+  const root = record(value);
+  const runs = record(root.runs);
+  const cache = record(root.cache);
+  const tokens = record(root.tokens);
+  return {
+    generatedAt: text(root.generatedAt),
+    reportingAvailableFrom: nullableText(root.reportingAvailableFrom),
+    retentionDays: integer(root.retentionDays),
+    runs: {
+      total: integer(runs.total),
+      completed: integer(runs.completed),
+      failed: integer(runs.failed),
+      cancelled: integer(runs.cancelled),
+      inProgress: integer(runs.inProgress),
+      successRate: nullableNumber(runs.successRate),
+    },
+    cache: {
+      hit: integer(cache.hit),
+      miss: integer(cache.miss),
+      unknown: integer(cache.unknown),
+      hitRate: nullableNumber(cache.hitRate),
+      tokenRate: nullableNumber(cache.tokenRate),
+      coverageRate: number(cache.coverageRate),
+    },
+    tokens: {
+      input: nullableInteger(tokens.input),
+      output: nullableInteger(tokens.output),
+      cachedInput: nullableInteger(tokens.cachedInput),
+      reasoning: nullableInteger(tokens.reasoning),
+      total: nullableInteger(tokens.total),
+      coverageRate: number(tokens.coverageRate),
+    },
+    byModel: array(root.byModel).map((item) => {
+      const model = record(item);
+      return {
+        deploymentKey: text(model.deploymentKey),
+        model: text(model.model),
+        attempts: integer(model.attempts),
+        inputTokens: nullableInteger(model.inputTokens),
+        outputTokens: nullableInteger(model.outputTokens),
+        cachedInputTokens: nullableInteger(model.cachedInputTokens),
+        reasoningTokens: nullableInteger(model.reasoningTokens),
+        totalTokens: nullableInteger(model.totalTokens),
+        unknownUsageCount: integer(model.unknownUsageCount),
+      };
+    }),
+    activity: array(root.activity).map((item) => {
+      const point = record(item);
+      return {
+        date: text(point.date),
+        runs: integer(point.runs),
+        completed: integer(point.completed),
+        failed: integer(point.failed),
+        totalTokens: nullableInteger(point.totalTokens),
+      };
+    }),
+  };
+}
+
+export function parseReportRunPage(value: unknown): InternalAiRuntimeRunPage {
+  const root = record(value);
+  return {
+    items: array(root.items).map(parseReportRun),
+    total: integer(root.total),
+    page: integer(root.page),
+    pageSize: integer(root.pageSize),
+  };
+}
+
+export function parseReportRunDetail(
+  value: unknown,
+): InternalAiRuntimeRunDetail {
+  const root = record(value);
+  return {
+    ...parseReportRun(root),
+    releaseId: text(root.releaseId),
+    traceId: text(root.traceId),
+    safeErrorCode: nullableText(root.safeErrorCode),
+    attempts: array(root.attempts).map(parseAttempt),
+  };
+}
+
+function parseReportRun(value: unknown): InternalAiRuntimeRunListItem {
+  const item = record(value);
+  return {
+    runId: text(item.runId),
+    operationKey: text(item.operationKey),
+    actorId: nullableText(item.actorId),
+    departmentId: nullableText(item.departmentId),
+    status: oneOf(item.status, [
+      "accepted",
+      "running",
+      "awaiting-approval",
+      "completed",
+      "failed",
+      "cancelled",
+    ]),
+    startedAt: nullableText(item.startedAt),
+    finishedAt: nullableText(item.finishedAt),
+    durationMs: nullableInteger(item.durationMs),
+    attemptCount: integer(item.attemptCount),
+    models: array(item.models).map(text),
+    cacheStatus: oneOf(item.cacheStatus, ["hit", "miss", "unknown"]),
+    usage: parseUsage(item.usage),
+  };
+}
+
+function parseAttempt(value: unknown): AiRuntimeAttemptDetail {
+  const item = record(value);
+  return {
+    attemptId: text(item.attemptId),
+    sequence: integer(item.sequence),
+    toolRound: integer(item.toolRound),
+    deploymentKey: text(item.deploymentKey),
+    model: text(item.model),
+    outcome: oneOf(item.outcome, [
+      "running",
+      "completed",
+      "failed",
+      "cancelled",
+      "blocked",
+      "abandoned",
+    ]),
+    cacheStatus: oneOf(item.cacheStatus, ["hit", "miss", "unknown"]),
+    usageSource: oneOf(item.usageSource, [
+      "provider-reported",
+      "estimated",
+      "unknown",
+    ]),
+    ...parseUsage(item),
+    firstTokenLatencyMs: nullableInteger(item.firstTokenLatencyMs),
+    durationMs: nullableInteger(item.durationMs),
+    safeErrorCode: nullableText(item.safeErrorCode),
+    startedAt: text(item.startedAt),
+    finishedAt: nullableText(item.finishedAt),
+  };
+}
+
+function parseUsage(value: unknown): AiRuntimeRunUsage {
+  const usage = record(value);
+  return {
+    inputTokens: nullableInteger(usage.inputTokens),
+    outputTokens: nullableInteger(usage.outputTokens),
+    cachedInputTokens: nullableInteger(usage.cachedInputTokens),
+    reasoningTokens: nullableInteger(usage.reasoningTokens),
+    totalTokens: nullableInteger(usage.totalTokens),
+  };
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid();
+  return value as Record<string, unknown>;
+}
+
+function array(value: unknown): unknown[] {
+  if (!Array.isArray(value)) invalid();
+  return value;
+}
+
+function text(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) invalid();
+  return value;
+}
+
+function nullableText(value: unknown): string | null {
+  return value === null ? null : text(value);
+}
+
+function number(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    invalid();
+  }
+  return value;
+}
+
+function nullableNumber(value: unknown): number | null {
+  return value === null ? null : number(value);
+}
+
+function integer(value: unknown): number {
+  const result = number(value);
+  if (!Number.isSafeInteger(result)) invalid();
+  return result;
+}
+
+function nullableInteger(value: unknown): number | null {
+  return value === null ? null : integer(value);
+}
+
+function oneOf<const T extends string>(
+  value: unknown,
+  values: readonly T[],
+): T {
+  if (typeof value !== "string" || !values.includes(value as T)) invalid();
+  return value as T;
+}
+
+function invalid(): never {
+  throw new Error("Agent Runtime 报表返回协议无效");
+}

package/template/apps/server/src/ai-runtime-report/remote-port.ts

@@ -0,0 +1,138 @@
+import type {
+  AiRuntimeReportQuery,
+  AiRuntimeReportRemotePort,
+  AiRuntimeReportScope,
+} from "./contracts.js";
+import {
+  parseReportRunDetail,
+  parseReportRunPage,
+  parseReportSummary,
+} from "./remote-parser.js";
+
+export interface RemoteAiRuntimeReportOptions {
+  baseUrl: string;
+  internalToken: string;
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+}
+
+export class RemoteAiRuntimeReportPort implements AiRuntimeReportRemotePort {
+  readonly #baseUrl: string;
+  readonly #timeoutMs: number;
+  readonly #maxResponseBytes: number;
+
+  constructor(private readonly options: RemoteAiRuntimeReportOptions) {
+    this.#baseUrl = normalizeInternalUrl(options.baseUrl);
+    this.#timeoutMs = options.timeoutMs ?? 10_000;
+    this.#maxResponseBytes = options.maxResponseBytes ?? 2 * 1024 * 1024;
+    if (!options.internalToken.trim()) {
+      throw new Error("Agent Server 内部 Token 不能为空");
+    }
+  }
+
+  async summary(
+    query: AiRuntimeReportQuery,
+    scope: AiRuntimeReportScope,
+    signal?: AbortSignal,
+  ) {
+    return parseReportSummary(
+      await this.get(
+        `/api/internal/ai-runtime-report/summary?${params(query, scope)}`,
+        signal,
+      ),
+    );
+  }
+
+  async runs(
+    query: AiRuntimeReportQuery & { page: number; pageSize: number },
+    scope: AiRuntimeReportScope,
+    signal?: AbortSignal,
+  ) {
+    const queryParams = params(query, scope);
+    queryParams.set("page", String(query.page));
+    queryParams.set("pageSize", String(query.pageSize));
+    return parseReportRunPage(
+      await this.get(
+        `/api/internal/ai-runtime-report/runs?${queryParams}`,
+        signal,
+      ),
+    );
+  }
+
+  async run(runId: string, signal?: AbortSignal) {
+    const response = await this.request(
+      `/api/internal/ai-runtime-report/runs/${encodeURIComponent(runId)}`,
+      signal,
+    );
+    if (response.status === 404) return undefined;
+    if (!response.ok) throw remoteFailure(response.status);
+    return parseReportRunDetail(
+      await boundedJson(response, this.#maxResponseBytes),
+    );
+  }
+
+  async get(path: string, signal?: AbortSignal): Promise<unknown> {
+    const response = await this.request(path, signal);
+    if (!response.ok) throw remoteFailure(response.status);
+    return boundedJson(response, this.#maxResponseBytes);
+  }
+
+  request(path: string, signal?: AbortSignal) {
+    return fetch(new URL(path, this.#baseUrl), {
+      headers: { authorization: `Bearer ${this.options.internalToken}` },
+      signal: signal
+        ? AbortSignal.any([signal, AbortSignal.timeout(this.#timeoutMs)])
+        : AbortSignal.timeout(this.#timeoutMs),
+    });
+  }
+}
+
+function params(
+  query: AiRuntimeReportQuery,
+  scope: AiRuntimeReportScope,
+): URLSearchParams {
+  const result = new URLSearchParams({
+    range: query.range,
+    scopeMode: scope.mode,
+  });
+  if (query.actorId) result.set("actorId", query.actorId);
+  for (const actorId of scope.actorIds) result.append("scopeActorId", actorId);
+  for (const departmentId of scope.departmentIds) {
+    result.append("scopeDepartmentId", departmentId);
+  }
+  return result;
+}
+
+async function boundedJson(
+  response: Response,
+  maximum: number,
+): Promise<unknown> {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maximum) throw responseTooLarge();
+  const body = await response.text();
+  if (Buffer.byteLength(body) > maximum) throw responseTooLarge();
+  try {
+    return JSON.parse(body) as unknown;
+  } catch {
+    throw new Error("Agent Runtime 报表返回协议无效");
+  }
+}
+
+function remoteFailure(status: number): Error {
+  return new Error(`Agent Runtime 报表请求失败（HTTP ${status}）`);
+}
+
+function responseTooLarge(): Error {
+  return new Error("Agent Runtime 报表响应超过安全上限");
+}
+
+function normalizeInternalUrl(raw: string): string {
+  const url = new URL(raw);
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error("Agent Server URL 只允许 HTTP 或 HTTPS");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent Server URL 不允许凭据、查询串或片段");
+  }
+  return url.toString();
+}