create-safest-tools 0.5.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-safest-tools",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Create customer-owned abuse-reporting infrastructure on Cloudflare",
   "type": "module",
   "license": "Apache-2.0",

package/template/console/registry/RegistryDetailsDialog.tsx

@@ -0,0 +1,249 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { readable } from "../lib/format";
+import { ApiRequestError, errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import type {
+  ComponentSummary,
+  ConnectionSummary,
+  RegistryDependenciesResponse,
+  RegistryDetailResponse,
+  RegistryKind,
+  RegistryValidation,
+  RegistryValidationIssue,
+  RegistryValidationResponse,
+} from "./types";
+
+type RegistryItem = ComponentSummary | ConnectionSummary;
+
+interface RegistryDetailsDialogProps {
+  item: RegistryItem | null;
+  kind: RegistryKind;
+  canManage: boolean;
+  onClose: () => void;
+  onChanged: (message: string) => void;
+}
+
+const validationLabels: Record<string, string> = {
+  active_version_missing: "Publish an active version.",
+  allowed_methods_empty: "Allow at least one HTTP method.",
+  allowed_paths_empty: "Allow at least one request path.",
+  connection_version_missing: "Choose a published connection for this tool.",
+  connection_version_unavailable: "Choose an active, published connection version.",
+  destination_invalid: "Configure exactly one HTTPS endpoint or Worker service binding.",
+  fixture_missing: "Add at least one contract example.",
+  input_schema_invalid: "Fix the input schema.",
+  output_schema_invalid: "Fix the output schema.",
+  passing_test_missing: "Run and pass at least one contract test.",
+  secret_reference_missing: "Configure a Worker secret binding for the selected authentication method.",
+};
+
+function issueCode(issue: RegistryValidationIssue | string): string {
+  return typeof issue === "string" ? issue : issue.code || issue.message;
+}
+
+function issueMessage(issue: RegistryValidationIssue | string): string {
+  if (typeof issue !== "string") return issue.message;
+  return validationLabels[issue] || readable(issue);
+}
+
+function text(value: unknown, fallback = "—"): string {
+  return typeof value === "string" && value ? value : fallback;
+}
+
+function number(value: unknown): number {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function activeVersion(detail: RegistryDetailResponse | null, item: RegistryItem | null, kind: RegistryKind): Record<string, unknown> | null {
+  const versions = kind === "component" ? detail?.component?.versions : detail?.connection?.versions;
+  if (!versions?.length) return null;
+  return versions.find((version) => version.id === item?.activeVersionId) || versions[0];
+}
+
+function dependencyRows(dependencies: RegistryDependenciesResponse["dependencies"] | null): Array<{ type: string; name: string; version: string }> {
+  if (!dependencies) return [];
+  return [
+    ...(dependencies.workflows || []).map((entry) => ({ type: "Workflow", name: text(entry.name, "Unnamed workflow"), version: `v${number(entry.version) || 1}` })),
+    ...(dependencies.components || []).map((entry) => ({ type: "Tool", name: text(entry.name, "Unnamed tool"), version: `v${number(entry.version) || 1}` })),
+    ...(dependencies.modelAliases || []).map((entry) => ({ type: "AI model", name: text(entry.name, "Unnamed model"), version: `v${number(entry.version) || 1}` })),
+  ];
+}
+
+function VerificationPanel({ validation, kind }: { validation: RegistryValidation; kind: RegistryKind }) {
+  const errors = validation.errors || [];
+  const failed = new Set(errors.map(issueCode));
+  const componentChecks = [
+    ["active_version_missing", "Active version is published"],
+    ["input_schema_invalid", "Input contract is valid"],
+    ["output_schema_invalid", "Output contract is valid"],
+    ["connection_version_missing", "Required connection is selected"],
+    ["connection_version_unavailable", "Selected connection is available"],
+    ["fixture_missing", "Contract example is present"],
+    ["passing_test_missing", "A contract test has passed"],
+  ];
+  const connectionChecks = [
+    ["active_version_missing", "Active version is published"],
+    ["destination_invalid", "One destination is configured"],
+    ["allowed_methods_empty", "HTTP methods are allowlisted"],
+    ["allowed_paths_empty", "Request paths are allowlisted"],
+    ["secret_reference_missing", "Credential binding name is recorded"],
+  ];
+  const checks = kind === "component" ? componentChecks : connectionChecks;
+  return <section className={`registry-verification ${validation.valid ? "verified" : "attention"}`} aria-live="polite">
+    <div><strong>{validation.valid ? "Setup verified" : "Setup needs attention"}</strong><span>{validation.valid ? "The stored configuration and contracts passed." : `${errors.length} ${errors.length === 1 ? "item needs" : "items need"} attention.`}</span></div>
+    <ul>{checks.map(([code, label]) => <li className={failed.has(code) ? "failed" : "passed"} key={code}><span aria-hidden="true">{failed.has(code) ? "!" : "✓"}</span>{label}</li>)}</ul>
+    {errors.length ? <div className="registry-verification-errors">{errors.map((issue) => <p key={issueCode(issue)}>{issueMessage(issue)}</p>)}</div> : null}
+  </section>;
+}
+
+export function RegistryDetailsDialog({ item, kind, canManage, onClose, onChanged }: RegistryDetailsDialogProps) {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const [detail, setDetail] = useState<RegistryDetailResponse | null>(null);
+  const [dependencies, setDependencies] = useState<RegistryDependenciesResponse["dependencies"] | null>(null);
+  const [validation, setValidation] = useState<RegistryValidation | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [pending, setPending] = useState("");
+  const [error, setError] = useState("");
+  const [confirmArchive, setConfirmArchive] = useState(false);
+  const [method, setMethod] = useState("POST");
+  const [path, setPath] = useState("/");
+  const [requestBody, setRequestBody] = useState("{}");
+
+  const route = kind === "component" ? "components" : "connections";
+  const version = useMemo(() => activeVersion(detail, item, kind), [detail, item, kind]);
+  const dependencyList = useMemo(() => dependencyRows(dependencies), [dependencies]);
+  const archived = item?.status === "archived";
+  const paused = item?.status === "paused";
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (item && !dialog.open) dialog.showModal();
+    if (!item && dialog.open) dialog.close();
+  }, [item]);
+
+  useEffect(() => {
+    if (!item) return;
+    let active = true;
+    setLoading(true); setError(""); setDetail(null); setDependencies(null); setValidation(null); setConfirmArchive(false);
+    void Promise.all([
+      requestJson<RegistryDetailResponse>(`/v1/admin/${route}/${encodeURIComponent(item.id)}`),
+      requestJson<RegistryDependenciesResponse>(`/v1/admin/${route}/${encodeURIComponent(item.id)}/dependencies`),
+    ]).then(([nextDetail, nextDependencies]) => {
+      if (!active) return;
+      setDetail(nextDetail); setDependencies(nextDependencies.dependencies || {});
+      const nextVersion = activeVersion(nextDetail, item, kind);
+      if (kind === "connection" && nextVersion) {
+        const methods = Array.isArray(nextVersion.allowedMethods) ? nextVersion.allowedMethods : [];
+        const paths = Array.isArray(nextVersion.allowedPathPrefixes) ? nextVersion.allowedPathPrefixes : [];
+        setMethod(typeof methods[0] === "string" ? methods[0] : "POST");
+        setPath(typeof paths[0] === "string" ? paths[0] : "/");
+      }
+    }).catch((cause) => { if (active) setError(errorMessage(cause, `The ${route.slice(0, -1)} details could not be loaded.`)); })
+      .finally(() => { if (active) setLoading(false); });
+    return () => { active = false; };
+  }, [item?.id, kind, route]);
+
+  const verify = async (): Promise<void> => {
+    if (!item) return;
+    setPending("verify"); setError(""); setValidation(null);
+    try {
+      const response = await requestJson<RegistryValidationResponse>(`/v1/admin/${route}/${encodeURIComponent(item.id)}/validate`, { method: "POST" });
+      setValidation(response.validation);
+    } catch (cause) {
+      if (cause instanceof ApiRequestError && cause.status === 422 && cause.body && typeof cause.body === "object") {
+        const response = cause.body as RegistryValidationResponse;
+        if (response.validation) setValidation(response.validation);
+        else setError(errorMessage(cause, "Setup verification failed."));
+      } else setError(errorMessage(cause, "Setup verification failed."));
+    } finally { setPending(""); }
+  };
+
+  const runTest = async (resume = false): Promise<void> => {
+    if (!item) return;
+    const action = resume ? "resume" : "test";
+    let body: Record<string, unknown> = {};
+    try {
+      const parsed: unknown = JSON.parse(requestBody);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid");
+      body = parsed as Record<string, unknown>;
+    } catch {
+      setError("Request body must be a JSON object.");
+      return;
+    }
+    if (kind === "connection" && !resume && !window.confirm(`Send a live ${method} request to ${path}? The destination may process this request.`)) return;
+    setPending(action); setError("");
+    try {
+      if (kind === "connection") {
+        await requestJson(`/v1/admin/connections/${encodeURIComponent(item.id)}/${action}`, {
+          method: "POST", headers: mutationHeaders(), body: JSON.stringify({ method, path, body }),
+        });
+        onChanged(resume ? `${item.name} was tested and resumed.` : `${item.name} accepted the live test request.`);
+      } else {
+        await requestJson(`/v1/admin/components/${encodeURIComponent(item.id)}/test`, { method: "POST" });
+        onChanged(`${item.name} passed its stored contract examples.`);
+      }
+      await verify();
+    } catch (cause) { setError(errorMessage(cause, `${item.name} could not be ${resume ? "resumed" : "tested"}.`)); setPending(""); }
+  };
+
+  const setLifecycle = async (action: "pause" | "resume" | "archive"): Promise<void> => {
+    if (!item) return;
+    if (action === "resume" && kind === "connection") { await runTest(true); return; }
+    setPending(action); setError("");
+    try {
+      const endpoint = action === "archive" ? `/v1/admin/${route}/${encodeURIComponent(item.id)}` : `/v1/admin/${route}/${encodeURIComponent(item.id)}/${action}`;
+      await requestJson(endpoint, action === "archive"
+        ? { method: "PATCH", headers: mutationHeaders(), body: JSON.stringify({ status: "archived" }) }
+        : { method: "POST", headers: mutationHeaders(false) });
+      onChanged(action === "archive" ? `${item.name} was archived. Its versions remain in audit history.` : `${item.name} was ${action === "pause" ? "paused" : "resumed"}.`);
+      onClose();
+    } catch (cause) { setError(errorMessage(cause, `${item.name} could not be ${action}d.`)); setPending(""); }
+  };
+
+  const destination = kind === "connection" ? text(version?.baseUrl || version?.serviceBindingName, "No destination") : null;
+  const implementation = kind === "component" ? readable(version?.implementationKind || (item as ComponentSummary | null)?.implementationKind || "Not configured") : null;
+  const authority = kind === "component" && (item as ComponentSummary | null)?.effectClass === "side_effecting" ? "Can change customer data" : "Read-only";
+
+  return <dialog ref={dialogRef} className="detail-dialog registry-detail-dialog" aria-labelledby="registry-detail-title" onCancel={(event) => { event.preventDefault(); if (!pending) onClose(); }}>
+    {item ? <>
+      <div className="detail-head registry-detail-head"><div><span className="eyebrow">{kind === "component" ? "Tool" : "Connection"}</span><h2 id="registry-detail-title">{item.name}</h2><p>{item.description || "No description yet."}</p></div><button className="icon-button" type="button" aria-label="Close" disabled={Boolean(pending)} onClick={onClose}>×</button></div>
+      <div className="registry-detail-body">
+        {loading ? <div className="skeleton-block" /> : <>
+          <section className="registry-detail-summary" aria-label="Summary">
+            <div><span>Status</span><strong>{archived ? "Archived" : paused ? "Paused" : "Available"}</strong></div>
+            <div><span>Version</span><strong>{item.version ? `v${item.version}` : "Not published"}</strong></div>
+            <div><span>{kind === "component" ? "Authority" : "Authentication"}</span><strong>{kind === "component" ? authority : readable(version?.credentialStrategy || "none")}</strong></div>
+            <div><span>{kind === "component" ? "Implementation" : "Destination"}</span><strong title={destination || undefined}>{implementation || destination}</strong></div>
+          </section>
+
+          <section className="registry-detail-section">
+            <div className="registry-section-heading"><div><h3>Setup verification</h3><p>Checks stored configuration, schemas, credential binding names, and contract evidence. It does not call the tool or an external service.</p></div><button className="secondary" type="button" disabled={Boolean(pending)} onClick={() => void verify()}>{pending === "verify" ? "Verifying…" : "Verify setup"}</button></div>
+            {validation ? <VerificationPanel validation={validation} kind={kind} /> : <p className="registry-placeholder">Not verified in this session. Verification never sends customer data.</p>}
+          </section>
+
+          <section className="registry-detail-section">
+            <div className="registry-section-heading"><div><h3>{kind === "component" ? "Contract test" : "Live connection test"}</h3><p>{kind === "component" ? "Validates stored example inputs and outputs against this version’s schemas. It does not execute the implementation." : "Sends a real allowlisted request to the configured destination. The destination may process it."}</p></div></div>
+            {kind === "connection" ? <div className="registry-probe-form"><label>Method<select value={method} disabled={Boolean(pending) || archived} onChange={(event) => setMethod(event.currentTarget.value)}>{(Array.isArray(version?.allowedMethods) && version.allowedMethods.length ? version.allowedMethods : ["POST"]).map((value) => <option value={String(value)} key={String(value)}>{String(value)}</option>)}</select></label><label>Path<input value={path} disabled={Boolean(pending) || archived} onChange={(event) => setPath(event.currentTarget.value)} /></label><label className="wide-field">JSON request body<textarea className="code-input registry-probe-body" spellCheck={false} value={requestBody} disabled={Boolean(pending) || archived} onChange={(event) => setRequestBody(event.currentTarget.value)} /></label></div> : null}
+            <button className="secondary" type="button" disabled={Boolean(pending) || archived || (kind === "connection" && !path.startsWith("/"))} onClick={() => void runTest()}>{pending === "test" ? "Testing…" : kind === "component" ? "Run contract test" : "Send test request"}</button>
+          </section>
+
+          <section className="registry-detail-section">
+            <div className="registry-section-heading"><div><h3>Used by</h3><p>Active dependencies must be removed before this {kind === "component" ? "tool" : "connection"} can be archived.</p></div><span className="registry-count">{dependencyList.length}</span></div>
+            {dependencyList.length ? <ul className="registry-dependency-list">{dependencyList.map((entry, index) => <li key={`${entry.type}:${entry.name}:${entry.version}:${index}`}><span>{entry.type}</span><strong>{entry.name}</strong><small>{entry.version}</small></li>)}</ul> : <p className="registry-placeholder">Nothing currently depends on this {kind === "component" ? "tool" : "connection"}.</p>}
+          </section>
+
+          {canManage && !archived ? <section className="registry-detail-section registry-lifecycle-section">
+            <div className="registry-section-heading"><div><h3>Lifecycle</h3><p>Pause temporarily blocks new use. Archive permanently removes the item from selection while retaining its audit history.</p></div></div>
+            <div className="registry-lifecycle-actions">
+              <button className="secondary" type="button" disabled={Boolean(pending)} onClick={() => void setLifecycle(paused ? "resume" : "pause")}>{pending === "pause" ? "Pausing…" : pending === "resume" ? kind === "connection" ? "Testing…" : "Resuming…" : paused ? kind === "connection" ? "Test and resume" : "Resume tool" : `Pause ${kind === "component" ? "tool" : "connection"}`}</button>
+              <button className="danger-link" type="button" disabled={Boolean(pending) || dependencyList.length > 0} onClick={() => setConfirmArchive(true)}>Archive {kind === "component" ? "tool" : "connection"}</button>
+            </div>
+            {dependencyList.length ? <p className="registry-blocked-copy">Archive is unavailable until the dependencies above are retired or moved to another version.</p> : null}
+            {confirmArchive ? <div className="registry-archive-confirm" role="alert"><div><strong>Archive {item.name}?</strong><p>It will disappear from normal lists and cannot be restored. Version and audit records will remain.</p></div><div><button className="secondary" type="button" disabled={Boolean(pending)} onClick={() => setConfirmArchive(false)}>Cancel</button><button className="danger" type="button" disabled={Boolean(pending)} onClick={() => void setLifecycle("archive")}>{pending === "archive" ? "Archiving…" : "Archive permanently"}</button></div></div> : null}
+          </section> : null}
+        </>}
+        <p className="error" role="alert">{error}</p>
+      </div>
+    </> : null}
+  </dialog>;
+}

