@desplega.ai/agent-swarm 2.8.1 → 2.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/dist/{acp-adapter-pdy3qsvg.js → acp-adapter-fqzkxyra.js} +3 -3
  2. package/dist/{actions-pwjpn0j6.js → actions-kxek041g.js} +17 -17
  3. package/dist/{amp-adapter-cq9jgj6x.js → amp-adapter-ce7jjke4.js} +1 -1
  4. package/dist/{app-cnfffgwg.js → app-v6zz8yh0.js} +3 -3
  5. package/dist/{assistant-kpn317y1.js → assistant-m0sw9xx2.js} +18 -18
  6. package/dist/{boot-args-schema-pbbnhmc3.js → boot-args-schema-66bk37wv.js} +1 -1
  7. package/dist/{boot-reembed-9m0ysxma.js → boot-reembed-edjpwsc1.js} +1 -1
  8. package/dist/{boot-reembed-majbn53m.js → boot-reembed-y27n09tz.js} +1 -1
  9. package/dist/{boot-scrub-sweep-app8g8ym.js → boot-scrub-sweep-1xc35965.js} +3 -3
  10. package/dist/{boot-seeds-pbtmvcjm.js → boot-seeds-7hjj91qj.js} +4 -4
  11. package/dist/{boxd-qbkxy6ap.js → boxd-ent8ch04.js} +1 -1
  12. package/dist/{claude-adapter-wn1g3qp5.js → claude-adapter-stw7jdcf.js} +3 -3
  13. package/dist/{claude-managed-setup-pd47nzch.js → claude-managed-setup-y6z2perp.js} +1 -1
  14. package/dist/{claude-sdk-session-3a2a6589.js → claude-sdk-session-vvya8wqk.js} +3 -3
  15. package/dist/{cli-wk18cm92.js → cli-0cq8y6m7.js} +1 -1
  16. package/dist/{cli-p1w18yhx.js → cli-1pz0330a.js} +1 -1
  17. package/dist/{cli-d3p5vwbk.js → cli-1qkz151v.js} +3 -3
  18. package/dist/{cli-89cqnasv.js → cli-26ctbcdp.js} +18 -6
  19. package/dist/{cli-syybb0p1.js → cli-2kvhc7x8.js} +7 -7
  20. package/dist/{cli-93k32c37.js → cli-3e875j5p.js} +128 -41
  21. package/dist/{cli-k0615eh8.js → cli-3sy2xags.js} +10 -10
  22. package/dist/{cli-dy32zecz.js → cli-3vmb0n58.js} +1 -1
  23. package/dist/{cli-4r05hnqa.js → cli-4vzgeta4.js} +13 -13
  24. package/dist/{cli-b5rs97a6.js → cli-5y340nzn.js} +4 -4
  25. package/dist/{cli-7p1kvkck.js → cli-6rc5frdm.js} +1 -1
  26. package/dist/{cli-jcpr5smb.js → cli-837vfs2x.js} +2 -2
  27. package/dist/{cli-b085njxz.js → cli-959kp5h2.js} +12 -11
  28. package/dist/{cli-k93bq1wq.js → cli-97ae65rz.js} +4 -4
  29. package/dist/{cli-m4dqmnbp.js → cli-9mb2q6pb.js} +1 -1
  30. package/dist/{cli-bb431xey.js → cli-a0z912j7.js} +121 -33
  31. package/dist/{cli-k26bkr9t.js → cli-b98a65ed.js} +3 -3
  32. package/dist/{cli-k0wwfqbg.js → cli-dns0y538.js} +4 -0
  33. package/dist/{cli-tk7cjj8h.js → cli-dzpc6en0.js} +1 -1
  34. package/dist/{cli-6mma83xa.js → cli-e1p3n5gq.js} +4 -4
  35. package/dist/{cli-re4raaj0.js → cli-f4e8r23x.js} +1 -1
  36. package/dist/{cli-qmqk2yc2.js → cli-f4r3g076.js} +1 -1
  37. package/dist/{cli-pcad4cb1.js → cli-f6bahpn5.js} +1 -1
  38. package/dist/{cli-b8e9nb04.js → cli-fpjmegdb.js} +1 -1
  39. package/dist/{cli-0ntbxyaa.js → cli-fwy8kfd6.js} +271 -37
  40. package/dist/{cli-tacge1w0.js → cli-g5mtmf6t.js} +6 -6
  41. package/dist/{cli-sn7rtnj4.js → cli-gyt3zydq.js} +3 -3
  42. package/dist/{cli-vbh10fqa.js → cli-j24zbska.js} +3 -3
  43. package/dist/{cli-vqptjbr7.js → cli-jdknh18m.js} +10 -10
  44. package/dist/{cli-7b8sbmag.js → cli-kjtwrhea.js} +1 -1
  45. package/dist/{cli-9vhebtjz.js → cli-mxn1qvbn.js} +3 -2
  46. package/dist/{cli-zcsw143p.js → cli-n6vtrcht.js} +1 -1
  47. package/dist/{cli-2zp0et3v.js → cli-pchypa1s.js} +55 -19
  48. package/dist/{cli-gax7fk3t.js → cli-pfs8adn4.js} +1 -1
  49. package/dist/{cli-1xh9a7hn.js → cli-q24n86d2.js} +2 -2
  50. package/dist/{cli-7w69ne2f.js → cli-rcecc3yq.js} +167 -43
  51. package/dist/{cli-xae4g51r.js → cli-rh15cakt.js} +1 -1
  52. package/dist/{cli-yn2bbre9.js → cli-rmzsadkf.js} +1 -1
  53. package/dist/{cli-a3b239vq.js → cli-t2tma8gb.js} +1 -1
  54. package/dist/{cli-9wngrawf.js → cli-tekytdq9.js} +2 -2
  55. package/dist/{cli-tqegb8eq.js → cli-vdektqgf.js} +1 -1
  56. package/dist/{cli-cyhbbd1z.js → cli-w401b9tq.js} +1 -1
  57. package/dist/{cli-jywyhqws.js → cli-xf3qw745.js} +3 -3
  58. package/dist/{cli-hxpyc9sn.js → cli-z1w943va.js} +2 -2
  59. package/dist/{cli-yncmerje.js → cli-zh9rsbqf.js} +2 -2
  60. package/dist/cli.js +16 -16
  61. package/dist/{codex-adapter-nha71q3n.js → codex-adapter-zerf5qsp.js} +1 -1
  62. package/dist/{codex-hook-h3vk6xzr.js → codex-hook-30gyhzxe.js} +1 -1
  63. package/dist/{codex-session-runner-ak9x1k1h.js → codex-session-runner-89s304py.js} +1 -1
  64. package/dist/{commands-f587qpq8.js → commands-jeh1b51j.js} +3 -3
  65. package/dist/{controller-hxx8wwy1.js → controller-mctfbrse.js} +3 -3
  66. package/dist/{controllers-connect-k5sg9m9h.js → controllers-connect-nxa1ddwn.js} +18 -18
  67. package/dist/{cursor-adapter-n5nc3mfe.js → cursor-adapter-qj8vehv6.js} +1 -1
  68. package/dist/{db-nzf8zb5z.js → db-2dvay0es.js} +3 -3
  69. package/dist/{db-amm8w15a.js → db-b36qn6k3.js} +2 -2
  70. package/dist/{dispatcher-89zrts8f.js → dispatcher-gndbta01.js} +16 -16
  71. package/dist/{dsh-adapter-nrhbrjz8.js → dsh-adapter-f75sz821.js} +1 -1
  72. package/dist/{e2b-jkwfhbcv.js → e2b-3gpc2n3w.js} +1 -1
  73. package/dist/{e2b-s16txnpx.js → e2b-jbm7mj93.js} +1 -1
  74. package/dist/{embedding-space-ezwenjmj.js → embedding-space-4p05vb2x.js} +6 -6
  75. package/dist/{embeddings-np74ht6g.js → embeddings-m6768mgh.js} +1 -1
  76. package/dist/{external-channel-z46yx9d7.js → external-channel-gjv3jne3.js} +2 -2
  77. package/dist/{fx-adapter-3q12snn6.js → fx-adapter-rpsgb1tw.js} +4 -4
  78. package/dist/{grok-adapter-ahb1w033.js → grok-adapter-n2m3zjg1.js} +4 -4
  79. package/dist/handlers-nv8edn19.js +32 -0
  80. package/dist/{heartbeat-dt9qw9c8.js → heartbeat-a1tv60gt.js} +19 -19
  81. package/dist/{hook-8k6fbz9b.js → hook-8h5dzcgq.js} +2 -2
  82. package/dist/{hook-jgcgygex.js → hook-cyaps9ba.js} +4 -4
  83. package/dist/{http-haw4r8ne.js → http-t15mhbd9.js} +1731 -77
  84. package/dist/{index-s4ewdma4.js → index-ksmyd6kc.js} +16 -16
  85. package/dist/{index-tez78qj3.js → index-qav6455f.js} +13 -11
  86. package/dist/index-rjnrje98.js +32 -0
  87. package/dist/index-tv3413wy.js +33 -0
  88. package/dist/{index-5gk12my8.js → index-w1zqf680.js} +1 -1
  89. package/dist/{keepalive-xn6s7rmg.js → keepalive-91s7hzrb.js} +3 -3
  90. package/dist/{lead-6ygbfhbh.js → lead-3hmddvrm.js} +30 -30
  91. package/dist/{maintenance-vdts800b.js → maintenance-7pjmy5xy.js} +1 -1
  92. package/dist/{oauth-refresh-sweep-094c8wfk.js → oauth-refresh-sweep-rzqfm94j.js} +2 -2
  93. package/dist/{onboard-v99eh56m.js → onboard-74st7pag.js} +3 -3
  94. package/dist/{opencode-adapter-dsagkhtw.js → opencode-adapter-arn7gm8q.js} +2 -2
  95. package/dist/{otel-impl-q7yr9yp0.js → otel-impl-rnzey8cb.js} +1 -1
  96. package/dist/{pi-mono-adapter-546cd1cc.js → pi-mono-adapter-6mkwq64n.js} +3 -2
  97. package/dist/{pricing-refresh-7dh2yase.js → pricing-refresh-ha21jhk7.js} +2 -2
  98. package/dist/{rbac-roles-npbmdh77.js → rbac-roles-59dxachk.js} +2 -2
  99. package/dist/{rbac-roles-mdmc96p4.js → rbac-roles-wqhma4dr.js} +3 -3
  100. package/dist/{render-v2-twhhwmms.js → render-v2-14kpzx12.js} +3 -3
  101. package/dist/{resume-5gsrjd5e.js → resume-gsa5fb5f.js} +6 -6
  102. package/dist/{session-access-m191x30x.js → session-access-skm7bnp6.js} +4 -4
  103. package/dist/{session-source-backfill-nt923ask.js → session-source-backfill-pbqzbncv.js} +2 -2
  104. package/dist/{setup-wv467afy.js → setup-5yermsem.js} +1 -1
  105. package/dist/{work-objects-8zkrpy13.js → work-objects-xj0ck0w4.js} +19 -19
  106. package/dist/{worker-follow-up-cecqszem.js → worker-follow-up-911xc0b8.js} +18 -16
  107. package/dist/{worker-mz5z7kj0.js → worker-qgg0m2gw.js} +30 -30
  108. package/openapi.json +1741 -290
  109. package/package.json +2 -2
  110. package/src/apps/catalog.generated.json +120 -1
  111. package/src/apps/definition.ts +38 -11
  112. package/src/apps/page-validator.ts +88 -0
  113. package/src/be/db/model-profiles.ts +110 -11
  114. package/src/be/db/tasks/read.ts +20 -0
  115. package/src/be/db/workflow-run-definitions.ts +19 -8
  116. package/src/be/db-client.ts +43 -5
  117. package/src/be/db.ts +9 -3
  118. package/src/be/migrations/284_model_profile_fallbacks.sql +9 -0
  119. package/src/be/model-profile-check.ts +43 -18
  120. package/src/be/runtime-pools/routing.ts +1 -0
  121. package/src/be/savings/calibrate.ts +468 -0
  122. package/src/be/savings/compute.ts +182 -0
  123. package/src/be/savings/model.ts +406 -0
  124. package/src/be/scripts/typecheck.ts +5 -0
  125. package/src/be/seed/agent-fs-provision.ts +48 -11
  126. package/src/be/seed/workflows-seeder.ts +67 -23
  127. package/src/be/skill-parser.ts +19 -7
  128. package/src/commands/onboard/agent-fs-version.ts +1 -1
  129. package/src/commands/provider-error-class.ts +97 -0
  130. package/src/commands/runner.ts +99 -17
  131. package/src/extensions/contract-types.generated.ts +1 -1
  132. package/src/http/all-routes.ts +2 -0
  133. package/src/http/fs.ts +8 -2
  134. package/src/http/index.ts +4 -0
  135. package/src/http/model-profiles.ts +43 -10
  136. package/src/http/poll.ts +1 -0
  137. package/src/http/savings-calibration.ts +277 -0
  138. package/src/http/savings.ts +363 -0
  139. package/src/http/tasks.ts +46 -4
  140. package/src/http/trackers/authorize-gate.ts +41 -0
  141. package/src/http/trackers/jira.ts +26 -4
  142. package/src/http/trackers/linear.ts +26 -4
  143. package/src/integrations/chat-sdk/limits.ts +6 -1
  144. package/src/jira/oauth.ts +7 -1
  145. package/src/linear/README.md +2 -1
  146. package/src/linear/oauth.ts +7 -1
  147. package/src/providers/amp-adapter.ts +1 -1
  148. package/src/providers/codex-adapter.ts +3 -0
  149. package/src/providers/pi-mono-adapter.ts +6 -5
  150. package/src/providers/types.ts +7 -0
  151. package/src/scripts-runtime/sdk-allowlist.ts +11 -1
  152. package/src/scripts-runtime/swarm-sdk.ts +6 -0
  153. package/src/scripts-runtime/types/stdlib.d.ts +9 -0
  154. package/src/scripts-runtime/types/swarm-extension.d.ts +34 -0
  155. package/src/scripts-runtime/types/swarm-sdk.d.ts +9 -0
  156. package/src/tasks/worker-follow-up.ts +142 -3
  157. package/src/tests/agent-fs-provision-seeder.test.ts +81 -0
  158. package/src/tests/apps-chart-shell.test.ts +170 -0
  159. package/src/tests/apps-icon.test.ts +156 -2
  160. package/src/tests/chat-sdk-relay.test.ts +12 -0
  161. package/src/tests/codex-adapter.test.ts +11 -0
  162. package/src/tests/comb-default.test.ts +6 -0
  163. package/src/tests/core-auth.test.ts +7 -6
  164. package/src/tests/db-client-busy-retry.test.ts +58 -6
  165. package/src/tests/deploy-guard.test.ts +154 -0
  166. package/src/tests/docs-index-footprint.test.js +3 -3
  167. package/src/tests/fixtures/app-shell-charts-definition.json.txt +180 -0
  168. package/src/tests/model-profile-fallbacks.test.ts +482 -0
  169. package/src/tests/model-profiles-api.test.ts +1 -0
  170. package/src/tests/pi-mono-session-cost-on-abort.test.ts +115 -0
  171. package/src/tests/provider-error-class.test.ts +174 -0
  172. package/src/tests/runner-provider-fallback.test.ts +197 -0
  173. package/src/tests/savings-calibration-api.test.ts +264 -0
  174. package/src/tests/savings-calibration.test.ts +201 -0
  175. package/src/tests/savings-compute.test.ts +406 -0
  176. package/src/tests/savings-model.test.ts +287 -0
  177. package/src/tests/script-connections.test.ts +2 -0
  178. package/src/tests/sdk-allowlist.test.ts +40 -0
  179. package/src/tests/seed-workflows.test.ts +167 -11
  180. package/src/tests/skill-parser.test.ts +45 -0
  181. package/src/tests/tracker-oauth-authorize-auth.test.ts +262 -0
  182. package/src/tests/workflow-definition-pinning.test.ts +128 -3
  183. package/src/tests/workflow-script-principal.test.ts +94 -4
  184. package/src/tools/app-upsert.ts +1 -1
  185. package/src/tools/model-profiles/list-model-profiles.ts +4 -2
  186. package/src/tools/update-profile.ts +1 -1
  187. package/src/types.ts +115 -33
  188. package/src/utils/constants.ts +2 -0
  189. package/templates/skills/apps/SKILL.md +62 -3
  190. package/templates/skills/apps/content.md +62 -3
  191. package/templates/skills/swarm-docs/content.md +2 -0
  192. package/dist/handlers-vbww69re.js +0 -32
  193. package/dist/index-4xwaf5th.js +0 -32
  194. package/dist/index-f0hcrs8e.js +0 -33
