create-safest-tools 0.2.0

package/template/src/assistant.ts

@@ -0,0 +1,554 @@
+import { canonicalJson } from "./audit";
+import { BudgetControlError, reserveBudgets, settleBudgets } from "./budget-control";
+import { executeAssistantReadOnlyComponent } from "./component-executor";
+import { validateConfiguration, type ConfigurationType } from "./configuration-registry";
+import { assertOperatorQueueAccess, projectOperatorFields } from "./report-auth";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { OperatorPermissions, OperatorSession } from "./report-types";
+import type { JsonObject } from "./workflow-platform-types";
+import { parseWorkflowGraph, validateWorkflowGraph } from "./workflow-platform-validation";
+
+interface AssistantSessionRow {
+  id: string;
+  principalId: string;
+  status: string;
+  timezone: string;
+  expiresAt: string;
+}
+
+interface AssistantAnswer {
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolOutput: Record<string, unknown>;
+  body: string;
+  citations: Record<string, unknown>[];
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function permissionSnapshot(session: OperatorSession): Record<string, unknown> {
+  return {
+    actor_id: session.actor.id,
+    roles: session.roles,
+    permissions: Object.fromEntries(Object.entries(session.permissions).filter(([, enabled]) => enabled)),
+    queue_scope: session.queueScope ?? null,
+    field_scope: session.fieldScope ?? null,
+  };
+}
+
+function requirePermission(session: OperatorSession, permission: keyof OperatorPermissions): void {
+  if (!session.permissions[permission]) throw new ApiError(403, "assistant_tool_permission_denied", "This assistant tool is not available to your role.");
+}
+
+function localParts(date: Date, timezone: string): { year: number; month: number; day: number; hour: number; minute: number; second: number } {
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone: timezone,
+      year: "numeric", month: "2-digit", day: "2-digit",
+      hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23",
+    }).formatToParts(date);
+  } catch {
+    throw new ApiError(409, "assistant_timezone_invalid", "The installation timezone is invalid.");
+  }
+  const value = (type: string) => Number(parts.find((part) => part.type === type)?.value ?? 0);
+  return { year: value("year"), month: value("month"), day: value("day"), hour: value("hour"), minute: value("minute"), second: value("second") };
+}
+
+function zonedDateToUtc(parts: { year: number; month: number; day: number; hour?: number }, timezone: string): Date {
+  const desired = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour ?? 0, 0, 0, 0);
+  let guess = desired;
+  for (let index = 0; index < 3; index += 1) {
+    const current = localParts(new Date(guess), timezone);
+    const represented = Date.UTC(current.year, current.month - 1, current.day, current.hour, current.minute, current.second);
+    guess += desired - represented;
+  }
+  return new Date(guess);
+}
+
+function dayWindow(timezone: string, offsetDays: number): { from: string; to: string; label: string } {
+  const current = localParts(new Date(), timezone);
+  const date = new Date(Date.UTC(current.year, current.month - 1, current.day + offsetDays));
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth() + 1;
+  const day = date.getUTCDate();
+  const next = new Date(Date.UTC(year, month - 1, day + 1));
+  return {
+    from: zonedDateToUtc({ year, month, day }, timezone).toISOString(),
+    to: zonedDateToUtc({ year: next.getUTCFullYear(), month: next.getUTCMonth() + 1, day: next.getUTCDate() }, timezone).toISOString(),
+    label: `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`,
+  };
+}
+
+async function loadAssistantSession(db: D1Database, sessionId: string, principalId: string): Promise<AssistantSessionRow> {
+  const row = await db.prepare(`
+    SELECT id, principal_id AS principalId, status, timezone, expires_at AS expiresAt
+    FROM assistant_sessions WHERE id = ?1 AND principal_id = ?2 LIMIT 1
+  `).bind(sessionId, principalId).first<AssistantSessionRow>();
+  if (!row) throw new ApiError(404, "assistant_session_not_found", "The assistant session does not exist.");
+  if (row.status !== "active" || row.expiresAt <= now()) throw new ApiError(409, "assistant_session_inactive", "The assistant session is no longer active.");
+  return row;
+}
+
+export async function createAssistantSession(
+  db: D1Database,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ sessionId: string; timezone: string; expiresAt: string; idempotentReplay: boolean }> {
+  const existing = await db.prepare(`
+    SELECT id, timezone, expires_at AS expiresAt FROM assistant_sessions
+    WHERE principal_id = ?1 AND idempotency_key = ?2 LIMIT 1
+  `).bind(session.actor.id, idempotencyKey).first<{ id: string; timezone: string; expiresAt: string }>();
+  if (existing) return { sessionId: existing.id, timezone: existing.timezone, expiresAt: existing.expiresAt, idempotentReplay: true };
+  const installation = await db.prepare(`SELECT timezone FROM installations WHERE id = 'default' LIMIT 1`).first<{ timezone: string }>();
+  const timezone = installation?.timezone ?? "UTC";
+  localParts(new Date(), timezone);
+  const sessionId = crypto.randomUUID();
+  const createdAt = now();
+  const expiresAt = new Date(Date.now() + 8 * 3_600_000).toISOString();
+  await db.prepare(`
+    INSERT INTO assistant_sessions (
+      id, installation_id, principal_id, status, timezone,
+      created_at, updated_at, expires_at, idempotency_key
+    ) VALUES (?1, 'default', ?2, 'active', ?3, ?4, ?4, ?5, ?6)
+  `).bind(sessionId, session.actor.id, timezone, createdAt, expiresAt, idempotencyKey).run();
+  return { sessionId, timezone, expiresAt, idempotentReplay: false };
+}
+
+export async function loadAssistantHistory(
+  db: D1Database,
+  sessionId: string,
+  session: OperatorSession,
+): Promise<Record<string, unknown>> {
+  const assistantSession = await db.prepare(`
+    SELECT id, principal_id AS principalId, status, timezone,
+      created_at AS createdAt, updated_at AS updatedAt, expires_at AS expiresAt
+    FROM assistant_sessions WHERE id = ?1 AND principal_id = ?2 LIMIT 1
+  `).bind(sessionId, session.actor.id).first<Record<string, unknown>>();
+  if (!assistantSession) throw new ApiError(404, "assistant_session_not_found", "The assistant session does not exist.");
+  const [messages, tools] = await Promise.all([
+    db.prepare(`SELECT id, role, body, citations_json AS citationsJson, created_at AS createdAt FROM assistant_messages WHERE session_id = ?1 ORDER BY created_at, id LIMIT 500`)
+      .bind(sessionId).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, message_id AS messageId, tool_name AS toolName, input_json AS inputJson, output_summary_json AS outputSummaryJson, status, error_code AS errorCode, started_at AS startedAt, finished_at AS finishedAt FROM assistant_tool_calls WHERE session_id = ?1 ORDER BY started_at, id LIMIT 500`)
+      .bind(sessionId).all<Record<string, unknown>>(),
+  ]);
+  return {
+    session: assistantSession,
+    messages: messages.results.map((message) => ({ ...message, citations: JSON.parse(String(message.citationsJson ?? "[]")), citationsJson: undefined })),
+    toolCalls: tools.results.map((tool) => ({
+      ...tool,
+      input: tool.inputJson ? JSON.parse(String(tool.inputJson)) : null,
+      outputSummary: tool.outputSummaryJson ? JSON.parse(String(tool.outputSummaryJson)) : null,
+      inputJson: undefined,
+      outputSummaryJson: undefined,
+    })),
+  };
+}
+
+async function metricsAnswer(
+  db: D1Database,
+  prompt: string,
+  timezone: string,
+  session: OperatorSession,
+): Promise<AssistantAnswer> {
+  requirePermission(session, "readAnalytics");
+  const lowered = prompt.toLocaleLowerCase("en-US");
+  const window = lowered.includes("yesterday") ? dayWindow(timezone, -1) : lowered.includes("today") ? dayWindow(timezone, 0) : dayWindow(timezone, -1);
+  const phishing = /phish(?:ing)?|phising/u.test(lowered);
+  const resolved = /resolved|closed|actioned/u.test(lowered);
+  const row = await db.prepare(`
+    SELECT COUNT(*) AS count FROM reports
+    WHERE (?1 = 0 OR lower(reason_code) LIKE '%phish%')
+      AND (?2 = 0 OR state IN ('resolved_by_human','resolved_by_ai','closed'))
+      AND COALESCE(resolved_at, updated_at) >= ?3 AND COALESCE(resolved_at, updated_at) < ?4
+      AND (?5 = 1 OR queue_id IN (SELECT value FROM json_each(?6)))
+  `).bind(
+    phishing ? 1 : 0, resolved ? 1 : 0, window.from, window.to,
+    session.queueScope === null || session.queueScope === undefined ? 1 : 0,
+    canonicalJson(session.queueScope ?? []),
+  ).first<{ count: number }>();
+  const filters = { phishing, resolved, from: window.from, to: window.to, timezone, localDate: window.label, queueScope: session.queueScope ?? null };
+  const count = Number(row?.count ?? 0);
+  return {
+    toolName: "query_metrics",
+    toolInput: filters,
+    toolOutput: { count, filters },
+    body: `${count} report${count === 1 ? "" : "s"} matched for ${window.label} (${timezone}).`,
+    citations: [{ type: "metric_window", source: "reports", ...filters }],
+  };
+}
+
+async function findReportId(db: D1Database, prompt: string, explicit?: string): Promise<string | null> {
+  if (explicit) {
+    const row = await db.prepare(`SELECT id FROM reports WHERE id = ?1 OR public_reference = ?1 LIMIT 1`).bind(explicit).first<{ id: string }>();
+    return row?.id ?? null;
+  }
+  const candidates = prompt.match(/[A-Za-z0-9][A-Za-z0-9_-]{5,99}/gu) ?? [];
+  for (const candidate of candidates.slice(-10).reverse()) {
+    const row = await db.prepare(`SELECT id FROM reports WHERE id = ?1 OR public_reference = ?1 LIMIT 1`).bind(candidate).first<{ id: string }>();
+    if (row) return row.id;
+  }
+  return null;
+}
+
+async function explainAnswer(
+  db: D1Database,
+  prompt: string,
+  explicitReport: string | undefined,
+  session: OperatorSession,
+): Promise<AssistantAnswer> {
+  requirePermission(session, "readReports");
+  requirePermission(session, "readEvidence");
+  const reportId = await findReportId(db, prompt, explicitReport);
+  if (!reportId) throw new ApiError(400, "assistant_report_reference_required", "Include a report ID or public reference to explain.");
+  const report = await db.prepare(`SELECT id, public_reference AS publicReference, queue_id AS queueId, state, reason_code AS reasonCode, policy_version_id AS policyVersionId FROM reports WHERE id = ?1 LIMIT 1`)
+    .bind(reportId).first<{ id: string; publicReference: string; queueId: string | null; state: string; reasonCode: string; policyVersionId: string | null }>();
+  if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
+  assertOperatorQueueAccess(session, report.queueId);
+  const [decision, findings, actions, runs] = await Promise.all([
+    db.prepare(`SELECT id, decision_code AS decisionCode, policy_version_id AS policyVersionId, policy_code AS policyCode, rationale, evidence_references_json AS evidenceReferencesJson, maker_type AS makerType, maker_id AS makerId, created_at AS createdAt FROM decisions WHERE report_id = ?1 ORDER BY created_at DESC, id DESC LIMIT 1`).bind(report.id).first<Record<string, unknown>>(),
+    db.prepare(`SELECT id, finding_type AS findingType, status, confidence, summary, component_version_id AS componentVersionId, output_digest AS outputDigest, created_at AS createdAt FROM findings WHERE report_id = ?1 ORDER BY created_at DESC, id DESC LIMIT 20`).bind(report.id).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, action_code AS actionCode, state, payload_digest AS payloadDigest, component_version_id AS componentVersionId, created_at AS createdAt FROM action_proposals WHERE report_id = ?1 ORDER BY created_at DESC, id DESC LIMIT 20`).bind(report.id).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, workflow_version_id AS workflowVersionId, authority_mode AS authorityMode, state, created_at AS createdAt, finished_at AS finishedAt FROM workflow_runs WHERE report_id = ?1 ORDER BY created_at DESC, id DESC LIMIT 20`).bind(report.id).all<Record<string, unknown>>(),
+  ]);
+  const explanation = decision
+    ? `Report ${report.publicReference} is ${report.state}. The latest recorded decision was ${String(decision.decisionCode)} under policy ${String(decision.policyCode)}: ${String(decision.rationale)}`
+    : `Report ${report.publicReference} is ${report.state}. No immutable decision has been recorded yet.`;
+  const citations = [
+    { type: "report", id: report.id, reference: report.publicReference },
+    ...(decision ? [{ type: "decision", id: decision.id, policy_version_id: decision.policyVersionId }] : []),
+    ...findings.results.map((finding) => ({ type: "finding", id: finding.id, component_version_id: finding.componentVersionId, output_digest: finding.outputDigest })),
+    ...actions.results.map((action) => ({ type: "action_proposal", id: action.id, component_version_id: action.componentVersionId, payload_digest: action.payloadDigest })),
+    ...runs.results.map((run) => ({ type: "workflow_run", id: run.id, workflow_version_id: run.workflowVersionId })),
+  ];
+  return {
+    toolName: "get_decision_trace",
+    toolInput: { reportId: report.id },
+    toolOutput: projectOperatorFields(session, "assistant_report_trace", { report, decision, findings: findings.results, actions: actions.results, runs: runs.results }),
+    body: explanation,
+    citations,
+  };
+}
+
+async function searchAnswer(db: D1Database, prompt: string, session: OperatorSession): Promise<AssistantAnswer> {
+  requirePermission(session, "searchWorkspace");
+  const term = prompt.replace(/^(?:find|search|show)(?:\s+me)?(?:\s+reports?)?\s*/iu, "").trim().slice(0, 100);
+  if (term.length < 2) throw new ApiError(400, "assistant_search_term_required", "Include at least two characters to search reports.");
+  const pattern = `%${term.replace(/[%_]/gu, "")} %`.replace(/ %$/u, "%");
+  const result = await db.prepare(`
+    SELECT DISTINCT r.id, r.public_reference AS publicReference, r.state,
+      r.reason_code AS reasonCode, r.queue_id AS queueId, r.received_at AS receivedAt
+    FROM reports r LEFT JOIN report_targets t ON t.report_id = r.id
+    WHERE (lower(r.public_reference) LIKE lower(?1) OR lower(r.reason_code) LIKE lower(?1)
+      OR lower(COALESCE(t.target_reference, '')) LIKE lower(?1))
+      AND (?2 = 1 OR r.queue_id IN (SELECT value FROM json_each(?3)))
+    ORDER BY r.received_at DESC, r.id DESC LIMIT 20
+  `).bind(
+    pattern,
+    session.queueScope === null || session.queueScope === undefined ? 1 : 0,
+    canonicalJson(session.queueScope ?? []),
+  ).all<Record<string, unknown>>();
+  const reports = projectOperatorFields(session, "reports", result.results);
+  return {
+    toolName: "search_reports",
+    toolInput: { term, limit: 20, queueScope: session.queueScope ?? null },
+    toolOutput: { reports },
+    body: `I found ${result.results.length} accessible report${result.results.length === 1 ? "" : "s"} matching “${term}”.`,
+    citations: result.results.map((report) => ({ type: "report", id: report.id, reference: report.publicReference })),
+  };
+}
+
+async function freshEnrichmentAnswer(
+  env: Env,
+  prompt: string,
+  explicitReport: string | undefined,
+  session: OperatorSession,
+  componentVersionId: string,
+  componentInput: JsonObject,
+  operationId: string,
+): Promise<AssistantAnswer> {
+  requirePermission(session, "readReports");
+  requirePermission(session, "readEvidence");
+  requirePermission(session, "runEnrichments");
+  const reportId = await findReportId(env.DB, prompt, explicitReport);
+  if (!reportId) throw new ApiError(400, "assistant_report_reference_required", "A report reference is required for fresh enrichment.");
+  const report = await env.DB.prepare(`SELECT id, public_reference AS publicReference, queue_id AS queueId FROM reports WHERE id = ?1 LIMIT 1`)
+    .bind(reportId).first<{ id: string; publicReference: string; queueId: string | null }>();
+  if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
+  assertOperatorQueueAccess(session, report.queueId);
+  const result = await executeAssistantReadOnlyComponent(env, {
+    reportId: report.id,
+    componentVersionId,
+    componentInput,
+    operationId,
+    actorId: session.actor.id,
+  });
+  return {
+    toolName: "run_published_enrichment",
+    toolInput: { reportId: report.id, componentVersionId, input: componentInput },
+    toolOutput: { componentRunId: result.componentRunId, findingId: result.findingId, data: result.data },
+    body: `I ran the published read-only enrichment for ${report.publicReference} and stored finding ${result.findingId}. It did not execute any action or change the report decision.`,
+    citations: [
+      { type: "report", id: report.id, reference: report.publicReference },
+      { type: "component_version", id: componentVersionId },
+      { type: "component_run", id: result.componentRunId },
+      { type: "finding", id: result.findingId },
+    ],
+  };
+}
+
+type AssistantDraftType = "workflow" | "form" | "policy" | "template" | "routing_rules";
+
+async function configurationDraftAnswer(
+  db: D1Database,
+  assistantSession: AssistantSessionRow,
+  session: OperatorSession,
+  draft: { type: AssistantDraftType; targetId?: string; title: string; content: JsonObject },
+  operationId: string,
+): Promise<AssistantAnswer> {
+  const permission: keyof OperatorPermissions = draft.type === "workflow" ? "manageWorkflows"
+    : draft.type === "form" ? "manageForms"
+      : draft.type === "template" ? "manageTemplates"
+        : draft.type === "routing_rules" ? "manageRouting" : "managePolicies";
+  requirePermission(session, permission);
+  if (draft.title.trim().length < 3 || draft.title.length > 200) throw new ApiError(400, "assistant_draft_title_invalid", "Draft titles must contain 3 to 200 characters.");
+  if (draft.type === "workflow") {
+    const graph = parseWorkflowGraph(draft.content);
+    const validation = validateWorkflowGraph(graph);
+    if (!validation.valid) throw new ApiError(422, "assistant_workflow_draft_invalid", "The proposed workflow draft is invalid.", { errors: validation.errors });
+    if (!draft.targetId) throw new ApiError(400, "assistant_draft_target_required", "Workflow drafts require target_id.");
+    const target = await db.prepare(`SELECT id, purpose FROM workflow_definitions WHERE id = ?1 AND status != 'archived' LIMIT 1`).bind(draft.targetId).first<{ id: string; purpose: string }>();
+    if (!target || target.purpose !== graph.purpose) throw new ApiError(409, "assistant_workflow_target_invalid", "The target workflow is unavailable or has a different purpose.");
+  } else {
+    const validation = validateConfiguration(draft.type as ConfigurationType, draft.content);
+    if (!validation.valid) throw new ApiError(422, "assistant_configuration_draft_invalid", "The proposed configuration draft is invalid.", { errors: validation.errors });
+  }
+  const existing = await db.prepare(`SELECT id FROM assistant_drafts WHERE session_id = ?1 AND idempotency_key = ?2 LIMIT 1`)
+    .bind(assistantSession.id, operationId).first<{ id: string }>();
+  const draftId = existing?.id ?? crypto.randomUUID();
+  const contentJson = canonicalJson(draft.content);
+  if (!existing) await db.prepare(`
+    INSERT INTO assistant_drafts (
+      id, installation_id, session_id, principal_id, draft_type,
+      target_id, title, content_json, content_digest, status,
+      idempotency_key, created_at
+    ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'draft', ?9, ?10)
+  `).bind(
+    draftId, assistantSession.id, session.actor.id, draft.type, draft.targetId ?? null,
+    draft.title.trim(), contentJson, `sha256:${await sha256(contentJson)}`, operationId, now(),
+  ).run();
+  return {
+    toolName: "create_configuration_draft",
+    toolInput: { draftType: draft.type, targetId: draft.targetId ?? null, title: draft.title },
+    toolOutput: { draftId, status: "draft", publishable: false },
+    body: `I created unpublished ${draft.type.replace(/_/gu, " ")} draft ${draftId}. Adopting it only copies it into the normal editor; it cannot publish itself.`,
+    citations: [{ type: "assistant_draft", id: draftId, draft_type: draft.type, target_id: draft.targetId ?? null }],
+  };
+}
+
+async function answerPrompt(
+  env: Env,
+  prompt: string,
+  assistantSession: AssistantSessionRow,
+  session: OperatorSession,
+  explicitReport?: string,
+  componentVersionId?: string,
+  componentInput?: JsonObject,
+  operationId?: string,
+  draft?: { type: AssistantDraftType; targetId?: string; title: string; content: JsonObject },
+): Promise<AssistantAnswer> {
+  const db = env.DB;
+  if (draft && operationId) return configurationDraftAnswer(db, assistantSession, session, draft, operationId);
+  if (componentVersionId && componentInput && operationId) {
+    return freshEnrichmentAnswer(env, prompt, explicitReport, session, componentVersionId, componentInput, operationId);
+  }
+  const lowered = prompt.toLocaleLowerCase("en-US");
+  if (/\bhow many\b|\bcount\b|\bmetrics?\b/u.test(lowered)) return metricsAnswer(db, prompt, assistantSession.timezone, session);
+  if (/\bwhy\b|\bexplain\b|\brationale\b|\bdecision trace\b/u.test(lowered)) return explainAnswer(db, prompt, explicitReport, session);
+  if (/\bfind\b|\bsearch\b|\bshow\b/u.test(lowered)) return searchAnswer(db, prompt, session);
+  return {
+    toolName: "capability_help",
+    toolInput: {},
+    toolOutput: { supported: ["query_metrics", "search_reports", "get_decision_trace", "run_published_enrichment"] },
+    body: "I can count reports over an exact time window, search accessible reports, explain a report from stored records, or run an explicitly selected published read-only enrichment. Include a report reference for report-specific tools.",
+    citations: [],
+  };
+}
+
+export async function sendAssistantMessage(
+  env: Env,
+  sessionId: string,
+  input: {
+    body: string;
+    reportReference?: string;
+    componentVersionId?: string;
+    componentInput?: JsonObject;
+    draft?: { type: AssistantDraftType; targetId?: string; title: string; content: JsonObject };
+  },
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ userMessageId: string; assistantMessageId: string; toolCallId: string; body: string; citations: Record<string, unknown>[]; idempotentReplay: boolean }> {
+  const db = env.DB;
+  const existing = await db.prepare(`
+    SELECT u.id AS userMessageId, a.id AS assistantMessageId, a.body,
+      a.citations_json AS citationsJson, t.id AS toolCallId
+    FROM assistant_messages u JOIN assistant_messages a ON a.session_id = u.session_id
+      AND a.idempotency_key = u.idempotency_key || ':answer'
+    JOIN assistant_tool_calls t ON t.message_id = a.id
+    WHERE u.session_id = ?1 AND u.idempotency_key = ?2 LIMIT 1
+  `).bind(sessionId, idempotencyKey).first<{
+    userMessageId: string; assistantMessageId: string; body: string; citationsJson: string; toolCallId: string;
+  }>();
+  if (existing) return {
+    userMessageId: existing.userMessageId,
+    assistantMessageId: existing.assistantMessageId,
+    toolCallId: existing.toolCallId,
+    body: existing.body,
+    citations: JSON.parse(existing.citationsJson) as Record<string, unknown>[],
+    idempotentReplay: true,
+  };
+  const assistantSession = await loadAssistantSession(db, sessionId, session.actor.id);
+  const prompt = input.body.trim();
+  if (prompt.length < 2 || prompt.length > 8_000) throw new ApiError(400, "assistant_message_invalid", "Assistant messages must contain 2 to 8,000 characters.");
+  const userMessageId = crypto.randomUUID();
+  const assistantMessageId = crypto.randomUUID();
+  const toolCallId = crypto.randomUUID();
+  const startedAt = now();
+  let budgetReservations;
+  try {
+    budgetReservations = await reserveBudgets(db, {
+      installationId: "default",
+      scopes: [{ type: "assistant", id: sessionId }, { type: "assistant", id: session.actor.id }],
+      metric: "calls", amount: 1, operationType: "assistant_message",
+      operationId: `${sessionId}:${idempotencyKey}`, attemptId: "1",
+    });
+  } catch (error) {
+    if (error instanceof BudgetControlError) {
+      throw new ApiError(error.retryable ? 429 : 409, error.code, "The assistant budget is unavailable for this request.", {
+        retryable: error.retryable,
+        retry_after_seconds: error.delaySeconds,
+        fallback_reference: error.fallbackReference,
+      });
+    }
+    throw error;
+  }
+  let answer: AssistantAnswer;
+  try {
+    answer = await answerPrompt(
+      env,
+      prompt,
+      assistantSession,
+      session,
+      input.reportReference,
+      input.componentVersionId,
+      input.componentInput,
+      `${sessionId}:${idempotencyKey}`,
+      input.draft,
+    );
+  } catch (error) {
+    await db.prepare(`
+      INSERT INTO assistant_tool_calls (
+        id, session_id, tool_name, permission_snapshot_json, input_digest,
+        status, error_code, started_at, finished_at
+      ) VALUES (?1, ?2, 'request_router', ?3, ?4, 'denied', ?5, ?6, ?6)
+    `).bind(
+      toolCallId, sessionId, canonicalJson(permissionSnapshot(session)),
+      `sha256:${await sha256(canonicalJson({ prompt }))}`,
+      error instanceof ApiError ? error.code : "assistant_tool_failed", now(),
+    ).run();
+    await settleBudgets(db, budgetReservations, true);
+    throw error;
+  }
+  const inputJson = canonicalJson(answer.toolInput);
+  const outputJson = canonicalJson(answer.toolOutput);
+  const finishedAt = now();
+  const auditId = crypto.randomUUID();
+  try {
+    await db.batch([
+    db.prepare(`
+      INSERT INTO assistant_messages (id, session_id, role, body, citations_json, created_at, idempotency_key)
+      VALUES (?1, ?2, 'user', ?3, '[]', ?4, ?5)
+    `).bind(userMessageId, sessionId, prompt, startedAt, idempotencyKey),
+    db.prepare(`
+      INSERT INTO assistant_messages (
+        id, session_id, role, body, citations_json, created_at, idempotency_key
+      ) VALUES (?1, ?2, 'assistant', ?3, ?4, ?5, ?6)
+    `).bind(assistantMessageId, sessionId, answer.body, canonicalJson(answer.citations), finishedAt, `${idempotencyKey}:answer`),
+    db.prepare(`
+      INSERT INTO audit_events (
+        id, idempotency_key, action, actor_type, actor_id,
+        target_type, target_id, details_json, created_at
+      ) VALUES (?1, ?2, 'assistant.tool_called', ?3, ?4,
+        'assistant_session', ?5, ?6, ?7)
+    `).bind(
+      auditId, `assistant-tool:${sessionId}:${idempotencyKey}`,
+      session.actor.type, session.actor.id, sessionId,
+      canonicalJson({ toolName: answer.toolName, inputDigest: `sha256:${await sha256(inputJson)}`, outputDigest: `sha256:${await sha256(outputJson)}` }),
+      finishedAt,
+    ),
+    db.prepare(`
+      INSERT INTO assistant_tool_calls (
+        id, session_id, message_id, tool_name, permission_snapshot_json,
+        input_json, input_digest, output_summary_json, output_digest,
+        status, started_at, finished_at, audit_event_id
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, 'succeeded', ?10, ?11, ?12)
+    `).bind(
+      toolCallId, sessionId, assistantMessageId, answer.toolName,
+      canonicalJson(permissionSnapshot(session)), inputJson, `sha256:${await sha256(inputJson)}`,
+      outputJson, `sha256:${await sha256(outputJson)}`, startedAt, finishedAt, auditId,
+    ),
+    db.prepare(`UPDATE assistant_sessions SET updated_at = ?2 WHERE id = ?1 AND status = 'active'`).bind(sessionId, finishedAt),
+    ]);
+  } catch (error) {
+    await settleBudgets(db, budgetReservations, false);
+    throw error;
+  }
+  await settleBudgets(db, budgetReservations, true);
+  return { userMessageId, assistantMessageId, toolCallId, body: answer.body, citations: answer.citations, idempotentReplay: false };
+}
+
+export async function closeAssistantSession(db: D1Database, sessionId: string, session: OperatorSession): Promise<void> {
+  const result = await db.prepare(`UPDATE assistant_sessions SET status = 'closed', updated_at = ?3 WHERE id = ?1 AND principal_id = ?2 AND status = 'active'`)
+    .bind(sessionId, session.actor.id, now()).run();
+  if (result.meta.changes !== 1) throw new ApiError(404, "assistant_session_not_found", "The active assistant session does not exist.");
+}
+
+export async function loadAssistantToolCall(db: D1Database, toolCallId: string, session: OperatorSession): Promise<Record<string, unknown>> {
+  const row = await db.prepare(`
+    SELECT t.*, s.principal_id AS principalId FROM assistant_tool_calls t
+    JOIN assistant_sessions s ON s.id = t.session_id
+    WHERE t.id = ?1 AND s.principal_id = ?2 LIMIT 1
+  `).bind(toolCallId, session.actor.id).first<Record<string, unknown>>();
+  if (!row) throw new ApiError(404, "assistant_tool_call_not_found", "The assistant tool call does not exist.");
+  return row;
+}
+
+export async function loadAssistantDraft(db: D1Database, draftId: string, session: OperatorSession): Promise<Record<string, unknown>> {
+  const row = await db.prepare(`
+    SELECT id, draft_type AS draftType, target_id AS targetId, title,
+      content_json AS contentJson, content_digest AS contentDigest,
+      status, created_at AS createdAt, adopted_at AS adoptedAt,
+      adopted_target_id AS adoptedTargetId
+    FROM assistant_drafts WHERE id = ?1 AND principal_id = ?2 LIMIT 1
+  `).bind(draftId, session.actor.id).first<Record<string, unknown>>();
+  if (!row) throw new ApiError(404, "assistant_draft_not_found", "The assistant draft does not exist.");
+  return { ...row, content: JSON.parse(String(row.contentJson)), contentJson: undefined };
+}
+
+export async function markAssistantDraftAdopted(
+  db: D1Database,
+  draftId: string,
+  adoptedTargetId: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<void> {
+  const timestamp = now();
+  const changed = await db.prepare(`UPDATE assistant_drafts SET status = 'adopted', adopted_at = ?3, adopted_target_id = ?4 WHERE id = ?1 AND principal_id = ?2 AND status = 'draft'`)
+    .bind(draftId, session.actor.id, timestamp, adoptedTargetId).run();
+  if (changed.meta.changes !== 1) throw new ApiError(409, "assistant_draft_not_adoptable", "The assistant draft is no longer adoptable.");
+  await db.prepare(`INSERT INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'assistant.draft_adopted', ?3, ?4, 'assistant_draft', ?5, ?6, ?7)`)
+    .bind(crypto.randomUUID(), `assistant-draft-adopt:${idempotencyKey}`, session.actor.type, session.actor.id, draftId, canonicalJson({ adoptedTargetId }), timestamp).run();
+}

package/template/src/audit.ts

@@ -0,0 +1,39 @@
+export const AUDIT_GENESIS_HASH = "0".repeat(64);
+
+export interface AuditHashInput {
+  sequence: number;
+  action: string;
+  actorType: string;
+  actorId: string;
+  targetType: string;
+  targetId: string;
+  detailsJson: string;
+  previousHash: string;
+  createdAt: string;
+}
+
+export function canonicalJson(value: unknown): string {
+  if (value === undefined) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, child]) => child !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`).join(",")}}`;
+}
+
+export async function hashAuditEntry(input: AuditHashInput): Promise<string> {
+  const payload = canonicalJson({
+    sequence: input.sequence,
+    action: input.action,
+    actorType: input.actorType,
+    actorId: input.actorId,
+    targetType: input.targetType,
+    targetId: input.targetId,
+    detailsJson: input.detailsJson,
+    previousHash: input.previousHash,
+    createdAt: input.createdAt,
+  });
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(payload));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}