@desplega.ai/agent-swarm 2.4.0 → 2.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "agent-swarm.dev — an open-source operating system for AI work: a lead agent breaks goals into tasks, routes them to specialized workers such as Claude Code or Codex, runs each worker in an isolated container, and preserves shared memory, tools, schedules, and review gates so delegated work compounds across sessions.",
   "keywords": [
     "agent-swarm.dev",
@@ -200,7 +200,7 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "1.9.0",
     "@ai-sdk/openai": "^3.0.41",
-    "@anthropic-ai/claude-agent-sdk": "0.3.302",
+    "@anthropic-ai/claude-agent-sdk": "0.3.303",
     "@anthropic-ai/sdk": "^0.135.0",
     "@asteasolutions/zod-to-openapi": "^8.0.0",
     "@aws-sdk/client-bedrock": "3.1048.0",
@@ -209,7 +209,7 @@
     "@chat-adapter/teams": "4.41.1",
     "@chat-adapter/telegram": "4.41.1",
     "@cursor/sdk": "1.0.38",
-    "@desplega.ai/agent-fs-just-bash": "0.18.4",
+    "@desplega.ai/agent-fs-just-bash": "0.18.5",
     "@desplega.ai/business-use": "^0.4.2",
     "@earendil-works/pi-agent-core": "^1.3.0",
     "@earendil-works/pi-ai": "^1.3.0",

package/src/apps/action-runner.ts

@@ -0,0 +1,146 @@
+import { normalizeAssetKey } from "../assets/key";
+import { getLeadAgent } from "../be/db";
+import { getScriptById } from "../be/scripts/db";
+import { getSavedScriptOwnerAgentId, runSavedScriptAsAgent } from "../be/scripts/run-saved";
+import { resolveTemplate } from "../prompts/resolver";
+import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
+import { scrubObject } from "../utils/secret-scrubber";
+import type { AppActionCaller } from "./action-caller";
+import type { AppRecord } from "./store";
+import { runAppSync } from "./sync";
+
+/**
+ * One `error` string for a sync result, or undefined when every pass succeeded.
+ * Each failed pair is named so a multi-pair sync says which one broke; the pass
+ * list in `result.passes` carries the rest.
+ */
+function syncPassError(sync: Awaited<ReturnType<typeof runAppSync>>): string | undefined {
+  const failed = sync.passes.filter((pass) => pass.error !== undefined);
+  if (failed.length === 0) return undefined;
+  return failed.map((pass) => `${pass.model}.${pass.source}: ${pass.error}`).join("; ");
+}
+
+export async function runAppAction({
+  app,
+  name,
+  input = {},
+  caller,
+  actor,
+}: {
+  app: AppRecord;
+  name: string;
+  input?: Record<string, unknown>;
+  caller: AppActionCaller;
+  actor: string;
+}) {
+  const actions = app.definition.actions;
+  if (!actions || !Object.hasOwn(actions, name)) {
+    return { status: 404 as const, body: { error: "app action not found" } };
+  }
+
+  const action = actions[name]!;
+
+  if (action.kind === "script") {
+    const script = await getScriptById(action.scriptId);
+    if (!script) {
+      return {
+        status: 400 as const,
+        body: {
+          error: "invalid app action",
+          issues: [
+            {
+              path: `actions.${name}.scriptId`,
+              message: `script "${action.scriptId}" no longer exists`,
+            },
+          ],
+        },
+      };
+    }
+
+    // Script actions use the owner's bindings. Definition validation checks
+    // which scripts an agent can wire into an app.
+    const runAsAgentId = getSavedScriptOwnerAgentId(script);
+    if (!runAsAgentId) {
+      return {
+        status: 400 as const,
+        body: { error: "agentId is required: this script has no owning agent to run as" },
+      };
+    }
+
+    const output = await runSavedScriptAsAgent({
+      script,
+      input: { ...action.args, ...input, app: { id: app.id }, caller },
+      agentId: runAsAgentId,
+    });
+    const ok = output.exitCode === 0 && !output.error && !output.runtimeError;
+    const error = ok
+      ? undefined
+      : output.runtimeError
+        ? `${output.runtimeError.name}: ${output.runtimeError.message}`
+        : (output.error ?? `Script exited with code ${output.exitCode}`);
+    return {
+      status: 200 as const,
+      body: scrubObject({
+        ok,
+        result: output.result,
+        stdout: output.stdout,
+        ...(error === undefined ? {} : { error }),
+        durationMs: output.durationMs,
+      }),
+    };
+  }
+
+  if (action.kind === "sync") {
+    const startedAt = Date.now();
+    const sync = await runAppSync({
+      appId: app.id,
+      ...(action.model === undefined ? {} : { model: action.model }),
+      ...(action.source === undefined ? {} : { source: action.source }),
+      invokedBy: actor,
+    });
+    const durationMs = Date.now() - startedAt;
+    if (sync.issues && sync.issues.length > 0) {
+      return { status: 400 as const, body: { error: "invalid sync action", issues: sync.issues } };
+    }
+    // Deliberately the SCRIPT-action response shape, minus `taskId`:
+    // app-surface.tsx branches on `taskId` first, so omitting it gives the
+    // dashboard running -> ok/error + refetchAll() with zero UI changes.
+    const error = syncPassError(sync);
+    return {
+      status: 200 as const,
+      body: scrubObject({
+        ok: sync.ok,
+        result: { passes: sync.passes },
+        ...(error === undefined ? {} : { error }),
+        durationMs,
+      }),
+    };
+  }
+
+  const lead = action.agentId ? null : await getLeadAgent();
+  const taskPrompt = resolveTemplate("task.app.action", {
+    prompt: action.prompt,
+    app_id: app.id,
+    action_name: name,
+    input_json: JSON.stringify(input),
+    caller_json: JSON.stringify(caller),
+  });
+  const task = await createTaskWithSiblingAwareness(
+    taskPrompt.text,
+    {
+      source: "api",
+      agentId: action.agentId ?? lead?.id,
+      routingReason: action.agentId ? "human_pinned" : lead ? "skill" : undefined,
+      routingSource: action.agentId || lead ? "engine_default" : undefined,
+      // App-spawned tasks group under the app's asset namespace so a
+      // swarm-tasks source can pull them back via config.assetKey.
+      key: normalizeAssetKey(`shared/app:${app.id}/action:${name}/`),
+      ...(actor.startsWith("user:") ? { requestedByUserId: actor.slice("user:".length) } : {}),
+    },
+    { origin: "app" },
+  );
+  return {
+    status: 200 as const,
+    body: { ok: true as const, taskId: task.id, status: task.status },
+  };
+}

package/src/apps/catalog.generated.json

@@ -1243,7 +1243,7 @@
       }
     },
     "Table": {
-      "description": "Data table. Bind `data`/`loading`/`error` to a named query (`/queries/<name>/...`). `rowActions` chains receive `{ \"$row\": \"<col>\" }` (or `{ \"$row\": \"\" }` for the whole row) and `{ \"$rowIndex\": true }`. Destructive row actions always confirm via a dialog; override the copy with `confirm: { title, description, confirmLabel }`. `search` (case-insensitive substring across every listed column) and `filters` (per-column equality, `null`/`\"\"` disables one; an array means \"one of\", which is what a multiple `Chips` writes, and an empty array disables it) narrow the polled rows client-side — bind them to a `SearchInput` / `Select` via `/ui/<id>/value`, or pin a constant (e.g. `\"filters\": { \"pinned\": true }`). Columns take `pinned: \"left\"|\"right\"` to survive horizontal scroll; `pagination` pages large row sets (auto past 200 rows); `density: \"compact\"` tightens row height. Column kinds: `status` (lifecycle values like pending/in_progress/completed/failed get the dashboard status icon, anything else a `tones` pill), `user` / `agent` (avatar + name), `relative` (smart time with the exact time on hover), `duration` (ms → 1m 23s), `progress` (bar, `max` default 100), `copy` (value + copy button), `switch` (runs the column's `onChange` chain with `$row` set to the new value; read-only without it), `link` (http(s) URL, opens in a new tab). Columns also take `align`, `truncate: \"middle\"` (ids, paths), a header `icon` and `tooltip` (a row field shown on hover). `onRowClick` runs a chain with `$row` when a row is clicked — pair it with `app.navigate` + a Drawer and bind `selectedId` to the drawer param to highlight the open row. `rowId` names the id field (default `id`). Below 768px the table renders as a phone list (`mobile: \"list\"`, fields picked by `mobileFields: { title, subtitle?, meta?, status? }`); `mobile: \"scroll\"` keeps the grid. `emptyState: { icon?, title, body? }` replaces the empty message. Row actions take `icon` and `placement: \"menu\"` (collected into a More menu).",
+      "description": "Data table. Bind `data`/`loading`/`error` to a named query (`/queries/<name>/...`). `rowActions` chains receive `{ \"$row\": \"<col>\" }` (or `{ \"$row\": \"\" }` for the whole row) and `{ \"$rowIndex\": true }`. Destructive row actions always confirm via a dialog; override the copy with `confirm: { title, description, confirmLabel }`. `search` (case-insensitive substring across every listed column) and `filters` (per-column equality, `null`/`\"\"` disables one; an array means \"one of\", which is what a multiple `Chips` writes, and an empty array disables it) narrow the polled rows client-side — bind them to a `SearchInput` / `Select` via `/ui/<id>/value`, or pin a constant (e.g. `\"filters\": { \"pinned\": true }`). Columns take `pinned: \"left\"|\"right\"` to survive horizontal scroll; `pagination` pages large row sets (auto past 200 rows); `density: \"compact\"` tightens row height. Column kinds: `status` (lifecycle values like pending/in_progress/completed/failed get the dashboard status icon, anything else a `tones` pill), `user` / `agent` (avatar + name), `relative` (smart time with the exact time on hover), `duration` (ms → 1m 23s), `progress` (bar, `max` default 100), `copy` (value + copy button), `switch` (runs the column's `onChange` chain with `$row` set to the new value; read-only without it), `link` (http(s) URL, opens in a new tab), `json` (compact single-line `JSON.stringify` preview, truncated). Columns also take `align`, `truncate: \"middle\"` (ids, paths), a header `icon` and `tooltip` (a row field shown on hover). `onRowClick` runs a chain with `$row` when a row is clicked — pair it with `app.navigate` + a Drawer and bind `selectedId` to the drawer param to highlight the open row. `rowId` names the id field (default `id`). Below 768px the table renders as a phone list (`mobile: \"list\"`, fields picked by `mobileFields: { title, subtitle?, meta?, status? }`); `mobile: \"scroll\"` keeps the grid. `emptyState: { icon?, title, body? }` replaces the empty message. Row actions take `icon` and `placement: \"menu\"` (collected into a More menu).",
       "props": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -1287,7 +1287,8 @@
                     "progress",
                     "copy",
                     "switch",
-                    "link"
+                    "link",
+                    "json"
                   ]
                 },
                 "tones": {

package/src/apps/definition.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import { listScriptConnections } from "../be/script-connections";
 import { getScriptById } from "../be/scripts/db";
 import { getSavedScriptOwnerAgentId } from "../be/scripts/run-saved";
+import { APPS_JSON_COLUMN_MAX_BYTES_BOUNDS } from "../be/swarm-config-guard";
 import { checkQuickJSCompat, quickJSCompatWarnings } from "../scripts-runtime/quickjs-compat";
 import catalog from "./catalog.generated.json";
 import {
@@ -16,7 +17,13 @@ export const AppNameSchema = z.string().regex(/^[a-z][a-zA-Z0-9_]{0,39}$/, {
   message: "must start with a lowercase letter and contain only letters, numbers, or underscores",
 });
 
-export const ColumnKindSchema = z.enum(["string", "number", "boolean", "date", "enum"]);
+export const ColumnKindSchema = z.enum(["string", "number", "boolean", "date", "enum", "json"]);
+
+/**
+ * Column kinds allowed where values must stay scalar (user-config fields and
+ * element props) — `json` is model-column only.
+ */
+export const ScalarColumnKindSchema = ColumnKindSchema.exclude(["json"]);
 
 const ISO_8601_PREFIX = /^\d{4}-\d{2}-\d{2}(?:T.*)?$/;
 
@@ -24,6 +31,77 @@ export function isIso8601Date(value: string): boolean {
   return ISO_8601_PREFIX.test(value) && !Number.isNaN(Date.parse(value));
 }
 
+/** Default serialized-size cap for json column values AND defaults: 256 KB. */
+export const DEFAULT_JSON_COLUMN_MAX_BYTES = 256 * 1024;
+
+/**
+ * The serialized-size cap for json column values and defaults, read on every
+ * call — never at module load — so a stored `APPS_JSON_COLUMN_MAX_BYTES`
+ * override, injected over the process env on config reload, applies without
+ * a restart. Mirrors the retention knobs: a non-digit or out-of-range value
+ * falls back to the default, and the config API rejects writes outside the
+ * same `APPS_JSON_COLUMN_MAX_BYTES_BOUNDS`.
+ */
+export function jsonColumnMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.APPS_JSON_COLUMN_MAX_BYTES?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return DEFAULT_JSON_COLUMN_MAX_BYTES;
+  const value = Number(raw);
+  const { min, max } = APPS_JSON_COLUMN_MAX_BYTES_BOUNDS;
+  return Number.isSafeInteger(value) && value >= min && value <= max
+    ? value
+    : DEFAULT_JSON_COLUMN_MAX_BYTES;
+}
+
+/** The cap as a message label: whole KB when it divides evenly (`256KB`), else bytes. */
+export function jsonColumnSizeLabel(bytes: number = jsonColumnMaxBytes()): string {
+  return bytes % 1024 === 0 ? `${bytes / 1024}KB` : `${bytes} bytes`;
+}
+
+export type JsonColumnValueIssue = "unserializable" | "non-finite" | "oversized";
+
+/**
+ * Why a value cannot live in a json column — not JSON-serializable, carrying a
+ * non-finite number anywhere inside it, or over `jsonColumnMaxBytes()` once
+ * serialized — or `null` when it fits. The single implementation of the cap:
+ * it serializes exactly once, flagging non-finite numbers on that same walk
+ * (a lenient parser turns `1e400` into `Infinity`, which `JSON.stringify`
+ * would quietly store as `null`), and each caller maps the reason to its own
+ * message.
+ */
+export function jsonColumnValueIssue(value: unknown): JsonColumnValueIssue | null {
+  let nonFinite = false;
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(value, (_key, entry: unknown) => {
+      if (typeof entry === "number" && !Number.isFinite(entry)) nonFinite = true;
+      return entry;
+    });
+  } catch {
+    return "unserializable"; // circular reference / BigInt / throwing toJSON
+  }
+  if (serialized === undefined) return "unserializable";
+  if (nonFinite) return "non-finite";
+  return Buffer.byteLength(serialized, "utf8") > jsonColumnMaxBytes() ? "oversized" : null;
+}
+
+/**
+ * The one per-kind check for a NON-null column value, shared by the row store,
+ * schema migrations and the sync engine so a value the store accepts is a
+ * value a migration directive or a projection accepts too. Null policy
+ * (required / hidden / nulling a projection) stays with each caller.
+ */
+export function isValidColumnValue(
+  column: Pick<ColumnDef, "kind" | "enum">,
+  value: unknown,
+): boolean {
+  if (column.kind === "string") return typeof value === "string";
+  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
+  if (column.kind === "boolean") return typeof value === "boolean";
+  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
+  if (column.kind === "json") return jsonColumnValueIssue(value) === null;
+  return typeof value === "string" && Boolean(column.enum?.includes(value));
+}
+
 export const SourceTransformSchema = z.enum(["slug", "lower", "upper", "cents", "date-parse"]);
 
 /** Column kind each transform may target — the sync engine projects into it. */
