@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.129.0",
+  "version": "1.131.0",
   "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",
@@ -92,6 +92,7 @@
     "check:api-key-boundary": "bash scripts/check-api-key-boundary.sh",
     "check:vendored-openapi": "bun scripts/check-vendored-openapi.ts",
     "check:rbac-coverage": "bun scripts/check-rbac-coverage.ts",
+    "check:openapi-response-coverage": "bun scripts/check-openapi-response-coverage.ts",
     "check:script-types": "bash scripts/check-script-types-freshness.sh",
     "check:audit-columns": "bash scripts/check-audit-columns.sh",
     "lint:structure": "konsistent check",
@@ -151,6 +152,7 @@
     "@types/bun": "latest",
     "dependency-cruiser": "^18.0.0",
     "konsistent": "1.0.0-beta.1",
+    "openapi-typescript": "^7",
     "ts-morph": "^28.0.0",
     "turbo": "^2.10.0"
   },
@@ -167,14 +169,14 @@
     "@aws-sdk/client-bedrock": "3.1048.0",
     "@desplega.ai/business-use": "^0.4.2",
     "@desplega.ai/localtunnel": "^2.2.0",
-    "@earendil-works/pi-agent-core": "^0.83.0",
-    "@earendil-works/pi-ai": "^0.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-agent-core": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@openai/codex-sdk": "^0.146.0",
-    "@opencode-ai/sdk": "^1.18.13",
+    "@openai/codex-sdk": "^0.147.0",
+    "@opencode-ai/sdk": "^1.18.15",
     "@openfort/openfort-node": "^0.9.1",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",

package/src/apps/definition.ts

@@ -1,4 +1,5 @@
 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 catalog from "./catalog.generated.json";
@@ -8,6 +9,7 @@ import {
   elementDefinitionIssues,
   validatePage,
 } from "./page-validator";
+import { resolveSyncRunAs } from "./sync-run-as";
 
 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",
@@ -21,6 +23,25 @@ export function isIso8601Date(value: string): boolean {
   return ISO_8601_PREFIX.test(value) && !Number.isNaN(Date.parse(value));
 }
 
+export const SourceTransformSchema = z.enum(["slug", "lower", "upper", "cents", "date-parse"]);
+
+/** Column kind each transform may target — the sync engine projects into it. */
+const TRANSFORM_COLUMN_KIND: Record<z.infer<typeof SourceTransformSchema>, ColumnKind> = {
+  slug: "string",
+  lower: "string",
+  upper: "string",
+  cents: "number",
+  "date-parse": "date",
+};
+
+const ColumnSourceBindingSchema = z
+  .object({
+    of: AppNameSchema,
+    field: z.string().min(1),
+    transform: SourceTransformSchema.optional(),
+  })
+  .strict();
+
 const ColumnDefSchema = z
   .object({
     kind: ColumnKindSchema,
@@ -29,6 +50,7 @@ const ColumnDefSchema = z
     index: z.boolean().optional(),
     default: z.union([z.string(), z.number(), z.boolean()]).optional(),
     hidden: z.boolean().optional(),
+    source: ColumnSourceBindingSchema.optional(),
   })
   .superRefine((column, ctx) => {
     if (column.kind === "enum") {
@@ -119,9 +141,36 @@ const UserConfigFieldSchema = z
 
 export const UserConfigSchema = z.record(AppNameSchema, UserConfigFieldSchema);
 
+/**
+ * An inbound projection of an external system into a model. Script sources are
+ * the extensible default; `swarm-tasks` is the one native connector. The union
+ * is discriminated so a merge patch can never splice two connector shapes.
+ */
+const SourceDefSchema = z.discriminatedUnion("connector", [
+  // Strict: a typo'd key (e.g. `connnection`) silently stripped here would
+  // surface only as an uncredentialed pull at sync time.
+  z
+    .object({
+      connector: z.literal("script"),
+      scriptId: z.string().uuid(),
+      joinKey: AppNameSchema,
+      args: z.record(z.string(), z.unknown()).optional(),
+      connection: z.string().min(1).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      connector: z.literal("swarm-tasks"),
+      joinKey: AppNameSchema,
+      config: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    })
+    .strict(),
+]);
+
 const ModelDefSchema = z
   .object({
     columns: z.record(AppNameSchema, ColumnDefSchema),
+    sources: z.record(AppNameSchema, SourceDefSchema).optional(),
   })
   .superRefine((model, ctx) => {
     const count = Object.keys(model.columns).length;
@@ -137,6 +186,9 @@ const ModelDefSchema = z
         });
       }
     }
+    if (Object.keys(model.sources ?? {}).length > 4) {
+      ctx.addIssue({ code: "custom", path: ["sources"], message: "must define at most 4 sources" });
+    }
   });
 
 const AppQueryParamRefSchema = z
