@desplega.ai/agent-swarm 1.129.0 → 1.131.0

package/src/be/migrations/129_asset_keys_apps_scripts.sql

@@ -0,0 +1,161 @@
+-- Extend canonical asset namespaces to apps and scripts.
+
+ALTER TABLE apps ADD COLUMN "key" TEXT NOT NULL DEFAULT 'shared/';
+ALTER TABLE scripts ADD COLUMN "key" TEXT NOT NULL DEFAULT 'shared/';
+
+UPDATE apps SET "key" = 'shared/' WHERE "key" IS NULL OR trim("key") = '';
+UPDATE scripts SET "key" = 'shared/' WHERE "key" IS NULL OR trim("key") = '';
+
+CREATE INDEX idx_apps_asset_key ON apps("key");
+CREATE INDEX idx_scripts_asset_key ON scripts("key");
+
+-- SQLite cannot widen a CHECK constraint in place. Rebuild the append-only
+-- history table with app and script added to the existing entity-type set.
+CREATE TABLE asset_key_history_new (
+  id           TEXT PRIMARY KEY,
+  entity_type  TEXT NOT NULL CHECK (entity_type IN ('task', 'workflow', 'schedule', 'page', 'app', 'script', 'file')),
+  entity_id    TEXT NOT NULL,
+  previous_key TEXT,
+  new_key      TEXT NOT NULL,
+  changed_by   TEXT REFERENCES users(id),
+  changed_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+INSERT INTO asset_key_history_new (
+  id,
+  entity_type,
+  entity_id,
+  previous_key,
+  new_key,
+  changed_by,
+  changed_at
+)
+SELECT
+  id,
+  entity_type,
+  entity_id,
+  previous_key,
+  new_key,
+  changed_by,
+  changed_at
+FROM asset_key_history;
+
+DROP TABLE asset_key_history;
+ALTER TABLE asset_key_history_new RENAME TO asset_key_history;
+
+CREATE INDEX idx_asset_key_history_entity
+  ON asset_key_history(entity_type, entity_id, changed_at DESC);
+
+-- Keep these bodies byte-for-byte aligned with migration 115's entity-table
+-- triggers. SQLite cannot express the remaining NFKC rule.
+CREATE TRIGGER validate_apps_asset_key_insert
+BEFORE INSERT ON apps
+WHEN NEW."key" IS NULL
+  OR length(NEW."key") = 0
+  OR NEW."key" != trim(NEW."key")
+  OR length(NEW."key") > 255
+  OR substr(NEW."key", -1, 1) != '/'
+  OR instr(NEW."key", char(0)) > 0
+  OR instr(NEW."key", char(92)) > 0
+  OR instr(NEW."key", '//') > 0
+  OR instr(NEW."key", '/../') > 0
+  OR instr(NEW."key", '/./') > 0
+  OR NEW."key" != lower(NEW."key")
+  OR NOT (
+    NEW."key" = 'shared/'
+    OR NEW."key" LIKE 'shared/%'
+    OR (
+      NEW."key" LIKE 'personal/%/%'
+      AND EXISTS (
+        SELECT 1 FROM users
+        WHERE id = substr(NEW."key", 10, instr(substr(NEW."key", 10), '/') - 1)
+      )
+    )
+  )
+BEGIN
+  SELECT RAISE(ABORT, 'invalid asset namespace key');
+END;
+
+CREATE TRIGGER validate_apps_asset_key_update
+BEFORE UPDATE OF "key" ON apps
+WHEN NEW."key" IS NULL
+  OR length(NEW."key") = 0
+  OR NEW."key" != trim(NEW."key")
+  OR length(NEW."key") > 255
+  OR substr(NEW."key", -1, 1) != '/'
+  OR instr(NEW."key", char(0)) > 0
+  OR instr(NEW."key", char(92)) > 0
+  OR instr(NEW."key", '//') > 0
+  OR instr(NEW."key", '/../') > 0
+  OR instr(NEW."key", '/./') > 0
+  OR NEW."key" != lower(NEW."key")
+  OR NOT (
+    NEW."key" = 'shared/'
+    OR NEW."key" LIKE 'shared/%'
+    OR (
+      NEW."key" LIKE 'personal/%/%'
+      AND EXISTS (
+        SELECT 1 FROM users
+        WHERE id = substr(NEW."key", 10, instr(substr(NEW."key", 10), '/') - 1)
+      )
+    )
+  )
+BEGIN
+  SELECT RAISE(ABORT, 'invalid asset namespace key');
+END;
+
+CREATE TRIGGER validate_scripts_asset_key_insert
+BEFORE INSERT ON scripts
+WHEN NEW."key" IS NULL
+  OR length(NEW."key") = 0
+  OR NEW."key" != trim(NEW."key")
+  OR length(NEW."key") > 255
+  OR substr(NEW."key", -1, 1) != '/'
+  OR instr(NEW."key", char(0)) > 0
+  OR instr(NEW."key", char(92)) > 0
+  OR instr(NEW."key", '//') > 0
+  OR instr(NEW."key", '/../') > 0
+  OR instr(NEW."key", '/./') > 0
+  OR NEW."key" != lower(NEW."key")
+  OR NOT (
+    NEW."key" = 'shared/'
+    OR NEW."key" LIKE 'shared/%'
+    OR (
+      NEW."key" LIKE 'personal/%/%'
+      AND EXISTS (
+        SELECT 1 FROM users
+        WHERE id = substr(NEW."key", 10, instr(substr(NEW."key", 10), '/') - 1)
+      )
+    )
+  )
+BEGIN
+  SELECT RAISE(ABORT, 'invalid asset namespace key');
+END;
+
+CREATE TRIGGER validate_scripts_asset_key_update
+BEFORE UPDATE OF "key" ON scripts
+WHEN NEW."key" IS NULL
+  OR length(NEW."key") = 0
+  OR NEW."key" != trim(NEW."key")
+  OR length(NEW."key") > 255
+  OR substr(NEW."key", -1, 1) != '/'
+  OR instr(NEW."key", char(0)) > 0
+  OR instr(NEW."key", char(92)) > 0
+  OR instr(NEW."key", '//') > 0
+  OR instr(NEW."key", '/../') > 0
+  OR instr(NEW."key", '/./') > 0
+  OR NEW."key" != lower(NEW."key")
+  OR NOT (
+    NEW."key" = 'shared/'
+    OR NEW."key" LIKE 'shared/%'
+    OR (
+      NEW."key" LIKE 'personal/%/%'
+      AND EXISTS (
+        SELECT 1 FROM users
+        WHERE id = substr(NEW."key", 10, instr(substr(NEW."key", 10), '/') - 1)
+      )
+    )
+  )
+BEGIN
+  SELECT RAISE(ABORT, 'invalid asset namespace key');
+END;

package/src/be/scripts/db.ts

@@ -1,3 +1,4 @@
+import { defaultAssetKey } from "../../assets/key";
 import type {
   ScriptApiAuthMode,
   ScriptApiRecord,
@@ -121,6 +122,7 @@ export function insertScript(args: ScriptWriteArgs): ScriptRecord {
       .prepare<
         ScriptRow,
         [
+          string,
           string,
           string,
           ScriptScope,
@@ -142,15 +144,16 @@ export function insertScript(args: ScriptWriteArgs): ScriptRecord {
         ]
       >(
         `INSERT INTO scripts (
-          id, name, scope, scopeId, source, description, intent, signatureJson,
+          id, "key", name, scope, scopeId, source, description, intent, signatureJson,
           argsJsonSchema, contentHash, isScratch, typeChecked, fsMode, createdByAgentId, createdAt, updatedAt,
           created_by, updated_by
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         RETURNING *`,
       )
       .get(
         id,
+        defaultAssetKey("script", id),
         args.name,
         args.scope,
         scopeId,

package/src/be/scripts/typecheck.ts

@@ -292,6 +292,7 @@ export interface SwarmSdk {
     migration?: Record<string, unknown>;
     forceElementBreak?: string[];
   }): Promise<unknown>;
+  app_sync(args: { appId: string; model?: string; source?: string }): Promise<unknown>;
   app_upsert(args: {
     name: string;
     description?: string;

package/src/be/seed-scripts/catalog/app-sync-run.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  appId: z.string().describe("App id to sync"),
+  model: z.string().optional().describe("Only sync this model (default: every model with sources)"),
+  source: z.string().optional().describe("Only sync this named source (default: every source)"),
+});
+
+/** Run an app's sync passes — the schedulable entry point for refreshing source-backed app rows. */
+export default async function appSyncRun(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args);
+  if (!parsed.success) throw new Error("invalid args: " + parsed.error.message);
+  const { appId, model, source } = parsed.data;
+  const result: any = await ctx.swarm.app_sync({
+    appId,
+    ...(model ? { model } : {}),
+    ...(source ? { source } : {}),
+  });
+  // The bridge serializes a FAILED sync as structured content in an HTTP 200:
+  // returning it would exit 0 and the scheduler would record a successful run.
+  // Throw so schedule error accounting sees the failure.
+  const payload = result && result.data !== undefined ? result.data : result;
+  const failed =
+    !result ||
+    result.success === false ||
+    (payload && (payload.success === false || payload.ok === false));
+  if (failed) {
+    const why = payload && typeof payload.error === "string" ? payload.error : "sync pass failed";
+    throw new Error("app sync failed: " + why);
+  }
+  return result;
+}

package/src/be/seed-scripts/catalog/github-issues-pull.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  repo: z.string().describe("Repository in 'owner/name' form, e.g. 'owner/name'"),
+  state: z
+    .enum(["open", "closed", "all"])
+    .optional()
+    .describe("Which issues to pull (default 'open')"),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .max(100)
+    .optional()
+    .describe("Page size, GitHub's per_page cap is 100 (default 100)"),
+  connection: z
+    .string()
+    .optional()
+    .describe(
+      "Connection slug the app source names; echoed back for provenance — credentials are resolved at the egress layer, not here",
+    ),
+});
+
+/** Pull a repository's GitHub issues as sync records: {records, complete} with pull requests filtered out. */
+export default async function githubIssuesPull(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args);
+  // Failures THROW: a returned {error} object exits 0 and the sync engine
+  // reports it as a generic invalid-payload error, burying the real cause.
+  if (!parsed.success) throw new Error("invalid args: " + parsed.error.message);
+  const { repo, state = "open", limit = 100, connection } = parsed.data;
+
+  const segments = repo.split("/");
+  if (
+    segments.length !== 2 ||
+    segments.some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new Error("repo must be in 'owner/name' form");
+  }
+  const path = segments.map((segment) => encodeURIComponent(segment)).join("/");
+
+  const payload: any = await ctx.stdlib.fetchJson(
+    "https://api.github.com/repos/" + path + "/issues?state=" + state + "&per_page=" + limit,
+    {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "agent-swarm-apps-sync",
+        // The placeholder is the point: the sandbox's egress layer swaps it for
+        // the real token on the way out, and only toward hosts allowlisted for
+        // the run-as identity. Never resolve the secret yourself — no
+        // resolved-config read, no token arg.
+        Authorization: "Bearer [REDACTED:GITHUB_TOKEN]",
+      },
+      signal: AbortSignal.timeout(10_000),
+    },
+  );
+
+  // fetchJson hands back the parsed body, not the status — a GitHub error is an
+  // object carrying `message`, a successful issues page is an array.
+  if (!Array.isArray(payload)) {
+    const why =
+      payload && typeof payload.message === "string" ? payload.message : "unexpected response";
+    throw new Error("GitHub issues " + repo + ": " + why);
+  }
+
+  // Completeness is computed on the RAW page, before the pull-request filter: a
+  // full raw page means "there may be more". Filtering first would let a page of
+  // mostly PRs look short and wrongly claim a complete window, and the engine
+  // would sweep still-live rows stale.
+  const complete = payload.length < limit;
+
+  // The issues endpoint interleaves pull requests; only PR entries carry
+  // `pull_request`.
+  const records = payload
+    .filter((issue: any) => issue && !issue.pull_request)
+    .map((issue: any) => ({
+      key: String(issue.number),
+      fields: {
+        number: issue.number,
+        id: issue.id,
+        title: issue.title,
+        state: issue.state,
+        // The FULL body goes back: the engine scrubs pulled values whole at
+        // its trusted boundary, and truncating here first could split a
+        // secret across the cut and defeat exact-value redaction. GitHub
+        // bounds issue bodies (~65k), so rows stay sane without a cap here.
+        body: typeof issue.body === "string" ? issue.body : "",
+        userLogin: issue.user ? issue.user.login : null,
+        labelsCsv: Array.isArray(issue.labels)
+          ? issue.labels
+              .map((label: any) => (typeof label === "string" ? label : label && label.name))
+              .filter((name: any) => typeof name === "string" && name.length > 0)
+              .join(",")
+          : "",
+        comments: issue.comments,
+        htmlUrl: issue.html_url,
+        createdAt: issue.created_at,
+        updatedAt: issue.updated_at,
+      },
+    }));
+
+  return { records, complete, ...(connection ? { connection } : {}) };
+}

