@ai-matrx/chat 0.1.77 → 0.2.1

package/dist/surfaces/runtime/surface-feedback.d.ts

@@ -0,0 +1,57 @@
+/**
+ * features/surfaces/runtime/surface-feedback.ts
+ *
+ * THE PLATFORM WRITE TARGET `surface_feedback` — an agent working on ANY
+ * mounted surface can leave feedback about that surface for the team ("the
+ * class list arrived as a lookup, not inline", "there is no target to change
+ * exam dates", "create_classes never said X"). The team reads it the next time
+ * it updates that surface (`pnpm surface:feedback --surface <name>`).
+ *
+ * Like `window_form_fields` (`window-forms.ts`) it is declared once on the
+ * baseline surface (`_baseline.manifest.ts`): `listLiveWriteTargets` offers it
+ * whenever at least one registered surface is mounted, and it is written
+ * through the one write door (`surface-writeback.ts` `applyPlatformWrite`). It changes NOTHING on the page, so
+ * it is `auto` — the person is never interrupted by a card for it.
+ *
+ * Storage is the central triage table `users.user_feedback`, written through
+ * the host's feedback port — in matrx-frontend the ONE existing submit path
+ * (`submitFeedback`, the same action the in-app feedback window uses) — filed
+ * in the organization the person is acting in.
+ */
+import type { ChatFeedbackInput, ChatFeedbackType } from "../../host/contract.js";
+import type { SurfaceWriteTarget } from "../types.js";
+import { SURFACE_FEEDBACK_KINDS } from "../manifests/_baseline.manifest.js";
+import type { SurfaceWriteOutcome } from "./SurfaceRuntimeContext.js";
+export declare const SURFACE_FEEDBACK_TARGET_NAME: "surface_feedback";
+export type SurfaceFeedbackKind = (typeof SURFACE_FEEDBACK_KINDS)[number];
+export interface SurfaceFeedbackValue {
+    kind: SurfaceFeedbackKind;
+    message: string;
+    target_or_value?: string;
+}
+/** The platform target — declared once on the baseline surface (`_baseline.manifest.ts`); offered whenever a surface is mounted. */
+export declare const SURFACE_FEEDBACK_TARGET: SurfaceWriteTarget;
+/**
+ * Pre-write check. Throws a sentence the agent can act on; nothing is written
+ * when it throws.
+ */
+export declare function validateSurfaceFeedback(value: unknown): asserts value is SurfaceFeedbackValue;
+/** Triage vocabulary (`users.user_feedback.feedback_type`). */
+export declare function feedbackTypeForKind(kind: SurfaceFeedbackKind): ChatFeedbackType;
+export interface SurfaceFeedbackContext {
+    surfaceName: string;
+    route: string;
+    organizationId: string;
+    conversationId?: string;
+    agentId?: string;
+    agentName?: string;
+}
+/** The exact feedback-port input one feedback write files. */
+export declare function buildSurfaceFeedbackInput(value: SurfaceFeedbackValue, ctx: SurfaceFeedbackContext): ChatFeedbackInput;
+/** The organization the person is acting in, or null when none is selected. */
+export declare function readActiveOrganizationId(): string | null;
+/**
+ * File one validated feedback value. Throws a plain Error when the submit
+ * path refuses; the seam turns that into the failure envelope.
+ */
+export declare function saveSurfaceFeedback(value: SurfaceFeedbackValue, ctx: SurfaceFeedbackContext): Promise<SurfaceWriteOutcome>;

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