@@ -156,8 +208,18 @@ export const SYSTEM_COLUMN_KINDS: Record<string, "string" | "date" | "boolean">
   updatedAt: "date",
   createdBy: "string",
   updatedBy: "string",
+  // Sync provenance, present only on source-owned rows.
+  source: "string",
+  syncedAt: "date",
+  stale: "boolean",
 };
 
+/**
+ * System row fields a sort may target alongside declared model columns. All are
+ * ISO-8601 dates, so membership also selects date-aware comparison.
+ */
+export const SORTABLE_SYSTEM_DATE_COLUMNS = new Set(["createdAt", "updatedAt", "syncedAt"]);
+
 const AppQueryDefSchema = z.object({
   model: AppNameSchema,
   filter: z
@@ -185,6 +247,12 @@ const AppActionDefSchema = z.discriminatedUnion("kind", [
     // non-UUID (custom stable ids), so no format pin here.
     agentId: z.string().min(1).optional(),
   }),
+  z.object({
+    kind: z.literal("sync"),
+    // Omitting both fans out to every (model x source) pair the app declares.
+    model: AppNameSchema.optional(),
+    source: AppNameSchema.optional(),
+  }),
 ]);
 
 const AppPageParamSchema = z
@@ -392,8 +460,7 @@ export const AppDefinitionSchema = z
       const sortColumn = query.sort?.column;
       if (
         sortColumn &&
-        sortColumn !== "createdAt" &&
-        sortColumn !== "updatedAt" &&
+        !SORTABLE_SYSTEM_DATE_COLUMNS.has(sortColumn) &&
         (!Object.hasOwn(model.columns, sortColumn) || model.columns[sortColumn]!.hidden === true)
       ) {
         ctx.addIssue({
@@ -407,6 +474,9 @@ export const AppDefinitionSchema = z
 
 export type ColumnKind = z.infer<typeof ColumnKindSchema>;
 export type ColumnDef = z.infer<typeof ColumnDefSchema>;
+export type ColumnSourceBinding = z.infer<typeof ColumnSourceBindingSchema>;
+export type SourceTransform = z.infer<typeof SourceTransformSchema>;
+export type SourceDef = z.infer<typeof SourceDefSchema>;
 export type UserConfigField = z.infer<typeof UserConfigFieldSchema>;
 export type ModelDef = z.infer<typeof ModelDefSchema>;
 export type AppQueryDef = z.infer<typeof AppQueryDefSchema>;
@@ -467,25 +537,287 @@ export type AppDefinitionParseContext = ElementReferenceContext & {
    */
   writerAgentId?: string | null;
   /**
-   * The app's current stored definition, for grandfathering: script ids already
-   * wired into the app stay referenceable so an agent can keep editing an app
-   * that legitimately carries another owner's script action.
+   * True when the writer is an authenticated web USER. Users own no scripts,
+   * so every fresh agent-scoped reference is foreign for them — without this
+   * flag a user write (which carries no agent id) would skip the ownership
+   * gate exactly like the trusted operator.
+   */
+  writerIsUser?: boolean;
+  /**
+   * The app's current stored definition, for grandfathering: a script already
+   * wired into the app stays referenceable AT ITS EXISTING PATH so an agent can
+   * keep editing an app that legitimately carries another owner's script. The
+   * bare id is never grandfathered — a stored foreign action must not seed a
+   * new foreign source (or vice versa) with fresh args or a connection.
    */
   existingDefinition?: unknown;
 };
 
-/** Defensively collect script action ids from a possibly-broken definition. */
-function collectScriptActionIds(definition: unknown): Set<string> {
-  const ids = new Set<string>();
-  if (!isMergePatchObject(definition)) return ids;
+/**
+ * Defensively collect every script reference a possibly-broken definition
+ * carries — script actions and model sources alike — keyed by script id with
+ * the definition paths that name it. Tolerant by design: it walks raw JSON, so
+ * an app whose definition no longer parses still reports its references.
+ *
+ * Two callers: grandfathering on write (an agent editing an app that
+ * legitimately carries another owner's script must not be locked out) and the
+ * script-delete guard in the scripts API.
+ */
+export function collectScriptReferences(definition: unknown): Map<string, string[]> {
+  const references = new Map<string, string[]>();
+  const add = (scriptId: unknown, path: string): void => {
+    if (typeof scriptId !== "string" || scriptId.length === 0) return;
+    const paths = references.get(scriptId);
+    if (paths) paths.push(path);
+    else references.set(scriptId, [path]);
+  };
+  if (!isMergePatchObject(definition)) return references;
+  const actions = definition.actions;
+  if (isMergePatchObject(actions)) {
+    for (const [actionName, action] of Object.entries(actions)) {
+      if (isMergePatchObject(action)) add(action.scriptId, `actions.${actionName}`);
+    }
+  }
+  const models = definition.models;
+  if (isMergePatchObject(models)) {
+    for (const [modelName, model] of Object.entries(models)) {
+      if (!isMergePatchObject(model) || !isMergePatchObject(model.sources)) continue;
+      for (const [sourceName, source] of Object.entries(model.sources)) {
+        if (isMergePatchObject(source)) {
+          add(source.scriptId, `models.${modelName}.sources.${sourceName}`);
+        }
+      }
+    }
+  }
+  return references;
+}
+
+/**
+ * Is this agent-scoped script foreign to the writing principal? Operators
+ * (no writer identity at all) may wire anything; an agent may wire its own;
+ * a web user owns no scripts, so every agent-scoped script is foreign to it.
+ */
+function foreignScriptForWriter(
+  context: AppDefinitionParseContext,
+  script: NonNullable<ReturnType<typeof getScriptById>>,
+): boolean {
+  if (script.scope !== "agent") return false;
+  if (context.writerIsUser === true) return true;
+  if (!context.writerAgentId) return false;
+  return getSavedScriptOwnerAgentId(script) !== context.writerAgentId;
+}
+
+/**
+ * Canonical form of everything security-relevant about a script reference:
+ * which script runs, with what arguments, over which connection. Grandfathering
+ * compares THIS, not the bare id — an id-only match would let a non-owner keep
+ * a stored foreign reference while swapping in attacker-chosen args or a
+ * different connection, all executed under the owner's credentials.
+ */
+function scriptRefKey(scriptId: unknown, args: unknown, connection: unknown): string | null {
+  if (typeof scriptId !== "string" || scriptId.length === 0) return null;
+  return JSON.stringify({ scriptId, args: args ?? null, connection: connection ?? null });
+}
+
+/**
+ * Path-exact grandfathering index: `definition path -> scriptRefKey`. A
+ * reference is grandfathered only when the stored definition already carries
+ * the SAME script, args, and connection at the SAME path.
+ */
+function collectScriptReferencePathMap(definition: unknown): Map<string, string> {
+  const byPath = new Map<string, string>();
+  if (!isMergePatchObject(definition)) return byPath;
   const actions = definition.actions;
-  if (!isMergePatchObject(actions)) return ids;
-  for (const action of Object.values(actions)) {
-    if (isMergePatchObject(action) && typeof action.scriptId === "string") {
-      ids.add(action.scriptId);
+  if (isMergePatchObject(actions)) {
+    for (const [actionName, action] of Object.entries(actions)) {
+      if (!isMergePatchObject(action)) continue;
+      const key = scriptRefKey(action.scriptId, action.args, undefined);
+      if (key) byPath.set(`actions.${actionName}`, key);
     }
   }
-  return ids;
+  const models = definition.models;
+  if (isMergePatchObject(models)) {
+    for (const [modelName, model] of Object.entries(models)) {
+      if (!isMergePatchObject(model) || !isMergePatchObject(model.sources)) continue;
+      for (const [sourceName, source] of Object.entries(model.sources)) {
+        if (!isMergePatchObject(source)) continue;
+        const key = scriptRefKey(source.scriptId, source.args, source.connection);
+        if (key) byPath.set(`models.${modelName}.sources.${sourceName}`, key);
+      }
+    }
+  }
+  return byPath;
+}
+
+/** Semantic checks for a model's sources and its columns' source bindings. */
+function modelSourceIssues(
+  modelName: string,
+  model: ModelDef,
+  context: AppDefinitionParseContext,
+  grandfatheredScriptRefs: Map<string, string>,
+): AppValidationIssue[] {
+  const issues: AppValidationIssue[] = [];
+  const sources = model.sources ?? {};
+  const sourceNames = new Set(Object.keys(sources));
+
+  for (const [sourceName, source] of Object.entries(sources)) {
+    const path = `models.${modelName}.sources.${sourceName}`;
+    const joinColumn = Object.hasOwn(model.columns, source.joinKey)
+      ? model.columns[source.joinKey]!
+      : undefined;
+    if (!joinColumn || joinColumn.hidden === true) {
+      issues.push({
+        path: `${path}.joinKey`,
+        message: `unknown or hidden column "${source.joinKey}"`,
+      });
+    } else if (joinColumn.kind !== "string") {
+      issues.push({
+        path: `${path}.joinKey`,
+        message: `join key column "${source.joinKey}" must be a string column`,
+      });
+    } else {
+      if (joinColumn.source) {
+        issues.push({
+          path: `${path}.joinKey`,
+          message: `join key column "${source.joinKey}" must not be bound to a source`,
+        });
+      }
+      if (joinColumn.required === true) {
+        issues.push({
+          path: `${path}.joinKey`,
+          message: `join key column "${source.joinKey}" must not be required`,
+        });
+      }
+      if (joinColumn.default !== undefined) {
+        issues.push({
+          path: `${path}.joinKey`,
+          message: `join key column "${source.joinKey}" must not declare a default`,
+        });
+      }
+    }
+
+    if (source.connector !== "script") continue;
+    const script = getScriptById(source.scriptId);
+    if (!script) {
+      issues.push({ path: `${path}.scriptId`, message: `script "${source.scriptId}" not found` });
+      continue;
+    }
+    const runAs = resolveSyncRunAs(script);
+    const grandfatheredRef =
+      grandfatheredScriptRefs.get(path) ===
+      scriptRefKey(source.scriptId, source.args, source.connection);
+    // A pull runs the script with its OWNER's bindings, so a writer may only
+    // wire scripts it owns (or global ones) — the script-action rule.
+    if (foreignScriptForWriter(context, script) && !grandfatheredRef) {
+      issues.push({
+        path: `${path}.scriptId`,
+        message: `script "${source.scriptId}" is agent-scoped to another agent — reference a script you own or a global script`,
+      });
+    } else if (
+      // Owner-less (and foreign-owned) GLOBAL scripts sync with runAs's
+      // credential bindings — for the catalog that is the LEAD. Introducing or
+      // altering such a source is that identity's (or the operator's)
+      // privilege; every other writer keeps only pinned stored references.
+      script.scope !== "agent" &&
+      (context.writerIsUser === true || typeof context.writerAgentId === "string") &&
+      context.writerAgentId !== runAs &&
+      !grandfatheredRef
+    ) {
+      issues.push({
+        path: `${path}.scriptId`,
+        message: `script "${source.scriptId}" syncs with agent "${runAs}"'s credentials — only that agent or the operator may wire or alter this source`,
+      });
+    }
+    if (source.connection !== undefined) {
+      const reachable = listScriptConnections({ agentId: runAs });
+      if (!reachable.some((connection) => connection.slug === source.connection)) {
+        issues.push({
+          path: `${path}.connection`,
+          message: `connection "${source.connection}" not found or disabled for the sync run-as identity`,
+        });
+      }
+    }
+  }
+
+  for (const [columnName, column] of Object.entries(model.columns)) {
+    const path = `models.${modelName}.columns.${columnName}`;
+    if (!column.source) {
+      // Sync creates rows from projected fields alone, so every required column
+      // it does NOT own has to be satisfiable without a writer.
+      if (
+        sourceNames.size > 0 &&
+        column.required === true &&
+        column.hidden !== true &&
+        column.default === undefined
+      ) {
+        issues.push({
+          path,
+          message:
+            "required column on a model with sources must declare a default — sync-created rows cannot supply it",
+        });
+      }
+      continue;
+    }
+    if (!sourceNames.has(column.source.of)) {
+      issues.push({ path: `${path}.source.of`, message: `unknown source "${column.source.of}"` });
+    }
+    const transform = column.source.transform;
+    if (transform && TRANSFORM_COLUMN_KIND[transform] !== column.kind) {
+      issues.push({
+        path: `${path}.source.transform`,
+        message: `transform "${transform}" requires a ${TRANSFORM_COLUMN_KIND[transform]} column`,
+      });
+    }
+    if (column.required === true) {
+      issues.push({
+        path: `${path}.required`,
+        message: "source-bound column must not be required",
+      });
+    }
+    if (column.default !== undefined) {
+      issues.push({
+        path: `${path}.default`,
+        message: "source-bound column must not declare a default",
+      });
+    }
+  }
+
+  return issues;
+}
+
+/** A `sync` action must resolve to at least one (model x source) pair. */
+function syncActionIssues(
+  name: string,
+  action: { model?: string; source?: string },
+  models: Record<string, ModelDef>,
+): AppValidationIssue[] {
+  if (action.model !== undefined && !Object.hasOwn(models, action.model)) {
+    return [{ path: `actions.${name}.model`, message: `unknown model "${action.model}"` }];
+  }
+  const candidates = action.model !== undefined ? [action.model] : Object.keys(models);
+  const pairs = candidates.flatMap((modelName) =>
+    Object.keys(models[modelName]?.sources ?? {}).filter(
+      (sourceName) => action.source === undefined || sourceName === action.source,
+    ),
+  );
+  if (pairs.length > 0) return [];
+  if (action.source !== undefined) {
+    return [
+      {
+        path: `actions.${name}.source`,
+        message:
+          action.model !== undefined
+            ? `unknown source "${action.source}" on model "${action.model}"`
+            : `unknown source "${action.source}" — no model declares it`,
+      },
+    ];
+  }
+  if (action.model !== undefined) {
+    return [
+      { path: `actions.${name}.model`, message: `model "${action.model}" declares no sources` },
+    ];
+  }
+  return [{ path: `actions.${name}`, message: "no model declares a source to sync" }];
 }
 
 export function parseAppDefinition(
@@ -527,8 +859,15 @@ export function parseAppDefinition(
     ...crossPageDefinitionIssues(parsed.data, catalog),
     ...elementDefinitionIssues(parsed.data, catalog, elementContext),
   ];
-  const grandfatheredScriptIds = collectScriptActionIds(elementContext.existingDefinition);
+  const grandfatheredScriptRefs = collectScriptReferencePathMap(elementContext.existingDefinition);
+  for (const [modelName, model] of Object.entries(parsed.data.models)) {
+    issues.push(...modelSourceIssues(modelName, model, elementContext, grandfatheredScriptRefs));
+  }
   for (const [name, action] of Object.entries(parsed.data.actions ?? {})) {
+    if (action.kind === "sync") {
+      issues.push(...syncActionIssues(name, action, parsed.data.models));
+      continue;
+    }
     if (action.kind !== "script") continue;
     const script = getScriptById(action.scriptId);
     if (!script) {
@@ -538,15 +877,15 @@ export function parseAppDefinition(
       });
       continue;
     }
-    // Invoke-time runs the script with the OWNER's bindings, so an agent writer
-    // may only wire scripts it owns (or global ones). Script ids already present
-    // in the stored definition are grandfathered so foreign-authored apps stay
-    // editable.
+    // Invoke-time runs the script with the OWNER's bindings, so a writer may
+    // only wire scripts it owns (or global ones). A reference the stored
+    // definition already carries at this exact path is grandfathered so
+    // foreign-authored apps stay editable — the bare id is not, so an existing
+    // foreign reference cannot seed a new one elsewhere.
     if (
-      elementContext.writerAgentId &&
-      script.scope === "agent" &&
-      getSavedScriptOwnerAgentId(script) !== elementContext.writerAgentId &&
-      !grandfatheredScriptIds.has(action.scriptId)
+      foreignScriptForWriter(elementContext, script) &&
+      grandfatheredScriptRefs.get(`actions.${name}`) !==
+        scriptRefKey(action.scriptId, action.args, undefined)
     ) {
       issues.push({
         path: `actions.${name}.scriptId`,
@@ -649,6 +988,7 @@ function applyMergePatch(target: unknown, patch: unknown, path: string[]): unkno
     (path.length === 1 && path[0] === "elements") ||
     (path.length === 1 && path[0] === "userConfig") ||
     (path.length === 3 && path[0] === "models" && path[2] === "columns") ||
+    (path.length === 3 && path[0] === "models" && path[2] === "sources") ||
     (path.length === 3 && path[0] === "elements" && path[2] === "elements") ||
     (path.length === 3 && path[0] === "pages" && (path[2] === "elements" || path[2] === "params"));
 
@@ -677,9 +1017,11 @@ function applyMergePatch(target: unknown, patch: unknown, path: string[]): unkno
 
 /**
  * Apply RFC 7396 JSON Merge Patch semantics to an app definition without
- * mutating either input. Individual action, page-element, and model-column
- * entries are intentionally atomic. A reusable-element patch containing only
- * `elements` merges node-by-node; any other key makes it a full replacement.
+ * mutating either input. Individual action, page-element, model-column, and
+ * model-source entries are intentionally atomic — whole-replaced, never
+ * key-merged — so a patch can never splice two connector shapes together.
+ * A reusable-element patch containing only `elements` merges node-by-node;
+ * any other key makes it a full replacement.
  */
 export function applyAppDefinitionPatch(
   stored: AppDefinition,