@agent-native/core 0.106.0 → 0.106.1

package/corpus/templates/design/server/lib/reprompt-action-guard.ts

@@ -0,0 +1,107 @@
+import { getThread, type ActionEntry } from "@agent-native/core/server";
+
+const REPROMPT_MUTATION_ALLOWLIST = new Set(["propose-node-rewrite"]);
+
+export function isRepromptSelectionMessage(value: string): boolean {
+  return /(?:^|\n)\[Reprompt selection\](?:\n|$)/.test(value);
+}
+
+export function isSelectionQuestionMessage(value: string): boolean {
+  return /(?:^|\n)\[Selection question\](?:\n|$)/.test(value);
+}
+
+function latestUserMessageText(threadData: string): string {
+  try {
+    const parsed = JSON.parse(threadData) as {
+      messages?: Array<{
+        message?: {
+          role?: unknown;
+          content?: unknown;
+        };
+        role?: unknown;
+        content?: unknown;
+      }>;
+    };
+    const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      const entry = messages[index]!;
+      const message = entry.message ?? entry;
+      if (message.role !== "user") continue;
+      if (typeof message.content === "string") return message.content;
+      if (!Array.isArray(message.content)) return "";
+      return message.content
+        .filter((part): part is { type: "text"; text: string } =>
+          Boolean(
+            part &&
+            typeof part === "object" &&
+            (part as { type?: unknown }).type === "text" &&
+            typeof (part as { text?: unknown }).text === "string",
+          ),
+        )
+        .map((part) => part.text)
+        .join("\n");
+    }
+  } catch {}
+  return "";
+}
+
+function threadSelectionIntent(thread: {
+  preview: string;
+  threadData: string;
+}): "reprompt" | "question" | null {
+  const latestMessage = latestUserMessageText(thread.threadData);
+  if (
+    isRepromptSelectionMessage(thread.preview) ||
+    isRepromptSelectionMessage(latestMessage)
+  ) {
+    return "reprompt";
+  }
+  if (
+    isSelectionQuestionMessage(thread.preview) ||
+    isSelectionQuestionMessage(latestMessage)
+  ) {
+    return "question";
+  }
+  return null;
+}
+
+export function guardRepromptActionRegistry(
+  actions: Record<string, ActionEntry>,
+): Record<string, ActionEntry> {
+  return Object.fromEntries(
+    Object.entries(actions).map(([name, entry]) => {
+      if (entry.readOnly === true) return [name, entry];
+      return [
+        name,
+        {
+          ...entry,
+          run: async (args, context) => {
+            if (context?.caller === "tool" && context.threadId) {
+              const thread = await getThread(context.threadId);
+              if (!thread) {
+                throw new Error(
+                  `Cannot verify the agent thread for mutating action ${name}.`,
+                );
+              }
+              const intent = threadSelectionIntent(thread);
+              if (
+                intent === "reprompt" &&
+                !REPROMPT_MUTATION_ALLOWLIST.has(name)
+              ) {
+                throw new Error(
+                  `The current [Reprompt selection] turn is preview-only. Do not call ${name}; call propose-node-rewrite with the captured repromptId, target, and baseVersionHash instead.`,
+                );
+              }
+              if (intent === "question") {
+                throw new Error(
+                  `The current [Selection question] turn is read-only. Answer the user's question without calling ${name} or changing the design.`,
+                );
+              }
+            }
+            return entry.run(args, context);
+          },
+        },
+      ];
+    }),
+  );
+}

package/corpus/templates/design/server/plugins/agent-chat.ts

@@ -5,6 +5,7 @@ import {
 } from "@agent-native/core/server";
 
 import actionsRegistry from "../../.generated/actions-registry.js";
+import { guardRepromptActionRegistry } from "../lib/reprompt-action-guard.js";
 import "../register-secrets.js";
 
 const DESIGN_BACKGROUND_RUN_SOFT_TIMEOUT_MS = 13 * 60_000;
