@maimaimai/swarm-kit

唯一编排工具：wave-orchestrator 的 waves/relay 编排 + fractal-swarm 的强类型 Envelope 归并与审计打回，跑在 pi-subagents 引擎上。

Packages

Package details

extensionskill

Install @maimaimai/swarm-kit from npm and Pi will load the resources declared by the package manifest.

npm report

$ pi install npm:@maimaimai/swarm-kit

Package: @maimaimai/swarm-kit
Version: 0.1.1
Published: Sep 27, 2026
Downloads: 289/mo · 289/wk
Author: maimaimai
License: MIT
Types: extension, skill
Size: 47.8 KB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

swarm-kit

全系统唯一的并行编排工具 wave_run——合并谱系：

wave-orchestrator（waves/relay 分批接力、event-bus RPC seam）
   + fractal-swarm（强类型 Envelope 归并、审计打回、DEGRADED 终态、树状归并）
   → 跑在 pi-subagents 引擎上

被合并的两份实现已归档：~/code/_archive/wave-orchestrator.ts、~/code/_archive/fractal-swarm/。

运行

npm run typecheck   # tsc --noEmit
npm test            # 44 条：契约/审计/脚本生成/防漂移/mock 沙箱干跑 + verify 循环

扩展装载（已就位）：~/.pi/agent/extensions/swarm-kit → 本仓库（目录扩展，入口必须是根 index.ts）。 重启 pi 后生效；headless 冒烟：pi -p --no-builtin-tools -t wave_run "..."。

安装（发布后）

pi install npm:@maimaimai/swarm-kit   # 官方机制：写入 settings packages，无需 symlink
# 前置：Node ≥22.6、pi 已装、pi-subagents 已装（pi install npm:pi-subagents）
# 重启 pi 生效

备选（裸目录装载）：npm i -g @maimaimai/swarm-kit 后把包目录放进 ~/.pi/agent/extensions/swarm-kit（Windows 用 mklink /J 目录联接，无需管理员）。

wave_run 参数

旧参数不变：mode(waves|relay|verify) / agent / tasks(复数) / batchSize / model / concurrency / maxSpawns。

新增（默认开 envelope）：

参数	默认	说明
`envelope`	`true`	子任务按强类型信封输出，父脚本机械校验，不合格打回；`false` 退回旧版纯文本语义
`audit_agent`	无	指定后归并前过模型对抗审查（不通过 → 打回修正，带审计理由）；与 `envelope=false` 互斥（参数报错）
`max_audit_retries`	`2`	契约/审计打回上限，超限标 `DEGRADED` 终态（防死循环）
`audit_sample_rate`	`1`	模型审计抽样率
`verify_agent`	verify 必填	沙箱执行者（需 bash/write 工具）；`mode=verify` 时只传 1 条总目标，失败回喂 ≤`max_rounds` 轮，未过 root=DEGRADED 禁落地

返回：旧字段 results[] 原样保留（兼容旧调用方）+ 新字段 root（树状归并信封：SUCCESS | FAILED | DEGRADED）。

实现要点

生成的 workflowScript 跑在 pi-subagents 沙箱：禁止嵌套 async 函数（打回/审计循环内联在主循环顶层 await）、无 import——运行时 helper 以内联纯函数注入
src/envelope.ts/audit.ts 是宿主侧同构实现，test/script.test.ts 的防漂移断言锁住两者一致
超大 payload 自动转 artifact:// 引用（摘要+路径），保护上级上下文
打回用新 key（w0.r1/w0.a0/w0.ra1），不复用原 key（同 key 返回同一回执）

已验证

44/44 单测 + tsc 零错
mock 沙箱干跑 8 条：一次过/打回超限 DEGRADED/修正后 SUCCESS/审计 3 轮耗尽/审计 PASS/子任务失败 FAILED/宽松模式/relay {{prev}}
真实冒烟 ×2：headless pi -p 下 2 任务 Envelope 归并全 SUCCESS；带 audit_agent 审计一次通过（子信封 confidence 0.95、error_context null）