@agent-native/core 0.106.0 → 0.106.1

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2283
-- template files: 6054
+- template files: 6062

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.106.1
+
+### Patch Changes
+
+- 0d8118e: Allow review comment composers to render a custom agent action in the standard action row, choose the Enter-key submit target, and atomically compare-and-set application state for race-safe UI workflows.
+
 ## 0.106.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.106.0",
+  "version": "0.106.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/application-state/index.ts

@@ -4,6 +4,7 @@ export {
   appStateGetMany,
   appStatePut,
   appStateDelete,
+  appStateCompareAndSet,
   appStateList,
   appStateDeleteByPrefix,
 } from "./store.js";
@@ -33,6 +34,7 @@ export {
   readAppState,
   writeAppState,
   deleteAppState,
+  compareAndSetAppState,
   listAppState,
   deleteAppStateByPrefix,
   readAppStateForCurrentTab,

package/corpus/core/src/application-state/script-helpers.ts

@@ -17,6 +17,7 @@ import {
   appStateGet,
   appStatePut,
   appStateDelete,
+  appStateCompareAndSet,
   appStateList,
   appStateDeleteByPrefix,
 } from "./store.js";
@@ -71,6 +72,17 @@ export async function deleteAppState(key: string): Promise<boolean> {
   });
 }
 