package/src/be/seed-scripts/index.ts

@@ -22,6 +22,7 @@ import { getScript, upsertScriptByName } from "../scripts/db";
 import { extractArgsJsonSchema } from "../scripts/extract-schema";
 import { typecheckScript } from "../scripts/typecheck";
 import type { Seeder, SeederRunOptions, SeedItem } from "../seed/types";
+import appSyncRunSrc from "./catalog/app-sync-run.ts" with { type: "text" };
 import bootTriageSrc from "./catalog/boot-triage.inline.ts" with { type: "text" };
 // @ts-expect-error Bun text imports synthesize a default string for this helper.
 import catalogReportSrc from "./catalog/catalog-report.inline.ts" with { type: "text" };
@@ -32,6 +33,7 @@ import delegateSrc from "./catalog/delegate.ts" with { type: "text" };
 import fetchReadableSrc from "./catalog/fetch-readable.ts" with { type: "text" };
 import getChildOutputsSrc from "./catalog/get-child-outputs.ts" with { type: "text" };
 import ghPrSnapshotSrc from "./catalog/gh-pr-snapshot.ts" with { type: "text" };
+import githubIssuesPullSrc from "./catalog/github-issues-pull.ts" with { type: "text" };
 import groupCountSrc from "./catalog/group-count.ts" with { type: "text" };
 import jsonQuerySrc from "./catalog/json-query.ts" with { type: "text" };
 import linearIssueSrc from "./catalog/linear-issue.ts" with { type: "text" };