@@ -49,11 +127,23 @@ const ColumnDefSchema = z
     required: z.boolean().optional(),
     enum: z.array(z.string()).optional(),
     index: z.boolean().optional(),
-    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    default: z
+      .union([
+        z.string(),
+        z.number(),
+        z.boolean(),
+        z.record(z.string(), z.unknown()),
+        z.array(z.unknown()),
+      ])
+      .optional(),
     hidden: z.boolean().optional(),
     source: ColumnSourceBindingSchema.optional(),
   })
   .superRefine((column, ctx) => {
+    if (column.kind === "json" && column.index) {
+      ctx.addIssue({ code: "custom", path: ["index"], message: "json columns cannot be indexed" });
+    }
+
     if (column.kind === "enum") {
       if (!column.enum || column.enum.length === 0) {
         ctx.addIssue({ code: "custom", path: ["enum"], message: "enum values are required" });
@@ -71,6 +161,24 @@ const ColumnDefSchema = z
     }
 
     if (column.default === undefined) return;
+    if (column.kind === "json") {
+      // Structural checks only; the size cap is write-time (`jsonColumnDefaultSizeIssues`).
+      const issue = jsonColumnValueIssue(column.default);
+      if (issue === "unserializable") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["default"],
+          message: "json column default must be JSON-serializable",
+        });
+      } else if (issue === "non-finite") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["default"],
+          message: "json column default contains a non-finite number",
+        });
+      }
+      return;
+    }
     const valid =
       (column.kind === "string" && typeof column.default === "string") ||
       (column.kind === "number" &&
@@ -94,7 +202,7 @@ const ColumnDefSchema = z
 
 const UserConfigFieldSchema = z
   .object({
-    kind: ColumnKindSchema,
+    kind: ScalarColumnKindSchema,
     default: z.union([z.string(), z.number(), z.boolean()]).optional(),
     enum: z.array(z.string()).optional(),
     label: z.string().optional(),
@@ -276,7 +384,7 @@ const AppPageSchema = z
 
 const ElementPropDefSchema = z
   .object({
-    kind: ColumnKindSchema,
+    kind: ScalarColumnKindSchema,
     required: z.boolean().optional(),
     enum: z.array(z.string()).min(1).optional(),
     default: z.union([z.string(), z.number(), z.boolean()]).optional(),
@@ -439,6 +547,14 @@ export const AppDefinitionSchema = z
           });
           continue;
         }
+        if (columnDefinition.kind === "json") {
+          ctx.addIssue({
+            code: "custom",
+            path: ["queries", queryName, "filter", column],
+            message: "json columns cannot be filtered",
+          });
+          continue;
+        }
         if (typeof value === "object") continue;
         const valid =
           (columnDefinition.kind === "string" && typeof value === "string") ||
@@ -469,6 +585,12 @@ export const AppDefinitionSchema = z
           path: ["queries", queryName, "sort", "column"],
           message: `unknown or hidden column "${sortColumn}"`,
         });