@@ -0,0 +1,101 @@
+import { getChatHost } from "../../host/configure.js";
+import { getStoreSingleton } from "../../store/store-singleton.js";
+import {
+  PLATFORM_WRITE_TARGETS,
+  SURFACE_FEEDBACK_KINDS,
+  SURFACE_FEEDBACK_MESSAGE_MAX,
+  SURFACE_FEEDBACK_MESSAGE_MIN
+} from "../manifests/_baseline.manifest.js";
+const SURFACE_FEEDBACK_TARGET_NAME = PLATFORM_WRITE_TARGETS.surface_feedback.name;
+const KIND_LIST = SURFACE_FEEDBACK_KINDS.join(" | ");
+const SURFACE_FEEDBACK_TARGET = PLATFORM_WRITE_TARGETS.surface_feedback;
+const ALLOWED_KEYS = /* @__PURE__ */ new Set(["kind", "message", "target_or_value"]);
+function validateSurfaceFeedback(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `surface_feedback expects an object { kind, message, target_or_value? }. Nothing was saved.`
+    );
+  }
+  const record = value;
+  const unknownKeys = Object.keys(record).filter((k) => !ALLOWED_KEYS.has(k));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `surface_feedback does not take ${unknownKeys.map((k) => `"${k}"`).join(", ")} \u2014 only kind, message and target_or_value. Nothing was saved.`
+    );
+  }
+  if (typeof record.kind !== "string" || !SURFACE_FEEDBACK_KINDS.includes(record.kind)) {
+    throw new Error(
+      `surface_feedback "kind" must be one of ${KIND_LIST}; received ${JSON.stringify(record.kind ?? null)}. Nothing was saved.`
+    );
+  }
+  const message = typeof record.message === "string" ? record.message.trim() : "";
+  if (message.length < SURFACE_FEEDBACK_MESSAGE_MIN) {
+    throw new Error(
+      `surface_feedback "message" must say what happened in at least ${SURFACE_FEEDBACK_MESSAGE_MIN} characters. Nothing was saved.`
+    );
+  }
+  if (message.length > SURFACE_FEEDBACK_MESSAGE_MAX) {
+    throw new Error(
+      `surface_feedback "message" is ${message.length} characters; the limit is ${SURFACE_FEEDBACK_MESSAGE_MAX}. Shorten it. Nothing was saved.`
+    );
+  }
+  if (record.target_or_value !== void 0 && record.target_or_value !== null && typeof record.target_or_value !== "string") {
+    throw new Error(
+      `surface_feedback "target_or_value" must be a string (a write target or value name). Nothing was saved.`
+    );
+  }
+}
+function feedbackTypeForKind(kind) {
+  if (kind === "bug") return "bug";
+  if (kind === "missing_capability") return "feature";
+  return "suggestion";
+}
+function buildSurfaceFeedbackInput(value, ctx) {
+  const message = value.message.trim();
+  const targetOrValue = value.target_or_value?.trim() || null;
+  return {
+    feedback_type: feedbackTypeForKind(value.kind),
+    route: ctx.route,
+    organization_id: ctx.organizationId,
+    description: `[surface feedback] ${ctx.surfaceName} \xB7 ${value.kind}` + (targetOrValue ? ` \xB7 ${targetOrValue}` : "") + `
+
+${message}`,
+    metadata: {
+      source: "surface_agent_feedback",
+      surface_name: ctx.surfaceName,
+      kind: value.kind,
+      target_or_value: targetOrValue,
+      ...ctx.conversationId ? { conversation_id: ctx.conversationId } : {},
+      ...ctx.agentId ? { agent_id: ctx.agentId } : {},
+      ...ctx.agentName ? { agent_name: ctx.agentName } : {}
+    }
+  };
+}
+function readActiveOrganizationId() {
+  const state = getStoreSingleton()?.getState();
+  return state?.appContext?.organization_id ?? null;
+}
+async function saveSurfaceFeedback(value, ctx) {
+  const result = await getChatHost().feedback.submit(
+    buildSurfaceFeedbackInput(value, ctx)
+  );
+  if (!result.success || !result.data) {
+    throw new Error(
+      `Saving feedback for ${ctx.surfaceName} failed: ${result.error ?? "no row came back"}.`
+    );
+  }
+  const id = result.data.id;
+  return {
+    summary: `Feedback saved for ${ctx.surfaceName} (id ${id}). Thank you \u2014 the team reads it on the next update.`,
+    data: { id }
+  };
+}
+export {
+  SURFACE_FEEDBACK_TARGET,
+  SURFACE_FEEDBACK_TARGET_NAME,
+  buildSurfaceFeedbackInput,
+  feedbackTypeForKind,
+  readActiveOrganizationId,
+  saveSurfaceFeedback,
+  validateSurfaceFeedback
+};

package/dist/surfaces/runtime/surface-mandates.d.ts