@@ -77,6 +79,22 @@ export const SEED_SCRIPTS: SeedScript[] = [
       "Triage a GitHub PR's status in a single call instead of running several gh pr view / gh pr checks / gh api invocations.",
     source: asText(ghPrSnapshotSrc),
   },
+  {
+    name: "github-issues-pull",
+    description:
+      "Pull a GitHub repository's issues (pull requests filtered out) as app-sync records: number, title, state, body, author, labels, comments and timestamps, with a completeness flag for the pull window.",
+    intent:
+      "Back a Swarm App model with GitHub issues — the worked example of a sync source script returning {records, complete} with placeholder-based auth.",
+    source: asText(githubIssuesPullSrc),
+  },
+  {
+    name: "app-sync-run",
+    description:
+      "Run a Swarm App's sync passes — refreshes every source-backed model, or just one model/source, and returns the per-pass created/updated/refreshed tallies.",
+    intent:
+      "Keep an app's synced rows fresh on a schedule or on demand; the script a targetType:'script' schedule points at to sync an app.",
+    source: asText(appSyncRunSrc),
+  },
   {
     name: "fetch-readable",
     description:

package/src/be/seed-skills/index.ts

@@ -130,6 +130,12 @@ import researchingContent from "../../../templates/skills/researching/content.md
 };
 import reviewingConfig from "../../../templates/skills/reviewing/config.json" with { type: "text" };
 import reviewingContent from "../../../templates/skills/reviewing/content.md" with { type: "text" };