+      } else if (sortColumn && model.columns[sortColumn]?.kind === "json") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["queries", queryName, "sort", "column"],
+          message: "json columns cannot be sorted",
+        });
       }
     }
   });
@@ -836,6 +958,31 @@ function syncActionIssues(
   return [{ path: `actions.${name}`, message: "no model declares a source to sync" }];
 }
 
+/**
+ * The serialized-size cap on json column defaults, applied on definition
+ * WRITES only. It lives outside `AppDefinitionSchema` on purpose: the schema
+ * also decodes persisted definitions (`decodeAppDefinition`, the row store's
+ * model lookup), and a cap lowered after an app was saved must not turn that
+ * app into one that "needs repair" on every read. Writing the definition
+ * again re-applies the current cap. An oversized default would otherwise be
+ * accepted only to fail every row create that relies on it.
+ */
+function jsonColumnDefaultSizeIssues(definition: AppDefinition): AppValidationIssue[] {
+  const issues: AppValidationIssue[] = [];
+  for (const [modelName, model] of Object.entries(definition.models)) {
+    for (const [columnName, column] of Object.entries(model.columns)) {
+      if (column.kind !== "json" || column.default === undefined) continue;
+      if (jsonColumnValueIssue(column.default) === "oversized") {
+        issues.push({
+          path: `models.${modelName}.columns.${columnName}.default`,
+          message: `json column default exceeds the ${jsonColumnSizeLabel()} size limit`,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
 export async function parseAppDefinition(
   input: unknown,
   elementContext: AppDefinitionParseContext = {},
@@ -871,6 +1018,7 @@ export async function parseAppDefinition(
   if (!parsed.success) return { success: false, issues: appDefinitionIssues(parsed.error) };
 
   const issues = [
+    ...jsonColumnDefaultSizeIssues(parsed.data),
     ...Object.keys(parsed.data.pages).flatMap((pageName) =>
       validatePage(parsed.data, catalog, pageName),
     ),

package/src/apps/row-store.ts

@@ -4,7 +4,9 @@ import {
   AppDefinitionSchema,
   type AppValidationIssue,
   type ColumnDef,
-  isIso8601Date,
+  isValidColumnValue,
+  jsonColumnSizeLabel,
+  jsonColumnValueIssue,
   type ModelDef,
 } from "./definition";
 import { upgradeAppDefinition } from "./format-upgrades";
@@ -94,6 +96,7 @@ export function appIndexKey(model: string, column: string, value: unknown, rowId
 
 function isIndexed(column: ColumnDef): boolean {
   if (column.hidden === true) return false;
+  if (column.kind === "json") return false;
   if (column.kind === "enum") return true;
   return column.index === true && (column.kind === "string" || column.kind === "boolean");
 }
@@ -109,13 +112,9 @@ function indexKeys(model: string, definition: ModelDef, row: AppRow): string[] {
   return keys;
 }
 
-function validValue(column: ColumnDef, value: unknown): boolean {
+export function validValue(column: ColumnDef, value: unknown): boolean {
   if (value === null) return column.required !== true;
-  if (column.kind === "string") return typeof value === "string";
-  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
-  if (column.kind === "boolean") return typeof value === "boolean";
-  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
-  return typeof value === "string" && Boolean(column.enum?.includes(value));
+  return isValidColumnValue(column, value);
 }
 
 function joinKeyColumnNames(definition: ModelDef): Set<string> {
@@ -185,7 +184,20 @@ function prepareValues(
   for (const [name, value] of Object.entries(prepared)) {
     if (!Object.hasOwn(definition.columns, name)) continue;
     const column = definition.columns[name]!;
-    if (!validValue(column, value)) {
+    if (column.kind === "json" && value !== null) {
+      // Asked directly so the value is serialized once and the size cap gets its own message.
+      const issue = jsonColumnValueIssue(value);
+      if (issue === "unserializable") {
+        issues.push({ path: `values.${name}`, message: "must be a valid json value" });
+      } else if (issue === "non-finite") {
+        issues.push({ path: `values.${name}`, message: "json value contains a non-finite number" });
+      } else if (issue === "oversized") {
+        issues.push({
+          path: `values.${name}`,
+          message: `json value exceeds the ${jsonColumnSizeLabel()} size limit`,
+        });
+      }
+    } else if (!validValue(column, value)) {
       issues.push({ path: `values.${name}`, message: `must be a valid ${column.kind} value` });
     }
   }
@@ -526,18 +538,20 @@ export async function rebuildAppColumnIndexUnlocked(
   }
 }
 
+/** `matches` re-checks the row under the lock; a row that no longer matches is kept. */
 export function deleteAppRow(
   appId: string,
   model: string,
   _definition: ModelDef,
   rowId: string,
+  matches?: (row: AppRow) => boolean,
 ): Promise<boolean> {
   return withMutationLock(appId, model, async () => {
     const currentDefinition = await currentModelDefinition(appId, model);
     if (!currentDefinition) return false;
     const namespace = appsNamespace(appId);
     const row = await getAppRow(appId, model, rowId);
-    if (!row) return false;
+    if (!row || (matches && !matches(row))) return false;
     for (const key of indexKeys(model, currentDefinition, row)) await deleteKv(namespace, key);
     await deleteKv(namespace, rowKey(model, rowId));
     return true;

package/src/apps/schema-migrate.ts

@@ -8,6 +8,7 @@ import {
   type AppValidationIssue,
   type ColumnDef,
   isIso8601Date,
+  isValidColumnValue,
   type ModelDef,
   parseAppDefinition,
   type SourceDef,
@@ -23,7 +24,18 @@ import {
 } from "./row-store";
 import { invalidateChangedSyncStatus } from "./sync";
 
-const MigrationValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+/**
+ * Literal directive values (`set`, `map` targets, `else`): scalars, plus the
+ * objects and arrays a `json` column holds. The per-column kind check in
+ * `validateDirectiveValues` is what rejects a shape the target column cannot take.
+ */
+const MigrationValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+]);
 
 export const AppMigrationDirectiveSchema = z.union([
   z.object({ set: MigrationValueSchema }).strict(),
@@ -368,11 +380,7 @@ function isPurgeDirective(
 
 function columnAccepts(column: ColumnDef, value: unknown): boolean {
   if (value === null) return column.hidden === true || column.required !== true;
-  if (column.kind === "string") return typeof value === "string";
-  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
-  if (column.kind === "boolean") return typeof value === "boolean";
-  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
-  return typeof value === "string" && Boolean(column.enum?.includes(value));
+  return isValidColumnValue(column, value);
 }
 
 function coerceValue(

package/src/apps/script-types.ts

@@ -69,6 +69,7 @@ function commentSafe(value: string): string {
 }
 
 function tsTypeForColumn(column: Pick<ColumnDef, "kind" | "enum">): string {
+  if (column.kind === "json") return "unknown";
   if (column.kind !== "enum") return column.kind === "date" ? "string" : column.kind;
   return column.enum?.map((value) => JSON.stringify(value)).join(" | ") || "string";
 }
@@ -206,7 +207,7 @@ function renderApp(app: AppRecord, namespace: string): string {
 export namespace ${namespace} {
 ${renderedModels.map((model) => model.source).join("\n\n")}
 
-  /** Declared actions. Invocation is REST-only: POST /api/apps/<id>/actions/<name>. */
+  /** Scripts can write rows. Declared actions are callable through REST or MCP only. */
   export type ActionName = ${actionType};
 
   /** Script action arguments include server-stamped app and caller context. */

package/src/apps/sync.ts

@@ -9,7 +9,7 @@ import {
   type AppDefinition,
   type AppValidationIssue,
   type ColumnDef,
-  isIso8601Date,
+  isValidColumnValue,
   type ModelDef,
   type SourceDef,
   type SourceTransform,
@@ -484,19 +484,6 @@ function applyTransform(value: unknown, transform: SourceTransform | undefined):
   }
 }
 
-/**
- * Mirrors the row-store's per-kind value check. Projections are pre-validated
- * here so one bad field nulls one column instead of throwing mid-reconcile and
- * leaving the pass half-applied.
- */
-function validForKind(column: ColumnDef, value: unknown): boolean {
-  if (column.kind === "string") return typeof value === "string";
-  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
-  if (column.kind === "boolean") return typeof value === "boolean";
-  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
-  return typeof value === "string" && Boolean(column.enum?.includes(value));
-}
-
 function projectRecord(args: {
   record: SourceRecord;
   bindings: Array<[string, ColumnDef]>;
@@ -518,7 +505,10 @@ function projectRecord(args: {
       );
       value = null;
     }
-    if (value !== null && !validForKind(column, value)) {
+    // Projections are pre-validated with the row store's own kind check so one
+    // bad field nulls one column instead of throwing mid-reconcile and leaving
+    // the pass half-applied.
+    if (value !== null && !isValidColumnValue(column, value)) {
       warn(
         args.warnings,
         `column "${name}": field "${binding.field}" produced a value that is not a valid ${column.kind}`,
@@ -530,9 +520,20 @@ function projectRecord(args: {
   return values;
 }
 
-/** A missing column and an explicit null are the same absence of a value. */
-function sameValue(existing: unknown, projected: unknown): boolean {
-  return Object.is(existing ?? null, projected ?? null);
+/**
+ * A missing column and an explicit null are the same absence of a value. A
+ * json column compares structurally — the value decoded from storage is never
+ * the same object as a fresh projection — every other kind by identity.
+ */
+function sameValue(
+  column: ModelDef["columns"][string] | undefined,
+  existing: unknown,
+  projected: unknown,
+): boolean {
+  const before = existing ?? null;
+  const after = projected ?? null;
+  if (column?.kind === "json") return Bun.deepEquals(before, after);
+  return Object.is(before, after);
 }
 
 // ---------------------------------------------------------------------------
@@ -701,7 +702,7 @@ function reconcile(args: {
         return;
       }
       const differs = Object.entries(values).some(
-        ([name, value]) => !sameValue(existing[name], value),
+        ([name, value]) => !sameValue(modelDef.columns[name], existing[name], value),
       );
       const updated = await patchAppRowUnlocked(appId, model, modelDef, existing.id, values, {
         allowSourceManaged: true,