@ai-matrx/chat 0.1.74 → 0.2.0

package/dist/surfaces/runtime/surface-writeback.js

@@ -0,0 +1,1241 @@
+"use client";
+import { contentIrKindValidator } from "../../host/content-ir-slots.js";
+import { getManifest } from "./registry.js";
+import {
+  isSurfaceWritePatch,
+  resolveSurfaceWritePatch
+} from "./surface-write-patch.js";
+import { captureError } from "../../host/diagnostics.js";
+import {
+  applyWindowFormChanges,
+  hasWindowForms,
+  labelWindowFormWrite,
+  WINDOW_FORM_TARGET,
+  WINDOW_FORM_TARGET_NAME
+} from "./window-forms.js";
+import {
+  readActiveOrganizationId,
+  saveSurfaceFeedback,
+  SURFACE_FEEDBACK_TARGET,
+  SURFACE_FEEDBACK_TARGET_NAME,
+  validateSurfaceFeedback
+} from "./surface-feedback.js";
+import {
+  applyCustomFieldsSetWrite,
+  applyCustomFieldsWrite,
+  CUSTOM_FIELDS_SET_TARGET_NAME,
+  CUSTOM_FIELDS_TARGET_NAME,
+  customFieldsSetTarget,
+  customFieldsTarget,
+  hasCustomFieldsDoors,
+  hasCustomFieldsSetDoors,
+  validateCustomFieldsSetWrite,
+  validateCustomFieldsWrite
+} from "./custom-field-targets.js";
+import { toast } from "../../host/notify.js";
+import { awaitEffectiveOrganizationId } from "../../host/ui-slots.js";
+import {
+  getGlobalSurfaceRegistry,
+  getSurfaceRuntimeStack
+} from "./SurfaceRuntimeContext.js";
+import { leaseAgentWriteSource } from "./agent-write-sources.js";
+function resolveHandlers(runtime, registry) {
+  return {
+    ...runtime.getWriteHandlers?.() ?? {},
+    ...registry.writeHandlers(runtime.surfaceName)
+  };
+}
+function splitHandler(entry, context = {}) {
+  if (!entry) return null;
+  if (!context.item) {
+    if (typeof entry === "function") return { apply: (value) => entry(value) };
+    if (typeof entry === "object" && typeof entry.apply === "function") {
+      return {
+        apply: (value) => entry.apply(value),
+        ...typeof entry.validate === "function" ? { validate: entry.validate } : {},
+        ...typeof entry.readCurrent === "function" ? { readCurrent: () => entry.readCurrent() } : {}
+      };
+    }
+    return null;
+  }
+  if (typeof entry === "function") return { apply: (value) => entry(value, context) };
+  if (typeof entry === "object" && typeof entry.apply === "function") {
+    const { apply, validate, readCurrent } = entry;
+    return {
+      apply: (value) => apply(value, context),
+      ...typeof validate === "function" ? { validate: (value) => validate(value, context) } : {},
+      ...typeof readCurrent === "function" ? { readCurrent: () => readCurrent(context) } : {}
+    };
+  }
+  return null;
+}
+function patchFromJsonString(target, value) {
+  if (!target.patchable || typeof value !== "string") return null;
+  const text = value.trim();
+  if (!text.startsWith("{") || !text.endsWith("}")) return null;
+  try {
+    const parsed = JSON.parse(text);
+    if (!isSurfaceWritePatch(parsed)) return null;
+    const fields = parsed;
+    return "old_str" in fields || "new_str" in fields ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function handlerTextReader(target, runtime, registry, context = {}) {
+  return splitHandler(resolveHandlers(runtime, registry)[target.name], context)?.readCurrent ?? null;
+}
+function toWriteOutcome(returned) {
+  if (!returned || typeof returned !== "object" || Array.isArray(returned)) {
+    return void 0;
+  }
+  const keys = Object.keys(returned);
+  if (keys.length === 0 || keys.some((k) => k !== "summary" && k !== "data")) {
+    return void 0;
+  }
+  const candidate = returned;
+  if (candidate.summary !== void 0 && typeof candidate.summary !== "string") {
+    return void 0;
+  }
+  const out = {};
+  if (typeof candidate.summary === "string" && candidate.summary.trim()) {
+    out.summary = candidate.summary.trim();
+  }
+  if (candidate.data !== void 0) {
+    try {
+      JSON.stringify(candidate.data);
+      out.data = candidate.data;
+    } catch (error) {
+      console.warn(
+        "[surface-writeback] a write handler returned outcome.data that is not JSON-serializable; it was dropped.",
+        error
+      );
+    }
+  }
+  return out.summary !== void 0 || out.data !== void 0 ? out : void 0;
+}
+const EXCERPT_MAX = 160;
+function jsonTypeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function withArticle(typeName) {
+  if (typeName === "null") return "null";
+  return /^[aeiou]/.test(typeName) ? `an ${typeName}` : `a ${typeName}`;
+}
+function excerptOf(value) {
+  let text;
+  if (typeof value === "string") {
+    text = value;
+  } else {
+    try {
+      text = JSON.stringify(value) ?? String(value);
+    } catch {
+      text = String(value);
+    }
+  }
+  text = text.replace(/\s+/g, " ").trim();
+  return text.length > EXCERPT_MAX ? `${text.slice(0, EXCERPT_MAX - 1)}\u2026` : text;
+}
+const RECEIPT_EXCERPT_MAX = 400;
+const BEFORE_READ_TIMEOUT_MS = 1500;
+const NOT_READ = /* @__PURE__ */ Symbol("surface-write-before-not-read");
+function receiptExcerpt(value) {
+  let text;
+  try {
+    text = typeof value === "string" ? value : JSON.stringify(value) ?? String(value);
+  } catch {
+    text = String(value);
+  }
+  text = text.replace(/\s+/g, " ").trim();
+  return text.length > RECEIPT_EXCERPT_MAX ? `${text.slice(0, RECEIPT_EXCERPT_MAX - 1)}\u2026` : text;
+}
+function sameValue(a, b) {
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+async function readPageValueBeforeWrite(target, runtime, readCurrent) {
+  const key = target.updatesValue;
+  if (!key) return NOT_READ;
+  let timer;
+  try {
+    if (readCurrent) {
+      const text = await Promise.race([
+        readCurrent(),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(NOT_READ), BEFORE_READ_TIMEOUT_MS);
+        })
+      ]);
+      return text === NOT_READ ? NOT_READ : { value: text };
+    }
+    const scope = await Promise.race([
+      Promise.resolve(runtime.getScope()),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(NOT_READ), BEFORE_READ_TIMEOUT_MS);
+      })
+    ]);
+    if (scope === NOT_READ || !scope || typeof scope !== "object") return NOT_READ;
+    return { value: scope[key] };
+  } catch (error) {
+    console.warn(
+      `[surface-writeback] could not read "${key}" before writing "${target.name}" \u2014 the receipt will omit "before"`,
+      error
+    );
+    return NOT_READ;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function writeReceipt(target, written, before) {
+  const read = before !== NOT_READ;
+  return {
+    ...target.updatesValue ? { pageValue: target.updatesValue } : {},
+    ...read ? { before: receiptExcerpt(before.value ?? null) } : {},
+    written: receiptExcerpt(written ?? null),
+    ...read && sameValue(before.value, written) ? { sameAsBefore: true } : {},
+    appliedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function stripJsonFence(text) {
+  const match = /^```[a-zA-Z0-9_-]*[ \t]*\r?\n?([\s\S]*?)\r?\n?```$/.exec(
+    text.trim()
+  );
+  return match ? match[1].trim() : text.trim();
+}
+function matchesStructuredType(valueType, value) {
+  return valueType === "array" ? Array.isArray(value) : typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function coerceDeclaredValueType(target, value) {
+  const valueType = target.valueType;
+  if (valueType !== "object" && valueType !== "array") {
+    return { ok: true, value };
+  }
+  if (value === null || value === void 0) return { ok: true, value };
+  if (matchesStructuredType(valueType, value)) return { ok: true, value };
+  const expected = valueType === "array" ? "a JSON array" : "a JSON object";
+  let detail = "";
+  if (typeof value === "string") {
+    const body = stripJsonFence(value);
+    try {
+      const parsed = JSON.parse(body);
+      if (matchesStructuredType(valueType, parsed)) {
+        return { ok: true, value: parsed };
+      }
+      detail = ` (it parses as JSON, but as ${withArticle(jsonTypeOf(parsed))})`;
+    } catch (error) {
+      detail = ` that is not valid JSON (${error instanceof Error ? error.message : "parse failed"})`;
+    }
+  }
+  const received = jsonTypeOf(value);
+  return {
+    ok: false,
+    error: `"${target.label}" (${target.name}) expects \`value\` to be ${expected}, but received ${withArticle(received)}${detail}: ${excerptOf(value)} \u2014 send the ${valueType} itself as \`value\`, not a JSON-encoded string. Nothing was changed and the user was not asked.`
+  };
+}
+function refuseBeforeApproval(message, raw) {
+  console.warn(`[surface-writeback] refused before approval: ${message}`, raw);
+  return { ok: false, refused: true, phase: "before_approval", error: message };
+}
+class SurfaceWriteRefusalError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SurfaceWriteRefusalError";
+  }
+}
+function refuseSurfaceWrite(message) {
+  throw new SurfaceWriteRefusalError(message);
+}
+function readSurfaceWriteAddress(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value;
+  const resourceType = record.resource_type ?? record.resourceType;
+  const resourceId = record.resource_id ?? record.resourceId;
+  if (typeof resourceType !== "string" || !resourceType.trim()) return null;
+  if (typeof resourceId !== "string" || !resourceId.trim()) return null;
+  return { resourceType: resourceType.trim(), resourceId: resourceId.trim() };
+}
+let nextPolicyRegId = 0;
+let policyRegistrations = [];
+function registerSurfaceWritePolicies(policies, key, surfaceName) {
+  const id = ++nextPolicyRegId;
+  policyRegistrations = [
+    ...policyRegistrations.filter((r) => !key || r.key !== key),
+    { id, key: key ?? null, surfaceName, policies }
+  ];
+  return () => {
+    policyRegistrations = policyRegistrations.filter((r) => r.id !== id);
+  };
+}
+function resolveApplyPolicy(target, surfaceName) {
+  const surfaceDefault = target.applyPolicy ?? "manual";
+  for (let i = policyRegistrations.length - 1; i >= 0; i--) {
+    if (policyRegistrations[i].surfaceName !== surfaceName) continue;
+    const override = policyRegistrations[i].policies[target.name];
+    if (!override) continue;
+    if (surfaceDefault === "manual" && override !== "manual") return "manual";
+    return override;
+  }
+  return surfaceDefault;
+}
+const reportedErrors = /* @__PURE__ */ new WeakSet();
+function reportedError(message) {
+  const error = new Error(message);
+  reportedErrors.add(error);
+  return error;
+}
+function stableInput(value) {
+  try {
+    return JSON.stringify(value ?? null) ?? "null";
+  } catch {
+    return String(value);
+  }
+}
+function doorKey(surfaceName, targetName) {
+  return `${surfaceName}\0${targetName}`;
+}
+const seamWrites = /* @__PURE__ */ new Map();
+let writeSequence = 0;
+function mintRunId(conversationId) {
+  writeSequence += 1;
+  return `surface-write:${conversationId ?? "page"}:${writeSequence}`;
+}
+const surfaceWriteApprovals = {
+  async ask(request) {
+    const write = request.runId ? seamWrites.get(request.runId) : void 0;
+    const approve = write?.approve;
+    if (!write || !approve || write.input !== stableInput(request.input)) {
+      throw new Error(
+        `No one is here to approve "${request.label}". Ask for it again from the conversation or page that should approve it.`
+      );
+    }
+    write.approve = void 0;
+    return approve();
+  }
+};
+const surfaceWriteDiagnostics = {
+  capture(error, context) {
+    if (error && typeof error === "object" && reportedErrors.has(error)) return;
+    const message = error instanceof Error ? error.message : String(error);
+    captureError({
+      source: "surface-writeback",
+      message: `[write-door:${context.area}] ${message}`,
+      raw: { area: context.area, detail: context.detail }
+    });
+  }
+};
+const surfaceWriteKinds = {
+  async validate(kindKey, value) {
+    const verdict = await contentIrKindValidator().validate(value, kindKey);
+    if (!verdict.checked) {
+      return {
+        ok: false,
+        unverifiable: true,
+        sentence: `The "${kindKey}" contract could not be checked (${verdict.degradedReason}): ${verdict.errors[0] ?? "no detail"}`,
+        remedy: "Check the connection, then try again."
+      };
+    }
+    if (!verdict.ok) {
+      return {
+        ok: false,
+        sentence: `This value isn't shaped like the "${kindKey}" kind: ${verdict.errors.join("; ")}`,
+        remedy: `Correct the value so it matches the "${kindKey}" kind, then try again.`
+      };
+    }
+    return { ok: true };
+  }
+};
+const surfaceWriteDeclarations = {
+  get(surfaceName) {
+    const manifest = getManifest(surfaceName);
+    if (!manifest) return void 0;
+    return {
+      writeTargets: (manifest.writeTargets ?? []).map((target) => ({
+        ...target,
+        applyPolicy: resolveApplyPolicy(target, surfaceName)
+      })),
+      ...manifest.itemTypes ? { itemTypes: manifest.itemTypes } : {}
+    };
+  }
+};
+let surfaceDoor = null;
+function loadSurfaceWriteDoor() {
+  if (!surfaceDoor) {
+    const loading = import("@ai-matrx/alchemy/operate").then(
+      ({ createWriteDoor }) => createWriteDoor({
+        ports: {
+          diagnostics: surfaceWriteDiagnostics,
+          kinds: surfaceWriteKinds,
+          approvals: surfaceWriteApprovals
+        },
+        declarations: surfaceWriteDeclarations
+      })
+    ).then((door) => {
+      routeMountedPages(door);
+      return door;
+    });
+    surfaceDoor = loading;
+    loading.catch(() => {
+      if (surfaceDoor === loading) surfaceDoor = null;
+    });
+  }
+  return surfaceDoor;
+}
+const pageRoutes = /* @__PURE__ */ new Map();
+let routedDoor = null;
+function releaseIfUnused(key, route) {
+  if (route.mounted || route.holds > 0) return;
+  route.release();
+  pageRoutes.delete(key);
+}
+function openRoute(door, surfaceName, targetName) {
+  const key = doorKey(surfaceName, targetName);
+  let route = pageRoutes.get(key);
+  if (!route) {
+    route = {
+      release: door.registerLive(surfaceName, targetName, routePageWrite),
+      mounted: false,
+      holds: 0
+    };
+    pageRoutes.set(key, route);
+  }
+  return route;
+}
+function syncMountedRoutes(door) {
+  const registry = getGlobalSurfaceRegistry();
+  const handled = /* @__PURE__ */ new Map();
+  for (const runtime of registry.stack()) {
+    let handlers;
+    try {
+      handlers = resolveHandlers(runtime, registry);
+    } catch (error) {
+      captureError({
+        source: "surface-writeback",
+        message: `[write-door:routes] ${runtime.surfaceName} could not list its write handlers: ${error instanceof Error ? error.message : String(error)}`,
+        raw: { surfaceName: runtime.surfaceName }
+      });
+      continue;
+    }
+    for (const targetName of Object.keys(handlers)) {
+      if (!splitHandler(handlers[targetName])) continue;
+      handled.set(doorKey(runtime.surfaceName, targetName), { surfaceName: runtime.surfaceName, targetName });
+    }
+  }
+  for (const { surfaceName, targetName } of handled.values()) {
+    openRoute(door, surfaceName, targetName).mounted = true;
+  }
+  for (const [key, route] of [...pageRoutes]) {
+    if (handled.has(key)) continue;
+    route.mounted = false;
+    releaseIfUnused(key, route);
+  }
+}
+function routeMountedPages(door) {
+  if (routedDoor === door) return;
+  routedDoor = door;
+  syncMountedRoutes(door);
+  getGlobalSurfaceRegistry().subscribe(() => {
+    if (routedDoor === door) syncMountedRoutes(door);
+  });
+}
+const routePageWrite = (request) => {
+  const seam = request.runId ? seamWrites.get(request.runId) : void 0;
+  if (seam) return seam.apply();
+  return applyMountedPageWrite(request);
+};
+async function applyMountedPageWrite(request) {
+  const label = request.target.label || request.target.name;
+  if (request.ops) {
+    throw new Error(`"${label}" takes a whole value on ${request.surfaceName}; send the finished text instead of edits.`);
+  }
+  if (request.item) {
+    throw new Error(`"${label}" for one ${request.item.itemType} is applied from the page's own conversation; ask for it there.`);
+  }
+  const registry = getGlobalSurfaceRegistry();
+  const runtime = registry.stack().find((entry) => entry.surfaceName === request.surfaceName);
+  const handler = runtime ? splitHandler(resolveHandlers(runtime, registry)[request.target.name]) : null;
+  if (!handler) {
+    throw new Error(`"${label}" can only be saved with ${request.surfaceName} open, and it is no longer open.`);
+  }
+  if (handler.validate) await handler.validate(request.value);
+  const outcome = toWriteOutcome(await handler.apply(request.value));
+  return { status: "applied", ...outcome?.summary ? { sentence: outcome.summary } : {} };
+}
+async function writeThroughDoor(request, conversationId, apply, approve) {
+  const door = await loadSurfaceWriteDoor();
+  const key = doorKey(request.surfaceName, request.target);
+  const runId = mintRunId(conversationId);
+  const write = {
+    conversationId,
+    input: stableInput(request.value),
+    apply,
+    ...approve ? { approve } : {}
+  };
+  seamWrites.set(runId, write);
+  const route = openRoute(door, request.surfaceName, request.target);
+  route.holds += 1;
+  try {
+    return await door.write({ ...request, runId });
+  } finally {
+    seamWrites.delete(runId);
+    route.holds -= 1;
+    releaseIfUnused(key, route);
+  }
+}
+function declined(target, instructions) {
+  return {
+    ok: false,
+    declined: true,
+    error: `The person chose to keep it as it was: "${target.label}" was not written.`,
+    ...instructions ? { instructions } : {}
+  };
+}
+function liveRuntimeFor(registry, runtime) {
+  const stack = registry.stack();
+  if (stack.includes(runtime)) return runtime;
+  return stack.find((entry) => entry.surfaceName === runtime.surfaceName) ?? null;
+}
+const targetWriteQueues = /* @__PURE__ */ new Map();
+function inTargetQueue(key, run) {
+  const previous = targetWriteQueues.get(key) ?? Promise.resolve();
+  const next = previous.then(run, run);
+  const settled = next.then(
+    () => void 0,
+    () => void 0
+  );
+  targetWriteQueues.set(key, settled);
+  void settled.then(() => {
+    if (targetWriteQueues.get(key) === settled) targetWriteQueues.delete(key);
+  });
+  return next;
+}
+const WRITE_SETTLE_TIMEOUT_MS = 1e3;
+const WRITE_SETTLE_POLL_MS = 16;
+async function awaitPageShows(registry, runtime, sourceName, value) {
+  const deadline = Date.now() + WRITE_SETTLE_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const live = liveRuntimeFor(registry, runtime);
+    if (!live) return;
+    try {
+      const scope = await live.getScope();
+      const current = scope[sourceName];
+      if (typeof current !== "string" || current === value) return;
+    } catch {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, WRITE_SETTLE_POLL_MS));
+  }
+}
+async function agentWriteAllowed(target, surfaceName, actorLabel, value, requestApproval, runtime, registry = getGlobalSurfaceRegistry(), patch, atApply, context = {}) {
+  const policy = resolveApplyPolicy(target, surfaceName);
+  if (policy === "auto") return true;
+  if (policy === "manual") {
+    return fail(
+      `"${target.label}" is not agent-writable on this surface (applyPolicy: manual). A person has to make this change.`,
+      { targetName: target.name, surfaceName, policy }
+    );
+  }
+  if (!requestApproval) {
+    return fail(
+      `"${target.label}" requires approval, but this agent write has no inline approval surface.`,
+      { targetName: target.name, surfaceName, policy }
+    );
+  }
+  const originalName = target.comparisonValue ?? target.updatesValue;
+  const originalDefinition = getManifest(surfaceName)?.values?.find(
+    (entry) => entry.name === originalName
+  );
+  const declaredComparison = target.approvalComparison === "text-replacement";
+  const compareText = originalName !== void 0 && (originalDefinition?.valueType === "string" || originalDefinition?.valueType === "document" || handlerTextReader(target, runtime, registry, context) !== null) && typeof value === "string" && !/^(append|insert)/.test(target.name);
+  let currentValue;
+  async function readCurrentText(from = runtime) {
+    if (!originalName)
+      throw new Error("The original text source is not declared.");
+    const reader = handlerTextReader(target, from, registry, context);
+    if (reader) return reader();
+    const scope = await from.getScope();
+    const current = scope[originalName];
+    if (current !== null && typeof current !== "string") {
+      throw new Error(
+        `The current text for "${target.label}" is unavailable. Reopen the editor and request the change again.`
+      );
+    }
+    return current;
+  }
+  let comparing = compareText;
+  if (compareText) {
+    try {
+      currentValue = await readCurrentText();
+    } catch (error) {
+      if (declaredComparison) {
+        return fail(
+          error instanceof Error ? error.message : "Could not read the original text for comparison.",
+          { targetName: target.name, surfaceName, error }
+        );
+      }
+      comparing = false;
+    }
+  }
+  const decision = await requestApproval({
+    surfaceName,
+    target,
+    value,
+    actorLabel,
+    ...currentValue !== void 0 ? { currentValue } : {},
+    ...patch ? { patch } : {}
+  });
+  if (decision.kind === "approved") {
+    const changedMessage = `"${target.label}" changed while you were reviewing it. Nothing was applied. Request the change again to review an updated comparison.`;
+    const live = liveRuntimeFor(registry, runtime);
+    if (live && atApply) atApply.runtime = live;
+    if (!live && (comparing || atApply?.resolvePatch)) {
+      const message = `"${target.label}" is no longer open here. Nothing was applied. Reopen it and request the change again.`;
+      toast.error(message);
+      return { ok: false, refused: true, error: message };
+    }
+    if (live && atApply?.resolvePatch) {
+      const rebased = await atApply.resolvePatch(live);
+      if (!rebased.ok) {
+        toast.error(changedMessage);
+        return {
+          ok: false,
+          refused: true,
+          error: `${changedMessage} (${rebased.error})`
+        };
+      }
+      atApply.value = rebased.value;
+      return true;
+    }
+    if (live && comparing) {
+      try {
+        if (await readCurrentText(live) !== currentValue) {
+          toast.error(changedMessage);
+          return { ok: false, refused: true, error: changedMessage };
+        }
+      } catch (error) {
+        return fail(
+          error instanceof Error ? error.message : "Could not verify the original text before applying.",
+          { targetName: target.name, surfaceName, error }
+        );
+      }
+    }
+    return true;
+  }
+  return declined(
+    target,
+    decision.kind === "declined" ? decision.instructions : void 0
+  );
+}
+async function valueContractHolds(target, surfaceName, value) {
+  const kind = target.valueKind;
+  if (!kind) return true;
+  const verdict = await contentIrKindValidator().validate(value, kind);
+  if (!verdict.checked) {
+    return fail(
+      `"${target.label}" declares the value contract "${kind}", but that contract could not be checked (${verdict.degradedReason}): ${verdict.errors[0] ?? "no detail"}. The write was refused \u2014 an unverifiable contract is not an approved one.`,
+      {
+        targetName: target.name,
+        surfaceName,
+        valueKind: kind,
+        degradedReason: verdict.degradedReason
+      }
+    );
+  }
+  if (!verdict.ok) {
+    return fail(
+      `"${target.label}" expects a value shaped like the "${kind}" kind, and this one isn't: ${verdict.errors.join("; ")}`,
+      {
+        targetName: target.name,
+        surfaceName,
+        valueKind: kind,
+        errors: verdict.errors
+      }
+    );
+  }
+  return true;
+}
+function findDeclaredTarget(surfaceName, targetName) {
+  const manifest = getManifest(surfaceName);
+  return manifest?.writeTargets?.find((entry) => entry.name === targetName) ?? null;
+}
+function fail(message, raw) {
+  toast.error(message);
+  captureError({
+    source: "surface-writeback",
+    message: `[surface-writeback] ${message}`,
+    raw
+  });
+  return { ok: false, error: message };
+}
+function failPatch(message, raw) {
+  toast.error("That edit didn't fit the current text", {
+    description: message
+  });
+  console.warn(`[surface-writeback] ${message}`, raw);
+  return { ok: false, error: message };
+}
+function failUnapplicable(message, raw) {
+  toast.error("This page can't apply that change", { description: message });
+  console.warn(`[surface-writeback] ${message}`, raw);
+  return { ok: false, error: message, unapplicable: true };
+}
+function otherItemsHintSentence(surfaceNames) {
+  const hints = [];
+  for (const name of surfaceNames) {
+    const hint = getManifest(name)?.otherItemsHint;
+    if (hint && !hints.includes(hint)) hints.push(hint);
+  }
+  return hints.length > 0 ? ` ${hints.join(" ")}` : "";
+}
+function unapplicableMessage(targetName, detail) {
+  return `${detail} No page open right now can apply "${targetName}", so nothing was written and nothing was changed. Open the page that owns this write \u2014 for a Rulebook that is the Rulebook's own workspace or its conduct page \u2014 and ask again there, or ask for a route that does not need that page.`;
+}
+async function resolveTargetPatch(target, runtime, patch, registry = getGlobalSurfaceRegistry(), context = {}) {
+  if (!target.patchable) {
+    return {
+      ok: false,
+      error: `"${target.label}" does not take an anchored edit \u2014 send the whole value for this target instead.`
+    };
+  }
+  const sourceName = target.comparisonValue ?? target.updatesValue;
+  if (!sourceName) {
+    return {
+      ok: false,
+      error: `"${target.label}" is marked patchable but declares no updatesValue, so there is no current text to edit. This is a defect in the ${runtime.surfaceName} manifest.`
+    };
+  }
+  let current;
+  try {
+    const reader = handlerTextReader(target, runtime, registry, context);
+    if (reader) {
+      current = await reader();
+    } else {
+      const scope = await runtime.getScope();
+      current = scope[sourceName];
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Could not read the current "${target.label}" to edit it. Reopen the editor and try again.` + (error instanceof Error ? ` (${error.message})` : "")
+    };
+  }
+  const outcome = resolveSurfaceWritePatch(current, patch);
+  if (!outcome.ok) {
+    return {
+      ok: false,
+      error: `"${target.label}": ${outcome.reason}`
+    };
+  }
+  return { ok: true, value: outcome.next, excerpt: outcome.excerpt };
+}
+async function applySurfaceWrite(targetName, rawValue, opts) {
+  if ((opts?.origin ?? "user") === "agent") {
+    return inTargetQueue(
+      `${opts?.conversationId ?? ""}::${targetName}`,
+      () => applySurfaceWriteNow(targetName, rawValue, opts)
+    );
+  }
+  return applySurfaceWriteNow(targetName, rawValue, opts);
+}
+async function applySurfaceWriteNow(targetName, rawValue, opts) {
+  const registry = opts?.source ?? getGlobalSurfaceRegistry();
+  const onScreen = registry.kind === "global";
+  if (onScreen && targetName === WINDOW_FORM_TARGET_NAME) {
+    return applyWindowFormWrite(rawValue, opts);
+  }
+  if (onScreen && targetName === SURFACE_FEEDBACK_TARGET_NAME) {
+    return applySurfaceFeedbackWrite(rawValue, opts);
+  }
+  if (onScreen && targetName === CUSTOM_FIELDS_TARGET_NAME) {
+    return applyCustomFieldsTargetWrite(rawValue, opts, "add");
+  }
+  if (onScreen && targetName === CUSTOM_FIELDS_SET_TARGET_NAME) {
+    return applyCustomFieldsTargetWrite(rawValue, opts, "set");
+  }
+  const stack = registry.stack().filter(
+    (entry) => !opts?.surfaceName || entry.surfaceName === opts.surfaceName
+  );
+  if (onScreen && opts?.origin === "agent") {
+    const lease = await leaseAgentWriteSource({
+      targetName,
+      ...opts.surfaceName ? { surfaceName: opts.surfaceName } : {},
+      ...opts.conversationId ? { conversationId: opts.conversationId } : {},
+      onScreenDeclares: stack.some(
+        (entry) => Boolean(findDeclaredTarget(entry.surfaceName, targetName))
+      )
+    });
+    if (lease) {
+      try {
+        return await applySurfaceWriteNow(targetName, rawValue, {
+          ...opts,
+          source: lease.source
+        });
+      } finally {
+        lease.release();
+      }
+    }
+  }
+  if (stack.length === 0) {
+    return failUnapplicable(
+      unapplicableMessage(
+        targetName,
+        opts?.surfaceName ? `Surface "${opts.surfaceName}" is not mounted here.` : "This screen mounts no writable surface."
+      ),
+      { targetName, surfaceName: opts?.surfaceName ?? null }
+    );
+  }
+  const writeContext = opts?.item ? { item: opts.item } : {};
+  for (const runtime of stack) {
+    const target = findDeclaredTarget(runtime.surfaceName, targetName);
+    if (!target) continue;
+    const handlers = resolveHandlers(runtime, registry);
+    const handler = splitHandler(handlers[targetName], writeContext);
+    if (!handler) {
+      return fail(
+        `Surface "${runtime.surfaceName}" declares write target "${targetName}" but registered no handler for it.`,
+        { targetName, surfaceName: runtime.surfaceName }
+      );
+    }
+    const patchInput = patchFromJsonString(target, rawValue) ?? rawValue;
+    let value = patchInput;
+    let patchExcerpt;
+    if (isSurfaceWritePatch(patchInput)) {
+      const resolved = await resolveTargetPatch(
+        target,
+        runtime,
+        patchInput,
+        registry,
+        writeContext
+      );
+      if (!resolved.ok) {
+        return failPatch(resolved.error, {
+          targetName: target.name,
+          surfaceName: runtime.surfaceName,
+          command: patchInput.command
+        });
+      }
+      value = resolved.value;
+      if (resolved.excerpt) {
+        patchExcerpt = { command: patchInput.command, ...resolved.excerpt };
+      }
+    }
+    const typed = coerceDeclaredValueType(target, value);
+    if (!typed.ok) {
+      return refuseBeforeApproval(typed.error, {
+        targetName: target.name,
+        surfaceName: runtime.surfaceName,
+        valueType: target.valueType
+      });
+    }
+    value = typed.value;
+    if (handler.validate) {
+      try {
+        await handler.validate(value);
+      } catch (error) {
+        return refuseBeforeApproval(
+          error instanceof Error && error.message ? error.message : `"${target.label}" refused this value.`,
+          { targetName: target.name, surfaceName: runtime.surfaceName, error }
+        );
+      }
+    }
+    let applyRuntime = runtime;
+    const origin = opts?.origin ?? "user";
+    const atApply = {};
+    if (origin === "agent" && isSurfaceWritePatch(patchInput)) {
+      const patchValue = patchInput;
+      atApply.resolvePatch = (live) => resolveTargetPatch(target, live, patchValue, registry, writeContext);
+    }
+    let settled;
+    const approve = origin === "agent" ? async () => {
+      const verdict = await agentWriteAllowed(
+        target,
+        runtime.surfaceName,
+        opts?.actorLabel,
+        value,
+        opts?.requestApproval,
+        runtime,
+        registry,
+        patchExcerpt,
+        atApply,
+        writeContext
+      );
+      if (verdict === true) return true;
+      settled = verdict;
+      if (!verdict.ok && verdict.declined) return false;
+      throw reportedError(verdict.ok ? `"${target.label}" was not applied.` : verdict.error);
+    } : void 0;
+    const apply = async () => {
+      if (atApply.runtime) applyRuntime = atApply.runtime;
+      if (atApply.value !== void 0 && atApply.value !== value) {
+        value = atApply.value;
+        const rebasedContract = await valueContractHolds(
+          target,
+          runtime.surfaceName,
+          value
+        );
+        if (rebasedContract !== true) {
+          settled = rebasedContract.ok ? rebasedContract : { ...rebasedContract, phase: "apply" };
+          throw reportedError(rebasedContract.ok ? `"${target.label}" was not applied.` : rebasedContract.error);
+        }
+      }
+      try {
+        const liveRuntime = liveRuntimeFor(registry, applyRuntime);
+        if (!liveRuntime)
+          throw new SurfaceWriteRefusalError("The page changed while approval was open. Review the current page before applying this change.");
+        applyRuntime = liveRuntime;
+        const currentHandler = splitHandler(
+          resolveHandlers(applyRuntime, registry)[targetName],
+          writeContext
+        );
+        if (!currentHandler)
+          throw new SurfaceWriteRefusalError("This operation is no longer available on the current page.");
+        if (currentHandler.validate) {
+          try {
+            await currentHandler.validate(value);
+          } catch (error) {
+            throw new SurfaceWriteRefusalError(error instanceof Error && error.message ? error.message : `"${target.label}" refused this value.`);
+          }
+        }
+        const before = await readPageValueBeforeWrite(
+          target,
+          applyRuntime,
+          currentHandler.readCurrent
+        );
+        const outcome = toWriteOutcome(await currentHandler.apply(value));
+        const textSource = target.comparisonValue ?? target.updatesValue;
+        if (origin === "agent" && textSource && typeof value === "string" && !currentHandler.readCurrent) {
+          await awaitPageShows(registry, applyRuntime, textSource, value);
+        }
+        if (!opts?.quiet && target.mode !== "ui") {
+          const headline = target.mode === "entity" ? `${target.label} \u2014 done.` : `${target.label} staged \u2014 review and save.`;
+          if (outcome?.summary) {
+            toast.success(headline, { description: outcome.summary });
+          } else {
+            toast.success(headline);
+          }
+        }
+        settled = {
+          ok: true,
+          surfaceName: runtime.surfaceName,
+          target,
+          ...outcome ? { outcome } : {},
+          change: writeReceipt(target, value, before)
+        };
+        return {
+          status: "applied",
+          ...outcome?.summary ? { sentence: outcome.summary } : {}
+        };
+      } catch (error) {
+        const message = error instanceof Error && error.message ? error.message : `Applying "${target.label}" failed.`;
+        if (error instanceof SurfaceWriteRefusalError) {
+          settled = { ok: false, refused: true, phase: "apply", error: message };
+          return {
+            status: "cannot-apply",
+            cannotApply: "stale",
+            sentence: message,
+            remedy: "Review the current page, then ask for the change again."
+          };
+        }
+        const failure = fail(message, {
+          targetName,
+          surfaceName: runtime.surfaceName,
+          error
+        });
+        settled = failure.ok ? failure : { ...failure, phase: "apply" };
+        throw reportedError(message);
+      }
+    };
+    const receipt = await writeThroughDoor(
+      {
+        surfaceName: runtime.surfaceName,
+        target: targetName,
+        value,
+        by: origin === "agent" ? "agent" : "person"
+      },
+      opts?.conversationId ?? null,
+      apply,
+      approve
+    );
+    if (receipt.status === "applied" && receipt.warning && !opts?.quiet) {
+      toast.warning(receipt.warning, receipt.fix ? { description: receipt.fix } : void 0);
+    }
+    const result = settled ?? // The door refused before this seam was asked anything.
+    (receipt.status === "refused" && receipt.reason === "manual_only" ? fail(
+      `"${target.label}" is not agent-writable on this surface (applyPolicy: manual). A person has to make this change.`,
+      { targetName: target.name, surfaceName: runtime.surfaceName, policy: "manual" }
+    ) : fail(receipt.status === "refused" ? receipt.sentence : `"${target.label}" was not applied: ${receipt.sentence}`, {
+      targetName,
+      surfaceName: runtime.surfaceName,
+      receipt
+    }));
+    return { ...result, receipt };
+  }
+  return failUnapplicable(
+    unapplicableMessage(
+      targetName,
+      `The page open here (${stack.map((entry) => entry.surfaceName).join(", ")}) declares no write target by that name.${otherItemsHintSentence(stack.map((entry) => entry.surfaceName))}`
+    ),
+    {
+      targetName,
+      mounted: stack.map((entry) => entry.surfaceName)
+    }
+  );
+}
+async function applyWindowFormWrite(rawValue, opts) {
+  const target = WINDOW_FORM_TARGET;
+  const primary = getSurfaceRuntimeStack()[0];
+  rawValue = labelWindowFormWrite(rawValue);
+  const surfaceName = primary?.surfaceName ?? "";
+  if ((opts?.origin ?? "user") === "agent") {
+    const verdict = await agentWriteAllowed(
+      target,
+      surfaceName,
+      opts?.actorLabel,
+      rawValue,
+      opts?.requestApproval,
+      primary ?? { surfaceName, getScope: () => ({}) }
+    );
+    if (verdict !== true) return verdict;
+  }
+  try {
+    await applyWindowFormChanges(rawValue);
+    if (!opts?.quiet) toast.success(`${target.label} \u2014 filled in. Review and save.`);
+    return { ok: true, surfaceName, target, change: writeReceipt(target, rawValue, NOT_READ) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : `Applying "${target.label}" failed.`;
+    if (error instanceof SurfaceWriteRefusalError) {
+      return { ok: false, refused: true, error: message };
+    }
+    return fail(message, { targetName: target.name, surfaceName, error });
+  }
+}
+async function applySurfaceFeedbackWrite(rawValue, opts) {
+  const target = SURFACE_FEEDBACK_TARGET;
+  const stack = getSurfaceRuntimeStack();
+  const mounted = stack.map((entry) => entry.surfaceName);
+  if (stack.length === 0) {
+    return failUnapplicable(
+      unapplicableMessage(target.name, "This screen mounts no registered surface to give feedback on."),
+      { targetName: target.name }
+    );
+  }
+  const runtime = opts?.surfaceName ? stack.find((entry) => entry.surfaceName === opts.surfaceName) : stack[0];
+  if (!runtime) {
+    return refuseBeforeApproval(
+      `Surface "${opts?.surfaceName}" is not open here, so feedback cannot be filed for it. Open surfaces: ${mounted.join(", ")}. Nothing was saved.`,
+      { targetName: target.name, surfaceName: opts?.surfaceName, mounted }
+    );
+  }
+  const surfaceName = runtime.surfaceName;
+  const typed = coerceDeclaredValueType(target, rawValue);
+  if (!typed.ok) {
+    return refuseBeforeApproval(typed.error, { targetName: target.name, surfaceName });
+  }
+  const value = typed.value;
+  try {
+    validateSurfaceFeedback(value);
+  } catch (error) {
+    return refuseBeforeApproval(
+      error instanceof Error ? error.message : `"${target.label}" refused this value.`,
+      { targetName: target.name, surfaceName }
+    );
+  }
+  if ((opts?.origin ?? "user") === "agent") {
+    const verdict = await agentWriteAllowed(
+      target,
+      surfaceName,
+      opts?.actorLabel,
+      value,
+      opts?.requestApproval,
+      runtime
+    );
+    if (verdict !== true) return verdict;
+  }
+  let organizationId = readActiveOrganizationId();
+  if (!organizationId) {
+    const resolved = await awaitEffectiveOrganizationId();
+    if (resolved.status === "ready") organizationId = resolved.organizationId;
+    else
+      return {
+        ok: false,
+        refused: true,
+        phase: "apply",
+        error: resolved.cause === "unreadable" ? "The person's organization could not be read just now, so nothing was saved. Tell them their feedback was not filed and to send it again in a moment." : "No organization is selected, and every feedback row is filed under one, so nothing was saved. Tell the person their feedback could not be filed until they pick their organization from the avatar menu, then send it again."
+      };
+  }
+  try {
+    const outcome = await saveSurfaceFeedback(value, {
+      surfaceName,
+      route: typeof window === "undefined" ? "" : window.location.pathname,
+      organizationId,
+      ...opts?.conversationId ? { conversationId: opts.conversationId } : {},
+      ...opts?.agentId ? { agentId: opts.agentId } : {},
+      ...opts?.actorLabel ? { agentName: opts.actorLabel } : {}
+    });
+    if (!opts?.quiet) {
+      toast.success("Feedback saved for the team.", { description: surfaceName });
+    }
+    return { ok: true, surfaceName, target, outcome, change: writeReceipt(target, value, NOT_READ) };
+  } catch (error) {
+    const failure = fail(
+      error instanceof Error && error.message ? error.message : `Saving "${target.label}" failed.`,
+      { targetName: target.name, surfaceName, error }
+    );
+    return failure.ok ? failure : { ...failure, phase: "apply" };
+  }
+}
+async function applyCustomFieldsTargetWrite(rawValue, opts, mode) {
+  const name = mode === "add" ? CUSTOM_FIELDS_TARGET_NAME : CUSTOM_FIELDS_SET_TARGET_NAME;
+  if (mode === "add" ? !hasCustomFieldsDoors() : !hasCustomFieldsSetDoors()) {
+    return failUnapplicable(
+      unapplicableMessage(name, "No custom-fields section is open on this page."),
+      { targetName: name }
+    );
+  }
+  const target = mode === "add" ? customFieldsTarget() : customFieldsSetTarget();
+  const primary = getSurfaceRuntimeStack()[0];
+  const surfaceName = primary?.surfaceName ?? "";
+  const typed = coerceDeclaredValueType(target, rawValue);
+  if (!typed.ok) {
+    return refuseBeforeApproval(typed.error, { targetName: target.name, surfaceName });
+  }
+  const value = typed.value;
+  try {
+    if (mode === "add") validateCustomFieldsWrite(value);
+    else validateCustomFieldsSetWrite(value);
+  } catch (error) {
+    return refuseBeforeApproval(
+      error instanceof Error ? error.message : `"${target.label}" refused this value.`,
+      { targetName: target.name, surfaceName }
+    );
+  }
+  if ((opts?.origin ?? "user") === "agent") {
+    const verdict = await agentWriteAllowed(
+      target,
+      surfaceName,
+      opts?.actorLabel,
+      value,
+      opts?.requestApproval,
+      primary ?? { surfaceName, getScope: () => ({}) }
+    );
+    if (verdict !== true) return verdict;
+  }
+  try {
+    const outcome = mode === "add" ? await applyCustomFieldsWrite(value) : await applyCustomFieldsSetWrite(value);
+    if (!opts?.quiet && outcome.summary) toast.success(outcome.summary);
+    return { ok: true, surfaceName, target, outcome, change: writeReceipt(target, value, NOT_READ) };
+  } catch (error) {
+    return {
+      ok: false,
+      refused: true,
+      phase: "apply",
+      error: error instanceof Error ? error.message : `"${target.label}" did not complete.`
+    };
+  }
+}
+const SURFACE_WRITE_TOOL_NAME = "apply_surface_write";
+function listAgentWritableTargets(source) {
+  const out = [];
+  for (const live of listLiveWriteTargets(source)) {
+    const policy = resolveApplyPolicy(live.target, live.surfaceName);
+    if (policy === "manual") continue;
+    if (!live.hasHandler) {
+      reportUnwiredTarget(live.surfaceName, live.target);
+      continue;
+    }
+    out.push({ surfaceName: live.surfaceName, target: live.target, policy });
+  }
+  return out;
+}
+function listUnwiredAgentTargets() {
+  return listLiveWriteTargets().filter(
+    (live) => !live.hasHandler && resolveApplyPolicy(live.target, live.surfaceName) !== "manual"
+  ).map((live) => ({ surfaceName: live.surfaceName, target: live.target }));
+}
+const reportedUnwiredTargets = /* @__PURE__ */ new Set();
+function reportUnwiredTarget(surfaceName, target) {
+  const key = `${surfaceName}:${target.name}`;
+  if (reportedUnwiredTargets.has(key)) return;
+  reportedUnwiredTargets.add(key);
+  const message = `[surface-writeback] Surface "${surfaceName}" declares agent-writable target "${target.name}", but the mounted page registered no handler for it \u2014 agents are not offered it here. Register it with useSurfaceWriteHandlers (or getWriteHandlers) on the component that owns that state, or drop the declaration from the manifest.`;
+  if (true) {
+    console.warn(message);
+  }
+}
+function __resetUnwiredTargetReports() {
+  reportedUnwiredTargets.clear();
+}
+function listLiveWriteTargets(source) {
+  const registry = source ?? getGlobalSurfaceRegistry();
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const runtime of registry.stack()) {
+    const manifest = getManifest(runtime.surfaceName);
+    if (!manifest?.writeTargets) continue;
+    const handlers = resolveHandlers(runtime, registry);
+    for (const target of manifest.writeTargets) {
+      const key = `${runtime.surfaceName}:${target.name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({
+        surfaceName: runtime.surfaceName,
+        target,
+        hasHandler: Boolean(handlers[target.name])
+      });
+    }
+  }
+  if (registry.kind !== "global") return out;
+  if (hasWindowForms()) {
+    out.push({
+      surfaceName: getSurfaceRuntimeStack()[0]?.surfaceName ?? "",
+      target: WINDOW_FORM_TARGET,
+      hasHandler: true
+    });
+  }
+  if (hasCustomFieldsDoors()) {
+    out.push({
+      surfaceName: getSurfaceRuntimeStack()[0]?.surfaceName ?? "",
+      target: customFieldsTarget(),
+      hasHandler: true
+    });
+  }
+  if (hasCustomFieldsSetDoors()) {
+    out.push({
+      surfaceName: getSurfaceRuntimeStack()[0]?.surfaceName ?? "",
+      target: customFieldsSetTarget(),
+      hasHandler: true
+    });
+  }
+  const mounted = getSurfaceRuntimeStack().map((entry) => entry.surfaceName);
+  if (mounted.length > 0) {
+    out.push({
+      surfaceName: mounted[0],
+      target: mounted.length > 1 ? {
+        ...SURFACE_FEEDBACK_TARGET,
+        description: `${SURFACE_FEEDBACK_TARGET.description} Open surfaces: ${mounted.join(", ")}.`
+      } : SURFACE_FEEDBACK_TARGET,
+      hasHandler: true
+    });
+  }
+  return out;
+}
+export {
+  SURFACE_WRITE_TOOL_NAME,
+  SurfaceWriteRefusalError,
+  __resetUnwiredTargetReports,
+  applySurfaceWrite,
+  coerceDeclaredValueType,
+  excerptOf,
+  listAgentWritableTargets,
+  listLiveWriteTargets,
+  listUnwiredAgentTargets,
+  loadSurfaceWriteDoor,
+  readSurfaceWriteAddress,
+  refuseSurfaceWrite,
+  registerSurfaceWritePolicies,
+  surfaceWriteApprovals,
+  surfaceWriteDeclarations
+};