+import scheduledTaskResilienceConfig from "../../../templates/skills/scheduled-task-resilience/config.json" with {
+  type: "text",
+};
+import scheduledTaskResilienceContent from "../../../templates/skills/scheduled-task-resilience/content.md" with {
+  type: "text",
+};
 import scriptBuilderConfig from "../../../templates/skills/script-builder/config.json" with {
   type: "text",
 };
@@ -280,6 +286,7 @@ const BUILT_IN_SKILL_SOURCES = [
   { config: questioningConfig, body: questioningContent },
   { config: researchingConfig, body: researchingContent },
   { config: reviewingConfig, body: reviewingContent },
+  { config: scheduledTaskResilienceConfig, body: scheduledTaskResilienceContent },
   { config: scriptBuilderConfig, body: scriptBuilderContent },
   { config: scriptWorkflowsConfig, body: scriptWorkflowsContent },
   { config: stepRunningConfig, body: stepRunningContent },

package/src/http/active-sessions.ts

@@ -11,8 +11,9 @@ import {
   resetOrphanedInProgressTasksForAgent,
   updateActiveSessionProviderSessionId,
 } from "../be/db";
+import { ActiveSessionSchema, AgentTaskSchema } from "../types";
 import { route } from "./route-def";
-import { json } from "./utils";
+import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -26,7 +27,10 @@ const listActiveSessions = route({
     agentId: z.string().optional(),
   }),
   responses: {
-    200: { description: "Active session list" },
+    200: {
+      description: "Active session list",
+      schema: z.object({ sessions: z.array(ActiveSessionSchema) }),
+    },
   },
 });
 
@@ -45,7 +49,7 @@ const createActiveSession = route({
     runnerSessionId: z.string().optional(),
   }),
   responses: {
-    201: { description: "Session created" },
+    201: { description: "Session created", schema: z.object({ session: ActiveSessionSchema }) },
     400: { description: "Validation error" },
   },
 });
@@ -58,7 +62,7 @@ const deleteSessionByTask = route({
   tags: ["Active Sessions"],
   params: z.object({ taskId: z.string() }),
   responses: {
-    200: { description: "Session deleted" },
+    200: { description: "Session deleted", schema: z.object({ deleted: z.boolean() }) },
   },
 });
 