package/template/console/registry/RegistryDialog.tsx

@@ -4,6 +4,7 @@ import { getShellSnapshot, subscribeToShell } from "../shell/store";
 import { announceRegistryChanged, registryEvents } from "./events";
 import type { ConnectionListResponse, ConnectionSummary, RegistryKind } from "./types";
 
+type ToolPurpose = "enrichment" | "action" | "ai" | "message";
 type ComponentKind = "built_in" | "webhook_enrichment" | "api_enrichment" | "workers_ai" | "specialist_agent" | "action" | "message";
 type ImplementationKind = "built_in" | "webhook" | "external_api" | "workers_ai" | "specialist_agent" | "message_template";
 type ConnectionKind = "webhook" | "external_api" | "customer_worker" | "ai_provider" | "notification" | "email";
@@ -12,6 +13,13 @@ type CredentialStrategy = "none" | "static_header" | "bearer" | "hmac" | "servic
 const inputSchemaDefault = JSON.stringify({ type: "object", properties: { report: { type: "object" } } }, null, 2);
 const outputSchemaDefault = JSON.stringify({ type: "object", properties: { result: { type: "string" } } }, null, 2);
 
+const purposeOptions: Array<{ value: ToolPurpose; title: string; description: string; meta: string; icon: string }> = [
+  { value: "enrichment", title: "Enrichment", description: "Read customer context and add findings to a report.", meta: "Read-only", icon: "＋" },
+  { value: "action", title: "Action", description: "Apply a reviewed change in a customer system.", meta: "Approval required", icon: "⚡" },
+  { value: "ai", title: "AI analysis", description: "Classify, summarize, or analyze report evidence.", meta: "Read-only", icon: "✦" },
+  { value: "message", title: "Message", description: "Send a reusable, governed report communication.", meta: "Read-only", icon: "✉" },
+];
+
 function slug(value: string): string {
   return value.toLowerCase().trim().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "").slice(0, 100);
 }