package/src/types.ts CHANGED
@@ -488,11 +488,48 @@ export const ModelProfileSchema = z.object({
488
488
  seededFrom: z.string().nullable(),
489
489
  /** Pooled-key allowlist (column `credentialAllowlist`); null uses the whole pool. */
490
490
  credentials: ModelProfileCredentialsSchema.nullable(),
491
+ /**
492
+ * Profiles on the same harness to hop to, in order, when a provider error
493
+ * (rate limit, seat, overload, auth, empty pool) ends a task running on
494
+ * this one. Empty: the task fails as before.
495
+ */
496
+ fallbacks: z.array(z.string()),
491
497
  createdAt: z.string(),
492
498
  lastUpdatedAt: z.string(),
493
499
  });
494
500
  export type ModelProfile = z.infer<typeof ModelProfileSchema>;
495
501
 
502
+ /**
503
+ * Why a provider session ended in a way another profile may survive. Set by
504
+ * the worker's classifier (`src/commands/provider-error-class.ts`); never a
505
+ * task failure, tool error, context overflow, cancellation or budget refusal.
506
+ */
507
+ export const ProviderErrorClassSchema = z.enum([
508
+ "rate_limit",
509
+ "model_window",
510
+ "seat",
511
+ "credits",
512
+ "overloaded",
513
+ "server_error",
514
+ "auth",
515
+ "pool_empty",
516
+ ]);
517
+ export type ProviderErrorClass = z.infer<typeof ProviderErrorClassSchema>;
518
+
519
+ /**
520
+ * One same-agent fallback hop: the task left `from` on `errorClass` and its
521
+ * resume runs `profile`. `skipped` lists the fallbacks passed over because
522
+ * they failed the profile check on the agent.
523
+ */
524
+ export const FallbackHopSchema = z.object({
525
+ from: z.string(),
526
+ profile: z.string(),
527
+ errorClass: ProviderErrorClassSchema,
528
+ at: z.string(),
529
+ skipped: z.array(z.object({ profile: z.string(), reason: z.string() })).optional(),
530
+ });
531
+ export type FallbackHop = z.infer<typeof FallbackHopSchema>;
532
+
496
533
  /** One check's verdict: only `fail` blocks; `unverified` means nothing to judge yet. */