@@ -0,0 +1,31 @@
+import type { AnyMandateKey } from "@ai-matrx/agents/mandates";
+export interface SurfaceMandateRef {
+    /** `agent.mandate.mandate_key`, e.g. `seo.topic_assigner` — typed, never
+     * `string` (V-L6a): a surface disclosing a key that no longer exists would
+     * put a dead job in the Agents menu. */
+    mandateKey: AnyMandateKey;
+    /** What this agent does HERE, in the surface's own words. */
+    does: string;
+    /** The surface it was registered from, when the host knows its name. */
+    surfaceName?: string | null;
+}
+/** Imperative registration. Returns an unregister that clears only this entry. */
+export declare function registerSurfaceMandates(refs: readonly SurfaceMandateRef[]): () => void;
+/** Every fixed mandate registered for the top menu, de-duplicated by key. */
+export declare function getLiveSurfaceMandates(): readonly SurfaceMandateRef[];
+/** Hook twin for chrome outside the page tree (the Agents header menu). */
+export declare function useLiveSurfaceMandates(): readonly SurfaceMandateRef[];
+/**
+ * Register fixed mandates this component's surface already runs in the top
+ * Agents menu. This hook renders no UI; never add a visible disclosure sibling.
+ *
+ * ```ts
+ * useDeclaredSurfaceMandates([
+ *   { mandateKey: "seo.topic_assigner", does: "assigns keywords to topics" },
+ * ]);
+ * ```
+ *
+ * The KEY SET is the registration identity, so an inline array literal is fine
+ * — it re-registers only when the set of keys actually changes.
+ */
+export declare function useDeclaredSurfaceMandates(refs: readonly SurfaceMandateRef[]): void;

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

