@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/http/apps.ts

@@ -6,9 +6,11 @@ import {
   type AppQueryDef,
   type AppValidationIssue,
   applyAppDefinitionPatch,
+  ColumnKindSchema,
   isIso8601Date,
   type ModelDef,
   parseAppDefinition,
+  SORTABLE_SYSTEM_DATE_COLUMNS,
   SYSTEM_COLUMN_KINDS,
 } from "../apps/definition";
 import {
@@ -41,6 +43,7 @@ import {
   listApps,
   updateApp,
 } from "../apps/store";
+import { collectAppSyncStatus, runAppSync } from "../apps/sync";
 import {
   getAppUserConfigValues,
   isReservedUserConfigKey,
@@ -56,6 +59,7 @@ import {
   rollbackApp,
   snapshotApp,
 } from "../apps/version";
+import { normalizeAssetKey } from "../assets/key";
 import { getAgentById, getAppVersion, getAppVersions, getLeadAgent } from "../be/db";
 import { getScriptById } from "../be/scripts/db";
 import { getSavedScriptOwnerAgentId, runSavedScriptAsAgent } from "../be/scripts/run-saved";
@@ -63,6 +67,7 @@ import { resolveTemplate } from "../prompts/resolver";
 import type { RbacPrincipal, RbacResource } from "../rbac";
 import { can } from "../rbac";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
+import { AgentTaskStatusSchema } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubObject } from "../utils/secret-scrubber";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
@@ -88,8 +93,142 @@ const rowParamsSchema = z.object({
   rowId: z.string().min(1),
 });
 const valuesSchema = z.record(z.string(), z.unknown());
+
+const AppValidationIssueSchema = z.object({ path: z.string(), message: z.string() });
+
+/**
+ * Any JSON value. Used for the genuinely free-form-but-ALWAYS-PRESENT payloads
+ * below. `z.unknown()` would be wrong for those: it accepts `undefined`, so the
+ * generator drops the property from the spec's `required` list even though
+ * every write path emits it (same reasoning as `argsJsonSchemaValueSchema` in
+ * src/http/scripts.ts).
+ */
+const JsonValueSchema = z.union([
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+
+/**
+ * Mirrors `AppRecord` (src/apps/store.ts). `definition` is free-form JSON: it's
+ * either a validated `AppDefinition & { schemaVersion }` or — when
+ * `definitionError` is set — the raw, possibly malformed, stored value (which
+ * `decodeApp` leaves as the un-parsed JSON *string* when the column itself is
+ * corrupt).
+ */
+const AppRecordSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  definition: JsonValueSchema,
+  definitionError: z.array(AppValidationIssueSchema).optional(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Mirrors what `listApps()` (src/apps/store.ts) actually builds. Its declared
+ * return type is `Omit<AppRecord, "definition">`, but the row mapper also never
+ * emits `definitionError` — so this is deliberately not derived from
+ * `AppRecordSchema`.
+ */
+const AppSummarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Mirrors `AppVersion` (src/be/db.ts). `snapshot` is a free-form JSON blob —
+ * normally an `AppSnapshot`, but `rollbackSnapshot()` proves historical rows can
+ * hold anything. Unlike `AppRecord.definition` it stays `z.unknown()` rather
+ * than `JsonValueSchema`: `AppVersion.snapshot` is declared `unknown` in db.ts,
+ * so narrowing it would need an unsafe cast at both call sites. The cost is
+ * that the generated spec lists `snapshot` as optional even though
+ * `rowToAppVersion` always emits it.
+ */
+const AppVersionSchema = z.object({
+  id: z.string(),
+  appId: z.string(),
+  version: z.number(),
+  snapshot: z.unknown(),
+  changedByAgentId: z.string().optional(),
+  createdAt: z.string(),
+});
+
+/** Mirrors `AppRow` (src/apps/row-store.ts): fixed system columns plus arbitrary model-defined columns. */
+const AppRowSchema = z.looseObject({
+  id: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  createdBy: z.string().optional(),
+  updatedBy: z.string().optional(),
+});
+
+/** Mirrors `SyncPassResult` (src/apps/sync.ts): one (model x source) sync pass outcome. */
+const SyncPassResultSchema = z.object({
+  model: z.string(),
+  source: z.string(),
+  connector: z.enum(["script", "swarm-tasks"]),
+  pulled: z.number(),
+  created: z.number(),
+  updated: z.number(),
+  refreshed: z.number(),
+  unchanged: z.number(),
+  markedStale: z.number(),
+  staleSweepSkipped: z.boolean().optional(),
+  warnings: z.array(z.string()),
+  durationMs: z.number(),
+  invokedBy: z.string().optional(),
+  error: z.string().optional(),
+  skipped: z.literal(true).optional(),
+  alreadyRunning: z.literal(true).optional(),
+});
+
+/** Mirrors `AppSyncStatus` (src/apps/sync.ts): per-(model:source) pass freshness. */
+const AppSyncStatusSchema = z.object({
+  lastStartedAt: z.string(),
+  lastFinishedAt: z.string(),
+  ok: z.boolean(),
+  created: z.number(),
+  updated: z.number(),
+  refreshed: z.number(),
+  markedStale: z.number(),
+  error: z.string().optional(),
+});
+
+/** Mirrors `UserConfigValues` (src/apps/user-config.ts). */
+const UserConfigValuesSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.number(), z.boolean(), z.null()]),
+);
+
+/**
+ * Wire mirror of one `userConfig` field declaration (`UserConfigFieldSchema`,
+ * src/apps/definition.ts). The definition module's own `UserConfigSchema` is
+ * deliberately NOT reused here: its `required: z.never().optional()` guard has
+ * no OpenAPI representation and makes the spec generator throw
+ * (`Unknown zod object type … {type: "never"}`), which breaks both
+ * `bun run docs:openapi` and `GET /openapi.json`. `required` is unobservable
+ * on the wire anyway — the key can only ever be absent.
+ */
+const AppUserConfigFieldSchema = z.object({
+  kind: ColumnKindSchema,
+  default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  enum: z.array(z.string()).optional(),
+  label: z.string().optional(),
+});
+
+/** Mirrors an app definition's `userConfig` declaration map. */
+const AppUserConfigSchema = z.record(AppNameSchema, AppUserConfigFieldSchema);
+
 const appWriteResponseSchema = z.object({
-  app: z.unknown(),
+  app: AppRecordSchema,
   migration: AppMigrationReportSchema,
 });
 const userConfigBodySchema = z.object({ values: z.record(z.string(), z.unknown()) }).strict();
@@ -104,7 +243,10 @@ const getUserConfigRoute = route({
   tags: ["Apps"],
   params: appParamsSchema,
   responses: {
-    200: { description: "Merged user configuration" },
+    200: {
+      description: "Merged user configuration",
+      schema: z.object({ values: UserConfigValuesSchema, schema: AppUserConfigSchema }),
+    },
     403: { description: "Permission denied" },
     404: { description: "App not found" },
     409: { description: "App definition needs repair" },
@@ -123,7 +265,10 @@ const putUserConfigRoute = route({
   params: appParamsSchema,
   body: userConfigBodySchema,
   responses: {
-    200: { description: "Stored user configuration" },
+    200: {
+      description: "Stored user configuration",
+      schema: z.object({ values: UserConfigValuesSchema, schema: AppUserConfigSchema }),
+    },
     400: { description: "Invalid user configuration" },
     403: { description: "Permission denied" },
     413: { description: "Request exceeds 64 KB or serialized values exceed 16 KB" },
@@ -139,7 +284,12 @@ const listAppsRoute = route({
   pattern: ["api", "apps"],
   summary: "List apps",
   tags: ["Apps"],
-  responses: { 200: { description: "App summaries without definitions" } },
+  responses: {
+    200: {
+      description: "App summaries without definitions",
+      schema: z.object({ apps: z.array(AppSummarySchema) }),
+    },
+  },
   // App summaries remain list-level until a future policy can filter them per app.
   rbac: { ungated: "app summaries are list-level; per-app filtering is future work" },
 });
@@ -157,7 +307,7 @@ const createAppRoute = route({
     forceElementBreak: ForceElementBreakSchema.optional(),
   }),
   responses: {
-    201: { description: "Created app" },
+    201: { description: "Created app", schema: z.object({ app: AppRecordSchema }) },
     400: { description: "Invalid app definition" },
     403: { description: "Permission denied" },
   },
@@ -172,7 +322,10 @@ const listAppVersionsRoute = route({
   tags: ["Apps"],
   params: appParamsSchema,
   responses: {
-    200: { description: "App definition versions" },
+    200: {
+      description: "App definition versions",
+      schema: z.object({ versions: z.array(AppVersionSchema) }),
+    },
     404: { description: "App not found" },
   },
   rbac: { permission: "app.manage" },
@@ -186,7 +339,7 @@ const getAppVersionRoute = route({
   tags: ["Apps"],
   params: appVersionParamsSchema,
   responses: {
-    200: { description: "App definition version" },
+    200: { description: "App definition version", schema: z.object({ version: AppVersionSchema }) },
     404: { description: "App or version not found" },
   },
   rbac: { permission: "app.manage" },
@@ -223,7 +376,14 @@ const getAppRoute = route({
   tags: ["Apps"],
   params: appParamsSchema,
   responses: {
-    200: { description: "App including its definition" },
+    200: {
+      description: "App including its definition",
+      schema: z.object({
+        app: AppRecordSchema,
+        // Present only once at least one declared source has completed a pass.
+        syncStatus: z.record(z.string(), AppSyncStatusSchema).optional(),
+      }),
+    },
     403: { description: "Permission denied" },
     404: { description: "App not found" },
   },
@@ -286,7 +446,7 @@ const deleteAppRoute = route({
   tags: ["Apps"],
   params: appParamsSchema,
   responses: {
-    200: { description: "App deleted" },
+    200: { description: "App deleted", schema: z.object({ ok: z.literal(true) }) },
     403: { description: "Permission denied" },
     404: { description: "App not found" },
   },
@@ -302,7 +462,7 @@ const createRowRoute = route({
   params: modelParamsSchema,
   body: z.object({ values: valuesSchema }),
   responses: {
-    201: { description: "Created row" },
+    201: { description: "Created row", schema: z.object({ row: AppRowSchema }) },
     400: { description: "Invalid row values" },
     403: { description: "Permission denied" },
     404: { description: "App or model not found" },
@@ -319,7 +479,7 @@ const bulkCreateRowsRoute = route({
   params: modelParamsSchema,
   body: z.object({ rows: z.array(z.object({ values: valuesSchema })).max(500) }),
   responses: {
-    200: { description: "Created rows" },
+    200: { description: "Created rows", schema: z.object({ rows: z.array(AppRowSchema) }) },
     400: { description: "Invalid row values" },
     403: { description: "Permission denied" },
     404: { description: "App or model not found" },
@@ -339,7 +499,10 @@ const listRowsRoute = route({
     limit: z.coerce.number().int().positive().max(1000).optional(),
   }),
   responses: {
-    200: { description: "Filtered app model rows" },
+    200: {
+      description: "Filtered app model rows",
+      schema: z.object({ rows: z.array(AppRowSchema), total: z.number() }),
+    },
     400: { description: "Invalid filter or sort" },
     403: { description: "Permission denied" },
     404: { description: "App or model not found" },
@@ -355,7 +518,7 @@ const getRowRoute = route({
   tags: ["Apps"],
   params: rowParamsSchema,
   responses: {
-    200: { description: "App model row" },
+    200: { description: "App model row", schema: z.object({ row: AppRowSchema }) },
     403: { description: "Permission denied" },
     404: { description: "App, model, or row not found" },
   },
@@ -371,7 +534,7 @@ const patchRowRoute = route({
   params: rowParamsSchema,
   body: z.object({ values: valuesSchema }),
   responses: {
-    200: { description: "Updated row" },
+    200: { description: "Updated row", schema: z.object({ row: AppRowSchema }) },
     400: { description: "Invalid row values" },
     403: { description: "Permission denied" },
     404: { description: "App, model, or row not found" },
@@ -387,7 +550,7 @@ const deleteRowRoute = route({
   tags: ["Apps"],
   params: rowParamsSchema,
   responses: {
-    200: { description: "Row deleted" },
+    200: { description: "Row deleted", schema: z.object({ ok: z.literal(true) }) },
     403: { description: "Permission denied" },
     404: { description: "App, model, or row not found" },
   },
@@ -402,7 +565,7 @@ const runNamedQueryRoute = route({
   tags: ["Apps"],
   params: z.object({ id: z.string().min(1), name: AppNameSchema }),
   responses: {
-    200: { description: "Named query rows" },
+    200: { description: "Named query rows", schema: z.object({ rows: z.array(AppRowSchema) }) },
     400: { description: "Missing or invalid named query parameters" },
     403: { description: "Permission denied" },
     409: { description: "App definition needs repair" },
@@ -411,6 +574,40 @@ const runNamedQueryRoute = route({
   rbac: { permission: "app.use" },
 });
 
+/**
+ * `runActionRoute`'s 200 shape branches on the action kind: script actions
+ * echo the script's exit result, task actions echo the created task's id and
+ * status.
+ */
+const runActionScriptResultSchema = z.object({
+  ok: z.boolean(),
+  result: z.unknown(),
+  stdout: z.string(),
+  error: z.string().optional(),
+  durationMs: z.number(),
+});
+const runActionTaskResultSchema = z.object({
+  ok: z.literal(true),
+  taskId: z.string(),
+  status: AgentTaskStatusSchema,
+});
+/**
+ * Sync actions deliberately reuse the SCRIPT-action shape minus `stdout`/
+ * `taskId` (see the handler comment): `result` carries the pass list instead
+ * of a script's return value.
+ */
+const runActionSyncResultSchema = z.object({
+  ok: z.boolean(),
+  result: z.object({ passes: z.array(SyncPassResultSchema) }),
+  error: z.string().optional(),
+  durationMs: z.number(),
+});
+const runActionResultSchema = z.union([
+  runActionScriptResultSchema,
+  runActionTaskResultSchema,
+  runActionSyncResultSchema,
+]);
+
 const runActionRoute = route({
   method: "post",
   path: "/api/apps/{id}/actions/{name}",
@@ -421,7 +618,7 @@ const runActionRoute = route({
   params: z.object({ id: z.string().min(1), name: AppNameSchema }),
   body: z.object({ input: z.record(z.string(), z.unknown()).optional() }),
   responses: {
-    200: { description: "Action invoked" },
+    200: { description: "Action invoked", schema: runActionResultSchema },
     400: { description: "Invalid action input or stale script reference" },
     403: { description: "Permission denied" },
     409: { description: "App definition needs repair" },
@@ -430,6 +627,29 @@ const runActionRoute = route({
   rbac: { permission: "app.use" },
 });
 
+const syncAppRoute = route({
+  method: "post",
+  path: "/api/apps/{id}/sync",
+  pattern: ["api", "apps", null, "sync"],
+  summary: "Sync an app's declared sources",
+  description:
+    "Runs every (model x source) pair the body selects. Each pass pulls outside the row mutation lock and reconciles inside it.",
+  tags: ["Apps"],
+  params: appParamsSchema,
+  body: z.object({ model: AppNameSchema.optional(), source: AppNameSchema.optional() }),
+  responses: {
+    200: {
+      description: "Sync passes",
+      schema: z.object({ ok: z.boolean(), passes: z.array(SyncPassResultSchema) }),
+    },
+    400: { description: "Unknown model or source, or no model declares a source" },
+    403: { description: "Permission denied" },
+    409: { description: "App definition needs repair" },
+    404: { description: "App not found" },
+  },
+  rbac: { permission: "app.use" },
+});
+
 /**
  * RBAC-gate an app operation and resolve the acting principal's stable actor id
  * (`user:<id>`, `agent:<id>`, or `operator`) for row provenance. Returns null
@@ -501,6 +721,17 @@ function definitionNeedsRepair(res: ServerResponse, app: ReturnType<typeof getAp
   return true;
 }
 
+/**
+ * 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("; ");
+}
+
 function snapshotFailure(res: ServerResponse): void {
   jsonError(res, "failed to snapshot app", 500);
 }
@@ -670,6 +901,12 @@ interface RowFilter {
   value: unknown;
 }
 
+/**
+ * Ad-hoc REST `filter.<col>` stays model-columns-only on purpose: system fields
+ * (including the sync envelope) are filterable through named queries, which
+ * validate kinds at definition-write time. Widening this loosely-typed
+ * query-string path would give two filter vocabularies with different rules.
+ */
 function filtersFromQuery(
   queryParams: URLSearchParams,
   model: ModelDef,
@@ -737,8 +974,7 @@ export function applyQuery(
         rowValue(a, sort.column),
         rowValue(b, sort.column),
         sort.dir,
-        sort.column === "createdAt" ||
-          sort.column === "updatedAt" ||
+        SORTABLE_SYSTEM_DATE_COLUMNS.has(sort.column) ||
           (Object.hasOwn(model.columns, sort.column) &&
             model.columns[sort.column]!.kind === "date"),
       );
@@ -772,27 +1008,24 @@ export async function handleApps(
     const definition = parseAppDefinition(parsed.body.definition, {
       resolveApp: getApp,
       writerAgentId: myAgentId ?? null,
+      writerIsUser: getRequestAuth(req)?.kind === "user",
     });
     if (!definition.success) {
       invalidDefinition(res, definition.issues);
       return true;
     }
-    json(
-      res,
-      {
-        app: createApp({
-          name: parsed.body.name,
-          description: parsed.body.description,
-          definition: definition.definition,
-        }),
-      },
-      201,
-    );
+    createAppRoute.respond(res, 201, {
+      app: createApp({
+        name: parsed.body.name,
+        description: parsed.body.description,
+        definition: definition.definition,
+      }),
+    });
     return true;
   }
 
   if (listAppsRoute.match(req.method, pathSegments)) {
-    json(res, { apps: listApps() });
+    listAppsRoute.respond(res, 200, { apps: listApps() });
     return true;
   }
 
@@ -804,7 +1037,9 @@ export async function handleApps(
       jsonError(res, "app not found", 404);
       return true;
     }
-    json(res, { versions: getAppVersions(parsed.params.id).map(decodeAppVersion) });
+    listAppVersionsRoute.respond(res, 200, {
+      versions: getAppVersions(parsed.params.id).map(decodeAppVersion),
+    });
     return true;
   }
 
@@ -821,7 +1056,7 @@ export async function handleApps(
       jsonError(res, "app version not found", 404);
       return true;
     }
-    json(res, { version: decodeAppVersion(version) });
+    getAppVersionRoute.respond(res, 200, { version: decodeAppVersion(version) });
     return true;
   }
 
@@ -837,8 +1072,10 @@ export async function handleApps(
         migration: parsed.body.migration,
         forceElementBreak: parsed.body.forceElementBreak,
         changedByAgentId: myAgentId,
+        writerAgentId: myAgentId ?? null,
+        writerIsUser: getRequestAuth(req)?.kind === "user",
       });
-      json(res, { app: rolledBack.app, migration: rolledBack.migration });
+      rollbackAppRoute.respond(res, 200, { app: rolledBack.app, migration: rolledBack.migration });
     } catch (error) {
       if (error instanceof AppRollbackAppNotFoundError) {
         jsonError(res, "app not found", 404);
@@ -874,7 +1111,7 @@ export async function handleApps(
         parsed.body.rows.map((row) => row.values),
         { actor },
       );
-      json(res, { rows });
+      bulkCreateRowsRoute.respond(res, 200, { rows });
     } catch (error) {
       if (!invalidRows(res, error)) throw error;
     }
@@ -897,7 +1134,7 @@ export async function handleApps(
         parsed.body.values,
         { actor },
       );
-      json(res, { row }, 201);
+      createRowRoute.respond(res, 201, { row });
     } catch (error) {
       if (!invalidRows(res, error)) throw error;
     }
@@ -925,8 +1162,7 @@ export async function handleApps(
         extra !== undefined ||
         !column ||
         (dir !== "asc" && dir !== "desc") ||
-        (column !== "createdAt" &&
-          column !== "updatedAt" &&
+        (!SORTABLE_SYSTEM_DATE_COLUMNS.has(column) &&
           (!Object.hasOwn(resolved.model.columns, column) ||
             resolved.model.columns[column]!.hidden === true))
       ) {
@@ -945,8 +1181,7 @@ export async function handleApps(
           rowValue(a, column),
           rowValue(b, column),
           dir,
-          column === "createdAt" ||
-            column === "updatedAt" ||
+          SORTABLE_SYSTEM_DATE_COLUMNS.has(column) ||
             (Object.hasOwn(resolved.model.columns, column) &&
               resolved.model.columns[column]!.kind === "date"),
         );
@@ -954,7 +1189,7 @@ export async function handleApps(
       });
     }
     const total = rows.length;
-    json(res, { rows: rows.slice(0, parsed.query.limit ?? 200), total });
+    listRowsRoute.respond(res, 200, { rows: rows.slice(0, parsed.query.limit ?? 200), total });
     return true;
   }
 
@@ -968,7 +1203,7 @@ export async function handleApps(
       jsonError(res, "row not found", 404);
       return true;
     }
-    json(res, { row });
+    getRowRoute.respond(res, 200, { row });
     return true;
   }
 
@@ -993,7 +1228,7 @@ export async function handleApps(
         jsonError(res, "row not found", 404);
         return true;
       }
-      json(res, { row });
+      patchRowRoute.respond(res, 200, { row });
     } catch (error) {
       if (!invalidRows(res, error)) throw error;
     }
@@ -1017,7 +1252,7 @@ export async function handleApps(
       jsonError(res, "row not found", 404);
       return true;
     }
-    json(res, { ok: true });
+    deleteRowRoute.respond(res, 200, { ok: true });
     return true;
   }
 
@@ -1039,7 +1274,7 @@ export async function handleApps(
     }
     const model = app.definition.models[query.model]!;
     try {
-      json(res, {
+      runNamedQueryRoute.respond(res, 200, {
         rows: applyQuery(
           listAppRows(app.id, query.model),
           query,
@@ -1121,8 +1356,9 @@ export async function handleApps(
         : output.runtimeError
           ? `${output.runtimeError.name}: ${output.runtimeError.message}`
           : (output.error ?? `Script exited with code ${output.exitCode}`);
-      json(
+      runActionRoute.respond(
         res,
+        200,
         scrubObject({
           ok,
           result: output.result,
@@ -1134,6 +1370,36 @@ export async function handleApps(
       return true;
     }
 
+    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) {
+        json(res, { error: "invalid sync action", issues: sync.issues }, 400);
+        return true;
+      }
+      // 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);
+      runActionRoute.respond(
+        res,
+        200,
+        scrubObject({
+          ok: sync.ok,
+          result: { passes: sync.passes },
+          ...(error === undefined ? {} : { error }),
+          durationMs,
+        }),
+      );
+      return true;
+    }
+
     const lead = action.agentId ? null : getLeadAgent();
     const taskPrompt = resolveTemplate("task.app.action", {
       prompt: action.prompt,
@@ -1144,9 +1410,40 @@ export async function handleApps(
     const task = createTaskWithSiblingAwareness(taskPrompt.text, {
       source: "api",
       agentId: action.agentId ?? lead?.id,
+      // 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:${parsed.params.name}/`),
       ...(actor.startsWith("user:") ? { requestedByUserId: actor.slice("user:".length) } : {}),
     });
-    json(res, { ok: true, taskId: task.id, status: task.status });
+    runActionRoute.respond(res, 200, { ok: true, taskId: task.id, status: task.status });
+    return true;
+  }
+
+  if (syncAppRoute.match(req.method, pathSegments)) {
+    if (enforceContentLengthCap(req, res, MAX_APP_ROW_BODY_BYTES) === BODY_TOO_LARGE) return true;
+    const parsed = await syncAppRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const actor = authorizeAppUse(req, res, myAgentId, parsed.params.id);
+    if (!actor) return true;
+
+    const app = getApp(parsed.params.id);
+    if (!app) {
+      jsonError(res, "app not found", 404);
+      return true;
+    }
+    if (definitionNeedsRepair(res, app)) return true;
+
+    const sync = await runAppSync({
+      appId: app.id,
+      ...(parsed.body.model === undefined ? {} : { model: parsed.body.model }),
+      ...(parsed.body.source === undefined ? {} : { source: parsed.body.source }),
+      invokedBy: actor,
+    });
+    if (sync.issues && sync.issues.length > 0) {
+      json(res, { error: "nothing to sync", issues: sync.issues }, 400);
+      return true;
+    }
+    syncAppRoute.respond(res, 200, scrubObject({ ok: sync.ok, passes: sync.passes }));
     return true;
   }
 
@@ -1185,6 +1482,7 @@ export async function handleApps(
           currentAppId: parsed.params.id,
           resolveApp: getApp,
           writerAgentId: myAgentId ?? null,
+          writerIsUser: getRequestAuth(req)?.kind === "user",
           existingDefinition: existing.definition,
         });
         if (!definition.success) {
@@ -1232,7 +1530,7 @@ export async function handleApps(
       jsonError(res, "app not found", 404);
       return true;
     }
-    json(res, { app, migration });
+    patchAppRoute.respond(res, 200, { app, migration });
     return true;
   }
 
@@ -1262,6 +1560,7 @@ export async function handleApps(
             currentAppId: parsed.params.id,
             resolveApp: getApp,
             writerAgentId: myAgentId ?? null,
+            writerIsUser: getRequestAuth(req)?.kind === "user",
             existingDefinition: existing.definition,
           });
           if (!parsedDefinition.success) {
@@ -1315,7 +1614,7 @@ export async function handleApps(
       jsonError(res, "app not found", 404);
       return true;
     }
-    json(res, { app, migration });
+    updateAppRoute.respond(res, 200, { app, migration });
     return true;
   }
 
@@ -1342,7 +1641,7 @@ export async function handleApps(
       jsonError(res, "app not found", 404);
       return true;
     }
-    json(res, { ok: true });
+    deleteAppRoute.respond(res, 200, { ok: true });
     return true;
   }
 
@@ -1355,7 +1654,13 @@ export async function handleApps(
       jsonError(res, "app not found", 404);
       return true;
     }
-    json(res, { app });
+    // Per-source freshness for the runtime payload — present only once a
+    // declared source has completed at least one pass.
+    const syncStatus = collectAppSyncStatus(app.id);
+    getAppRoute.respond(res, 200, {
+      app,
+      ...(Object.keys(syncStatus).length > 0 ? { syncStatus } : {}),
+    });
     return true;
   }
 
@@ -1372,7 +1677,7 @@ export async function handleApps(
     const schema = app.definition.userConfig ?? {};
     const owner = resolveHttpFavoriteOwner(req, myAgentId);
     const stored = owner ? getAppUserConfigValues(app.id, owner.scope) : {};
-    json(res, { values: mergeUserConfigValues(schema, stored), schema });
+    getUserConfigRoute.respond(res, 200, { values: mergeUserConfigValues(schema, stored), schema });
     return true;
   }
 
@@ -1418,7 +1723,10 @@ export async function handleApps(
       return true;
     }
     upsertAppUserConfigValues(app.id, owner.scope, parsed.body.values);
-    json(res, { values: mergeUserConfigValues(schema, parsed.body.values), schema });
+    putUserConfigRoute.respond(res, 200, {
+      values: mergeUserConfigValues(schema, parsed.body.values),
+      schema,
+    });
     return true;
   }