497
534
  export const ProfileCheckStateSchema = z.enum(["pass", "warn", "fail", "unverified"]);
498
535
  export type ProfileCheckState = z.infer<typeof ProfileCheckStateSchema>;
@@ -830,6 +867,9 @@ export const AgentTaskSchema = z
830
867
  // the agent's default). Unset when no profile applied.
831
868
  profile: z.string().optional(),
832
869
  resolvedProfile: z.string().optional(),
870
+ // Provider-error fallback hops so far, oldest first; carried by every
871
+ // resume of the same work. Unset when the work never hopped.
872
+ fallbackHops: z.array(FallbackHopSchema).optional(),
833
873
 
834
874
  // Schedule linking (optional — set when task was created by a schedule).
835
875
  // z.string(): also reachable verbatim from the create-task query param.
@@ -962,6 +1002,8 @@ export const CreateTaskOptionsSchema = z.object({
962
1002
  modelTier: ModelTierSchema.optional(),
963
1003
  effort: ReasoningEffortSchema.optional(),
964
1004
  profile: z.string().optional(),
1005
+ /** Internal: the fallback hops a resume carries over (`createResumeFollowUp`). */
1006
+ fallbackHops: z.array(FallbackHopSchema).optional(),
965
1007
  scheduleId: z.string().optional(),
966
1008
  workflowRunId: z.string().optional(),
967
1009
  workflowRunStepId: z.string().optional(),
@@ -1309,32 +1351,80 @@ export type TaskTemplate = z.infer<typeof TaskTemplateSchema>;
1309
1351
 
1310
1352
  export const AgentStatusSchema = z.enum(["idle", "busy", "offline", "waiting_for_credentials"]);
1311
1353
 
1312
- // Discriminated union so future avatar types (emoji, image, ...) can be added
1313
- // with zero migrations — just a new zod branch + a UI renderer branch. Server
1314
- // validates shape only; the UI owns the curated icon catalog and deterministic
1315
- // fallback, so an unrecognized/hand-set icon name can never break rendering.
1316
- export const AgentAvatarSchema = z.discriminatedUnion("type", [
1317
- z.object({
1318
- type: z.literal("lucide"),
1319
- icon: z
1320
- .string()
1321
- .regex(/^[a-z0-9-]+$/)
1322
- .max(64),
1323
- color: z
1354
+ // An https image link, shared by Slack icons and media icons so the rules
1355
+ // can't drift: https only, at most 2048 characters, no embedded credentials.
1356
+ export const HttpsImageUrlSchema = z
1357
+ .url({ protocol: /^https$/, error: "Must be an https:// URL" })
1358
+ .max(2048)
1359
+ .refine((value) => {
1360
+ try {
1361
+ const parsed = new URL(value);
1362
+ return !parsed.username && !parsed.password;
1363
+ } catch {
1364
+ return false;
1365
+ }
1366
+ }, "URL must be valid and contain no credentials");
1367
+
1368
+ // Server validates shape only; the UI owns the curated icon catalog and
1369
+ // deterministic fallback, so an unrecognized/hand-set icon name can never
1370
+ // break rendering.
1371
+ export const LucideIconSchema = z.object({
1372
+ type: z.literal("lucide"),
1373
+ icon: z
1374
+ .string()
1375
+ .regex(/^[a-z0-9-]+$/)
1376
+ .max(64),
1377
+ color: z
1378
+ .string()
1379
+ .regex(/^#[0-9a-fA-F]{6}$/)
1380
+ .optional(),
1381
+ });
1382
+
1383
+ export const UrlIconSchema = z.object({
1384
+ type: z.literal("url"),
1385
+ url: HttpsImageUrlSchema,
1386
+ });
1387
+
1388
+ // Same addressing as the agent-fs task attachment ref: an absolute path, plus
1389
+ // both `orgId` and `driveId` for a specific drive, or neither for the swarm
1390
+ // drive. A single ID is never mixed with the swarm defaults.
1391
+ export const AgentFsIconSchema = z
1392
+ .object({
1393
+ type: z.literal("agent-fs"),
1394
+ path: z
1324
1395
  .string()
1325
- .regex(/^#[0-9a-fA-F]{6}$/)
1326
- .optional(),
1327
- }),
1396
+ .min(2)
1397
+ .max(1024)
1398
+ .refine((value) => value.startsWith("/"), "Path must be absolute (start with /)")
1399
+ .refine((value) => !value.split("/").includes(".."), 'Path must not contain ".." segments'),
1400
+ orgId: z.string().min(1).optional(),
1401
+ driveId: z.string().min(1).optional(),
1402
+ })
1403
+ .refine(
1404
+ (value) => (value.orgId === undefined) === (value.driveId === undefined),
1405
+ "Pass both orgId and driveId, or neither for the swarm drive",
1406
+ );
1407
+
1408
+ // Discriminated union so future icon types can be added with zero migrations:
1409
+ // a new zod branch plus a UI renderer branch. Images that can't load fall back
1410
+ // to a lucide glyph in the dashboard.
1411
+ export const MediaIconSchema = z.discriminatedUnion("type", [
1412
+ LucideIconSchema,
1413
+ UrlIconSchema,
1414
+ AgentFsIconSchema,
1328
1415
  ]);
1329
- export type AgentAvatar = z.infer<typeof AgentAvatarSchema>;
1416
+ export type MediaIcon = z.infer<typeof MediaIconSchema>;
1417
+
1418
+ // Agent avatars accept the same shapes as app icons.
1419
+ export const AgentAvatarSchema = MediaIconSchema;
1420
+ export type AgentAvatar = MediaIcon;
1330
1421
 
1331
1422
  /**
1332
- * Apps reuse the same avatar shape as agents (lucide icon + optional hex
1333
- * color) for their dashboard tile icon. A distinct export name keeps app call
1334
- * sites self-documenting.
1423
+ * Icon shown for an app on the dashboard Apps page: a lucide glyph, an https
1424
+ * image link, or an image in agent-fs.
1335
1425
  */
1336
- export const AppIconSchema = AgentAvatarSchema;
1337
- export type AppIcon = AgentAvatar;
1426
+ export const AppIconSchema = MediaIconSchema;
1427
+ export type AppIcon = MediaIcon;
1338
1428
 
1339
1429
  // Separate from `avatar` so an agent can keep its lucide disc and still post
1340
1430
  // to Slack with its own emoji or image.
@@ -1349,17 +1439,7 @@ export const AgentSlackIconSchema = z
1349
1439
  }),
1350
1440
  z.object({
1351
1441
  type: z.literal("url"),
1352
- url: z
1353
- .url({ protocol: /^https$/ })
1354
- .max(2048)
1355
- .refine((value) => {
1356
- try {
1357
- const parsed = new URL(value);
1358
- return !parsed.username && !parsed.password;
1359
- } catch {
1360
- return false;
1361
- }
1362
- }, "URL must be valid and contain no credentials"),
1442
+ url: HttpsImageUrlSchema,
1363
1443
  }),
1364
1444
  // No icon override: Slack shows the app's own avatar.
1365
1445
  z.object({ type: z.literal("app") }),
@@ -1432,7 +1512,8 @@ export const AgentSchema = z
1432
1512
  .nullable()
1433
1513
  .optional(),
1434
1514
 
1435
- // Custom avatar (icon + color). Null/missing = fall back to the
1515
+ // Custom avatar: a lucide glyph, an https image link, or an agent-fs image.
1516
+ // Null/missing = fall back to the
1436
1517
  // deterministic hash-derived icon and color (see apps/ui/src/lib/agent-icon.ts
1437
1518
  // and agent-color.ts). Migration 119 adds the column.
1438
1519
  avatar: z
@@ -1787,6 +1868,7 @@ export const ResumeReasonSchema = z.enum([
1787
1868
  "context_limits", // Provider session approaching context-window limits (Phase 6)
1788
1869
  "manual_supersede", // Operator-triggered (e.g. dashboard button)
1789
1870
  "crash_recovery", // Heartbeat sweep detected dead/stalled worker (DES-523)
1871
+ "provider_fallback", // Provider error; the resume runs the next fallback profile
1790
1872
  ]);
1791
1873
  export type ResumeReason = z.infer<typeof ResumeReasonSchema>;
1792
1874
 
@@ -273,6 +273,7 @@ export function isBrowserReachableUrl(value: string): boolean {
273
273
  // IPv4-mapped `::ffff:a.b.c.d`: judge the embedded IPv4 address.
274
274
  if (parsed.slice(0, 5).every((x) => x === 0) && g(5) === 0xffff) {
275
275
  const a = g(6) >> 8;
276
+ if (a === 0) return false;
276
277
  return a === 127 || !isPrivateIpv4(a, g(6) & 0xff);
277
278
  }
278
279
  return true;
@@ -280,6 +281,7 @@ export function isBrowserReachableUrl(value: string): boolean {
280
281
  const octets = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
281
282
  if (octets) {
282
283
  const [a, b] = [Number(octets[1]), Number(octets[2])];
284
+ if (a === 0) return false;
283
285
  return a === 127 || !isPrivateIpv4(a, b);
284
286
  }
285
287
  if (!host.includes(".")) return false;
@@ -137,7 +137,14 @@ An optional top-level `"theme"` sets the preset the dashboard applies to the app
137
137
 
138
138
  Viewers can override the preset per app from the app's settings drawer; the override rides the reserved `$theme` key of the user-config values (accepted on every app, even without a declared `userConfig` schema, and never visible at `/user/...`). A present override always beats the definition's `theme` — even an unrecognized one, which degrades to the dashboard theme — so treat `theme` as the app's default styling, not a guarantee.
139
139
 
140
- An optional top-level `"icon"` sets the app's icon on the dashboard Apps page, in the same shape as agent avatars: `{ "type": "lucide", "icon": "<kebab-case lucide name>", "color": "#RRGGBB" }` (`color` optional). The server validates shape only; the dashboard looks the name up in its curated icon catalog and shows a generic grid icon for an unknown name, so omitting `icon` is always safe.
140
+ An optional top-level `"icon"` sets the app's icon on the dashboard Apps page. It takes one of three shapes:
141
+
142
+ - `{ "type": "lucide", "icon": "<kebab-case lucide name>", "color": "#RRGGBB" }` (`color` optional). The dashboard looks the name up in its curated icon catalog and shows a generic grid icon for an unknown name.
143
+ - `{ "type": "url", "url": "https://..." }`: an https image link, at most 2048 characters, no credentials.
144
+ - `{ "type": "agent-fs", "path": "/apps/<appId>/icon.png" }`: an image on the swarm's agent-fs drive. Add both `orgId` and `driveId` for another drive; never just one.
145
+
146
+ The server validates shape only. The dashboard shows the grid glyph while an image loads, when it fails to load, and when the viewer has no agent-fs connected, so omitting `icon` is always safe. `app-patch` replaces `icon` whole, so switching shapes leaves no keys from the old one.
147
+
141
148
 
142
149
  Distinguish the two rollback 400s. A lossy-migration 400 is fixable: copy the required `migration` entries from the message and retry. A target-snapshot validation 400 explicitly says that directives cannot repair that historical definition; use `app-history` and choose a different version.
143
150
 
@@ -168,6 +175,8 @@ When a schema patch reports stale page/query bindings, repair them in that same
168
175
  }
169
176
  ```
170
177
 
178
+ Optional top-level `layout: "sidebar"` turns on the app shell (see Pages, routes, and page trees). Without it every page renders on the plain canvas, exactly as before.
179
+
171
180
  Model, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-10 models and at most 20 reusable elements; each declared model has 1-40 columns. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.
172
181
 
173
182
  ### Reusable elements
@@ -473,11 +482,58 @@ Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, pa
473
482
 
474
483
  Drawer variant: declare a route param on the containing page, set the Drawer `props.param` to that literal param name, and use the same `app.navigate` shape targeting that page with the row id assigned to the Drawer's param. The Drawer then opens from route state without a separate action contract.
475
484
 
485
+ App shell (`layout: "sidebar"` at the top level of the definition): every page renders inside a left sidebar that lists the app's pages and a sticky page header. Per page:
486
+
487
+ - `title`: the sidebar label and the header heading (defaults to the page name).
488
+ - `icon`: one catalog icon name (the list under Component catalog) before the sidebar label; unknown names are rejected.
489
+ - `description`: one line under the header title (at most 280 characters).
490
+ - `headerActions`: the key of one element of this page, rendered in the header's actions slot (right side), e.g. a Refresh `Button` with `on.press: [{ "action": "app.refresh" }]` or a row `Stack` of buttons. It is a second root: it must exist in the page's `elements` and must NOT also be reachable from `root`. It shares the page's state and actions.
491
+ - `nav: false`: leave the page out of the sidebar. Pages with a `required` param never list (they cannot open without it); open them with `app.navigate`.
492
+
493
+ The sidebar lists pages in definition order and marks the current one. Below 768px it folds into a menu button at the left of the header. Crumbs back to the default page show in the header only on pages the sidebar does not list. The shell renders in every view mode: inside the bordered canvas (default view, under the dashboard header that names the app), under the slim bar in `?mode=full`, and as the whole viewport in `?mode=chromeless`, where the sidebar also shows the app name (it is the only navigation inside an iframe). `headerActions` and `nav` without `layout: "sidebar"` are rejected; `icon` and `description` are accepted and unused.
494
+
495
+ ```json
496
+ {
497
+ "layout": "sidebar",
498
+ "defaultPage": "overview",
499
+ "pages": {
500
+ "overview": {
501
+ "title": "Overview",
502
+ "icon": "activity",
503
+ "description": "Deploys and spend, last 14 days.",
504
+ "headerActions": "refresh",
505
+ "root": "root",
506
+ "elements": {
507
+ "root": { "type": "Stack", "props": {}, "children": ["spend"] },
508
+ "spend": {
509
+ "type": "Chart",
510
+ "props": {
511
+ "kind": "area",
512
+ "data": { "$state": "/queries/days/data" },
513
+ "loading": { "$state": "/queries/days/loading" },
514
+ "x": "date",
515
+ "xType": "time",
516
+ "format": "currency",
517
+ "series": [{ "key": "spend", "label": "Spend" }]
518
+ }
519
+ },
520
+ "refresh": {
521
+ "type": "Button",
522
+ "props": { "label": "Refresh", "icon": "refresh-cw", "variant": "outline", "size": "sm" },
523
+ "on": { "press": [{ "action": "app.refresh" }] }
524
+ }
525
+ }
526
+ },
527
+ "settings": { "title": "Settings", "icon": "pencil", "root": "root", "elements": { "root": { "type": "Text", "props": { "content": "…" } } } }
528
+ }
529
+ }
530
+ ```
531
+
476
532
  Param `kind` is `string` by default, or `number` / `boolean`; `required` defaults to false. The names `mode`, `apiUrl`, `apiKey`, `email`, and `name` are reserved. `/apps/<id>` renders `defaultPage`; `/apps/<id>/p/<page>?issueId=42` is the shareable deep link for another page. Browser navigation is client-side, so app state and polled data stay warm across page changes.
477
533
 
478
534
  Within each page, `root` names one entry in its non-empty `elements` map. Elements are a flat, single-parent tree: ids are map keys, `children` contains ids (not nested elements), all elements must be reachable from `root`, and cycles, missing children, or shared children are invalid. Element and Form/UI ids are page-local. Element keys are `type`, `props`, `children`, `on`, `visible`, `repeat`, and `watch`; only components with a `default` child slot accept `children` (Stack, Grid, Split, Tabs, Container, Card, Section, and Drawer). `watch` maps state paths to an action step or chain.
479
535
 
480
- ## Component catalog (all 34)
536
+ ## Component catalog (all 35)
481
537
 
482
538
  Props reject unknown keys. A `{"$state":"..."}` binding may replace a literal prop value at any depth.
483
539
 
@@ -502,7 +558,8 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
502
558
  | `NumberInput` | `id` | `label`, `placeholder`, `min`, `max`; a text field with a decimal keyboard that writes the parsed number to `/ui/<id>/value` on every change (no debounce), or null when the field is empty; non-numeric text (a bare `-` mid-edit, letters) leaves the stored value untouched; `min`/`max` clamp the stored value and the visible text snaps to it when the field loses focus; no children. |
503
559
  | `Chips` | `id`, `options` | Toggle chips for quick filters. `options` are strings or `{ value, label?, icon? }`; `multiple`; `label` (group name for screen readers). Writes a string or null to `/ui/<id>/value`, or a string array with `multiple`; pressing the selected chip clears it. |
504
560
  | `Button` | `label` | `variant: "default", "secondary", "outline", "ghost", "destructive", or "destructive-outline"` (use `destructive-outline` for standalone deletes); `disabled` (constant or bound boolean); `busyWith: "<actionName>"` swaps the label for a spinner while that custom action's `/actions/<name>/status` is `"running"` (presses are ignored), then shows a check and `successLabel` for about 1.5s when it turns `"ok"`; `icon`, `iconPosition: "start" or "end"`; `size: "sm", "default", or "lg"`; `shortcut` (one key, shown as a keycap, presses the button); `hint` (tooltip); dispatch with element-level `on.press`. |
505
- | `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: "up", "down", or "flat", label }`; `info` (explanation tooltip next to the label). |
561
+ | `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: "up", "down", or "flat", label }`; `info` (explanation tooltip next to the label). `sparkline`: a small trend line under the value in the `tone` color, from an array of numbers (`null` is a gap) or from rows (bind `/queries/<name>/data`) read through `sparklineKey`; fewer than two points draws nothing. |
562
+ | `Chart` | `kind`, `x`, `series` | `kind: "line", "area", or "bar"`; bind `data` / `loading` / `error` to a named query like Table. `x` is the row field on the x axis; `xType: "category"` (default, row order) or `"time"` (ISO date or epoch ms, sorted, date ticks; rows whose `x` does not parse are dropped). `series`: 1-8 `{ key, label?, color? }`, `color` one of `chart-1`..`chart-5`, `primary`, `success`, `warning`, `error`, `info`, `muted` (default palette, in order: `primary`, `chart-2`..`chart-5`). `stacked` stacks area and bar series (lines never stack). `format: "number"` (default), `"currency"` (with `currency`, an ISO code, default `USD`) or `"percent"` (values are ratios: 0.42 is 42%). Tooltip on hover; the legend shows with two or more series (`legend` forces it on or off). `height` 120-640 px (default 240); `emptyMessage` (default "No data yet"). `x` and every `series[].key` must be columns of the bound query's model. Wrap it in a `Card` for a title. |
506
563
  | `Alert` | `message` | `title`, `tone: "info", "success", "warning", or "error"`, `icon` (overrides the tone icon), `actionLabel` (a button inside the callout that emits `press`; wire it with `on.press`). |
507
564
  | `Badge` | `text` | `text` is string or number; `tone`; `icon` replaces the dot; `variant: "tag"` (default uppercase chip), `"status"` (sentence-case pill), `"count"` (numeric pill), or `"beta"` (the BETA tag); `status` (a lifecycle value renders the dashboard status chip); `hint` (tooltip; the beta tag's explanation). |
508
565
  | `Icon` | `name` | `size: "sm", "md", or "lg"`, `tone: "default", "muted", "success", "warning", "error", or "info"`, `label` (accessible name; decorative without it). |
@@ -615,6 +672,8 @@ Shortcut details:
615
672
 
616
673
  ## Layout & interactivity
617
674
 
675
+ For a multi-page app that should feel like a product (a sidebar of pages, a sticky title bar with actions), set `layout: "sidebar"` (see Pages, routes, and page trees) instead of building navigation out of Tabs or button rows. Pair `Metric` tiles (with `sparkline`) in a `Grid` with `Chart`s inside `Card`s for dashboards.
676
+
618
677
  Use `Stack` as the primary page and section layout; `Container` is the legacy two-prop primitive retained for existing pages. Stack supports vertical or horizontal flow, shared spacing, alignment, justification, wrapping, and padding; row Stacks (filter bars, button rows) should set `collapseBelow: "sm"|"md"|"lg"` so they stack vertically on phones. Use `Grid` for responsive card or metric strips: a bare column count is responsive shorthand (1 column on phones, 2 from `sm`, the count from `md` up), or pin breakpoints explicitly with `{ "base": 1, "md": 2, "lg": 3 }`. `Grid` and `Split` also accept `padding` on the shared spacing scale.
619
678
 
620
679
  `Stack` and `Split` size to their content by default, so a page scrolls as a whole. Set `fill: true` to make one grow to fill the remaining height of a `fill`-aware parent (another `fill` Stack or Split) instead; chain it from the page root down through every container on the path to the element that should scroll, and that element scrolls within whatever height is left while the page itself does not. A non-`fill` sibling (a toolbar, a header) keeps its natural height and the `fill` sibling absorbs the rest. A `fill` Split stretches both panes to the full row height, so nesting a `fill` Split inside one pane of another `fill` Split is the way to build a three-or-more column viewport-height layout (`ratio` is only ever two panes).
@@ -132,7 +132,14 @@ An optional top-level `"theme"` sets the preset the dashboard applies to the app
132
132
 
133
133
  Viewers can override the preset per app from the app's settings drawer; the override rides the reserved `$theme` key of the user-config values (accepted on every app, even without a declared `userConfig` schema, and never visible at `/user/...`). A present override always beats the definition's `theme` — even an unrecognized one, which degrades to the dashboard theme — so treat `theme` as the app's default styling, not a guarantee.
134
134
 
135
- An optional top-level `"icon"` sets the app's icon on the dashboard Apps page, in the same shape as agent avatars: `{ "type": "lucide", "icon": "<kebab-case lucide name>", "color": "#RRGGBB" }` (`color` optional). The server validates shape only; the dashboard looks the name up in its curated icon catalog and shows a generic grid icon for an unknown name, so omitting `icon` is always safe.
135
+ An optional top-level `"icon"` sets the app's icon on the dashboard Apps page. It takes one of three shapes:
136
+
137
+ - `{ "type": "lucide", "icon": "<kebab-case lucide name>", "color": "#RRGGBB" }` (`color` optional). The dashboard looks the name up in its curated icon catalog and shows a generic grid icon for an unknown name.
138
+ - `{ "type": "url", "url": "https://..." }`: an https image link, at most 2048 characters, no credentials.
139
+ - `{ "type": "agent-fs", "path": "/apps/<appId>/icon.png" }`: an image on the swarm's agent-fs drive. Add both `orgId` and `driveId` for another drive; never just one.
140
+
141
+ The server validates shape only. The dashboard shows the grid glyph while an image loads, when it fails to load, and when the viewer has no agent-fs connected, so omitting `icon` is always safe. `app-patch` replaces `icon` whole, so switching shapes leaves no keys from the old one.
142
+
136
143
 
137
144
  Distinguish the two rollback 400s. A lossy-migration 400 is fixable: copy the required `migration` entries from the message and retry. A target-snapshot validation 400 explicitly says that directives cannot repair that historical definition; use `app-history` and choose a different version.
138
145
 
@@ -163,6 +170,8 @@ When a schema patch reports stale page/query bindings, repair them in that same
163
170
  }
164
171
  ```
165
172
 
173
+ Optional top-level `layout: "sidebar"` turns on the app shell (see Pages, routes, and page trees). Without it every page renders on the plain canvas, exactly as before.
174
+
166
175
  Model, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-10 models and at most 20 reusable elements; each declared model has 1-40 columns. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.
167
176
 
168
177
  ### Reusable elements
@@ -468,11 +477,58 @@ Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, pa
468
477
 
469
478
  Drawer variant: declare a route param on the containing page, set the Drawer `props.param` to that literal param name, and use the same `app.navigate` shape targeting that page with the row id assigned to the Drawer's param. The Drawer then opens from route state without a separate action contract.
470
479
 
480
+ App shell (`layout: "sidebar"` at the top level of the definition): every page renders inside a left sidebar that lists the app's pages and a sticky page header. Per page:
481
+
482
+ - `title`: the sidebar label and the header heading (defaults to the page name).
483
+ - `icon`: one catalog icon name (the list under Component catalog) before the sidebar label; unknown names are rejected.
484
+ - `description`: one line under the header title (at most 280 characters).
485
+ - `headerActions`: the key of one element of this page, rendered in the header's actions slot (right side), e.g. a Refresh `Button` with `on.press: [{ "action": "app.refresh" }]` or a row `Stack` of buttons. It is a second root: it must exist in the page's `elements` and must NOT also be reachable from `root`. It shares the page's state and actions.
486
+ - `nav: false`: leave the page out of the sidebar. Pages with a `required` param never list (they cannot open without it); open them with `app.navigate`.
487
+
488
+ The sidebar lists pages in definition order and marks the current one. Below 768px it folds into a menu button at the left of the header. Crumbs back to the default page show in the header only on pages the sidebar does not list. The shell renders in every view mode: inside the bordered canvas (default view, under the dashboard header that names the app), under the slim bar in `?mode=full`, and as the whole viewport in `?mode=chromeless`, where the sidebar also shows the app name (it is the only navigation inside an iframe). `headerActions` and `nav` without `layout: "sidebar"` are rejected; `icon` and `description` are accepted and unused.
489
+
490
+ ```json
491
+ {
492
+ "layout": "sidebar",
493
+ "defaultPage": "overview",
494
+ "pages": {
495
+ "overview": {
496
+ "title": "Overview",
497
+ "icon": "activity",
498
+ "description": "Deploys and spend, last 14 days.",
499
+ "headerActions": "refresh",
500
+ "root": "root",
501
+ "elements": {
502
+ "root": { "type": "Stack", "props": {}, "children": ["spend"] },
503
+ "spend": {
504
+ "type": "Chart",
505
+ "props": {
506
+ "kind": "area",
507
+ "data": { "$state": "/queries/days/data" },
508
+ "loading": { "$state": "/queries/days/loading" },
509
+ "x": "date",
510
+ "xType": "time",
511
+ "format": "currency",
512
+ "series": [{ "key": "spend", "label": "Spend" }]
513
+ }
514
+ },
515
+ "refresh": {
516
+ "type": "Button",
517
+ "props": { "label": "Refresh", "icon": "refresh-cw", "variant": "outline", "size": "sm" },
518
+ "on": { "press": [{ "action": "app.refresh" }] }
519
+ }
520
+ }
521
+ },
522
+ "settings": { "title": "Settings", "icon": "pencil", "root": "root", "elements": { "root": { "type": "Text", "props": { "content": "…" } } } }
523
+ }
524
+ }
525
+ ```
526
+
471
527
  Param `kind` is `string` by default, or `number` / `boolean`; `required` defaults to false. The names `mode`, `apiUrl`, `apiKey`, `email`, and `name` are reserved. `/apps/<id>` renders `defaultPage`; `/apps/<id>/p/<page>?issueId=42` is the shareable deep link for another page. Browser navigation is client-side, so app state and polled data stay warm across page changes.
472
528
 
473
529
  Within each page, `root` names one entry in its non-empty `elements` map. Elements are a flat, single-parent tree: ids are map keys, `children` contains ids (not nested elements), all elements must be reachable from `root`, and cycles, missing children, or shared children are invalid. Element and Form/UI ids are page-local. Element keys are `type`, `props`, `children`, `on`, `visible`, `repeat`, and `watch`; only components with a `default` child slot accept `children` (Stack, Grid, Split, Tabs, Container, Card, Section, and Drawer). `watch` maps state paths to an action step or chain.
474
530
 
475
- ## Component catalog (all 34)
531
+ ## Component catalog (all 35)
476
532
 
477
533
  Props reject unknown keys. A `{"$state":"..."}` binding may replace a literal prop value at any depth.
478
534
 
@@ -497,7 +553,8 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
497
553
  | `NumberInput` | `id` | `label`, `placeholder`, `min`, `max`; a text field with a decimal keyboard that writes the parsed number to `/ui/<id>/value` on every change (no debounce), or null when the field is empty; non-numeric text (a bare `-` mid-edit, letters) leaves the stored value untouched; `min`/`max` clamp the stored value and the visible text snaps to it when the field loses focus; no children. |
498
554
  | `Chips` | `id`, `options` | Toggle chips for quick filters. `options` are strings or `{ value, label?, icon? }`; `multiple`; `label` (group name for screen readers). Writes a string or null to `/ui/<id>/value`, or a string array with `multiple`; pressing the selected chip clears it. |
499
555
  | `Button` | `label` | `variant: "default", "secondary", "outline", "ghost", "destructive", or "destructive-outline"` (use `destructive-outline` for standalone deletes); `disabled` (constant or bound boolean); `busyWith: "<actionName>"` swaps the label for a spinner while that custom action's `/actions/<name>/status` is `"running"` (presses are ignored), then shows a check and `successLabel` for about 1.5s when it turns `"ok"`; `icon`, `iconPosition: "start" or "end"`; `size: "sm", "default", or "lg"`; `shortcut` (one key, shown as a keycap, presses the button); `hint` (tooltip); dispatch with element-level `on.press`. |
500
- | `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: "up", "down", or "flat", label }`; `info` (explanation tooltip next to the label). |
556
+ | `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: "up", "down", or "flat", label }`; `info` (explanation tooltip next to the label). `sparkline`: a small trend line under the value in the `tone` color, from an array of numbers (`null` is a gap) or from rows (bind `/queries/<name>/data`) read through `sparklineKey`; fewer than two points draws nothing. |
557
+ | `Chart` | `kind`, `x`, `series` | `kind: "line", "area", or "bar"`; bind `data` / `loading` / `error` to a named query like Table. `x` is the row field on the x axis; `xType: "category"` (default, row order) or `"time"` (ISO date or epoch ms, sorted, date ticks; rows whose `x` does not parse are dropped). `series`: 1-8 `{ key, label?, color? }`, `color` one of `chart-1`..`chart-5`, `primary`, `success`, `warning`, `error`, `info`, `muted` (default palette, in order: `primary`, `chart-2`..`chart-5`). `stacked` stacks area and bar series (lines never stack). `format: "number"` (default), `"currency"` (with `currency`, an ISO code, default `USD`) or `"percent"` (values are ratios: 0.42 is 42%). Tooltip on hover; the legend shows with two or more series (`legend` forces it on or off). `height` 120-640 px (default 240); `emptyMessage` (default "No data yet"). `x` and every `series[].key` must be columns of the bound query's model. Wrap it in a `Card` for a title. |
501
558
  | `Alert` | `message` | `title`, `tone: "info", "success", "warning", or "error"`, `icon` (overrides the tone icon), `actionLabel` (a button inside the callout that emits `press`; wire it with `on.press`). |
502
559
  | `Badge` | `text` | `text` is string or number; `tone`; `icon` replaces the dot; `variant: "tag"` (default uppercase chip), `"status"` (sentence-case pill), `"count"` (numeric pill), or `"beta"` (the BETA tag); `status` (a lifecycle value renders the dashboard status chip); `hint` (tooltip; the beta tag's explanation). |
503
560
  | `Icon` | `name` | `size: "sm", "md", or "lg"`, `tone: "default", "muted", "success", "warning", "error", or "info"`, `label` (accessible name; decorative without it). |
@@ -610,6 +667,8 @@ Shortcut details:
610
667
 
611
668
  ## Layout & interactivity
612
669
 
670
+ For a multi-page app that should feel like a product (a sidebar of pages, a sticky title bar with actions), set `layout: "sidebar"` (see Pages, routes, and page trees) instead of building navigation out of Tabs or button rows. Pair `Metric` tiles (with `sparkline`) in a `Grid` with `Chart`s inside `Card`s for dashboards.
671
+
613
672
  Use `Stack` as the primary page and section layout; `Container` is the legacy two-prop primitive retained for existing pages. Stack supports vertical or horizontal flow, shared spacing, alignment, justification, wrapping, and padding; row Stacks (filter bars, button rows) should set `collapseBelow: "sm"|"md"|"lg"` so they stack vertically on phones. Use `Grid` for responsive card or metric strips: a bare column count is responsive shorthand (1 column on phones, 2 from `sm`, the count from `md` up), or pin breakpoints explicitly with `{ "base": 1, "md": 2, "lg": 3 }`. `Grid` and `Split` also accept `padding` on the shared spacing scale.
614
673
 
615
674
  `Stack` and `Split` size to their content by default, so a page scrolls as a whole. Set `fill: true` to make one grow to fill the remaining height of a `fill`-aware parent (another `fill` Stack or Split) instead; chain it from the page root down through every container on the path to the element that should scroll, and that element scrolls within whatever height is left while the page itself does not. A non-`fill` sibling (a toolbar, a header) keeps its natural height and the `fill` sibling absorbs the rest. A `fill` Split stretches both panes to the full row height, so nesting a `fill` Split inside one pane of another `fill` Split is the way to build a three-or-more column viewport-height layout (`ratio` is only ever two panes).
@@ -61,6 +61,7 @@ Fetch the page as markdown: `curl -fsSL https://docs.agent-swarm.dev/llms.mdx/do
61
61
  ## Guides
62
62
 
63
63
  - [Choosing an AI operating model](https://docs.agent-swarm.dev/docs/guides/choosing-an-ai-operating-model). Reference.
64
+ - [Small tech team operating model](https://docs.agent-swarm.dev/docs/guides/small-tech-team-operating-model). Reference.
64
65
  - [Deployment Guide](https://docs.agent-swarm.dev/docs/guides/deployment). When: Someone wants to run Agent Swarm on their own server with Docker Compose.
65
66
  - [One-click deploy](https://docs.agent-swarm.dev/docs/guides/one-click-deploy). When: Someone has no server yet and wants Agent Swarm running in the cloud with HTTPS.
66
67
  - [Kubernetes and Helm](https://docs.agent-swarm.dev/docs/guides/kubernetes). When: Someone wants to install Agent Swarm on Kubernetes.
@@ -70,6 +71,7 @@ Fetch the page as markdown: `curl -fsSL https://docs.agent-swarm.dev/llms.mdx/do
70
71
  - [Asset Namespaces](https://docs.agent-swarm.dev/docs/guides/asset-namespaces). Reference.
71
72
  - [agent-fs Co-deployment](https://docs.agent-swarm.dev/docs/guides/agent-fs-co-deployment). When: Someone wants shared persistent files for agents on a self-hosted swarm.
72
73
  - [Self-Hosted SSO](https://docs.agent-swarm.dev/docs/guides/self-hosted-sso). When: Someone wants their self-hosted swarm dashboard behind single sign-on.
74
+ - [AI operations governance for small companies](https://docs.agent-swarm.dev/docs/guides/ai-operations-governance). Reference.
73
75
  - [E2B Provider Smoke Tests](https://docs.agent-swarm.dev/docs/guides/e2b-provider-smoke-tests). Reference.
74
76
  - [Evals Harness](https://docs.agent-swarm.dev/docs/guides/evals-harness). Reference.
75
77
  - [Personalization & Status](https://docs.agent-swarm.dev/docs/guides/personalization). Reference.
@@ -1,32 +0,0 @@
1
- import {
2
- isUserAllowed2,
3
- registerMessageHandler2,
4
- init_handlers
5
- } from "./cli-syybb0p1.js";
6
- import"./cli-tacge1w0.js";
7
- import"./cli-jywyhqws.js";
8
- import"./cli-93k32c37.js";
9
- import"./cli-k26bkr9t.js";
10
- import"./cli-a3b239vq.js";
11
- import"./cli-0ntbxyaa.js";
12
- import"./cli-yn2bbre9.js";
13
- import"./cli-7cp6aa1q.js";
14
- import"./cli-b5rs97a6.js";
15
- import"./cli-x6t50dmw.js";
16
- import"./cli-vbh10fqa.js";
17
- import"./cli-vqptjbr7.js";
18
- import"./cli-4r05hnqa.js";
19
- import"./cli-dy32zecz.js";
20
- import"./cli-b8e9nb04.js";
21
- import"./cli-zcsw143p.js";
22
- import"./cli-k93bq1wq.js";
23
- import"./cli-1xh9a7hn.js";
24
- import"./cli-re4raaj0.js";
25
- import"./cli-7w69ne2f.js";
26
- import"./cli-eddnyg3t.js";
27
- init_handlers();
28
-
29
- export {
30
- isUserAllowed2 as isUserAllowed,
31
- registerMessageHandler2 as registerMessageHandler
32
- };
@@ -1,32 +0,0 @@
1
- import"./cli-ns59dc6r.js";
2
- import {
3
- parseHeartbeatIntervalMs2,
4
- startHeartbeat2,
5
- stopHeartbeat2
6
- } from "./cli-b085njxz.js";
7
- import"./cli-k0615eh8.js";
8
- import"./cli-m4dqmnbp.js";
9
- import"./cli-93k32c37.js";
10
- import"./cli-k26bkr9t.js";
11
- import"./cli-a3b239vq.js";
12
- import"./cli-0ntbxyaa.js";
13
- import"./cli-yn2bbre9.js";
14
- import"./cli-7cp6aa1q.js";
15
- import"./cli-b5rs97a6.js";
16
- import"./cli-x6t50dmw.js";
17
- import"./cli-vbh10fqa.js";
18
- import"./cli-vqptjbr7.js";
19
- import"./cli-4r05hnqa.js";
20
- import"./cli-dy32zecz.js";
21
- import"./cli-b8e9nb04.js";
22
- import"./cli-zcsw143p.js";
23
- import"./cli-k93bq1wq.js";
24
- import"./cli-1xh9a7hn.js";
25
- import"./cli-re4raaj0.js";
26
- import"./cli-7w69ne2f.js";
27
- import"./cli-eddnyg3t.js";
28
- export {
29
- parseHeartbeatIntervalMs2 as parseHeartbeatIntervalMs,
30
- startHeartbeat2 as startHeartbeat,
31
- stopHeartbeat2 as stopHeartbeat
32
- };
@@ -1,33 +0,0 @@
1
- import {
2
- calculateNextRun2,
3
- startScheduler2,
4
- stopScheduler2,
5
- runScheduleNow2,
6
- init_scheduler2
7
- } from "./cli-93k32c37.js";
8
- import"./cli-k26bkr9t.js";
9
- import"./cli-a3b239vq.js";
10
- import"./cli-0ntbxyaa.js";
11
- import"./cli-yn2bbre9.js";
12
- import"./cli-7cp6aa1q.js";
13
- import"./cli-b5rs97a6.js";
14
- import"./cli-x6t50dmw.js";
15
- import"./cli-vbh10fqa.js";
16
- import"./cli-vqptjbr7.js";
17
- import"./cli-4r05hnqa.js";
18
- import"./cli-dy32zecz.js";
19
- import"./cli-b8e9nb04.js";
20
- import"./cli-zcsw143p.js";
21
- import"./cli-k93bq1wq.js";
22
- import"./cli-1xh9a7hn.js";
23
- import"./cli-re4raaj0.js";
24
- import"./cli-7w69ne2f.js";
25
- import"./cli-eddnyg3t.js";
26
- init_scheduler2();
27
-
28
- export {
29
- calculateNextRun2 as calculateNextRun,
30
- runScheduleNow2 as runScheduleNow,
31
- startScheduler2 as startScheduler,
32
- stopScheduler2 as stopScheduler
33
- };