+export async function compareAndSetAppState(
+  key: string,
+  expectedValue: Record<string, unknown>,
+  nextValue: Record<string, unknown> | null,
+): Promise<boolean> {
+  const sessionId = await resolveSessionId();
+  return appStateCompareAndSet(sessionId, key, expectedValue, nextValue, {
+    requestSource: "agent",
+  });
+}
+
 export async function listAppState(
   prefix: string,
 ): Promise<Array<{ key: string; value: Record<string, unknown> }>> {

package/corpus/core/src/application-state/store.ts

@@ -191,6 +191,44 @@ export async function appStateDelete(
   return deleted;
 }
 
+export async function appStateCompareAndSet(
+  sessionId: string,
+  key: string,
+  expectedValue: Record<string, unknown>,
+  nextValue: Record<string, unknown> | null,
+  options?: StoreWriteOptions,
+): Promise<boolean> {
+  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: string,
   keyPrefix: string,

package/corpus/core/src/client/review/ReviewCommentComposer.tsx

@@ -2,6 +2,7 @@ import { Button } from "@agent-native/toolkit/ui/button";
 import { Spinner } from "@agent-native/toolkit/ui/spinner";
 import { Textarea } from "@agent-native/toolkit/ui/textarea";
 import { IconFocus2, IconMessageCircle, IconSend } from "@tabler/icons-react";
+import type { ReactNode } from "react";
 
 import type { ReviewResolutionTarget } from "../../review/types.js";
 import { cn } from "../utils.js";
@@ -13,12 +14,14 @@ export interface ReviewCommentComposerProps {
   submittingTarget?: ReviewResolutionTarget | null;
   disabled?: boolean;
   showAgentAction?: boolean;
+  agentAction?: ReactNode;
   placeholder?: string;
   commentLabel?: string;
   agentLabel?: string;
   contextLabel?: string;
   autoFocus?: boolean;
   submitOnEnter?: boolean;
+  enterSubmitTarget?: ReviewResolutionTarget;
   onEscape?: () => void;
   className?: string;
 }
@@ -30,12 +33,14 @@ export function ReviewCommentComposer({
   submittingTarget = null,
   disabled = false,
   showAgentAction = false,
+  agentAction,
   placeholder = "Add a comment...",
   commentLabel = "Comment",
   agentLabel = "Send to agent",
   contextLabel,
   autoFocus = false,
   submitOnEnter = false,
+  enterSubmitTarget = "human",
   onEscape,
   className,
 }: ReviewCommentComposerProps) {
@@ -75,7 +80,7 @@ export function ReviewCommentComposer({
           }
           if (submitOnEnter && event.key === "Enter" && !event.shiftKey) {
             event.preventDefault();
-            submit("human");
+            submit(enterSubmitTarget);
           }
         }}
       />
@@ -84,7 +89,7 @@ export function ReviewCommentComposer({
           type="submit"
           size="sm"
           disabled={!canSubmit}
-          className="h-8 w-full min-w-0 gap-1.5 @2xs/review:w-auto"
+          className="h-8 w-full gap-1.5 @2xs/review:w-auto @2xs/review:min-w-28 @2xs/review:shrink-0"
         >
           {submittingTarget === "human" ? (
             <Spinner className="size-3.5" />
@@ -93,7 +98,9 @@ export function ReviewCommentComposer({
           )}
           <span className="truncate">{commentLabel}</span>
         </Button>
-        {showAgentAction ? (
+        {showAgentAction && agentAction ? (
+          agentAction
+        ) : showAgentAction ? (
           <Button
             type="button"
             size="sm"

package/corpus/templates/design/.agents/skills/visual-edit/SKILL.md

@@ -47,6 +47,28 @@ iframe-backed screens on the infinite canvas.
   and create one screen per URL/path. Shorthand like
   `localhost:1234/onboarding/1` means `http://localhost:1234/onboarding/1`.
 
+## Select And Reprompt
+
+When a chat message begins with `[Reprompt selection]`, the selected subtree is
+a hard write boundary. The only mutation path is `propose-node-rewrite` with
+the exact `repromptId`, target, and `baseVersionHash` captured in
+`design-reprompt-pending:<designId>:<fileId>`. Never use `apply-visual-edit`,
+`apply-source-edit`, `write-source`, `write-local-file`, `edit-design`, or any
+other content-writing action for that request. Clarifying questions are allowed,
+but a requested change must remain a proposal.
+
+Produce one variant by default. Produce two or three only when the instruction
+asks for options. A retry includes `priorProposalId`; keep the same target and
+base version, incorporate the feedback, and call `propose-node-rewrite` again.
+The UI previews the returned subtree without persisting it.
+
+Use `resolve-node-rewrite` for the accept/reject lifecycle. Accept applies the
+chosen variant as one version-checked inline/Yjs content transaction so one
+undo restores the prior structure; reject clears the proposal without changing
+content. For conversational resolution such as “apply the second one,” call
+`view-screen`, read the active `design.reprompt.proposal`, and pass its
+`proposalId` plus the zero-based `variantIndex` to `resolve-node-rewrite`.
+
 ## Review Quality
 
 - Treat the running app as the truth. Preserve its component language, tokens,

package/corpus/templates/design/AGENTS.md

@@ -16,6 +16,13 @@ patterns live in `.agents/skills/`.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use the app actions for designs, files, versions, design systems, variants,
   export, and sharing. Do not write design rows directly with SQL.
+- A message beginning with `[Reprompt selection]` is preview-only. Call
+  `propose-node-rewrite` with its exact `repromptId`, target, and base hash;
+  never call `edit-design`, `update-design`, `update-file`, `generate-design`,
+  `apply-visual-edit`, or another content writer. Only the frontend-only
+  `resolve-node-rewrite` action may persist an explicitly accepted proposal.
+- A message beginning with `[Selection question]` is read-only. Answer about
+  the captured element and subtree without calling content-writing actions.
 - When a user wants an established public system as a starting point, call
   `create-design-system` with `templateId: material-3`, `carbon-white`, or
   `primer-light`. These are source-linked, versioned token snapshots with
@@ -268,6 +275,15 @@ patterns live in `.agents/skills/`.
   generation planning state created by `generate-screens` (canvas region
   assignments and per-frame instructions consumed by `generate-design` and
   `view-screen`; not rendered as canvas overlays).
+- `design-reprompt-pending:<designId>:<fileId>` is the client-captured source
+  selection, instruction, base hash, and authoritative current request id for
+  a scoped regenerate request.
+- `design-reprompt-proposal:<designId>:<fileId>:<repromptId>` is one
+  request-specific preview-only subtree proposal. Candidate payloads have a
+  256 KiB aggregate serialized limit. Resolution and cancellation use atomic
+  compare-and-set cleanup so an older request cannot erase a newer one.
+  `view-screen` lists only proposals paired to the current pending request as
+  `pendingCandidateReviews`.
 - `show-design-questions` opens focused pre-generation questions in the main
   design canvas (`show-questions` application state).
 - `guided-questions` may contain a one-click chat choice for the current

package/corpus/templates/design/actions/cancel-node-rewrite-request.ts

@@ -0,0 +1,54 @@
+import { defineAction } from "@agent-native/core";
+import {
+  compareAndSetAppState,
+  readAppState,
+} from "@agent-native/core/application-state";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import {
+  designRepromptPendingStateKey,
+  designRepromptProposalStateKey,
+  isNodeRewriteProposal,
+  isPendingDesignReprompt,
+} from "../shared/node-rewrite.js";
+
+export default defineAction({
+  agentTool: false,
+  description:
+    "Cancel one pending node rewrite only when it is still the current request.",
+  schema: z.object({
+    designId: z.string().min(1),
+    fileId: z.string().min(1),
+    repromptId: z.string().min(1),
+  }),
+  run: async ({ designId, fileId, repromptId }) => {
+    await assertAccess("design", designId, "editor");
+    const pendingKey = designRepromptPendingStateKey(designId, fileId);
+    const pending = await readAppState(pendingKey);
+    if (
+      !isPendingDesignReprompt(pending) ||
+      pending.repromptId !== repromptId
+    ) {
+      return { cancelled: false, superseded: true };
+    }
+
+    const proposalKey = designRepromptProposalStateKey(
+      designId,
+      fileId,
+      repromptId,
+    );
+    const proposal = await readAppState(proposalKey);
+    const [pendingCancelled, proposalCancelled] = await Promise.all([
+      compareAndSetAppState(pendingKey, pending, null),
+      isNodeRewriteProposal(proposal)
+        ? compareAndSetAppState(proposalKey, proposal, null)
+        : Promise.resolve(false),
+    ]);
+    return {
+      cancelled: pendingCancelled,
+      proposalCancelled,
+      superseded: !pendingCancelled,
+    };
+  },
+});

package/corpus/templates/design/actions/propose-node-rewrite.ts

@@ -0,0 +1,290 @@
+import { defineAction } from "@agent-native/core";
+import {
+  compareAndSetAppState,
+  readAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import {
+  readLiveSourceFile,
+  type SourceWorkspaceFile,
+} from "../server/source-workspace.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import {
+  designRepromptPendingStateKey,
+  designRepromptProposalStateKey,
+  MAX_NODE_REWRITE_PROPOSAL_BYTES,
+  resolveNodeRewriteTarget,
+  validateNodeRewriteVariant,
+  type NodeHtmlPreviewBridgeMessage,
+  type NodeRewriteProposal,
+  type NodeRewriteTarget,
+} from "../shared/node-rewrite.js";
+import { designSourceTypeFromData } from "../shared/source-mode.js";
+
+const sourceSchema = z
+  .object({
+    designId: z.string().min(1).optional(),
+    fileId: z.string().min(1).optional(),
+    filename: z.string().min(1).optional(),
+  })
+  .superRefine((source, ctx) => {
+    if (!source.designId && !source.fileId) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["designId"],
+        message: "source.designId or source.fileId is required",
+      });
+    }
+  });
+
+const targetSchema = z
+  .object({
+    nodeId: z.string().min(1).optional(),
+    selector: z.string().min(1).optional(),
+  })
+  .superRefine((target, ctx) => {
+    if (!target.nodeId && !target.selector) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["nodeId"],
+        message: "target.nodeId or target.selector is required",
+      });
+    }
+  });
+
+const variantSchema = z.object({
+  html: z
+    .string()
+    .min(1)
+    .max(250_000)
+    .describe("Replacement outerHTML for the selected subtree"),
+  summary: z.string().trim().min(1).max(240),
+});
+
+const pendingRepromptSchema = z.object({
+  repromptId: z.string().min(1),
+  designId: z.string().min(1),
+  fileId: z.string().min(1),
+  target: targetSchema,
+  baseVersionHash: z.string().min(1),
+  instruction: z.string(),
+  createdAt: z.string(),
+  priorProposalId: z.string().min(1).optional(),
+  priorRepromptId: z.string().min(1).optional(),
+});
+
+interface EditableDesignFile extends SourceWorkspaceFile {
+  designData: string | null;
+}
+
+async function resolveEditableDesignFile(source: {
+  designId?: string;
+  fileId?: string;
+  filename?: string;
+}): Promise<EditableDesignFile> {
+  const db = getDb();
+  const conditions = [
+    accessFilter(schema.designs, schema.designShares),
+    source.fileId
+      ? eq(schema.designFiles.id, source.fileId)
+      : eq(schema.designFiles.designId, source.designId ?? ""),
+  ];
+  if (!source.fileId) {
+    conditions.push(
+      eq(schema.designFiles.filename, source.filename ?? "index.html"),
+    );
+  }
+
+  const [file] = await db
+    .select({
+      id: schema.designFiles.id,
+      designId: schema.designFiles.designId,
+      filename: schema.designFiles.filename,
+      fileType: schema.designFiles.fileType,
+      content: schema.designFiles.content,
+      createdAt: schema.designFiles.createdAt,
+      updatedAt: schema.designFiles.updatedAt,
+      designData: schema.designs.data,
+    })
+    .from(schema.designFiles)
+    .innerJoin(
+      schema.designs,
+      eq(schema.designFiles.designId, schema.designs.id),
+    )
+    .where(and(...conditions))
+    .limit(1);
+
+  if (!file) throw new Error("Design HTML file not found.");
+  if (source.designId && source.designId !== file.designId) {
+    throw new Error(
+      `source.designId "${source.designId}" does not match file "${file.id}"`,
+    );
+  }
+  if (source.filename && source.filename !== file.filename) {
+    throw new Error(
+      `source.filename "${source.filename}" does not match file "${file.id}"`,
+    );
+  }
+  if (file.fileType !== "html") {
+    throw new Error("Node rewrites only support HTML design files.");
+  }
+  if (designSourceTypeFromData(file.designData) !== "inline") {
+    throw new Error("Node rewrites only support inline design screens.");
+  }
+  await assertAccess("design", file.designId, "editor");
+  return file;
+}
+
+function targetsMatch(a: NodeRewriteTarget, b: NodeRewriteTarget): boolean {
+  const nodeIdsConflict = a.nodeId && b.nodeId && a.nodeId !== b.nodeId;
+  const selectorsConflict =
+    a.selector && b.selector && a.selector !== b.selector;
+  if (nodeIdsConflict || selectorsConflict) return false;
+  return Boolean(
+    (a.nodeId && b.nodeId && a.nodeId === b.nodeId) ||
+    (a.selector && b.selector && a.selector === b.selector),
+  );
+}
+
+export default defineAction({
+  description:
+    "Propose one to three scoped HTML rewrites for a pending Design selection. " +
+    "This previews only: it stores proposal state and never changes the design file. " +
+    "The target must identify, and the reprompt id and base hash must exactly match, the pending client selection.",
+  schema: z.object({
+    source: sourceSchema,
+    target: targetSchema,
+    baseVersionHash: z.string().min(1),
+    variants: z.array(variantSchema).min(1).max(3),
+    repromptId: z.string().min(1),
+  }),
+  run: async ({ source, target, baseVersionHash, variants, repromptId }) => {
+    const file = await resolveEditableDesignFile(source);
+    const sourceDescriptor: CodeLayerSource = {
+      kind: "design-file",
+      sourceType: "inline",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+    const live = await readLiveSourceFile(file);
+    if (live.versionHash !== baseVersionHash) {
+      throw new Error(
+        "Screen changed since the selection was captured — regenerate the proposal.",
+      );
+    }
+
+    const pendingKey = designRepromptPendingStateKey(file.designId, file.id);
+    const pending = pendingRepromptSchema.parse(await readAppState(pendingKey));
+    if (pending.repromptId !== repromptId) {
+      throw new Error("Pending reprompt does not match this request.");
+    }
+    if (
+      pending.designId !== file.designId ||
+      pending.fileId !== file.id ||
+      !targetsMatch(pending.target, target)
+    ) {
+      throw new Error(
+        "The proposed target does not match the pending selected subtree.",
+      );
+    }
+    if (pending.baseVersionHash !== baseVersionHash) {
+      throw new Error(
+        "The proposal base hash does not match the pending selection.",
+      );
+    }
+
+    const authoritativeTarget = pending.target;
+    const node = resolveNodeRewriteTarget(
+      live.content,
+      authoritativeTarget,
+      sourceDescriptor,
+    );
+    const validatedVariants = variants.map((variant) =>
+      validateNodeRewriteVariant(variant, sourceDescriptor),
+    );
+    const proposalId = `node-rewrite-${nanoid()}`;
+    const resolvedTarget = {
+      nodeId: node.id,
+      selector: node.selector,
+    };
+    const proposal: NodeRewriteProposal = {
+      proposalId,
+      repromptId,
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+      target: authoritativeTarget,
+      resolvedTarget,
+      baseVersionHash,
+      variants: validatedVariants,
+      chosenIndex: 0,
+      createdAt: new Date().toISOString(),
+    };
+    const serializedProposal = JSON.stringify(proposal);
+    if (
+      Buffer.byteLength(serializedProposal, "utf8") >
+      MAX_NODE_REWRITE_PROPOSAL_BYTES
+    ) {
+      throw new Error(
+        "Generated candidates are too large to preview safely. Use fewer variants or regenerate a smaller selected subtree.",
+      );
+    }
+    const proposalKey = designRepromptProposalStateKey(
+      file.designId,
+      file.id,
+      repromptId,
+    );
+    await writeAppState(
+      proposalKey,
+      proposal as unknown as Record<string, unknown>,
+    );
+    const currentPending = await readAppState(pendingKey);
+    if (currentPending?.repromptId !== repromptId) {
+      await compareAndSetAppState(
+        proposalKey,
+        proposal as unknown as Record<string, unknown>,
+        null,
+      );
+      throw new Error(
+        "This regeneration was superseded by a newer request before its candidates were published.",
+      );
+    }
+    if (pending.priorProposalId && pending.priorRepromptId) {
+      const priorProposalKey = designRepromptProposalStateKey(
+        file.designId,
+        file.id,
+        pending.priorRepromptId,
+      );
+      const priorProposal = await readAppState(priorProposalKey);
+      if (priorProposal?.proposalId === pending.priorProposalId) {
+        await compareAndSetAppState(priorProposalKey, priorProposal, null);
+      }
+    }
+
+    const bridgeMessages: NodeHtmlPreviewBridgeMessage[] = [
+      {
+        type: "node-html-preview",
+        proposalId,
+        target: resolvedTarget,
+        html: validatedVariants[0]!.html,
+        operation: "preview",
+      },
+    ];
+    return {
+      proposalId,
+      repromptId,
+      designId: file.designId,
+      fileId: file.id,
+      target: resolvedTarget,
+      variants: validatedVariants,
+      bridgeMessages,
+    };
+  },
+});