@@ -70,7 +74,7 @@ const deleteSessionById = route({
   tags: ["Active Sessions"],
   params: z.object({ id: z.string() }),
   responses: {
-    200: { description: "Session deleted" },
+    200: { description: "Session deleted", schema: z.object({ deleted: z.boolean() }) },
   },
 });
 
@@ -82,7 +86,7 @@ const heartbeatSession = route({
   tags: ["Active Sessions"],
   params: z.object({ taskId: z.string() }),
   responses: {
-    200: { description: "Heartbeat updated" },
+    200: { description: "Heartbeat updated", schema: z.object({ updated: z.boolean() }) },
   },
 });
 
@@ -95,7 +99,7 @@ const updateProviderSession = route({
   params: z.object({ taskId: z.string() }),
   body: z.object({ providerSessionId: z.string().min(1) }),
   responses: {
-    200: { description: "Provider session ID updated" },
+    200: { description: "Provider session ID updated", schema: z.object({ updated: z.boolean() }) },
   },
 });
 
@@ -112,7 +116,7 @@ const cleanupSessions = route({
     })
     .optional(),
   responses: {
-    200: { description: "Cleanup result" },
+    200: { description: "Cleanup result", schema: z.object({ cleaned: z.number().int() }) },
   },
 });
 
@@ -127,7 +131,11 @@ const recoverOrphanedTasks = route({
     minAgeSeconds: z.number().int().positive().optional(),
   }),
   responses: {
-    200: { description: "Recovery result" },
+    200: {
+      description: "Recovery result",
+      schema: z.object({ recovered: z.number().int(), tasks: z.array(AgentTaskSchema) }),
+    },
+    403: { description: "Can only recover orphaned tasks for the calling agent" },
   },
 });
 
@@ -144,7 +152,7 @@ export async function handleActiveSessions(
     const parsed = await listActiveSessions.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const sessions = getActiveSessions(parsed.query.agentId || undefined);
-    json(res, { sessions });
+    listActiveSessions.respond(res, 200, { sessions });
     return true;
   }
 
@@ -159,7 +167,7 @@ export async function handleActiveSessions(
       taskDescription: parsed.body.taskDescription,
       runnerSessionId: parsed.body.runnerSessionId,
     });
-    json(res, { session }, 201);
+    createActiveSession.respond(res, 201, { session });
     return true;
   }
 
@@ -167,7 +175,7 @@ export async function handleActiveSessions(
     const parsed = await deleteSessionByTask.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const deleted = deleteActiveSession(parsed.params.taskId);
-    json(res, { deleted });
+    deleteSessionByTask.respond(res, 200, { deleted });
     return true;
   }
 
@@ -175,7 +183,7 @@ export async function handleActiveSessions(
     const parsed = await deleteSessionById.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const deleted = deleteActiveSessionById(parsed.params.id);
-    json(res, { deleted });
+    deleteSessionById.respond(res, 200, { deleted });
     return true;
   }
 
@@ -183,7 +191,7 @@ export async function handleActiveSessions(
     const parsed = await heartbeatSession.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const updated = heartbeatActiveSession(parsed.params.taskId);
-    json(res, { updated });
+    heartbeatSession.respond(res, 200, { updated });
     return true;
   }
 
@@ -194,7 +202,7 @@ export async function handleActiveSessions(
       parsed.params.taskId,
       parsed.body.providerSessionId,
     );
-    json(res, { updated });
+    updateProviderSession.respond(res, 200, { updated });
     return true;
   }
 
@@ -207,7 +215,7 @@ export async function handleActiveSessions(
     } else {
       cleaned = cleanupStaleSessions(parsed.body?.maxAgeMinutes ?? 30);
     }
-    json(res, { cleaned });
+    cleanupSessions.respond(res, 200, { cleaned });
     return true;
   }
 
@@ -215,14 +223,14 @@ export async function handleActiveSessions(
     const parsed = await recoverOrphanedTasks.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     if (!myAgentId || parsed.body.agentId !== myAgentId) {
-      json(res, { error: "Can only recover orphaned tasks for the calling agent" }, 403);
+      jsonError(res, "Can only recover orphaned tasks for the calling agent", 403);
       return true;
     }
     const tasks = resetOrphanedInProgressTasksForAgent(
       parsed.body.agentId,
       parsed.body.minAgeSeconds ?? 60,
     );
-    json(res, { recovered: tasks.length, tasks });
+    recoverOrphanedTasks.respond(res, 200, { recovered: tasks.length, tasks });
     return true;
   }