@@ -0,0 +1,62 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useSyncExternalStore } from "react";
+let nextId = 0;
+let entries = [];
+const listeners = /* @__PURE__ */ new Set();
+let snapshot = [];
+function recompute() {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    for (const ref of entry.refs) {
+      if (!byKey.has(ref.mandateKey)) byKey.set(ref.mandateKey, ref);
+    }
+  }
+  snapshot = [...byKey.values()];
+  for (const listener of listeners) listener();
+}
+function subscribe(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function getSnapshot() {
+  return snapshot;
+}
+const EMPTY = [];
+function getServerSnapshot() {
+  return EMPTY;
+}
+function registerSurfaceMandates(refs) {
+  const id = ++nextId;
+  entries = [...entries, { id, refs }];
+  recompute();
+  return () => {
+    entries = entries.filter((entry) => entry.id !== id);
+    recompute();
+  };
+}
+function getLiveSurfaceMandates() {
+  return snapshot;
+}
+function useLiveSurfaceMandates() {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+function useDeclaredSurfaceMandates(refs) {
+  const refsRef = useRef(refs);
+  useEffect(() => {
+    refsRef.current = refs;
+  });
+  const identity = refs.map((ref) => `${ref.mandateKey}|${ref.does}|${ref.surfaceName ?? ""}`).sort().join("\n");
+  useEffect(() => {
+    if (refsRef.current.length === 0) return;
+    return registerSurfaceMandates([...refsRef.current]);
+  }, [identity]);
+}
+export {
+  getLiveSurfaceMandates,
+  registerSurfaceMandates,
+  useDeclaredSurfaceMandates,
+  useLiveSurfaceMandates
+};

package/dist/surfaces/runtime/surface-ui-state.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Publish (or clear, with `undefined`) one piece of surface UI state.
+ *
+ * Call from the page that OWNS the state — typically in an effect mirroring
+ * the state it already holds. Publishing an identical value is a no-op, so
+ * calling this on every render is safe as long as the value is stable.
+ */
+export declare function publishSurfaceUiState(surfaceName: string, key: string, value: unknown): void;
+/** Imperative read of ONE surface's value — for non-React callers. */
+export declare function readSurfaceUiState<T = unknown>(surfaceName: string, key: string): T | undefined;
+/**
+ * Imperative stack-walking read: the value from the DEEPEST mounted surface
+ * that publishes `key`. This is the same resolution `applySurfaceWrite` uses
+ * for targets — read and write MUST agree, or a block reads one surface's
+ * state while its writes land on another's.
+ */
+export declare function readCurrentSurfaceUiState<T = unknown>(key: string): T | undefined;
+/**
+ * Subscribe to ONE named surface's value. Returns `undefined` when that
+ * surface is not publishing the key.
+ *
+ * Prefer `useCurrentSurfaceUiState` in a rendered block — a block must not
+ * know which surface it landed on.
+ */
+export declare function useSurfaceUiState<T = unknown>(surfaceName: string, key: string): T | undefined;
+/**
+ * Read a key from the mounted surface stack — deepest publisher wins, the same
+ * resolution `applySurfaceWrite` uses for write targets.
+ *
+ * This is the form a rendered block wants: a block does not know, and must not
+ * know, which page it landed on. It names a key; if a mounted surface is
+ * publishing that key it gets a value, and if not (chat, a share page, SSR) it
+ * gets `undefined` and renders its non-interactive form. Same key, same block,
+ * every surface.
+ *
+ * It walks the stack rather than asking only the single deepest runtime,
+ * because those are NOT the same surface: an overlay-hosted window registers
+ * near the top of the tree (shallow depth) while the page behind it can be
+ * nested deeper. Asking only the winner made a keyword window's blocks read
+ * the content-plan node panel's (absent) state and silently render
+ * non-interactive.
+ */
+export declare function useCurrentSurfaceUiState<T = unknown>(key: string): T | undefined;
+/** Test/unmount cleanup. Never call from product code mid-session. */
+export declare function clearSurfaceUiState(surfaceName?: string): void;

package/dist/surfaces/runtime/surface-ui-state.js

@@ -0,0 +1,94 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { getSurfaceRuntimeStack } from "./SurfaceRuntimeContext.js";
+const store = /* @__PURE__ */ new Map();
+const listeners = /* @__PURE__ */ new Map();
+const subscribers = /* @__PURE__ */ new Map();
+const keyOf = (surfaceName, key) => `${surfaceName}::${key}`;
+function emit(key) {
+  const set = listeners.get(key);
+  if (!set) return;
+  for (const listener of set) listener();
+}
+function subscriberFor(key) {
+  const existing = subscribers.get(key);
+  if (existing) return existing;
+  const subscribe = (listener) => {
+    let set = listeners.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      listeners.set(key, set);
+    }
+    set.add(listener);
+    return () => {
+      const current = listeners.get(key);
+      if (!current) return;
+      current.delete(listener);
+      if (current.size === 0) listeners.delete(key);
+    };
+  };
+  subscribers.set(key, subscribe);
+  return subscribe;
+}
+function publishSurfaceUiState(surfaceName, key, value) {
+  const storeKey = keyOf(surfaceName, key);
+  if (store.get(storeKey) === value) return;
+  if (value === void 0) {
+    if (!store.has(storeKey)) return;
+    store.delete(storeKey);
+  } else {
+    store.set(storeKey, value);
+  }
+  emit(key);
+}
+function readSurfaceUiState(surfaceName, key) {
+  return store.get(keyOf(surfaceName, key));
+}
+function readCurrentSurfaceUiState(key) {
+  for (const runtime of getSurfaceRuntimeStack()) {
+    const storeKey = keyOf(runtime.surfaceName, key);
+    if (store.has(storeKey)) return store.get(storeKey);
+  }
+  return void 0;
+}
+function useSurfaceUiState(surfaceName, key) {
+  const storeKey = keyOf(surfaceName, key);
+  return useSyncExternalStore(
+    subscriberFor(key),
+    () => store.get(storeKey),
+    // Server snapshot: nothing is published during SSR, and it must be the
+    // SAME value every call or React throws an infinite-loop error.
+    () => void 0
+  );
+}
+function useCurrentSurfaceUiState(key) {
+  return useSyncExternalStore(
+    subscriberFor(key),
+    () => readCurrentSurfaceUiState(key),
+    () => void 0
+  );
+}
+function clearSurfaceUiState(surfaceName) {
+  const bareKey = (storeKey) => storeKey.split("::").slice(1).join("::");
+  if (!surfaceName) {
+    const keys = [...store.keys()];
+    store.clear();
+    for (const key of keys) emit(bareKey(key));
+    return;
+  }
+  const prefix = `${surfaceName}::`;
+  for (const key of [...store.keys()]) {
+    if (key.startsWith(prefix)) {
+      store.delete(key);
+      emit(bareKey(key));
+    }
+  }
+}
+export {
+  clearSurfaceUiState,
+  publishSurfaceUiState,
+  readCurrentSurfaceUiState,
+  readSurfaceUiState,
+  useCurrentSurfaceUiState,
+  useSurfaceUiState
+};

package/dist/surfaces/runtime/surface-write-patch.d.ts

@@ -0,0 +1,127 @@
+/**
+ * SURFACE WRITE PATCH — the anchored edit for a text write target.
+ *
+ * ## Why this exists
+ *
+ * Every text write target in the manifest set is a WHOLE-VALUE replacement:
+ * the tool carries one `value` and the page handler takes what it is given.
+ * For a short field (`agent_name`) that is exactly right. For a long one it is
+ * a tax that gets paid in tokens and in risk — changing one sentence of a
+ * 45,000-character system prompt meant re-transmitting all 45,000 characters,
+ * where every one of them is a chance to silently drop a paragraph the model
+ * never meant to touch.
+ *
+ * The workaround the repo reached for first was a SECOND TARGET
+ * (`append_system_instruction` beside `system_instruction`). That buys append
+ * and nothing else: there is no hand-written target shape that expresses
+ * "replace this sentence", and adding one per field per operation multiplies
+ * the manifest without ever covering the case.
+ *
+ * So the edit is expressed as a PATCH against the target's current text, and
+ * resolved to a whole string HERE, at the seam, before anything downstream
+ * looks at it. That ordering is the whole design:
+ *
+ *   patch → [resolve here] → value contract → approval card → page handler
+ *
+ * Downstream is unchanged and unaware. The kind contract still validates a
+ * final value, the approval card still diffs a real before→after (which is why
+ * `approvalComparison: "text-replacement"` keeps working, and in fact reads
+ * better), and every page handler keeps its `(value: string)` signature. No
+ * handler in the repo changes to gain patch support.
+ *
+ * ## Why this is not `applyWorkingDocPatch`
+ *
+ * `features/tool-call-visualization/.../applyWorkingDocPatch.ts` applies the
+ * same `ctx_patch` vocabulary, and the overlap is deliberate — both mirror the
+ * backend so the model writes one shape everywhere. It is NOT reused here
+ * because it is documented as OPTIMISTIC: it exists to paint a fast local
+ * preview that the server's authoritative result later reconciles. Two of its
+ * compromises are correct there and unacceptable in a real write:
+ *
+ *  - `insert` with no anchor best-effort APPENDS. In a preview that is a
+ *    cosmetic guess the server corrects a moment later; in a write it would
+ *    silently put the model's text somewhere it did not ask for, and nothing
+ *    downstream would ever correct it.
+ *  - every failure collapses to `ok: false` with no reason, because the
+ *    renderer only needs to know to fall back. A write has to tell the model
+ *    WHICH anchor missed and whether it missed by being absent or by being
+ *    ambiguous, or the model cannot fix its own call.
+ *
+ * What genuinely is shared is the matcher — `matchText`, the one fuzzy
+ * anchor-finder in the repo (exact pass, then a whitespace-insensitive pass),
+ * including its refusal to guess when a pattern matches more than once. That
+ * is the part that must never fork, and it does not.
+ *
+ * The vocabulary here is therefore the SAFE SUBSET of `ctx_patch`: the four
+ * commands whose meaning against a plain string is unambiguous. `insert`
+ * (needs an anchor this envelope has no room for) and `json_patch` /
+ * `json_merge` (structural, meaningless against text) are refused by name
+ * rather than approximated, so a model that reaches for one is told to use
+ * `str_replace` instead of quietly getting an append.
+ */
+/**
+ * The commands a surface text patch may use — the subset of the backend
+ * `ctx_patch` vocabulary that is unambiguous against a plain string.
+ */
+export declare const SURFACE_PATCH_COMMANDS: readonly ["str_replace", "append", "prepend", "overwrite"];
+export type SurfaceWritePatchCommand = (typeof SURFACE_PATCH_COMMANDS)[number];
+/** The patch envelope an agent sends as `value` for a patchable target. */
+export interface SurfaceWritePatch {
+    command: SurfaceWritePatchCommand;
+    /** `str_replace`: the exact text to find. Must match exactly once. */
+    old_str?: string;
+    /** The replacement / appended / prepended text. */
+    new_str?: string;
+    /** `append` / `prepend`: text placed between the old and new text. */
+    separator?: string;
+}
+export type SurfaceWritePatchOutcome = {
+    ok: true;
+    next: string;
+    matchedRange: {
+        start: number;
+        end: number;
+    } | null;
+    /** One line for the toast and the audit trail. */
+    summary: string;
+    /**
+     * What the edit changed, cut to the WHOLE LINES it touched — the
+     * approval card diffs this, so a one-word edit on a 5,000-character
+     * note is reviewed as one line, not as the whole note. `null` for an
+     * `overwrite`, which genuinely replaces everything (the card then diffs
+     * the full before/after).
+     */
+    excerpt: {
+        before: string;
+        after: string;
+    } | null;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Does this value LOOK like a patch envelope rather than a replacement value?
+ *
+ * Deliberately narrow: an object carrying a `command` string. A plain string
+ * is never a patch, so a patchable target still accepts a whole-value write
+ * unchanged — patchability ADDS an option, it never takes the simple one away.
+ */
+export declare function isSurfaceWritePatch(value: unknown): value is SurfaceWritePatch;
+/**
+ * Apply a patch envelope to the target's CURRENT text and return the whole
+ * resulting value.
+ *
+ * Never throws and never silently no-ops: every path either returns the new
+ * text or a `reason` written for the model that sent the patch — it names what
+ * missed and what to do instead, because a refusal the caller cannot act on is
+ * just a failure with better manners.
+ */
+export declare function resolveSurfaceWritePatch(current: unknown, patch: SurfaceWritePatch): SurfaceWritePatchOutcome;
+/**
+ * The one sentence the injected tool spec uses to teach the patch envelope.
+ *
+ * Written once, here, beside the implementation that honours it — the wire
+ * teaches, the seam enforces, and both read from the same file so they cannot
+ * drift into describing different shapes.
+ */
+export declare function surfacePatchContractLine(): string;

package/dist/surfaces/runtime/surface-write-patch.js

@@ -0,0 +1,144 @@
+import { matchText } from "@ai-matrx/diff/text";
+const SURFACE_PATCH_COMMANDS = [
+  "str_replace",
+  "append",
+  "prepend",
+  "overwrite"
+];
+const REFUSED_COMMANDS = {
+  insert: 'needs an anchor this envelope cannot carry, and approximating it as an append would put your text somewhere you did not ask for. Use "str_replace" with the surrounding text as old_str.',
+  json_patch: 'is a structural edit and this target holds text. Use "str_replace" or "overwrite".',
+  json_merge: 'is a structural edit and this target holds text. Use "str_replace" or "overwrite".'
+};
+function lineExcerpt(base, next, start, oldEnd, newEnd) {
+  const lineStart = base.lastIndexOf("\n", start - 1) + 1;
+  const oldLineEndRaw = base.indexOf("\n", Math.max(oldEnd, start));
+  const oldLineEnd = oldLineEndRaw === -1 ? base.length : oldLineEndRaw;
+  const tail = base.length - oldLineEnd;
+  const newLineEnd = Math.max(newEnd, next.length - tail);
+  return {
+    before: base.slice(lineStart, oldLineEnd),
+    after: next.slice(lineStart, newLineEnd)
+  };
+}
+function isSurfaceWritePatch(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.command === "string";
+}
+function isSupportedCommand(command) {
+  return SURFACE_PATCH_COMMANDS.includes(command);
+}
+function refuse(reason) {
+  return { ok: false, reason };
+}
+function resolveSurfaceWritePatch(current, patch) {
+  const command = String(patch.command ?? "").trim();
+  if (command in REFUSED_COMMANDS) {
+    return refuse(`Patch command "${command}" ${REFUSED_COMMANDS[command]}`);
+  }
+  if (!isSupportedCommand(command)) {
+    return refuse(
+      `Patch command "${command}" is not one this target accepts. Use one of: ${SURFACE_PATCH_COMMANDS.join(", ")}.`
+    );
+  }
+  if (current === null || current === void 0) {
+    if (command !== "overwrite") {
+      return refuse(
+        `This target currently holds no text, so there is nothing to ${command} against. Send the whole value, or use "overwrite".`
+      );
+    }
+  } else if (typeof current !== "string") {
+    return refuse(
+      `A patch only applies to a text value, and this target currently holds ${Array.isArray(current) ? "an array" : typeof current}. Send the whole value instead.`
+    );
+  }
+  const base = typeof current === "string" ? current : "";
+  const newStr = patch.new_str;
+  const separator = typeof patch.separator === "string" ? patch.separator : "\n\n";
+  switch (command) {
+    case "str_replace": {
+      const oldStr = patch.old_str;
+      if (typeof oldStr !== "string" || oldStr.length === 0) {
+        return refuse(
+          'A "str_replace" patch needs a non-empty old_str naming the exact text to replace.'
+        );
+      }
+      if (typeof newStr !== "string") {
+        return refuse(
+          'A "str_replace" patch needs new_str (send an empty string to delete the matched text).'
+        );
+      }
+      const match = matchText(base, oldStr);
+      if (!match.found || match.startIndex === void 0 || match.endIndex === void 0) {
+        return refuse(
+          `old_str did not resolve to exactly one place in the current text: ${match.error ?? "no match"}. Include more surrounding text so the anchor is unique.`
+        );
+      }
+      const next = base.slice(0, match.startIndex) + newStr + base.slice(match.endIndex);
+      return {
+        ok: true,
+        next,
+        matchedRange: {
+          start: match.startIndex,
+          end: match.startIndex + newStr.length
+        },
+        summary: match.matchType === "exact" ? "replaced one exact match" : `replaced one ${match.matchType} match`,
+        excerpt: lineExcerpt(
+          base,
+          next,
+          match.startIndex,
+          match.endIndex,
+          match.startIndex + newStr.length
+        )
+      };
+    }
+    case "append": {
+      if (typeof newStr !== "string") {
+        return refuse('An "append" patch needs new_str.');
+      }
+      const join = base.length === 0 ? "" : separator;
+      const next = base + join + newStr;
+      return {
+        ok: true,
+        next,
+        matchedRange: { start: base.length + join.length, end: next.length },
+        summary: "appended to the end",
+        excerpt: { before: "", after: newStr }
+      };
+    }
+    case "prepend": {
+      if (typeof newStr !== "string") {
+        return refuse('A "prepend" patch needs new_str.');
+      }
+      const join = base.length === 0 ? "" : separator;
+      const next = newStr + join + base;
+      return {
+        ok: true,
+        next,
+        matchedRange: { start: 0, end: newStr.length },
+        summary: "prepended to the start",
+        excerpt: { before: "", after: newStr }
+      };
+    }
+    case "overwrite": {
+      if (typeof newStr !== "string") {
+        return refuse('An "overwrite" patch needs new_str.');
+      }
+      return {
+        ok: true,
+        next: newStr,
+        matchedRange: { start: 0, end: newStr.length },
+        summary: "replaced the whole value",
+        excerpt: null
+      };
+    }
+  }
+}
+function surfacePatchContractLine() {
+  return `A target marked [patchable] takes an anchored edit as its value. For any change smaller than a rewrite \u2014 a word, a line, a paragraph \u2014 SEND THE EDIT, never the whole text again: {"command": "str_replace", "old_str": "<the exact text to find, unique>", "new_str": "<what replaces it>"}. Commands: ${SURFACE_PATCH_COMMANDS.join(", ")} (append/prepend also take an optional separator). old_str must match exactly once \u2014 if it misses or is ambiguous the write is refused and nothing changes, so widen the anchor and send it again. Send the whole text as a plain string only for a genuine rewrite of most of it.`;
+}
+export {
+  SURFACE_PATCH_COMMANDS,
+  isSurfaceWritePatch,
+  resolveSurfaceWritePatch,
+  surfacePatchContractLine
+};