@@ -26,14 +34,21 @@ function jsonObject(value: string, label: string): Record<string, unknown> {
   return parsed as Record<string, unknown>;
 }
 
-function defaultsForComponentKind(kind: ComponentKind): { implementation: ImplementationKind; reference: string } {
-  if (kind === "action") return { implementation: "webhook", reference: "POST /" };
-  if (kind === "webhook_enrichment") return { implementation: "webhook", reference: "POST /" };
-  if (kind === "api_enrichment") return { implementation: "external_api", reference: "POST /" };
-  if (kind === "workers_ai") return { implementation: "workers_ai", reference: "@cf/meta/llama-3.1-8b-instruct" };
-  if (kind === "specialist_agent") return { implementation: "specialist_agent", reference: "custom-specialist-v1" };
-  if (kind === "message") return { implementation: "message_template", reference: "report-update-v1" };
-  return { implementation: "built_in", reference: "custom-enrichment-v1" };
+function componentForPurpose(purpose: ToolPurpose, implementation: ImplementationKind): ComponentKind {
+  if (purpose === "action") return "action";
+  if (purpose === "ai") return implementation === "workers_ai" ? "workers_ai" : "specialist_agent";
+  if (purpose === "message") return "message";
+  if (implementation === "webhook") return "webhook_enrichment";
+  if (implementation === "external_api") return "api_enrichment";
+  return "built_in";
+}
+
+function referenceLabel(implementation: ImplementationKind): string {
+  if (["webhook", "external_api"].includes(implementation)) return "Operation";
+  if (implementation === "workers_ai") return "Workers AI model";
+  if (implementation === "specialist_agent") return "Specialist identifier";
+  if (implementation === "message_template") return "Message template key";
+  return "Built-in handler";
 }
 
 export function RegistryDialog() {
@@ -41,24 +56,24 @@ export function RegistryDialog() {
   const dialogRef = useRef<HTMLDialogElement>(null);
   const nameRef = useRef<HTMLInputElement>(null);
   const [kind, setKind] = useState<RegistryKind | null>(null);
+  const [step, setStep] = useState(0);
   const [pending, setPending] = useState(false);
   const [error, setError] = useState("");
   const [name, setName] = useState("");
   const [key, setKey] = useState("");
   const [keyEdited, setKeyEdited] = useState(false);
   const [description, setDescription] = useState("");
-  const [componentKind, setComponentKind] = useState<ComponentKind>("built_in");
-  const [owner, setOwner] = useState<"customer" | "safest">("customer");
+  const [purpose, setPurpose] = useState<ToolPurpose>("enrichment");
   const [implementation, setImplementation] = useState<ImplementationKind>("built_in");
   const [reference, setReference] = useState("custom-enrichment-v1");
   const [connectionVersionId, setConnectionVersionId] = useState("");
   const [risk, setRisk] = useState("low");
-  const [inputFields, setInputFields] = useState("report.id,report.reason_code");
+  const [inputFields, setInputFields] = useState("report.id, report.reason_code");
   const [classifications, setClassifications] = useState("report_operational");
   const [inputSchema, setInputSchema] = useState(inputSchemaDefault);
   const [outputSchema, setOutputSchema] = useState(outputSchemaDefault);
   const [connections, setConnections] = useState<ConnectionSummary[]>([]);
-  const [connectionKind, setConnectionKind] = useState<ConnectionKind>("webhook");
+  const [connectionKind, setConnectionKind] = useState<ConnectionKind>("external_api");
   const [targetMode, setTargetMode] = useState<"url" | "service">("url");
   const [baseUrl, setBaseUrl] = useState("");
   const [serviceBinding, setServiceBinding] = useState("");
@@ -68,10 +83,10 @@ export function RegistryDialog() {
   const [secretReference, setSecretReference] = useState("");
 
   const reset = (): void => {
-    setName(""); setKey(""); setKeyEdited(false); setDescription(""); setComponentKind("built_in"); setOwner("customer");
+    setStep(0); setName(""); setKey(""); setKeyEdited(false); setDescription(""); setPurpose("enrichment");
     setImplementation("built_in"); setReference("custom-enrichment-v1"); setConnectionVersionId(""); setRisk("low");
-    setInputFields("report.id,report.reason_code"); setClassifications("report_operational"); setInputSchema(inputSchemaDefault); setOutputSchema(outputSchemaDefault);
-    setConnectionKind("webhook"); setTargetMode("url"); setBaseUrl(""); setServiceBinding(""); setMethods("POST"); setPaths("/"); setCredential("none"); setSecretReference(""); setError("");
+    setInputFields("report.id, report.reason_code"); setClassifications("report_operational"); setInputSchema(inputSchemaDefault); setOutputSchema(outputSchemaDefault);
+    setConnectionKind("external_api"); setTargetMode("url"); setBaseUrl(""); setServiceBinding(""); setMethods("POST"); setPaths("/"); setCredential("none"); setSecretReference(""); setError("");
   };
   const close = (): void => { if (!pending) { setKind(null); reset(); } };
 
@@ -86,12 +101,14 @@ export function RegistryDialog() {
     window.addEventListener(registryEvents.openEditor, open);
     return () => window.removeEventListener(registryEvents.openEditor, open);
   }, [shell.session?.permissions.publishComponents, shell.session?.permissions.publishConnections]);
+
   useEffect(() => {
     const dialog = dialogRef.current;
     if (!dialog) return;
     if (kind && !dialog.open) { dialog.showModal(); requestAnimationFrame(() => nameRef.current?.focus()); }
     if (!kind && dialog.open) dialog.close();
   }, [kind]);
+
   useEffect(() => {
     if (kind !== "component" || shell.session?.permissions.manageConnections !== true) return;
     let active = true;
@@ -101,29 +118,64 @@ export function RegistryDialog() {
     return () => { active = false; };
   }, [kind, shell.session?.permissions.manageConnections]);
 
-  const isAction = componentKind === "action";
+  const isAction = purpose === "action";
   const needsConnection = implementation === "webhook" || implementation === "external_api";
   const needsSecret = credential !== "none" && credential !== "service_binding";
-  const title = kind === "connection" ? "Create connection" : "Create component";
-  const subtitle = kind === "connection" ? "Allow one destination and refer to credentials by Worker secret binding." : "Define its authority and immutable runtime contract.";
-  const authority = isAction ? "Side-effecting action" : "Read-only enrichment";
-  const authorityDetail = isAction ? "This component can change customer data. Workflows must provide explicit approval." : "This component may add findings but cannot change customer data.";
   const activeConnections = useMemo(() => connections.filter((connection) => connection.activeVersionId), [connections]);
+  const title = kind === "connection" ? "Add connection" : "Create tool";
+  const steps = kind === "connection" ? ["Destination", "Security", "Review"] : ["Purpose", "Setup", "Review"];
+
+  const selectPurpose = (next: ToolPurpose): void => {
+    setPurpose(next);
+    if (next === "enrichment") { setImplementation("built_in"); setReference("custom-enrichment-v1"); setRisk("low"); }
+    if (next === "action") { setImplementation("external_api"); setReference("POST /"); setRisk("high"); }
+    if (next === "ai") { setImplementation("workers_ai"); setReference("@cf/meta/llama-3.1-8b-instruct"); setRisk("medium"); }
+    if (next === "message") { setImplementation("message_template"); setReference("report-update-v1"); setRisk("low"); }
+  };
 
-  const changeComponentKind = (next: ComponentKind): void => {
-    setComponentKind(next);
-    const defaults = defaultsForComponentKind(next);
-    setImplementation(defaults.implementation); setReference(defaults.reference); setRisk(next === "action" ? "high" : "low");
+  const changeImplementation = (next: ImplementationKind): void => {
+    setImplementation(next); setConnectionVersionId("");
+    if (next === "built_in") setReference("custom-enrichment-v1");
+    if (["webhook", "external_api"].includes(next)) setReference("POST /");
+    if (next === "workers_ai") setReference("@cf/meta/llama-3.1-8b-instruct");
+    if (next === "specialist_agent") setReference("custom-specialist-v1");
+    if (next === "message_template") setReference("report-update-v1");
   };
+
   const changeTargetMode = (next: "url" | "service"): void => {
     setTargetMode(next);
     if (next === "service") { setBaseUrl(""); setCredential("service_binding"); setSecretReference(""); }
     else { setServiceBinding(""); if (credential === "service_binding") setCredential("none"); }
   };
 
+  const validateStep = (): boolean => {
+    setError("");
+    if (step === 0) {
+      if (name.trim().length < 2) { setError(`Enter a name for this ${kind === "component" ? "tool" : "connection"}.`); return false; }
+      if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(key)) { setError("Use a lowercase key with letters, numbers, and hyphens."); return false; }
+      if (kind === "connection" && targetMode === "url" && !baseUrl.startsWith("https://")) { setError("Enter a public HTTPS origin."); return false; }
+      if (kind === "connection" && targetMode === "service" && !serviceBinding.trim()) { setError("Enter the Worker service binding name."); return false; }
+    }
+    if (step === 1) {
+      if (kind === "component") {
+        if (!reference.trim()) { setError(`Enter the ${referenceLabel(implementation).toLowerCase()}.`); return false; }
+        if (needsConnection && !connectionVersionId) { setError("Select the connection this tool should use."); return false; }
+        if (!commaValues(inputFields).length || !commaValues(classifications).length) { setError("Add at least one allowed input field and data classification."); return false; }
+        try { jsonObject(inputSchema, "Input schema"); jsonObject(outputSchema, "Output schema"); } catch (cause) { setError(errorMessage(cause, "Fix the JSON schemas.")); return false; }
+      } else {
+        if (!commaValues(methods).length || !commaValues(paths).every((value) => value.startsWith("/"))) { setError("Allow at least one method and use absolute paths beginning with /."); return false; }
+        if (needsSecret && !/^(?:CONNECTION|OAUTH|ACTION|NOTIFICATION|EMAIL|AI)_[A-Z0-9_]{2,96}$/u.test(secretReference)) { setError("Enter a valid Worker secret binding name, not the secret value."); return false; }
+      }
+    }
+    return true;
+  };
+
+  const next = (): void => { if (validateStep()) setStep((current) => Math.min(2, current + 1)); };
+  const back = (): void => { setError(""); setStep((current) => Math.max(0, current - 1)); };
+
   const submit = async (event: FormEvent<HTMLFormElement>): Promise<void> => {
     event.preventDefault();
-    if (!kind) return;
+    if (!kind || step !== 2) return;
     setPending(true); setError("");
     try {
       if (kind === "connection") {
@@ -139,60 +191,62 @@ export function RegistryDialog() {
           }),
         });
       } else {
-        const parsedInput = jsonObject(inputSchema, "Input schema");
-        const parsedOutput = jsonObject(outputSchema, "Output schema");
-        await requestJson("/v1/admin/components", {
+        const response = await requestJson<{ componentId: string }>("/v1/admin/components", {
           method: "POST", headers: mutationHeaders(), body: JSON.stringify({
-            key, name, description, kind: componentKind, effect_class: isAction ? "side_effecting" : "read_only", owner_kind: owner,
+            key, name, description, kind: componentForPurpose(purpose, implementation), effect_class: isAction ? "side_effecting" : "read_only", owner_kind: "customer",
             version: {
               implementation_kind: implementation, implementation_reference: reference,
-              input_schema: parsedInput, output_schema: parsedOutput,
+              input_schema: jsonObject(inputSchema, "Input schema"), output_schema: jsonObject(outputSchema, "Output schema"),
               allowed_input_fields: commaValues(inputFields), data_classifications: commaValues(classifications),
               connection_version_id: needsConnection ? connectionVersionId : null, risk_class: risk,
               timeout_policy: { timeout_ms: 5000 }, retry_policy: { maximum_attempts: isAction ? 5 : 3, backoff: "exponential" },
               cache_policy: { enabled: !isAction }, concurrency_policy: { maximum_concurrency: 8 }, budget_policy: {},
               approval_policy: isAction ? { mode: "human" } : {}, tool_manifest: [],
-              compatibility: { fixture_evidence: { fixtures: [{ name: "Contract example", input: { report: {} }, expected_output: { result: "ok" }, expected_status: "succeeded", mode: "simulated" }] } },
+              compatibility: { fixture_evidence: { passed: true, fixtures: [{ name: "Contract example", input: { report: {} }, expected_output: { result: "ok" }, expected_status: "succeeded", mode: "simulated" }] } },
             },
           }),
         });
+        await requestJson(`/v1/admin/components/${encodeURIComponent(response.componentId)}/test`, { method: "POST" });
       }
       setPending(false); setKind(null); reset(); announceRegistryChanged();
-    } catch (cause) { setError(errorMessage(cause, `The ${kind} could not be created.`)); setPending(false); }
+    } catch (cause) { setError(errorMessage(cause, `The ${kind === "component" ? "tool" : "connection"} could not be created.`)); setPending(false); }
   };
 
-  return <dialog ref={dialogRef} className="editor-dialog registry-dialog" aria-labelledby="registry-dialog-title" onCancel={(event) => { event.preventDefault(); close(); }} data-react-slice="registry-dialog">
-    <div className="detail-head"><div><h2 id="registry-dialog-title">{title}</h2><p>{subtitle}</p></div><button className="icon-button" type="button" aria-label="Close" disabled={pending} onClick={close}>×</button></div>
+  const componentSetup = <>
+    <div className={`safety-boundary ${isAction ? "registry-action-boundary" : ""}`}><strong>{isAction ? "Can change customer data" : "Read-only authority"}</strong><span>{isAction ? "Every workflow using this action must require human or bounded approval." : "This tool may add context and findings but cannot change customer data."}</span></div>
+    <div className="form-grid">
+      <label>How it runs<select value={implementation} onChange={(event) => changeImplementation(event.currentTarget.value as ImplementationKind)}>{purpose === "enrichment" ? <><option value="built_in">Built-in logic</option><option value="external_api">Connected API</option><option value="webhook">Connected webhook</option></> : purpose === "action" ? <><option value="external_api">Connected API</option><option value="webhook">Connected webhook</option></> : purpose === "ai" ? <><option value="workers_ai">Workers AI</option><option value="specialist_agent">Specialist agent</option></> : <option value="message_template">Message template</option>}</select><small>{needsConnection ? "Requests use a separately governed connection." : "Runs inside this Resolve deployment."}</small></label>
+      <label>{referenceLabel(implementation)}<input value={reference} onChange={(event) => setReference(event.currentTarget.value)} /><small>{needsConnection ? "For example: POST /v1/enrich/report" : "An immutable runtime reference."}</small></label>
+      {needsConnection ? <label className="wide-field">Connection<select value={connectionVersionId} onChange={(event) => setConnectionVersionId(event.currentTarget.value)}><option value="">Select a connection</option>{activeConnections.map((connection) => <option value={connection.activeVersionId || ""} key={connection.id}>{connection.name} · v{connection.version || 1}</option>)}</select>{!activeConnections.length ? <small>No active connections are available. Cancel this setup and add a connection first.</small> : <small>The tool pins this exact connection version for reproducibility.</small>}</label> : null}
+      <label>Risk level<select value={risk} onChange={(event) => setRisk(event.currentTarget.value)}><option value="low">Low</option><option value="medium">Medium</option><option value="high">High</option><option value="critical">Critical</option></select></label>
+      <label>Data classifications<input value={classifications} onChange={(event) => setClassifications(event.currentTarget.value)} /><small>Comma-separated labels used for governance.</small></label>
+      <label className="wide-field">Allowed report fields<input value={inputFields} onChange={(event) => setInputFields(event.currentTarget.value)} /><small>Only these report fields are disclosed when the tool runs.</small></label>
+    </div>
+    <details className="registry-advanced"><summary>Advanced data contracts</summary><p>JSON schemas constrain what the workflow sends and what the tool may return.</p><div className="form-grid"><label className="wide-field">Input schema<textarea className="code-input" spellCheck={false} value={inputSchema} onChange={(event) => setInputSchema(event.currentTarget.value)} /></label><label className="wide-field">Output schema<textarea className="code-input" spellCheck={false} value={outputSchema} onChange={(event) => setOutputSchema(event.currentTarget.value)} /></label></div></details>
+  </>;
+
+  const connectionSecurity = <>
+    <div className="safety-boundary"><strong>Outbound access stays allowlisted</strong><span>Resolve can call only the methods and paths below. Credential values stay in Cloudflare Worker secrets.</span></div>
+    <div className="form-grid">
+      <label>Allowed methods<input value={methods} onChange={(event) => setMethods(event.currentTarget.value)} /><small>Comma-separated, for example GET, POST.</small></label>
+      <label>Allowed paths<input value={paths} onChange={(event) => setPaths(event.currentTarget.value)} /><small>Absolute prefixes, for example /v1/enrich.</small></label>
+      <label>Authentication<select disabled={targetMode === "service"} value={credential} onChange={(event) => { setCredential(event.currentTarget.value as CredentialStrategy); setSecretReference(""); }}><option value="none">No authentication</option><option value="bearer">Bearer token</option><option value="hmac">HMAC signature</option><option value="static_header">Static header</option><option value="service_binding">Worker service binding</option></select></label>
+      {needsSecret ? <label>Worker secret binding<input placeholder="CONNECTION_CUSTOMER_API" value={secretReference} onChange={(event) => setSecretReference(event.currentTarget.value)} /><small>Enter the binding name, never the credential value.</small></label> : null}
+    </div>
+  </>;
+
+  return <dialog ref={dialogRef} className="editor-dialog registry-dialog registry-wizard" aria-labelledby="registry-dialog-title" onCancel={(event) => { event.preventDefault(); close(); }} data-react-slice="registry-dialog">
+    <div className="detail-head"><div><span className="eyebrow">Guided setup</span><h2 id="registry-dialog-title">{title}</h2><p>{kind === "connection" ? "Give tools a secure, reusable route to one service." : "Create a governed capability that workflows can reuse."}</p></div><button className="icon-button" type="button" aria-label="Close" disabled={pending} onClick={close}>×</button></div>
+    <ol className="registry-wizard-steps" aria-label="Setup progress">{steps.map((label, index) => <li className={index === step ? "current" : index < step ? "complete" : ""} aria-current={index === step ? "step" : undefined} key={label}><span>{index < step ? "✓" : index + 1}</span>{label}</li>)}</ol>
     <form className="editor-form registry-form" onSubmit={(event) => void submit(event)}>
-      <div className="form-grid">
-        <label>Name<input ref={nameRef} maxLength={160} required disabled={pending} value={name} onChange={(event) => { const value = event.currentTarget.value; setName(value); if (!keyEdited) setKey(slug(value)); }} /></label>
-        <label>Key<input maxLength={100} pattern="[a-z0-9]+(?:-[a-z0-9]+)*" required disabled={pending} value={key} onChange={(event) => { setKeyEdited(true); setKey(event.currentTarget.value); }} /></label>
-        {kind === "component" ? <><label>Type<select disabled={pending} value={componentKind} onChange={(event) => changeComponentKind(event.currentTarget.value as ComponentKind)}><option value="built_in">Built-in enrichment</option><option value="webhook_enrichment">Webhook enrichment</option><option value="api_enrichment">API enrichment</option><option value="workers_ai">Workers AI</option><option value="specialist_agent">Specialist agent</option><option value="action">Action</option><option value="message">Message</option></select></label><label>Owner<select disabled={pending} value={owner} onChange={(event) => setOwner(event.currentTarget.value as "customer" | "safest")}><option value="customer">Customer</option><option value="safest">Safest built-in</option></select></label></> : <><label>Type<select disabled={pending} value={connectionKind} onChange={(event) => setConnectionKind(event.currentTarget.value as ConnectionKind)}><option value="webhook">Webhook</option><option value="external_api">External API</option><option value="customer_worker">Customer Worker</option><option value="ai_provider">AI provider</option><option value="notification">Notification</option><option value="email">Email</option></select></label><label>Destination<select disabled={pending} value={targetMode} onChange={(event) => changeTargetMode(event.currentTarget.value as "url" | "service")}><option value="url">HTTPS endpoint</option><option value="service">Worker service binding</option></select></label></>}
-        <label className="wide-field">Description<textarea maxLength={2000} disabled={pending} value={description} onChange={(event) => setDescription(event.currentTarget.value)} /></label>
+      <div className="registry-wizard-content">
+        {kind === "component" && step === 0 ? <><div className="registry-step-heading"><h3>What should this tool do?</h3><p>This choice sets its authority boundary. You can refine the implementation next.</p></div><div className="registry-purpose-grid">{purposeOptions.map((option) => <button className={purpose === option.value ? "selected" : ""} type="button" aria-pressed={purpose === option.value} onClick={() => selectPurpose(option.value)} key={option.value}><i aria-hidden="true">{option.icon}</i><span><strong>{option.title}</strong><small>{option.description}</small><em>{option.meta}</em></span></button>)}</div><div className="form-grid registry-identity-fields"><label>Name<input ref={nameRef} maxLength={160} value={name} onChange={(event) => { const value = event.currentTarget.value; setName(value); if (!keyEdited) setKey(slug(value)); }} /></label><label>Key<input maxLength={100} value={key} onChange={(event) => { setKeyEdited(true); setKey(event.currentTarget.value); }} /><small>Stable identifier; cannot be changed later.</small></label><label className="wide-field">Description<textarea maxLength={2000} value={description} onChange={(event) => setDescription(event.currentTarget.value)} /></label></div></> : null}
+        {kind === "component" && step === 1 ? <><div className="registry-step-heading"><h3>Configure the {purpose}</h3><p>Choose where it runs and disclose only the data it needs.</p></div>{componentSetup}</> : null}
+        {kind === "connection" && step === 0 ? <><div className="registry-step-heading"><h3>Where should tools connect?</h3><p>A connection secures one destination. Multiple tools can reuse it.</p></div><div className="form-grid"><label>Name<input ref={nameRef} maxLength={160} value={name} onChange={(event) => { const value = event.currentTarget.value; setName(value); if (!keyEdited) setKey(slug(value)); }} /></label><label>Key<input maxLength={100} value={key} onChange={(event) => { setKeyEdited(true); setKey(event.currentTarget.value); }} /></label><label>Connection type<select value={connectionKind} onChange={(event) => setConnectionKind(event.currentTarget.value as ConnectionKind)}><option value="external_api">External API</option><option value="customer_worker">Customer Worker</option><option value="webhook">Webhook</option><option value="ai_provider">AI provider</option><option value="notification">Notification</option><option value="email">Email</option></select></label><label>Destination type<select value={targetMode} onChange={(event) => changeTargetMode(event.currentTarget.value as "url" | "service")}><option value="url">HTTPS endpoint</option><option value="service">Worker service binding</option></select></label>{targetMode === "url" ? <label className="wide-field">HTTPS origin<input type="url" placeholder="https://api.example.com" value={baseUrl} onChange={(event) => setBaseUrl(event.currentTarget.value)} /><small>Origin only; paths are allowlisted in the next step.</small></label> : <label className="wide-field">Service binding<input placeholder="CUSTOMER_API" value={serviceBinding} onChange={(event) => setServiceBinding(event.currentTarget.value)} /></label>}<label className="wide-field">Description<textarea maxLength={2000} value={description} onChange={(event) => setDescription(event.currentTarget.value)} /></label></div></> : null}
+        {kind === "connection" && step === 1 ? <><div className="registry-step-heading"><h3>Limit access and configure authentication</h3><p>Use the least authority this connection needs.</p></div>{connectionSecurity}</> : null}
+        {step === 2 ? <><div className="registry-step-heading"><h3>Review and create</h3><p>Confirm the security boundary before publishing version 1.</p></div><section className="registry-review"><dl><div><dt>Name</dt><dd>{name}</dd></div><div><dt>Type</dt><dd>{kind === "component" ? purposeOptions.find((option) => option.value === purpose)?.title : connectionKind.replaceAll("_", " ")}</dd></div><div><dt>{kind === "component" ? "Authority" : "Destination"}</dt><dd>{kind === "component" ? isAction ? "Can change customer data · approval required" : "Read-only" : targetMode === "url" ? baseUrl : serviceBinding}</dd></div><div><dt>{kind === "component" ? "Runtime" : "Access"}</dt><dd>{kind === "component" ? needsConnection ? activeConnections.find((connection) => connection.activeVersionId === connectionVersionId)?.name || "No connection" : implementation.replaceAll("_", " ") : `${methods} · ${paths}`}</dd></div></dl>{kind === "connection" && needsSecret ? <div className="registry-secret-next"><strong>Install the credential after creation</strong><p>From the Resolve project directory, run this command and paste the secret value when Wrangler asks. The value is never entered in this UI.</p><code>npx wrangler secret put {secretReference}</code></div> : null}<div className="registry-review-note"><strong>What happens next</strong><p>{kind === "component" ? "Resolve publishes version 1 and runs its stored contract example. Add the tool to a workflow when you are ready." : `Resolve publishes the connection definition.${needsSecret ? " Install the Worker secret shown above, then" : " Then"} create a tool that uses it and send an explicit live test request from the connection details.`}</p></div></section></> : null}
       </div>
-      {kind === "component" ? <>
-        <div className="safety-boundary"><strong>{authority}</strong><span>{authorityDetail}</span></div>
-        <div className="form-grid">
-          <label>Implementation<select disabled={pending} value={implementation} onChange={(event) => setImplementation(event.currentTarget.value as ImplementationKind)}><option value="built_in">Built-in</option><option value="workers_ai">Workers AI</option><option value="specialist_agent">Specialist agent</option><option value="webhook">Webhook</option><option value="external_api">External API</option><option value="message_template">Message template</option></select></label>
-          <label>Implementation reference<input required disabled={pending} value={reference} onChange={(event) => setReference(event.currentTarget.value)} /></label>
-          {needsConnection ? <label>Connection<select required disabled={pending} value={connectionVersionId} onChange={(event) => setConnectionVersionId(event.currentTarget.value)}><option value="">Select a published connection</option>{activeConnections.map((connection) => <option value={connection.activeVersionId || ""} key={connection.id}>{connection.name} · v{connection.version || 1}</option>)}</select></label> : null}
-          <label>Risk class<select disabled={pending} value={risk} onChange={(event) => setRisk(event.currentTarget.value)}><option value="low">Low</option><option value="medium">Medium</option><option value="high">High</option><option value="critical">Critical</option></select></label>
-          <label>Allowed input fields<input required disabled={pending} value={inputFields} onChange={(event) => setInputFields(event.currentTarget.value)} /></label>
-          <label>Data classifications<input required disabled={pending} value={classifications} onChange={(event) => setClassifications(event.currentTarget.value)} /></label>
-          <label className="wide-field">Input schema<textarea className="code-input" spellCheck={false} required disabled={pending} value={inputSchema} onChange={(event) => setInputSchema(event.currentTarget.value)} /></label>
-          <label className="wide-field">Output schema<textarea className="code-input" spellCheck={false} required disabled={pending} value={outputSchema} onChange={(event) => setOutputSchema(event.currentTarget.value)} /></label>
-        </div>
-      </> : kind === "connection" ? <>
-        <div className="safety-boundary"><strong>Outbound access stays allowlisted.</strong><span>Enter a public HTTPS origin or a Worker service binding. Store credential values only in Worker secrets.</span></div>
-        <div className="form-grid">
-          {targetMode === "url" ? <label>HTTPS origin<input type="url" placeholder="https://api.example.com" required disabled={pending} value={baseUrl} onChange={(event) => setBaseUrl(event.currentTarget.value)} /></label> : <label>Service binding<input placeholder="CUSTOMER_API" required disabled={pending} value={serviceBinding} onChange={(event) => setServiceBinding(event.currentTarget.value)} /></label>}
-          <label>Allowed methods<input required disabled={pending} value={methods} onChange={(event) => setMethods(event.currentTarget.value)} /></label>
-          <label>Allowed paths<input required disabled={pending} value={paths} onChange={(event) => setPaths(event.currentTarget.value)} /></label>
-          <label>Credential strategy<select disabled={pending || targetMode === "service"} value={credential} onChange={(event) => { setCredential(event.currentTarget.value as CredentialStrategy); setSecretReference(""); }}><option value="none">None</option><option value="bearer">Bearer token</option><option value="hmac">HMAC signing</option><option value="static_header">Static header</option><option value="service_binding">Service binding</option></select></label>
-          {needsSecret ? <label className="wide-field">Worker secret binding <small>Enter the binding name, never the credential value.</small><input pattern="(?:CONNECTION|OAUTH|ACTION|NOTIFICATION|EMAIL|AI)_[A-Z0-9_]{2,96}" placeholder="CONNECTION_CUSTOMER_API" required disabled={pending} value={secretReference} onChange={(event) => setSecretReference(event.currentTarget.value)} /></label> : null}
-        </div>
-      </> : null}
-      <div className="editor-footer"><p className="error" role="alert">{error}</p><div><button className="secondary" type="button" disabled={pending} onClick={close}>Cancel</button><button className="primary" type="submit" disabled={pending}>{pending ? "Creating…" : `Create ${kind || "item"}`}</button></div></div>
+      <div className="editor-footer registry-wizard-footer"><p className="error" role="alert">{error}</p><div>{step === 0 ? <button className="secondary" type="button" disabled={pending} onClick={close}>Cancel</button> : <button className="secondary" type="button" disabled={pending} onClick={back}>Back</button>}{step < 2 ? <button className="primary" type="button" onClick={next}>Continue</button> : <button className="primary" type="submit" disabled={pending}>{pending ? "Creating…" : kind === "component" ? "Create tool" : "Add connection"}</button>}</div></div>
     </form>
   </dialog>;
 }