@@ -33,6 +34,7 @@ const INITIAL_TOOL_NAMES = [
   "edit-design",
   "generate-design",
   "present-design-variants",
+  "propose-node-rewrite",
   "insert-asset",
   "connect-assets-mcp",
   "apply-tweaks",
@@ -48,7 +50,9 @@ const INITIAL_TOOL_NAMES = [
 
 export default createAgentChatPlugin({
   appId: "design",
-  actions: loadActionsFromStaticRegistry(actionsRegistry),
+  actions: guardRepromptActionRegistry(
+    loadActionsFromStaticRegistry(actionsRegistry),
+  ),
   initialToolNames: INITIAL_TOOL_NAMES,
   // Enable sandboxed JavaScript execution so Design agents can fetch,
   // paginate, and reduce provider data through providerFetch() without us
@@ -60,6 +64,10 @@ export default createAgentChatPlugin({
   resolveOrgId: async (event) => (await getOrgContext(event)).orgId,
   systemPrompt: `You are an AI prototyping assistant. You create and edit designs, files, design systems, variants, exports, sharing, and connected repository context through actions and shared application state.
 
+When a user message begins with [Reprompt selection], the design must remain unchanged until the user accepts a preview. Call propose-node-rewrite with the exact repromptId, target, and baseVersionHash from the message. Never call edit-design, update-design, update-file, generate-design, apply-visual-edit, or any other content-writing action for that turn. The proposal action stores preview state only; the frontend-only resolve-node-rewrite action persists a chosen variant after the user presses Accept.
+
+When a user message begins with [Selection question], answer about the captured element and selected subtree without changing the design. You may use read-only actions when more context is needed, but do not call any content-writing action. If the user actually intended an edit, explain that they can choose Preview change from the composer mode menu and resend.
+
 When the user asks for a new design and the current navigation view is list, settings, design-systems, or otherwise has no designId, create a new design first. Do not reuse, delete screens from, or edit a previous design unless the user explicitly names that design or the current navigation state is an editor/present view with that designId.
 
 Every web design must be responsive. Use mobile-first CSS, a viewport meta tag, and responsive layout changes for narrow widths; never ship a fixed-width desktop shell. Desktop is the default primary artboard: use a 1440×1024 canvas frame (or primaryViewport "desktop") unless the user explicitly asks for a mobile- or tablet-primary design. After generation, inspect desktop and mobile screenshots and correct overflow or broken reflow before reporting completion.

package/corpus/templates/design/shared/code-layer.ts

@@ -2709,6 +2709,21 @@ function resolveTarget(
   };
 }
 
+export function resolveCodeLayerTarget(
+  html: string,
+  target: EditIntentTarget,
+  options: { source?: CodeLayerSource } = {},
+): { projection: CodeLayerProjection; resolution: EditIntentResolution } {
+  const build = buildProjection(
+    html,
+    options.source ?? { kind: "inline-html" },
+  );
+  return {
+    projection: build.projection,
+    resolution: resolveTarget(build, target),
+  };
+}
+
 function summarizeNode(node: CodeLayerNode): PatchNodeSummary {
   return {
     nodeId: node.id,

package/corpus/templates/design/shared/node-rewrite.ts

@@ -0,0 +1,213 @@
+import type {
+  CodeLayerNode,
+  CodeLayerSource,
+  EditIntentTarget,
+} from "./code-layer.js";
+import { resolveCodeLayerTarget } from "./code-layer.js";
+import { assertDesignHtmlEditIntegrity } from "./html-integrity.js";
+import { annotateScreenHtmlForPersist } from "./screen-annotation.js";
+
+export const DESIGN_REPROMPT_PENDING_STATE_PREFIX = "design-reprompt-pending:";
+export const DESIGN_REPROMPT_PROPOSAL_STATE_PREFIX =
+  "design-reprompt-proposal:";
+export const MAX_NODE_REWRITE_PROPOSAL_BYTES = 256 * 1024;
+
+export type NodeRewriteTarget = EditIntentTarget;
+
+export interface PendingDesignReprompt {
+  repromptId: string;
+  designId: string;
+  fileId: string;
+  target: NodeRewriteTarget;
+  baseVersionHash: string;
+  instruction: string;
+  createdAt: string;
+  priorProposalId?: string;
+  priorRepromptId?: string;
+}
+
+export interface NodeRewriteVariant {
+  html: string;
+  summary: string;
+}
+
+export interface NodeRewriteProposal {
+  proposalId: string;
+  repromptId: string;
+  designId: string;
+  fileId: string;
+  filename: string;
+  target: NodeRewriteTarget;
+  resolvedTarget: Required<NodeRewriteTarget>;
+  baseVersionHash: string;
+  variants: NodeRewriteVariant[];
+  chosenIndex: number;
+  createdAt: string;
+}
+
+export function isNodeRewriteProposal(
+  value: unknown,
+): value is NodeRewriteProposal {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proposal = value as Partial<NodeRewriteProposal>;
+  return (
+    typeof proposal.proposalId === "string" &&
+    typeof proposal.repromptId === "string" &&
+    typeof proposal.designId === "string" &&
+    typeof proposal.fileId === "string" &&
+    typeof proposal.baseVersionHash === "string" &&
+    Boolean(proposal.target) &&
+    Boolean(proposal.resolvedTarget) &&
+    Array.isArray(proposal.variants) &&
+    proposal.variants.length > 0
+  );
+}
+
+export function isPendingDesignReprompt(
+  value: unknown,
+): value is PendingDesignReprompt {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const pending = value as Partial<PendingDesignReprompt>;
+  return (
+    typeof pending.repromptId === "string" &&
+    typeof pending.designId === "string" &&
+    typeof pending.fileId === "string" &&
+    typeof pending.baseVersionHash === "string" &&
+    typeof pending.instruction === "string" &&
+    typeof pending.createdAt === "string" &&
+    Boolean(pending.target)
+  );
+}
+
+export interface NodeHtmlPreviewBridgeMessage {
+  type: "node-html-preview";
+  proposalId: string;
+  target: NodeRewriteTarget;
+  operation: "preview" | "restore";
+  html?: string;
+}
+
+export function designRepromptPendingStateKey(
+  designId: string,
+  fileId: string,
+): string {
+  return `${DESIGN_REPROMPT_PENDING_STATE_PREFIX}${designId}:${fileId}`;
+}
+
+export function designRepromptProposalStateKey(
+  designId: string,
+  fileId: string,
+  repromptId: string,
+): string {
+  return `${DESIGN_REPROMPT_PROPOSAL_STATE_PREFIX}${designId}:${fileId}:${repromptId}`;
+}
+
+export function designRepromptProposalStatePrefix(
+  designId: string,
+  fileId?: string,
+): string {
+  return `${DESIGN_REPROMPT_PROPOSAL_STATE_PREFIX}${designId}:${fileId ? `${fileId}:` : ""}`;
+}
+
+function assertSingleElementFragment(
+  html: string,
+  source: CodeLayerSource,
+): void {
+  if (!html.trim()) throw new Error("Variant HTML must not be empty.");
+  if (/<\/?(?:html|head|body)\b|<!doctype\b/i.test(html)) {
+    throw new Error("Variant HTML must be one subtree, not a full document.");
+  }
+
+  const { projection } = resolveCodeLayerTarget(
+    html,
+    { selector: "__node_rewrite_validation_target__" },
+    { source },
+  );
+  if (projection.rootNodeIds.length !== 1) {
+    throw new Error("Variant HTML must contain exactly one root element.");
+  }
+  const root = projection.nodes.find(
+    (node) => node.id === projection.rootNodeIds[0],
+  );
+  if (!root?.source) {
+    throw new Error("Variant HTML could not be parsed as an element subtree.");
+  }
+  if (
+    html.slice(0, root.source.start).trim() ||
+    html.slice(root.source.end).trim()
+  ) {
+    throw new Error("Variant HTML must contain exactly one root element.");
+  }
+
+  const voidElements = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+  ]);
+  const unclosed = projection.nodes.find(
+    (node) =>
+      node.source &&
+      !voidElements.has(node.tag) &&
+      node.source.closeEnd === undefined,
+  );
+  if (unclosed) {
+    throw new Error(`Variant HTML has an unclosed <${unclosed.tag}> element.`);
+  }
+}
+
+export function validateNodeRewriteVariant(
+  variant: NodeRewriteVariant,
+  source: CodeLayerSource,
+): NodeRewriteVariant {
+  const html = variant.html.trim();
+  assertSingleElementFragment(html, source);
+  return { html, summary: variant.summary.trim() };
+}
+
+export function resolveNodeRewriteTarget(
+  content: string,
+  target: NodeRewriteTarget,
+  source: CodeLayerSource,
+): CodeLayerNode {
+  const { resolution } = resolveCodeLayerTarget(content, target, { source });
+  if (resolution.status !== "resolved" || !resolution.node?.source) {
+    throw new Error(
+      `Target missing — re-anchor the selection. ${resolution.message ?? "The selected node no longer exists."}`,
+    );
+  }
+  return resolution.node;
+}
+
+export function spliceNodeRewriteVariant(args: {
+  content: string;
+  target: NodeRewriteTarget;
+  variant: NodeRewriteVariant;
+  source: CodeLayerSource;
+  fileType: string;
+}): { content: string; node: CodeLayerNode; variant: NodeRewriteVariant } {
+  const node = resolveNodeRewriteTarget(args.content, args.target, args.source);
+  const variant = validateNodeRewriteVariant(args.variant, args.source);
+  const replacement = annotateScreenHtmlForPersist(variant.html, args.fileType);
+  const nextContent = `${args.content.slice(0, node.source!.start)}${replacement}${args.content.slice(node.source!.end)}`;
+  assertDesignHtmlEditIntegrity({
+    previousContent: args.content,
+    nextContent,
+    fileType: args.fileType,
+  });
+  return {
+    content: nextContent,
+    node,
+    variant: { ...variant, html: replacement },
+  };
+}

package/corpus/templates/design/shared/review-anchor.ts

@@ -5,22 +5,25 @@ export interface ReviewAnchorPoint {
 
 export interface DesignReviewAnchor {
   nodeId?: string;
+  selector?: string;
   point: ReviewAnchorPoint;
 }
 
 export interface ResolvedReviewAnchor {
   anchor: DesignReviewAnchor;
   point: ReviewAnchorPoint;
-  source: "node" | "point";
+  source: "node" | "selector" | "point";
 }
 
 export function createElementReviewAnchor(input: {
   nodeId?: string | null;
+  selector?: string | null;
   rect?: { x: number; y: number; width: number; height: number } | null;
   viewportWidth?: number | null;
   viewportHeight?: number | null;
 }): DesignReviewAnchor | null {
   const nodeId = input.nodeId?.trim() ?? "";
+  const selector = input.selector?.trim() ?? "";
   const rect = input.rect;
   const hasRect = Boolean(
     rect &&
@@ -37,7 +40,7 @@ export function createElementReviewAnchor(input: {
     Number.isFinite(input.viewportHeight) &&
     input.viewportHeight > 0,
   );
-  if (!nodeId && !hasRect) return null;
+  if (!nodeId && !selector && !hasRect) return null;
 
   const point = hasRect
     ? {
@@ -58,6 +61,7 @@ export function createElementReviewAnchor(input: {
 
   return {
     ...(nodeId ? { nodeId } : {}),
+    ...(selector ? { selector } : {}),
     point,
   };
 }
@@ -100,16 +104,21 @@ export function parseReviewAnchor(value: unknown): DesignReviewAnchor | null {
   if (xPct === null || yPct === null) return null;
 
   const nodeId = typeof record.nodeId === "string" ? record.nodeId.trim() : "";
+  const selector =
+    typeof record.selector === "string" ? record.selector.trim() : "";
   return {
     ...(nodeId ? { nodeId } : {}),
+    ...(selector ? { selector } : {}),
     point: { xPct, yPct },
   };
 }
 
-/** Resolve a node-id position first, then degrade to the stored click point. */
+/** Resolve a node or selector position first, then degrade to the click point. */
 export function resolveReviewAnchor(
   value: unknown,
   resolveNodePoint: (nodeId: string) => ReviewAnchorPoint | null,
+  resolveSelectorPoint: (selector: string) => ReviewAnchorPoint | null = () =>
+    null,
 ): ResolvedReviewAnchor | null {
   const anchor = parseReviewAnchor(value);
   if (!anchor) return null;
@@ -127,5 +136,19 @@ export function resolveReviewAnchor(
       }
     }
   }
+  if (anchor.selector) {
+    const selectorPoint = resolveSelectorPoint(anchor.selector);
+    if (selectorPoint) {
+      const xPct = inBoundsPercentage(selectorPoint.xPct);
+      const yPct = inBoundsPercentage(selectorPoint.yPct);
+      if (xPct !== null && yPct !== null) {
+        return {
+          anchor,
+          point: { xPct, yPct },
+          source: "selector",
+        };
+      }
+    }
+  }
   return { anchor, point: anchor.point, source: "point" };
 }

package/dist/application-state/index.d.ts

@@ -1,5 +1,5 @@
-export { appStateGet, appStateGetMany, appStatePut, appStateDelete, appStateList, appStateDeleteByPrefix, } from "./store.js";
+export { appStateGet, appStateGetMany, appStatePut, appStateDelete, appStateCompareAndSet, appStateList, appStateDeleteByPrefix, } from "./store.js";
 export { getAppStateEmitter, emitAppStateChange, emitAppStateDelete, type AppStateEvent, } from "./emitter.js";
 export { getState, putState, deleteState, listComposeDrafts, getComposeDraft, putComposeDraft, deleteComposeDraft, deleteAllComposeDrafts, } from "./handlers.js";
-export { readAppState, writeAppState, deleteAppState, listAppState, deleteAppStateByPrefix, readAppStateForCurrentTab, writeAppStateForCurrentTab, appStateKeyForBrowserTab, getCurrentRequestBrowserTabId, } from "./script-helpers.js";
+export { readAppState, writeAppState, deleteAppState, compareAndSetAppState, listAppState, deleteAppStateByPrefix, readAppStateForCurrentTab, writeAppStateForCurrentTab, appStateKeyForBrowserTab, getCurrentRequestBrowserTabId, } from "./script-helpers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/application-state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/application-state/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/application-state/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC"}

package/dist/application-state/index.js

@@ -1,9 +1,9 @@
 // Store
-export { appStateGet, appStateGetMany, appStatePut, appStateDelete, appStateList, appStateDeleteByPrefix, } from "./store.js";
+export { appStateGet, appStateGetMany, appStatePut, appStateDelete, appStateCompareAndSet, appStateList, appStateDeleteByPrefix, } from "./store.js";
 // Emitter (for SSE wiring)
 export { getAppStateEmitter, emitAppStateChange, emitAppStateDelete, } from "./emitter.js";
 // H3 route handlers (for templates)
 export { getState, putState, deleteState, listComposeDrafts, getComposeDraft, putComposeDraft, deleteComposeDraft, deleteAllComposeDrafts, } from "./handlers.js";
 // Script helpers
-export { readAppState, writeAppState, deleteAppState, listAppState, deleteAppStateByPrefix, readAppStateForCurrentTab, writeAppStateForCurrentTab, appStateKeyForBrowserTab, getCurrentRequestBrowserTabId, } from "./script-helpers.js";
+export { readAppState, writeAppState, deleteAppState, compareAndSetAppState, listAppState, deleteAppStateByPrefix, readAppStateForCurrentTab, writeAppStateForCurrentTab, appStateKeyForBrowserTab, getCurrentRequestBrowserTabId, } from "./script-helpers.js";
 //# sourceMappingURL=index.js.map

package/dist/application-state/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/application-state/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,2BAA2B;AAC3B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,cAAc,CAAC;AAEtB,oCAAoC;AACpC,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC","sourcesContent":["// Store\nexport {\n  appStateGet,\n  appStateGetMany,\n  appStatePut,\n  appStateDelete,\n  appStateList,\n  appStateDeleteByPrefix,\n} from \"./store.js\";\n\n// Emitter (for SSE wiring)\nexport {\n  getAppStateEmitter,\n  emitAppStateChange,\n  emitAppStateDelete,\n  type AppStateEvent,\n} from \"./emitter.js\";\n\n// H3 route handlers (for templates)\nexport {\n  getState,\n  putState,\n  deleteState,\n  listComposeDrafts,\n  getComposeDraft,\n  putComposeDraft,\n  deleteComposeDraft,\n  deleteAllComposeDrafts,\n} from \"./handlers.js\";\n\n// Script helpers\nexport {\n  readAppState,\n  writeAppState,\n  deleteAppState,\n  listAppState,\n  deleteAppStateByPrefix,\n  readAppStateForCurrentTab,\n  writeAppStateForCurrentTab,\n  appStateKeyForBrowserTab,\n  getCurrentRequestBrowserTabId,\n} from \"./script-helpers.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/application-state/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,2BAA2B;AAC3B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,cAAc,CAAC;AAEtB,oCAAoC;AACpC,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAEvB,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC","sourcesContent":["// Store\nexport {\n  appStateGet,\n  appStateGetMany,\n  appStatePut,\n  appStateDelete,\n  appStateCompareAndSet,\n  appStateList,\n  appStateDeleteByPrefix,\n} from \"./store.js\";\n\n// Emitter (for SSE wiring)\nexport {\n  getAppStateEmitter,\n  emitAppStateChange,\n  emitAppStateDelete,\n  type AppStateEvent,\n} from \"./emitter.js\";\n\n// H3 route handlers (for templates)\nexport {\n  getState,\n  putState,\n  deleteState,\n  listComposeDrafts,\n  getComposeDraft,\n  putComposeDraft,\n  deleteComposeDraft,\n  deleteAllComposeDrafts,\n} from \"./handlers.js\";\n\n// Script helpers\nexport {\n  readAppState,\n  writeAppState,\n  deleteAppState,\n  compareAndSetAppState,\n  listAppState,\n  deleteAppStateByPrefix,\n  readAppStateForCurrentTab,\n  writeAppStateForCurrentTab,\n  appStateKeyForBrowserTab,\n  getCurrentRequestBrowserTabId,\n} from \"./script-helpers.js\";\n"]}

package/dist/application-state/script-helpers.d.ts

@@ -14,6 +14,7 @@
 export declare function readAppState(key: string): Promise<Record<string, unknown> | null>;
 export declare function writeAppState(key: string, value: Record<string, unknown>): Promise<void>;
 export declare function deleteAppState(key: string): Promise<boolean>;
+export declare function compareAndSetAppState(key: string, expectedValue: Record<string, unknown>, nextValue: Record<string, unknown> | null): Promise<boolean>;
 export declare function listAppState(prefix: string): Promise<Array<{
     key: string;
     value: Record<string, unknown>;

package/dist/application-state/script-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script-helpers.d.ts","sourceRoot":"","sources":["../../src/application-state/script-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAqCH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAGzC;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKlE;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC,CAGjE;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK5E;AAUD;;;;GAIG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,GAAG,IAAI,CAM7D;AAED,uEAAuE;AACvE,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,OAAO,GACpB,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAQzC;AAED,oEAAoE;AACpE,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAGf"}
+{"version":3,"file":"script-helpers.d.ts","sourceRoot":"","sources":["../../src/application-state/script-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsCH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAGzC;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKlE;AAED,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACxC,OAAO,CAAC,OAAO,CAAC,CAKlB;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC,CAGjE;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK5E;AAUD;;;;GAIG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,GAAG,IAAI,CAM7D;AAED,uEAAuE;AACvE,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,OAAO,GACpB,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAQzC;AAED,oEAAoE;AACpE,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/application-state/script-helpers.js

@@ -12,7 +12,7 @@
  * context) should fall through to the env var.
  */
 import { getRequestRunContext } from "../server/request-context.js";
-import { appStateGet, appStatePut, appStateDelete, appStateList, appStateDeleteByPrefix, } from "./store.js";
+import { appStateGet, appStatePut, appStateDelete, appStateCompareAndSet, appStateList, appStateDeleteByPrefix, } from "./store.js";
 /**
  * Resolve session ID for the current caller.
  *
@@ -52,6 +52,12 @@ export async function deleteAppState(key) {
         requestSource: "agent",
     });
 }
+export async function compareAndSetAppState(key, expectedValue, nextValue) {
+    const sessionId = await resolveSessionId();
+    return appStateCompareAndSet(sessionId, key, expectedValue, nextValue, {
+        requestSource: "agent",
+    });
+}
 export async function listAppState(prefix) {
     const sessionId = await resolveSessionId();
     return appStateList(sessionId, prefix);

package/dist/application-state/script-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"script-helpers.js","sourceRoot":"","sources":["../../src/application-state/script-helpers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Application state helpers for use in scripts and actions.\n *\n * The session ID determines which user's application state is read/written.\n * Resolution order:\n *   1. Per-request context (AsyncLocalStorage) — set by the HTTP handler\n *   2. AGENT_USER_EMAIL env var — CLI scripts only\n *\n * The per-request context is critical in multi-user deployments: the env var\n * is process-global and gets overwritten by concurrent requests, so it cannot\n * reliably identify the caller. Only CLI scripts (single-user, no HTTP\n * context) should fall through to the env var.\n */\n\nimport { getRequestRunContext } from \"../server/request-context.js\";\nimport {\n  appStateGet,\n  appStatePut,\n  appStateDelete,\n  appStateList,\n  appStateDeleteByPrefix,\n} from \"./store.js\";\n\n/**\n * Resolve session ID for the current caller.\n *\n * In an HTTP/action context, uses the per-request user email from\n * AsyncLocalStorage so concurrent users don't collide. In a CLI context\n * (no request), falls back to AGENT_USER_EMAIL. Throws when neither is\n * present — application state must be scoped to a real identity.\n */\nasync function resolveSessionId(): Promise<string> {\n  try {\n    const { getRequestUserEmail } =\n      await import(\"../server/request-context.js\");\n    const ctxEmail = getRequestUserEmail();\n    if (ctxEmail) return ctxEmail;\n  } catch {\n    // request-context not available — fall through to env var\n  }\n\n  const email = process.env.AGENT_USER_EMAIL;\n  if (email) return email;\n\n  throw new Error(\n    \"Application state access requires an authenticated request context or AGENT_USER_EMAIL env var\",\n  );\n}\n\nexport async function readAppState(\n  key: string,\n): Promise<Record<string, unknown> | null> {\n  const sessionId = await resolveSessionId();\n  return appStateGet(sessionId, key);\n}\n\nexport async function writeAppState(\n  key: string,\n  value: Record<string, unknown>,\n): Promise<void> {\n  const sessionId = await resolveSessionId();\n  return appStatePut(sessionId, key, value, {\n    requestSource: \"agent\",\n  });\n}\n\nexport async function deleteAppState(key: string): Promise<boolean> {\n  const sessionId = await resolveSessionId();\n  return appStateDelete(sessionId, key, {\n    requestSource: \"agent\",\n  });\n}\n\nexport async function listAppState(\n  prefix: string,\n): Promise<Array<{ key: string; value: Record<string, unknown> }>> {\n  const sessionId = await resolveSessionId();\n  return appStateList(sessionId, prefix);\n}\n\nexport async function deleteAppStateByPrefix(prefix: string): Promise<number> {\n  const sessionId = await resolveSessionId();\n  return appStateDeleteByPrefix(sessionId, prefix, {\n    requestSource: \"agent\",\n  });\n}\n\nconst SAFE_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;\n\nfunction normalizeBrowserTabId(value: unknown): string | null {\n  if (typeof value !== \"string\") return null;\n  const trimmed = value.trim();\n  return SAFE_TAB_ID_RE.test(trimmed) ? trimmed : null;\n}\n\n/**\n * Browser tab id for the current request, if the client sent one. Used to\n * scope ambient UI state (navigation, selection, etc.) so a chat from one tab\n * reads that tab's state instead of whichever tab wrote the global key last.\n */\nexport function getCurrentRequestBrowserTabId(): string | null {\n  try {\n    return normalizeBrowserTabId(getRequestRunContext()?.browserTabId);\n  } catch {\n    return null;\n  }\n}\n\n/** `key:<tabId>` when a browser tab id is present, otherwise `key`. */\nexport function appStateKeyForBrowserTab(\n  key: string,\n  browserTabId: unknown,\n): string {\n  const normalized = normalizeBrowserTabId(browserTabId);\n  return normalized ? `${key}:${normalized}` : key;\n}\n\n/**\n * Read application state scoped to the requesting browser tab. Reads the\n * tab-scoped key first and (by default) falls back to the global key so\n * CLI/external agents and pre-scoping clients keep working.\n */\nexport async function readAppStateForCurrentTab(\n  key: string,\n  options?: { fallbackToGlobal?: boolean },\n): Promise<Record<string, unknown> | null> {\n  const tabKey = appStateKeyForBrowserTab(key, getCurrentRequestBrowserTabId());\n  if (tabKey !== key) {\n    const scoped = await readAppState(tabKey).catch(() => null);\n    if (scoped) return scoped;\n    if (options?.fallbackToGlobal === false) return null;\n  }\n  return readAppState(key);\n}\n\n/** Write application state scoped to the requesting browser tab. */\nexport async function writeAppStateForCurrentTab(\n  key: string,\n  value: Record<string, unknown>,\n): Promise<void> {\n  const tabKey = appStateKeyForBrowserTab(key, getCurrentRequestBrowserTabId());\n  return writeAppState(tabKey, value);\n}\n"]}
+{"version":3,"file":"script-helpers.js","sourceRoot":"","sources":["../../src/application-state/script-helpers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Application state helpers for use in scripts and actions.\n *\n * The session ID determines which user's application state is read/written.\n * Resolution order:\n *   1. Per-request context (AsyncLocalStorage) — set by the HTTP handler\n *   2. AGENT_USER_EMAIL env var — CLI scripts only\n *\n * The per-request context is critical in multi-user deployments: the env var\n * is process-global and gets overwritten by concurrent requests, so it cannot\n * reliably identify the caller. Only CLI scripts (single-user, no HTTP\n * context) should fall through to the env var.\n */\n\nimport { getRequestRunContext } from \"../server/request-context.js\";\nimport {\n  appStateGet,\n  appStatePut,\n  appStateDelete,\n  appStateCompareAndSet,\n  appStateList,\n  appStateDeleteByPrefix,\n} from \"./store.js\";\n\n/**\n * Resolve session ID for the current caller.\n *\n * In an HTTP/action context, uses the per-request user email from\n * AsyncLocalStorage so concurrent users don't collide. In a CLI context\n * (no request), falls back to AGENT_USER_EMAIL. Throws when neither is\n * present — application state must be scoped to a real identity.\n */\nasync function resolveSessionId(): Promise<string> {\n  try {\n    const { getRequestUserEmail } =\n      await import(\"../server/request-context.js\");\n    const ctxEmail = getRequestUserEmail();\n    if (ctxEmail) return ctxEmail;\n  } catch {\n    // request-context not available — fall through to env var\n  }\n\n  const email = process.env.AGENT_USER_EMAIL;\n  if (email) return email;\n\n  throw new Error(\n    \"Application state access requires an authenticated request context or AGENT_USER_EMAIL env var\",\n  );\n}\n\nexport async function readAppState(\n  key: string,\n): Promise<Record<string, unknown> | null> {\n  const sessionId = await resolveSessionId();\n  return appStateGet(sessionId, key);\n}\n\nexport async function writeAppState(\n  key: string,\n  value: Record<string, unknown>,\n): Promise<void> {\n  const sessionId = await resolveSessionId();\n  return appStatePut(sessionId, key, value, {\n    requestSource: \"agent\",\n  });\n}\n\nexport async function deleteAppState(key: string): Promise<boolean> {\n  const sessionId = await resolveSessionId();\n  return appStateDelete(sessionId, key, {\n    requestSource: \"agent\",\n  });\n}\n\nexport async function compareAndSetAppState(\n  key: string,\n  expectedValue: Record<string, unknown>,\n  nextValue: Record<string, unknown> | null,\n): Promise<boolean> {\n  const sessionId = await resolveSessionId();\n  return appStateCompareAndSet(sessionId, key, expectedValue, nextValue, {\n    requestSource: \"agent\",\n  });\n}\n\nexport async function listAppState(\n  prefix: string,\n): Promise<Array<{ key: string; value: Record<string, unknown> }>> {\n  const sessionId = await resolveSessionId();\n  return appStateList(sessionId, prefix);\n}\n\nexport async function deleteAppStateByPrefix(prefix: string): Promise<number> {\n  const sessionId = await resolveSessionId();\n  return appStateDeleteByPrefix(sessionId, prefix, {\n    requestSource: \"agent\",\n  });\n}\n\nconst SAFE_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;\n\nfunction normalizeBrowserTabId(value: unknown): string | null {\n  if (typeof value !== \"string\") return null;\n  const trimmed = value.trim();\n  return SAFE_TAB_ID_RE.test(trimmed) ? trimmed : null;\n}\n\n/**\n * Browser tab id for the current request, if the client sent one. Used to\n * scope ambient UI state (navigation, selection, etc.) so a chat from one tab\n * reads that tab's state instead of whichever tab wrote the global key last.\n */\nexport function getCurrentRequestBrowserTabId(): string | null {\n  try {\n    return normalizeBrowserTabId(getRequestRunContext()?.browserTabId);\n  } catch {\n    return null;\n  }\n}\n\n/** `key:<tabId>` when a browser tab id is present, otherwise `key`. */\nexport function appStateKeyForBrowserTab(\n  key: string,\n  browserTabId: unknown,\n): string {\n  const normalized = normalizeBrowserTabId(browserTabId);\n  return normalized ? `${key}:${normalized}` : key;\n}\n\n/**\n * Read application state scoped to the requesting browser tab. Reads the\n * tab-scoped key first and (by default) falls back to the global key so\n * CLI/external agents and pre-scoping clients keep working.\n */\nexport async function readAppStateForCurrentTab(\n  key: string,\n  options?: { fallbackToGlobal?: boolean },\n): Promise<Record<string, unknown> | null> {\n  const tabKey = appStateKeyForBrowserTab(key, getCurrentRequestBrowserTabId());\n  if (tabKey !== key) {\n    const scoped = await readAppState(tabKey).catch(() => null);\n    if (scoped) return scoped;\n    if (options?.fallbackToGlobal === false) return null;\n  }\n  return readAppState(key);\n}\n\n/** Write application state scoped to the requesting browser tab. */\nexport async function writeAppStateForCurrentTab(\n  key: string,\n  value: Record<string, unknown>,\n): Promise<void> {\n  const tabKey = appStateKeyForBrowserTab(key, getCurrentRequestBrowserTabId());\n  return writeAppState(tabKey, value);\n}\n"]}

package/dist/application-state/store.d.ts

@@ -8,6 +8,7 @@ export declare function appStateGet(sessionId: string, key: string): Promise<Rec
 export declare function appStateGetMany(sessionId: string, keys: readonly string[]): Promise<Record<string, Record<string, unknown> | null>>;
 export declare function appStatePut(sessionId: string, key: string, value: Record<string, unknown>, options?: StoreWriteOptions): Promise<void>;
 export declare function appStateDelete(sessionId: string, key: string, options?: StoreWriteOptions): Promise<boolean>;
+export declare function appStateCompareAndSet(sessionId: string, key: string, expectedValue: Record<string, unknown>, nextValue: Record<string, unknown> | null, options?: StoreWriteOptions): Promise<boolean>;
 export declare function appStateList(sessionId: string, keyPrefix: string): Promise<Array<{
     key: string;
     value: Record<string, unknown>;

package/dist/application-state/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/application-state/store.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAyF9D,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAgBzC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAsBzD;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC,CAWjE;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAsBjB"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/application-state/store.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAyF9D,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAgBzC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAsBzD;AAED,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACzC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,OAAO,CAAC,CA8BlB;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC,CAWjE;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAsBjB"}

package/dist/application-state/store.js

@@ -157,6 +157,34 @@ export async function appStateDelete(sessionId, key, options) {
         emitAppStateDelete(key, options?.requestSource, sessionId);
     return deleted;
 }
+export async function appStateCompareAndSet(sessionId, key, expectedValue, nextValue, options) {
+    await ensureTable();
+    const client = getDbExec();
+    const expected = JSON.stringify(expectedValue);
+    if (nextValue === null) {
+        const result = await client.execute({
+            sql: `DELETE FROM application_state WHERE session_id = ? AND key = ? AND value = ?`,
+            args: [sessionId, key, expected],
+        });
+        const changed = result.rowsAffected > 0;
+        if (changed)
+            emitAppStateDelete(key, options?.requestSource, sessionId);
+        return changed;
+    }
+    const next = JSON.stringify(nextValue);
+    if (!isLocalDatabase() &&
+        Buffer.byteLength(next, "utf8") > MAX_HOSTED_APP_STATE_VALUE_BYTES) {
+        throw new Error(`application_state value "${key}" is too large for hosted SQL storage. Store large files, base64, or blobs in file storage and write only a URL or handle.`);
+    }
+    const result = await client.execute({
+        sql: `UPDATE application_state SET value = ?, updated_at = ? WHERE session_id = ? AND key = ? AND value = ?`,
+        args: [next, Date.now(), sessionId, key, expected],
+    });
+    const changed = result.rowsAffected > 0;
+    if (changed)
+        emitAppStateChange(key, options?.requestSource, sessionId);
+    return changed;
+}
 export async function appStateList(sessionId, keyPrefix) {
     await ensureTable();
     const client = getDbExec();