create-safest-tools 0.2.0

package/template/src/ai-registry-validation.ts

@@ -0,0 +1,244 @@
+import { ApiError } from "./report-http";
+import type { JsonObject } from "./workflow-platform-types";
+
+function object(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ApiError(400, "invalid_ai_configuration", `${name} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function exact(value: Record<string, unknown>, allowed: string[], name: string): void {
+  const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unexpected) throw new ApiError(400, "invalid_ai_configuration", `${name} contains unsupported field ${unexpected}.`);
+}
+
+function text(value: unknown, name: string, minimum: number, maximum: number, pattern?: RegExp): string {
+  if (typeof value !== "string" || value.trim().length < minimum || value.trim().length > maximum || (pattern && !pattern.test(value.trim()))) {
+    throw new ApiError(400, "invalid_ai_configuration", `${name} is invalid.`);
+  }
+  return value.trim();
+}
+
+function jsonObject(value: unknown, name: string): JsonObject {
+  const result = object(value, name);
+  try {
+    return JSON.parse(JSON.stringify(result)) as JsonObject;
+  } catch {
+    throw new ApiError(400, "invalid_ai_configuration", `${name} must be JSON serializable.`);
+  }
+}
+
+function schema(value: unknown, name: string): JsonObject {
+  const result = jsonObject(value, name);
+  if (result.type !== "object") throw new ApiError(400, "invalid_ai_configuration", `${name} must be an object JSON Schema.`);
+  assertSupportedSchema(result, name, 0);
+  return result;
+}
+
+function assertSupportedSchema(value: JsonObject, name: string, depth: number): void {
+  if (depth > 8) throw new ApiError(400, "invalid_ai_configuration", `${name} exceeds the schema nesting limit.`);
+  const supported = new Set(["type", "properties", "required", "additionalProperties", "items", "enum", "minLength", "maxLength", "minimum", "maximum", "maxItems"]);
+  if (Object.keys(value).some((key) => !supported.has(key))) throw new ApiError(400, "invalid_ai_configuration", `${name} uses unsupported JSON Schema features.`);
+  const types = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+  if (typeof value.type !== "string" || !types.has(value.type)) throw new ApiError(400, "invalid_ai_configuration", `${name}.type is unsupported.`);
+  if (value.properties !== undefined) {
+    if (!value.properties || typeof value.properties !== "object" || Array.isArray(value.properties) || Object.keys(value.properties).length > 100) {
+      throw new ApiError(400, "invalid_ai_configuration", `${name}.properties is invalid.`);
+    }
+    for (const [key, child] of Object.entries(value.properties)) {
+      if (!/^[A-Za-z][A-Za-z0-9_-]{0,99}$/u.test(key) || !child || typeof child !== "object" || Array.isArray(child)) {
+        throw new ApiError(400, "invalid_ai_configuration", `${name}.properties contains an invalid entry.`);
+      }
+      assertSupportedSchema(child as JsonObject, `${name}.properties.${key}`, depth + 1);
+    }
+  }
+  if (value.items !== undefined) {
+    if (!value.items || typeof value.items !== "object" || Array.isArray(value.items)) throw new ApiError(400, "invalid_ai_configuration", `${name}.items is invalid.`);
+    assertSupportedSchema(value.items as JsonObject, `${name}.items`, depth + 1);
+  }
+}
+
+const keyPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const idPattern = /^[A-Za-z0-9._:-]{1,200}$/u;
+
+export interface PromptPublicationInput {
+  key: string;
+  name: string;
+  templateText: string;
+  variableSchema: JsonObject;
+}
+
+export function parsePromptPublication(value: unknown): PromptPublicationInput {
+  const input = object(value, "prompt");
+  exact(input, ["key", "name", "template_text", "variable_schema"], "prompt");
+  const templateText = text(input.template_text, "template_text", 20, 20_000);
+  if (/\{\{\{?|<%|\$\{|javascript:/iu.test(templateText)) {
+    throw new ApiError(400, "invalid_ai_configuration", "template_text contains an unsupported interpolation form.");
+  }
+  return {
+    key: text(input.key, "key", 2, 80, keyPattern),
+    name: text(input.name, "name", 2, 120),
+    templateText,
+    variableSchema: schema(input.variable_schema ?? { type: "object" }, "variable_schema"),
+  };
+}
+
+export interface ModelAliasVersionInput {
+  provider: "workers_ai" | "openai_compatible" | "anthropic" | "google" | "custom_connection";
+  model: string;
+  connectionVersionId: string | null;
+  fallbackAliasVersionId: string | null;
+  inputCostMicrousdPerMillion: number;
+  outputCostMicrousdPerMillion: number;
+  capability: JsonObject;
+  dataPolicy: JsonObject;
+}
+
+export interface ModelAliasCreateInput {
+  key: string;
+  name: string;
+  version: ModelAliasVersionInput;
+}
+
+function nonnegativeInteger(value: unknown, name: string, maximum: number): number {
+  if (!Number.isInteger(value) || Number(value) < 0 || Number(value) > maximum) {
+    throw new ApiError(400, "invalid_ai_configuration", `${name} must be a non-negative integer at most ${maximum}.`);
+  }
+  return Number(value);
+}
+
+export function parseModelAliasVersion(value: unknown): ModelAliasVersionInput {
+  const input = object(value, "model alias version");
+  exact(input, [
+    "provider", "model", "connection_version_id", "fallback_alias_version_id",
+    "input_cost_microusd_per_million", "output_cost_microusd_per_million",
+    "capability", "data_policy",
+  ], "model alias version");
+  const providers = new Set(["workers_ai", "openai_compatible", "anthropic", "google", "custom_connection"]);
+  if (typeof input.provider !== "string" || !providers.has(input.provider)) {
+    throw new ApiError(400, "invalid_ai_configuration", "provider is unsupported.");
+  }
+  const provider = input.provider as ModelAliasVersionInput["provider"];
+  const model = text(input.model, "model", 2, 200, /^[A-Za-z0-9@._:/-]+$/u);
+  const connectionVersionId = input.connection_version_id === null || input.connection_version_id === undefined
+    ? null : text(input.connection_version_id, "connection_version_id", 1, 200, idPattern);
+  if (provider === "workers_ai" && (!model.startsWith("@cf/") || connectionVersionId)) {
+    throw new ApiError(400, "invalid_ai_configuration", "Workers AI aliases require an @cf model and no connection.");
+  }
+  if (provider !== "workers_ai" && !connectionVersionId) {
+    throw new ApiError(400, "invalid_ai_configuration", "External model aliases require a connection_version_id.");
+  }
+  const fallbackAliasVersionId = input.fallback_alias_version_id === null || input.fallback_alias_version_id === undefined
+    ? null : text(input.fallback_alias_version_id, "fallback_alias_version_id", 1, 200, idPattern);
+  return {
+    provider,
+    model,
+    connectionVersionId,
+    fallbackAliasVersionId,
+    inputCostMicrousdPerMillion: nonnegativeInteger(input.input_cost_microusd_per_million ?? 0, "input_cost_microusd_per_million", 1_000_000_000),
+    outputCostMicrousdPerMillion: nonnegativeInteger(input.output_cost_microusd_per_million ?? 0, "output_cost_microusd_per_million", 1_000_000_000),
+    capability: jsonObject(input.capability ?? {}, "capability"),
+    dataPolicy: jsonObject(input.data_policy ?? {}, "data_policy"),
+  };
+}
+
+export function parseModelAliasCreate(value: unknown): ModelAliasCreateInput {
+  const input = object(value, "model alias");
+  exact(input, ["key", "name", "version"], "model alias");
+  return {
+    key: text(input.key, "key", 2, 80, keyPattern),
+    name: text(input.name, "name", 2, 120),
+    version: parseModelAliasVersion(input.version),
+  };
+}
+
+export interface AgentVersionInput {
+  promptVersionId: string;
+  modelAliasVersionId: string;
+  toolManifest: string[];
+  memoryPolicy: JsonObject;
+  maximumTurns: number;
+  approvalPolicy: JsonObject;
+  inputSchema: JsonObject;
+  outputSchema: JsonObject;
+}
+
+export interface AgentCreateInput {
+  key: string;
+  name: string;
+  description: string;
+  kind: "routing" | "specialist" | "assistant" | "shadow";
+  version: AgentVersionInput;
+}
+
+export function parseAgentVersion(value: unknown): AgentVersionInput {
+  const input = object(value, "agent version");
+  exact(input, [
+    "prompt_version_id", "model_alias_version_id", "tool_manifest", "memory_policy",
+    "maximum_turns", "approval_policy", "input_schema", "output_schema",
+  ], "agent version");
+  if (!Array.isArray(input.tool_manifest) || input.tool_manifest.length > 8
+    || input.tool_manifest.some((tool) => typeof tool !== "string" || !["read_report_context", "read_findings"].includes(tool))
+    || new Set(input.tool_manifest).size !== input.tool_manifest.length) {
+    throw new ApiError(400, "invalid_ai_configuration", "tool_manifest contains unsupported or duplicate tools.");
+  }
+  return {
+    promptVersionId: text(input.prompt_version_id, "prompt_version_id", 1, 200, idPattern),
+    modelAliasVersionId: text(input.model_alias_version_id, "model_alias_version_id", 1, 200, idPattern),
+    toolManifest: input.tool_manifest as string[],
+    memoryPolicy: jsonObject(input.memory_policy ?? {}, "memory_policy"),
+    maximumTurns: nonnegativeInteger(input.maximum_turns ?? 1, "maximum_turns", 8) || 1,
+    approvalPolicy: jsonObject(input.approval_policy ?? {}, "approval_policy"),
+    inputSchema: schema(input.input_schema, "input_schema"),
+    outputSchema: schema(input.output_schema, "output_schema"),
+  };
+}
+
+export function parseAgentCreate(value: unknown): AgentCreateInput {
+  const input = object(value, "agent");
+  exact(input, ["key", "name", "description", "kind", "version"], "agent");
+  if (typeof input.kind !== "string" || !["routing", "specialist", "assistant", "shadow"].includes(input.kind)) {
+    throw new ApiError(400, "invalid_ai_configuration", "kind is unsupported.");
+  }
+  return {
+    key: text(input.key, "key", 2, 80, keyPattern),
+    name: text(input.name, "name", 2, 120),
+    description: typeof input.description === "string" ? input.description.trim().slice(0, 2_000) : "",
+    kind: input.kind as AgentCreateInput["kind"],
+    version: parseAgentVersion(input.version),
+  };
+}
+
+export interface BudgetPublicationInput {
+  scopeType: "installation" | "queue" | "workflow" | "component" | "connection" | "agent" | "assistant" | "shadow";
+  scopeId: string;
+  metric: "reports" | "calls" | "concurrent_calls" | "input_units" | "output_units" | "cost_microusd" | "emails" | "actions" | "evidence_fetches" | "storage_bytes";
+  limitValue: number;
+  windowSeconds: number;
+  behavior: "block" | "fallback" | "defer" | "sample" | "pause";
+  fallbackReference: string | null;
+}
+
+export function parseBudgetPublication(value: unknown): BudgetPublicationInput {
+  const input = object(value, "budget");
+  exact(input, ["scope_type", "scope_id", "metric", "limit_value", "window_seconds", "behavior", "fallback_reference"], "budget");
+  const scopes = ["installation", "queue", "workflow", "component", "connection", "agent", "assistant", "shadow"] as const;
+  const metrics = ["reports", "calls", "concurrent_calls", "input_units", "output_units", "cost_microusd", "emails", "actions", "evidence_fetches", "storage_bytes"] as const;
+  const behaviors = ["block", "fallback", "defer", "sample", "pause"] as const;
+  if (typeof input.scope_type !== "string" || !scopes.includes(input.scope_type as typeof scopes[number])) throw new ApiError(400, "invalid_budget", "scope_type is unsupported.");
+  if (typeof input.metric !== "string" || !metrics.includes(input.metric as typeof metrics[number])) throw new ApiError(400, "invalid_budget", "metric is unsupported.");
+  if (typeof input.behavior !== "string" || !behaviors.includes(input.behavior as typeof behaviors[number])) throw new ApiError(400, "invalid_budget", "behavior is unsupported.");
+  const fallbackReference = input.fallback_reference === null || input.fallback_reference === undefined
+    ? null : text(input.fallback_reference, "fallback_reference", 1, 200, idPattern);
+  if (input.behavior === "fallback" && !fallbackReference) throw new ApiError(400, "invalid_budget", "Fallback behavior requires fallback_reference.");
+  return {
+    scopeType: input.scope_type as BudgetPublicationInput["scopeType"],
+    scopeId: text(input.scope_id, "scope_id", 1, 200, idPattern),
+    metric: input.metric as BudgetPublicationInput["metric"],
+    limitValue: nonnegativeInteger(input.limit_value, "limit_value", Number.MAX_SAFE_INTEGER),
+    windowSeconds: nonnegativeInteger(input.window_seconds, "window_seconds", 2_678_400) || 1,
+    behavior: input.behavior as BudgetPublicationInput["behavior"],
+    fallbackReference,
+  };
+}

package/template/src/ai-registry.ts

@@ -0,0 +1,292 @@
+import { canonicalJson } from "./audit";
+import type {
+  AgentCreateInput,
+  AgentVersionInput,
+  BudgetPublicationInput,
+  ModelAliasCreateInput,
+  ModelAliasVersionInput,
+  PromptPublicationInput,
+} from "./ai-registry-validation";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+
+interface MutationRow { action: string; actor_id: string; response_json: string }
+
+function now(): string { return new Date().toISOString(); }
+
+function parsed<T>(value: string, fallback: T): T {
+  try { return JSON.parse(value) as T; } catch { return fallback; }
+}
+
+async function replay(db: D1Database, key: string, action: string, actorId: string): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`SELECT action, actor_id, response_json FROM ai_registry_mutations WHERE idempotency_key = ?1 LIMIT 1`)
+    .bind(key).first<MutationRow>();
+  if (!row) return null;
+  if (row.action !== action || row.actor_id !== actorId) throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was used for another AI registry mutation.");
+  return parsed(row.response_json, {});
+}
+
+function audit(db: D1Database, session: OperatorSession, key: string, action: string, targetType: string, targetId: string, details: unknown, timestamp: string): D1PreparedStatement {
+  return db.prepare(`
+    INSERT OR IGNORE INTO audit_events (
+      id, idempotency_key, action, actor_type, actor_id,
+      target_type, target_id, details_json, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+  `).bind(crypto.randomUUID(), key, action, session.actor.type, session.actor.id, targetType, targetId, canonicalJson(details), timestamp);
+}
+
+function mutation(db: D1Database, key: string, action: string, actorId: string, targetId: string, response: unknown, timestamp: string): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO ai_registry_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+    VALUES (?1, ?2, ?3, ?4, ?5, ?6)
+  `).bind(key, action, actorId, targetId, canonicalJson(response), timestamp);
+}
+
+export async function listPrompts(db: D1Database): Promise<Record<string, unknown>[]> {
+  const result = await db.prepare(`
+    SELECT id, prompt_key AS key, version, name, prompt_digest AS promptDigest,
+      variable_schema_json AS variableSchemaJson, status, published_at AS publishedAt,
+      retired_at AS retiredAt, created_by AS createdBy
+    FROM prompt_versions WHERE installation_id = 'default'
+    ORDER BY prompt_key, version DESC, id DESC
+  `).all<Record<string, unknown>>();
+  return result.results.map((row) => ({
+    ...row,
+    variableSchema: parsed(String(row.variableSchemaJson ?? "{}"), {}),
+    variableSchemaJson: undefined,
+  }));
+}
+
+export async function publishPrompt(
+  db: D1Database,
+  input: PromptPublicationInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ promptVersionId: string; version: number; promptDigest: string; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "prompt.publish", session.actor.id);
+  if (existing) return {
+    promptVersionId: String(existing.promptVersionId), version: Number(existing.version),
+    promptDigest: String(existing.promptDigest), idempotentReplay: true,
+  };
+  const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM prompt_versions WHERE installation_id = 'default' AND prompt_key = ?1`)
+    .bind(input.key).first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const promptVersionId = crypto.randomUUID();
+  const promptDigest = `sha256:${await sha256(canonicalJson({ template: input.templateText, schema: input.variableSchema }))}`;
+  const timestamp = now();
+  const response = { promptVersionId, version, promptDigest };
+  await db.batch([
+    db.prepare(`
+      INSERT INTO prompt_versions (
+        id, installation_id, prompt_key, version, name, template_text,
+        variable_schema_json, prompt_digest, status, published_at, created_by, created_at
+      ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, 'published', ?8, ?9, ?8)
+    `).bind(promptVersionId, input.key, version, input.name, input.templateText, canonicalJson(input.variableSchema), promptDigest, timestamp, session.actor.id),
+    mutation(db, idempotencyKey, "prompt.publish", session.actor.id, promptVersionId, response, timestamp),
+    audit(db, session, `prompt:${idempotencyKey}`, "prompt.version_published", "prompt_version", promptVersionId, { key: input.key, version, promptDigest }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+function modelVersionInsert(db: D1Database, aliasId: string, versionId: string, version: number, input: ModelAliasVersionInput, actorId: string, timestamp: string): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO model_alias_versions (
+      id, alias_id, version, provider, model, connection_version_id,
+      fallback_alias_version_id, input_cost_microusd_per_million,
+      output_cost_microusd_per_million, capability_json, data_policy_json,
+      published_at, created_by, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?12)
+  `).bind(
+    versionId, aliasId, version, input.provider, input.model, input.connectionVersionId,
+    input.fallbackAliasVersionId, input.inputCostMicrousdPerMillion,
+    input.outputCostMicrousdPerMillion, canonicalJson(input.capability),
+    canonicalJson(input.dataPolicy), timestamp, actorId,
+  );
+}
+
+async function validateModelDependencies(db: D1Database, input: ModelAliasVersionInput, aliasId?: string): Promise<void> {
+  if (input.connectionVersionId) {
+    const connection = await db.prepare(`
+      SELECT v.id FROM connection_versions v JOIN connection_definitions d ON d.id = v.connection_id
+      WHERE v.id = ?1 AND v.retired_at IS NULL AND d.status = 'active' LIMIT 1
+    `).bind(input.connectionVersionId).first();
+    if (!connection) throw new ApiError(400, "model_connection_unavailable", "The model connection version is not active.");
+  }
+  if (input.fallbackAliasVersionId) {
+    const fallback = await db.prepare(`
+      SELECT v.alias_id AS aliasId FROM model_alias_versions v JOIN model_aliases a ON a.id = v.alias_id
+      WHERE v.id = ?1 AND v.retired_at IS NULL AND a.status = 'active' LIMIT 1
+    `).bind(input.fallbackAliasVersionId).first<{ aliasId: string }>();
+    if (!fallback || fallback.aliasId === aliasId) throw new ApiError(400, "model_fallback_invalid", "The fallback model alias version is unavailable or circular.");
+  }
+}
+
+export async function listModelAliases(db: D1Database): Promise<Record<string, unknown>[]> {
+  const result = await db.prepare(`
+    SELECT a.id, a.alias_key AS key, a.name, a.status, a.active_version_id AS activeVersionId,
+      a.created_by AS createdBy, a.created_at AS createdAt, a.updated_at AS updatedAt,
+      v.version, v.provider, v.model, v.connection_version_id AS connectionVersionId,
+      v.fallback_alias_version_id AS fallbackAliasVersionId,
+      v.input_cost_microusd_per_million AS inputCostMicrousdPerMillion,
+      v.output_cost_microusd_per_million AS outputCostMicrousdPerMillion,
+      v.capability_json AS capabilityJson, v.data_policy_json AS dataPolicyJson,
+      v.published_at AS publishedAt
+    FROM model_aliases a LEFT JOIN model_alias_versions v ON v.id = a.active_version_id
+    WHERE a.installation_id = 'default' ORDER BY a.name, a.id
+  `).all<Record<string, unknown>>();
+  return result.results.map((row) => ({ ...row, capability: parsed(String(row.capabilityJson ?? "{}"), {}), dataPolicy: parsed(String(row.dataPolicyJson ?? "{}"), {}), capabilityJson: undefined, dataPolicyJson: undefined }));
+}
+
+export async function createModelAlias(db: D1Database, input: ModelAliasCreateInput, session: OperatorSession, idempotencyKey: string): Promise<{ aliasId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "model_alias.create", session.actor.id);
+  if (existing) return { aliasId: String(existing.aliasId), versionId: String(existing.versionId), version: Number(existing.version), idempotentReplay: true };
+  if (await db.prepare(`SELECT id FROM model_aliases WHERE installation_id = 'default' AND alias_key = ?1`).bind(input.key).first()) throw new ApiError(409, "model_alias_key_exists", "A model alias with this key already exists.");
+  await validateModelDependencies(db, input.version);
+  const aliasId = crypto.randomUUID();
+  const versionId = crypto.randomUUID();
+  const timestamp = now();
+  const response = { aliasId, versionId, version: 1 };
+  await db.batch([
+    db.prepare(`INSERT INTO model_aliases (id, installation_id, alias_key, name, status, active_version_id, created_by, created_at, updated_at) VALUES (?1, 'default', ?2, ?3, 'active', ?4, ?5, ?6, ?6)`)
+      .bind(aliasId, input.key, input.name, versionId, session.actor.id, timestamp),
+    modelVersionInsert(db, aliasId, versionId, 1, input.version, session.actor.id, timestamp),
+    mutation(db, idempotencyKey, "model_alias.create", session.actor.id, aliasId, response, timestamp),
+    audit(db, session, `model-alias:${idempotencyKey}`, "model_alias.created", "model_alias", aliasId, { key: input.key, versionId }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function publishModelAliasVersion(db: D1Database, aliasId: string, input: ModelAliasVersionInput, session: OperatorSession, idempotencyKey: string): Promise<{ aliasId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "model_alias.version.publish", session.actor.id);
+  if (existing) return { aliasId: String(existing.aliasId), versionId: String(existing.versionId), version: Number(existing.version), idempotentReplay: true };
+  const alias = await db.prepare(`SELECT status FROM model_aliases WHERE id = ?1 AND installation_id = 'default' LIMIT 1`).bind(aliasId).first<{ status: string }>();
+  if (!alias) throw new ApiError(404, "model_alias_not_found", "The model alias does not exist.");
+  if (alias.status === "archived") throw new ApiError(409, "model_alias_archived", "Archived model aliases cannot receive versions.");
+  await validateModelDependencies(db, input, aliasId);
+  const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM model_alias_versions WHERE alias_id = ?1`).bind(aliasId).first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const versionId = crypto.randomUUID();
+  const timestamp = now();
+  const response = { aliasId, versionId, version };
+  await db.batch([
+    modelVersionInsert(db, aliasId, versionId, version, input, session.actor.id, timestamp),
+    db.prepare(`UPDATE model_aliases SET active_version_id = ?2, status = 'active', updated_at = ?3 WHERE id = ?1`).bind(aliasId, versionId, timestamp),
+    mutation(db, idempotencyKey, "model_alias.version.publish", session.actor.id, versionId, response, timestamp),
+    audit(db, session, `model-alias-version:${idempotencyKey}`, "model_alias.version_published", "model_alias", aliasId, { versionId, version }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+async function validateAgentDependencies(db: D1Database, input: AgentVersionInput): Promise<void> {
+  const [prompt, model] = await Promise.all([
+    db.prepare(`SELECT id FROM prompt_versions WHERE id = ?1 AND installation_id = 'default' AND status = 'published' LIMIT 1`).bind(input.promptVersionId).first(),
+    db.prepare(`SELECT v.id FROM model_alias_versions v JOIN model_aliases a ON a.id = v.alias_id WHERE v.id = ?1 AND v.retired_at IS NULL AND a.status = 'active' LIMIT 1`).bind(input.modelAliasVersionId).first(),
+  ]);
+  if (!prompt) throw new ApiError(400, "agent_prompt_unavailable", "The prompt version is not published.");
+  if (!model) throw new ApiError(400, "agent_model_unavailable", "The model alias version is not active.");
+}
+
+function agentVersionInsert(db: D1Database, agentId: string, versionId: string, version: number, input: AgentVersionInput, actorId: string, timestamp: string): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO agent_versions (
+      id, agent_id, version, prompt_version_id, model_alias_version_id,
+      tool_manifest_json, memory_policy_json, maximum_turns, approval_policy_json,
+      input_schema_json, output_schema_json, published_at, created_by, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?12)
+  `).bind(
+    versionId, agentId, version, input.promptVersionId, input.modelAliasVersionId,
+    canonicalJson(input.toolManifest), canonicalJson(input.memoryPolicy), input.maximumTurns,
+    canonicalJson(input.approvalPolicy), canonicalJson(input.inputSchema),
+    canonicalJson(input.outputSchema), timestamp, actorId,
+  );
+}
+
+export async function listAgents(db: D1Database): Promise<Record<string, unknown>[]> {
+  const result = await db.prepare(`
+    SELECT a.id, a.agent_key AS key, a.name, a.description, a.agent_kind AS kind,
+      a.status, a.active_version_id AS activeVersionId, a.created_by AS createdBy,
+      a.created_at AS createdAt, a.updated_at AS updatedAt,
+      v.version, v.prompt_version_id AS promptVersionId,
+      v.model_alias_version_id AS modelAliasVersionId, v.tool_manifest_json AS toolManifestJson,
+      v.maximum_turns AS maximumTurns, v.published_at AS publishedAt
+    FROM agent_definitions a LEFT JOIN agent_versions v ON v.id = a.active_version_id
+    WHERE a.installation_id = 'default' ORDER BY a.name, a.id
+  `).all<Record<string, unknown>>();
+  return result.results.map((row) => ({ ...row, toolManifest: parsed(String(row.toolManifestJson ?? "[]"), []), toolManifestJson: undefined }));
+}
+
+export async function createAgent(db: D1Database, input: AgentCreateInput, session: OperatorSession, idempotencyKey: string): Promise<{ agentId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "agent.create", session.actor.id);
+  if (existing) return { agentId: String(existing.agentId), versionId: String(existing.versionId), version: Number(existing.version), idempotentReplay: true };
+  if (await db.prepare(`SELECT id FROM agent_definitions WHERE installation_id = 'default' AND agent_key = ?1`).bind(input.key).first()) throw new ApiError(409, "agent_key_exists", "An agent with this key already exists.");
+  await validateAgentDependencies(db, input.version);
+  const agentId = crypto.randomUUID();
+  const versionId = crypto.randomUUID();
+  const timestamp = now();
+  const response = { agentId, versionId, version: 1 };
+  await db.batch([
+    db.prepare(`INSERT INTO agent_definitions (id, installation_id, agent_key, name, description, agent_kind, status, active_version_id, created_by, created_at, updated_at) VALUES (?1, 'default', ?2, ?3, ?4, ?5, 'active', ?6, ?7, ?8, ?8)`)
+      .bind(agentId, input.key, input.name, input.description, input.kind, versionId, session.actor.id, timestamp),
+    agentVersionInsert(db, agentId, versionId, 1, input.version, session.actor.id, timestamp),
+    mutation(db, idempotencyKey, "agent.create", session.actor.id, agentId, response, timestamp),
+    audit(db, session, `agent:${idempotencyKey}`, "agent.created", "agent", agentId, { key: input.key, kind: input.kind, versionId }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function publishAgentVersion(db: D1Database, agentId: string, input: AgentVersionInput, session: OperatorSession, idempotencyKey: string): Promise<{ agentId: string; versionId: string; version: number; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "agent.version.publish", session.actor.id);
+  if (existing) return { agentId: String(existing.agentId), versionId: String(existing.versionId), version: Number(existing.version), idempotentReplay: true };
+  const agent = await db.prepare(`SELECT status FROM agent_definitions WHERE id = ?1 AND installation_id = 'default' LIMIT 1`).bind(agentId).first<{ status: string }>();
+  if (!agent) throw new ApiError(404, "agent_not_found", "The agent does not exist.");
+  if (agent.status === "archived") throw new ApiError(409, "agent_archived", "Archived agents cannot receive versions.");
+  await validateAgentDependencies(db, input);
+  const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM agent_versions WHERE agent_id = ?1`).bind(agentId).first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const versionId = crypto.randomUUID();
+  const timestamp = now();
+  const response = { agentId, versionId, version };
+  await db.batch([
+    agentVersionInsert(db, agentId, versionId, version, input, session.actor.id, timestamp),
+    db.prepare(`UPDATE agent_definitions SET active_version_id = ?2, status = 'active', updated_at = ?3 WHERE id = ?1`).bind(agentId, versionId, timestamp),
+    mutation(db, idempotencyKey, "agent.version.publish", session.actor.id, versionId, response, timestamp),
+    audit(db, session, `agent-version:${idempotencyKey}`, "agent.version_published", "agent", agentId, { versionId, version }, timestamp),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function listBudgets(db: D1Database): Promise<Record<string, unknown>[]> {
+  const result = await db.prepare(`
+    SELECT p.id, p.scope_type AS scopeType, p.scope_id AS scopeId, p.metric,
+      p.limit_value AS limitValue, p.window_seconds AS windowSeconds, p.behavior,
+      p.fallback_reference AS fallbackReference, p.published_at AS publishedAt,
+      p.retired_at AS retiredAt, p.created_by AS createdBy,
+      COALESCE((SELECT SUM(u.reserved_value) FROM budget_usage u WHERE u.policy_id = p.id), 0) AS reservedValue,
+      COALESCE((SELECT SUM(u.consumed_value) FROM budget_usage u WHERE u.policy_id = p.id), 0) AS consumedValue
+    FROM budget_policies p WHERE p.installation_id = 'default'
+    ORDER BY p.published_at DESC, p.id DESC
+  `).all<Record<string, unknown>>();
+  return result.results;
+}
+
+export async function publishBudget(db: D1Database, input: BudgetPublicationInput, session: OperatorSession, idempotencyKey: string): Promise<{ budgetPolicyId: string; idempotentReplay: boolean }> {
+  const existing = await replay(db, idempotencyKey, "budget.publish", session.actor.id);
+  if (existing) return { budgetPolicyId: String(existing.budgetPolicyId), idempotentReplay: true };
+  if (input.scopeType === "installation" && input.scopeId !== "default") throw new ApiError(400, "budget_scope_invalid", "Installation budgets must use the default installation ID.");
+  const budgetPolicyId = crypto.randomUUID();
+  const timestamp = now();
+  const response = { budgetPolicyId };
+  await db.batch([
+    db.prepare(`
+      INSERT INTO budget_policies (
+        id, installation_id, scope_type, scope_id, metric, limit_value,
+        window_seconds, behavior, fallback_reference, published_at, created_by, created_at
+      ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?9)
+    `).bind(budgetPolicyId, input.scopeType, input.scopeId, input.metric, input.limitValue, input.windowSeconds, input.behavior, input.fallbackReference, timestamp, session.actor.id),
+    mutation(db, idempotencyKey, "budget.publish", session.actor.id, budgetPolicyId, response, timestamp),
+    audit(db, session, `budget:${idempotencyKey}`, "budget.published", "budget_policy", budgetPolicyId, input, timestamp),
+  ]);
+  return { budgetPolicyId, idempotentReplay: false };
+}
+

package/template/src/api-cursor.ts

@@ -0,0 +1,84 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+interface CursorEnvelope {
+  v: 1;
+  scope: string;
+  position: Record<string, string | number | boolean | null>;
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+
+function base64UrlDecode(value: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]+$/u.test(value)) throw new Error("invalid_base64url");
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+  const binary = atob(padded);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+async function cursorKey(secret: string, usage: "sign" | "verify"): Promise<CryptoKey> {
+  if (encoder.encode(secret).byteLength < 32) throw new Error("Cursor signing secrets must contain at least 32 bytes.");
+  return crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage],
+  );
+}
+
+function invalidCursor(): ApiError {
+  return new ApiError(400, "cursor_invalid", "cursor is invalid or does not belong to this query.");
+}
+
+export async function encodeApiCursor(
+  secret: string,
+  scope: string,
+  position: Record<string, string | number | boolean | null>,
+): Promise<string> {
+  if (!scope || scope.length > 500) throw new Error("Cursor scope is invalid.");
+  const payload = base64UrlEncode(encoder.encode(canonicalJson({ v: 1, scope, position })));
+  const key = await cursorKey(secret, "sign");
+  const signature = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(payload)));
+  return `${payload}.${base64UrlEncode(signature)}`;
+}
+
+export async function decodeApiCursor<T extends Record<string, string | number | boolean | null>>(
+  secret: string,
+  scope: string,
+  cursor: string | null,
+): Promise<T | null> {
+  if (!cursor) return null;
+  if (cursor.length > 4_096) throw invalidCursor();
+  try {
+    const segments = cursor.split(".");
+    if (segments.length !== 2) throw new Error("invalid_segments");
+    const [payload, signature] = segments as [string, string];
+    const key = await cursorKey(secret, "verify");
+    const verified = await crypto.subtle.verify(
+      "HMAC",
+      key,
+      base64UrlDecode(signature),
+      encoder.encode(payload),
+    );
+    if (!verified) throw new Error("invalid_signature");
+    const decoded = JSON.parse(decoder.decode(base64UrlDecode(payload))) as unknown;
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) throw new Error("invalid_envelope");
+    const envelope = decoded as Partial<CursorEnvelope>;
+    if (envelope.v !== 1 || envelope.scope !== scope || !envelope.position
+      || typeof envelope.position !== "object" || Array.isArray(envelope.position)) {
+      throw new Error("invalid_envelope");
+    }
+    return envelope.position as T;
+  } catch (error) {
+    if (error instanceof ApiError) throw error;
+    throw invalidCursor();
+  }
+}