pi-fabric 0.130.2 → 0.131.0

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 (225) hide show
  1. package/dist/activity/store.d.ts +2 -1
  2. package/dist/activity/store.d.ts.map +1 -1
  3. package/dist/actors/directory.d.ts.map +1 -1
  4. package/dist/actors/global-registry.d.ts.map +1 -1
  5. package/dist/actors/manager.d.ts +4 -3
  6. package/dist/actors/manager.d.ts.map +1 -1
  7. package/dist/actors/mesh-monitor.d.ts +2 -0
  8. package/dist/actors/mesh-monitor.d.ts.map +1 -1
  9. package/dist/actors/name-policy.d.ts +3 -0
  10. package/dist/actors/name-policy.d.ts.map +1 -0
  11. package/dist/actors/registry-store.d.ts +1 -1
  12. package/dist/actors/registry-store.d.ts.map +1 -1
  13. package/dist/agents/agent-files.d.ts +8 -0
  14. package/dist/agents/agent-files.d.ts.map +1 -1
  15. package/dist/agents/agent-files.js +48 -3
  16. package/dist/agents/agent-files.js.map +2 -2
  17. package/dist/agents/child-skills.d.ts +60 -0
  18. package/dist/agents/child-skills.d.ts.map +1 -0
  19. package/dist/agents/child-skills.js +94 -0
  20. package/dist/agents/child-skills.js.map +7 -0
  21. package/dist/agents/clone-first-worktree.d.ts +6 -0
  22. package/dist/agents/clone-first-worktree.d.ts.map +1 -1
  23. package/dist/agents/cow-clone.d.ts.map +1 -1
  24. package/dist/agents/handoff.d.ts +12 -2
  25. package/dist/agents/handoff.d.ts.map +1 -1
  26. package/dist/agents/manager.d.ts +4 -1
  27. package/dist/agents/manager.d.ts.map +1 -1
  28. package/dist/agents/model-pin-guard.d.ts +27 -0
  29. package/dist/agents/model-pin-guard.d.ts.map +1 -0
  30. package/dist/agents/model-pin-guard.js +86 -0
  31. package/dist/agents/model-pin-guard.js.map +7 -0
  32. package/dist/agents/model-pin.d.ts +25 -0
  33. package/dist/agents/model-pin.d.ts.map +1 -0
  34. package/dist/agents/provider-bridge.d.ts +5 -4
  35. package/dist/agents/provider-bridge.d.ts.map +1 -1
  36. package/dist/agents/provider-bridge.js +32 -4
  37. package/dist/agents/provider-bridge.js.map +3 -3
  38. package/dist/agents/request.d.ts.map +1 -1
  39. package/dist/agents/service-schema.d.ts.map +1 -1
  40. package/dist/agents/types.d.ts +25 -0
  41. package/dist/agents/types.d.ts.map +1 -1
  42. package/dist/agents/worktree-manager.d.ts.map +1 -1
  43. package/dist/agents.js +6 -5
  44. package/dist/agents.js.map +2 -2
  45. package/dist/audit/details.d.ts +4 -0
  46. package/dist/audit/details.d.ts.map +1 -1
  47. package/dist/chunks/{chunk-SBAROA4Y.js → chunk-2RWNVCFD.js} +17 -1
  48. package/dist/chunks/{chunk-SBAROA4Y.js.map → chunk-2RWNVCFD.js.map} +2 -2
  49. package/dist/chunks/{chunk-6O6UWMBO.js → chunk-36XQFTEN.js} +2 -2
  50. package/dist/chunks/chunk-3PKZSIRA.js +1312 -0
  51. package/dist/chunks/chunk-3PKZSIRA.js.map +7 -0
  52. package/dist/chunks/{chunk-JJXUOXI5.js → chunk-4KX6BIPL.js} +17 -2
  53. package/dist/chunks/chunk-4KX6BIPL.js.map +7 -0
  54. package/dist/chunks/{chunk-EYHTTMSM.js → chunk-4PBW54I2.js} +5 -5
  55. package/dist/chunks/{chunk-WTIF3MIM.js → chunk-56NMRVTV.js} +8 -8
  56. package/dist/chunks/{chunk-WQFG7ZVC.js → chunk-5BOTHX47.js} +48 -13
  57. package/dist/chunks/chunk-5BOTHX47.js.map +7 -0
  58. package/dist/chunks/chunk-5QJFDKPN.js +179 -0
  59. package/dist/chunks/chunk-5QJFDKPN.js.map +7 -0
  60. package/dist/chunks/chunk-6HO2IUQ5.js +104 -0
  61. package/dist/chunks/chunk-6HO2IUQ5.js.map +7 -0
  62. package/dist/chunks/{chunk-NF6W327N.js → chunk-7CIES6X2.js} +9 -2
  63. package/dist/chunks/chunk-7CIES6X2.js.map +7 -0
  64. package/dist/chunks/{chunk-KDX3762L.js → chunk-DGERP4VL.js} +4 -4
  65. package/dist/chunks/{chunk-K3ZWBUUL.js → chunk-IOGDTIGN.js} +13 -13
  66. package/dist/chunks/chunk-IOGDTIGN.js.map +7 -0
  67. package/dist/chunks/{chunk-UXIBKMUM.js → chunk-KIFOEBYJ.js} +4 -4
  68. package/dist/chunks/{chunk-D5224P2R.js → chunk-LKYLD5SN.js} +7 -7
  69. package/dist/chunks/chunk-NENQZCGW.js +45 -0
  70. package/dist/chunks/chunk-NENQZCGW.js.map +7 -0
  71. package/dist/chunks/{chunk-YTYLKL3Z.js → chunk-OJ4HAALD.js} +8 -8
  72. package/dist/chunks/{chunk-TBB7F7WS.js → chunk-PQVUMJ5J.js} +84 -18
  73. package/dist/chunks/chunk-PQVUMJ5J.js.map +7 -0
  74. package/dist/chunks/chunk-UD7LFV43.js +28 -0
  75. package/dist/chunks/chunk-UD7LFV43.js.map +7 -0
  76. package/dist/chunks/{chunk-CH2QMORW.js → chunk-UFMYN5TA.js} +2 -2
  77. package/dist/chunks/chunk-V4OW2ULC.js +422 -0
  78. package/dist/chunks/chunk-V4OW2ULC.js.map +7 -0
  79. package/dist/chunks/{chunk-6C2DMTQC.js → chunk-VNWQIGQL.js} +552 -145
  80. package/dist/chunks/chunk-VNWQIGQL.js.map +7 -0
  81. package/dist/chunks/{chunk-OA5SJT2T.js → chunk-WGMCNCP6.js} +183 -82
  82. package/dist/chunks/chunk-WGMCNCP6.js.map +7 -0
  83. package/dist/chunks/{chunk-HAHRJMWY.js → chunk-WWTGWGH7.js} +6 -6
  84. package/dist/chunks/{chunk-F4HL6KJR.js → chunk-X7QETPBC.js} +7 -7
  85. package/dist/chunks/{chunk-SSRSCT2M.js → chunk-XFOSUGLU.js} +4 -4
  86. package/dist/chunks/{chunk-4VGB6HMU.js → chunk-ZFWICFNJ.js} +23 -18
  87. package/dist/chunks/{chunk-4VGB6HMU.js.map → chunk-ZFWICFNJ.js.map} +2 -2
  88. package/dist/commands/fabric-handler.d.ts.map +1 -1
  89. package/dist/commands/fabric-handler.js +43 -7
  90. package/dist/commands/fabric-handler.js.map +2 -2
  91. package/dist/compaction/claim-events.js +2 -2
  92. package/dist/components/configuration.js +3 -3
  93. package/dist/config.d.ts +9 -1
  94. package/dist/config.d.ts.map +1 -1
  95. package/dist/core/action-registry.js +4 -4
  96. package/dist/core/model-aliases.d.ts +22 -0
  97. package/dist/core/model-aliases.d.ts.map +1 -0
  98. package/dist/core/model-resolution.d.ts +41 -20
  99. package/dist/core/model-resolution.d.ts.map +1 -1
  100. package/dist/core/prompt-guidance.js +9 -4
  101. package/dist/core/prompt-guidance.js.map +2 -2
  102. package/dist/core/system-guidance.d.ts.map +1 -1
  103. package/dist/decisions/command.d.ts +2 -1
  104. package/dist/decisions/command.d.ts.map +1 -1
  105. package/dist/decisions/command.js +31 -11
  106. package/dist/decisions/command.js.map +2 -2
  107. package/dist/decisions/events.js +2 -1
  108. package/dist/decisions/events.js.map +1 -1
  109. package/dist/decisions/host.d.ts +8 -0
  110. package/dist/decisions/host.d.ts.map +1 -1
  111. package/dist/decisions/render.d.ts +44 -0
  112. package/dist/decisions/render.d.ts.map +1 -0
  113. package/dist/durable/agent.d.ts +6 -0
  114. package/dist/durable/agent.d.ts.map +1 -1
  115. package/dist/durable/worker-host.d.ts.map +1 -1
  116. package/dist/durable/worker-host.js +7 -1283
  117. package/dist/durable/worker-host.js.map +4 -4
  118. package/dist/durable/worker-options.d.ts +2 -0
  119. package/dist/durable/worker-options.d.ts.map +1 -1
  120. package/dist/durable/worker-role-seed.d.ts +82 -0
  121. package/dist/durable/worker-role-seed.d.ts.map +1 -0
  122. package/dist/durable/worker.js +10 -1
  123. package/dist/durable/worker.js.map +2 -2
  124. package/dist/durable-extension.d.ts +1 -1
  125. package/dist/durable-extension.js +1 -1
  126. package/dist/durable-extension.js.map +1 -1
  127. package/dist/durable-host.d.ts +8 -0
  128. package/dist/durable-host.d.ts.map +1 -0
  129. package/dist/durable-host.js +20 -0
  130. package/dist/durable-host.js.map +7 -0
  131. package/dist/entropy/index.js +1 -1
  132. package/dist/execution-service.d.ts.map +1 -1
  133. package/dist/extension-bootstrap.d.ts.map +1 -1
  134. package/dist/extension-bootstrap.js +16 -16
  135. package/dist/extension.d.ts.map +1 -1
  136. package/dist/fabric-exec-tool.d.ts.map +1 -1
  137. package/dist/fabric-runtime-state.d.ts +2 -0
  138. package/dist/fabric-runtime-state.d.ts.map +1 -1
  139. package/dist/fabric-runtime-state.js +203 -124
  140. package/dist/fabric-runtime-state.js.map +2 -2
  141. package/dist/fabric-state.d.ts +26 -1
  142. package/dist/fabric-state.d.ts.map +1 -1
  143. package/dist/index.js +20 -16
  144. package/dist/index.js.map +1 -1
  145. package/dist/jev/client.js +2 -2
  146. package/dist/jev/observation.js +3 -3
  147. package/dist/jev.js +7 -7
  148. package/dist/protocol.d.ts +84 -0
  149. package/dist/protocol.d.ts.map +1 -1
  150. package/dist/protocol.js +5 -1
  151. package/dist/providers/agents-actions.d.ts.map +1 -1
  152. package/dist/providers/agents-provider.d.ts +3 -0
  153. package/dist/providers/agents-provider.d.ts.map +1 -1
  154. package/dist/providers/jev-provider.js +7 -7
  155. package/dist/residency/host.d.ts.map +1 -1
  156. package/dist/residency/host.js +13 -10
  157. package/dist/residency/pi-entry.js +13 -10
  158. package/dist/residency/pi-entry.js.map +1 -1
  159. package/dist/runtime/core-override-guest-types.js +2 -2
  160. package/dist/runtime/cpython-runtime.js +3 -3
  161. package/dist/runtime/exec-journal.js +3 -3
  162. package/dist/runtime/guest-types.d.ts +1 -1
  163. package/dist/runtime/guest-types.d.ts.map +1 -1
  164. package/dist/runtime/guest-types.js +1 -1
  165. package/dist/runtime/monty-runtime.js +6 -6
  166. package/dist/runtime/node-process-runtime.js +5 -5
  167. package/dist/runtime/quickjs-runtime.js +3 -3
  168. package/dist/runtime/typescript-kernel.js +11 -11
  169. package/dist/storage/retention.d.ts.map +1 -1
  170. package/dist/type-error-guidance.js +1 -1
  171. package/dist/ui/conversation-chrome.js +2 -2
  172. package/dist/ui/conversation.js +10 -10
  173. package/dist/ui/dashboard.d.ts.map +1 -1
  174. package/dist/ui/dashboard.js +14 -12
  175. package/dist/ui/dashboard.js.map +2 -2
  176. package/dist/ui/settings-sections-presentation.d.ts.map +1 -1
  177. package/dist/ui/settings.js +12 -9
  178. package/dist/ui/settings.js.map +2 -2
  179. package/dist/ui/widget.d.ts.map +1 -1
  180. package/dist/verified/generated/actor-name.d.ts +4 -0
  181. package/dist/verified/generated/actor-name.js +17 -0
  182. package/dist/verified/generated/manifest.json +11 -3
  183. package/dist/worker/options.d.ts.map +1 -1
  184. package/dist/worker/options.js +20 -0
  185. package/dist/worker/options.js.map +2 -2
  186. package/dist/worker.js +57 -8
  187. package/dist/worker.js.map +2 -2
  188. package/docs/actor-name-policy-handoff.md +5 -0
  189. package/docs/agents.md +64 -5
  190. package/docs/audit-trace.md +2 -1
  191. package/docs/components.md +1 -1
  192. package/docs/configuration.md +7 -4
  193. package/docs/decisions.md +47 -2
  194. package/docs/durable-pi.md +162 -2
  195. package/docs/interface.md +1 -1
  196. package/docs/providers.md +1 -1
  197. package/docs/verified-kernels.md +1 -0
  198. package/package.json +5 -1
  199. package/proofs/actor-name.ts +27 -0
  200. package/proofs/index.ts +2 -0
  201. package/scripts/verified-kernels.ts +1 -1
  202. package/skillsets/python/fabric-exec/references/agents.md +6 -4
  203. package/skillsets/typescript/fabric-exec/references/agents.md +6 -3
  204. package/dist/chunks/chunk-6C2DMTQC.js.map +0 -7
  205. package/dist/chunks/chunk-JJXUOXI5.js.map +0 -7
  206. package/dist/chunks/chunk-K3ZWBUUL.js.map +0 -7
  207. package/dist/chunks/chunk-KJZAOENY.js +0 -212
  208. package/dist/chunks/chunk-KJZAOENY.js.map +0 -7
  209. package/dist/chunks/chunk-NF6W327N.js.map +0 -7
  210. package/dist/chunks/chunk-OA5SJT2T.js.map +0 -7
  211. package/dist/chunks/chunk-TBB7F7WS.js.map +0 -7
  212. package/dist/chunks/chunk-WQFG7ZVC.js.map +0 -7
  213. package/dist/chunks/chunk-ZLNJDTCN.js +0 -226
  214. package/dist/chunks/chunk-ZLNJDTCN.js.map +0 -7
  215. /package/dist/chunks/{chunk-6O6UWMBO.js.map → chunk-36XQFTEN.js.map} +0 -0
  216. /package/dist/chunks/{chunk-EYHTTMSM.js.map → chunk-4PBW54I2.js.map} +0 -0
  217. /package/dist/chunks/{chunk-WTIF3MIM.js.map → chunk-56NMRVTV.js.map} +0 -0
  218. /package/dist/chunks/{chunk-KDX3762L.js.map → chunk-DGERP4VL.js.map} +0 -0
  219. /package/dist/chunks/{chunk-UXIBKMUM.js.map → chunk-KIFOEBYJ.js.map} +0 -0
  220. /package/dist/chunks/{chunk-D5224P2R.js.map → chunk-LKYLD5SN.js.map} +0 -0
  221. /package/dist/chunks/{chunk-YTYLKL3Z.js.map → chunk-OJ4HAALD.js.map} +0 -0
  222. /package/dist/chunks/{chunk-CH2QMORW.js.map → chunk-UFMYN5TA.js.map} +0 -0
  223. /package/dist/chunks/{chunk-HAHRJMWY.js.map → chunk-WWTGWGH7.js.map} +0 -0
  224. /package/dist/chunks/{chunk-F4HL6KJR.js.map → chunk-X7QETPBC.js.map} +0 -0
  225. /package/dist/chunks/{chunk-SSRSCT2M.js.map → chunk-XFOSUGLU.js.map} +0 -0
@@ -0,0 +1,27 @@
1
+ // A decision over one host-supplied snapshot, not a name reservation.
2
+ import { bool, fun } from "gdp-wired";
3
+ import type { Kernel } from "./kernel.js";
4
+
5
+ type ActorNameBug = "stopped overrides active" | "admit stopped-only" | "refuse absent";
6
+ const decision = (bug?: ActorNameBug) => fun("actor name decision")
7
+ .inputs({ hasActive: bool, hasStopped: bool })
8
+ .returns(({ hasActive, hasStopped }) => ({
9
+ active: bug === "stopped overrides active" ? hasActive.and(hasStopped.not()) : hasActive,
10
+ stopped: bug === "stopped overrides active" ? hasStopped
11
+ : bug === "admit stopped-only" ? hasActive.and(hasActive.not())
12
+ : bug === "refuse absent" ? hasActive.not()
13
+ : hasActive.not().and(hasStopped),
14
+ available: bug === "admit stopped-only" ? hasActive.not()
15
+ : bug === "refuse absent" ? hasActive.and(hasActive.not())
16
+ : hasActive.not().and(hasStopped.not()),
17
+ }));
18
+
19
+ export const actorNameKernels = (bug?: ActorNameBug): Kernel[] => {
20
+ const f = decision(bug);
21
+ return [{ id: "actorName", fun: f, decisions: [
22
+ f.law("active dominates even when stopped exists", ({ hasActive }) => hasActive, (o) => o.active.and(o.stopped.not(), o.available.not())),
23
+ f.law("stopped is refused when no active exists", ({ hasActive, hasStopped }) => hasActive.not().and(hasStopped), (o) => o.stopped.and(o.active.not(), o.available.not())),
24
+ f.law("neither exists means available", ({ hasActive, hasStopped }) => hasActive.not().and(hasStopped.not()), (o) => o.available.and(o.active.not(), o.stopped.not())),
25
+ ] }];
26
+ };
27
+ export const ACTOR_NAME_BUGS: ActorNameBug[] = ["stopped overrides active", "admit stopped-only", "refuse absent"];
package/proofs/index.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  // The registered kernels. Each module is proved, refused in every broken
2
2
  // variant, cross-checked against its builders, and compiled to
3
3
  // `src/verified/generated/<module>.js`.
4
+ import { actorNameKernels, ACTOR_NAME_BUGS } from "./actor-name.js";
4
5
  import { authorityKernels, AUTHORITY_BUGS } from "./authority.js";
5
6
  import { compactionKernels, CUT_BUGS } from "./compaction.js";
6
7
  import { budgetKernels, BUDGET_BUGS } from "./budget.js";
@@ -34,5 +35,6 @@ export const modules: readonly KernelModule[] = [
34
35
  { stem: "authority", source: "proofs/authority.ts", kernels: authorityKernels as any, bugs: AUTHORITY_BUGS },
35
36
  { stem: "grants", source: "proofs/grants.ts", kernels: grantKernels as any, bugs: GRANT_BUGS },
36
37
  { stem: "speculation", source: "proofs/speculation.ts", kernels: speculationKernels as any, bugs: SPECULATION_BUGS },
38
+ { stem: "actor-name", source: "proofs/actor-name.ts", kernels: actorNameKernels as any, bugs: ACTOR_NAME_BUGS },
37
39
  { stem: "budget", source: "proofs/budget.ts", kernels: budgetKernels as any, bugs: BUDGET_BUGS },
38
40
  ];
@@ -13,7 +13,7 @@ const root = fileURLToPath(new URL("../", import.meta.url));
13
13
  const read = (path: string): string => readFileSync(resolve(root, path), "utf8");
14
14
  const hash = (text: string): string => createHash("sha256").update(text).digest("hex");
15
15
  const receipt = "src/verified/generated/manifest.json";
16
- const stems = ["policy", "compaction", "resources", "lifecycle", "storage", "provider", "authority", "grants", "speculation", "budget"];
16
+ const stems = ["policy", "compaction", "resources", "lifecycle", "storage", "provider", "authority", "grants", "speculation", "budget", "actor-name"];
17
17
  const sources = ["proofs/index.ts", "proofs/kernel.ts", ...stems.map((stem) => `proofs/${stem}.ts`), "scripts/verified-kernels.ts", "scripts/verified-kernel-pool.ts", "scripts/verified-kernel-worker.ts"];
18
18
  const artifacts = stems.flatMap((stem) => [`src/verified/generated/${stem}.js`, `src/verified/generated/${stem}.d.ts`]);
19
19
  const pinned = (): string => {
@@ -13,13 +13,15 @@ result = await agents.run(name="security-review", task="Review the current diff
13
13
  return {"status": result["status"], "text": result["text"], "error": result.get("error")}
14
14
  ```
15
15
 
16
- Request fields include task, agent, name, runner, kernel, transport, model, persona, thinking, thinkingBounds, tools, timeoutMs, extensions, recursive, cwd, worktree, worktreeSetup, seed, seedMessages, readOnly, writableRoots, shell, scope, schema, systemPrompt. Omit timeoutMs normally; per-call values below the configured agent timeout floor are ignored. Use top-level agentBudget for bounded calls; the Python guest has no callback-helper tokenBudget API. Host concurrency and settled-usage checks still apply.
16
+ Request fields include task, agent, name, runner, kernel, transport, model, modelMatch, persona, thinking, thinkingBounds, tools, timeoutMs, extensions, recursive, cwd, worktree, worktreeSetup, seed, seedMessages, readOnly, writableRoots, shell, scope, schema, systemPrompt, skills, plus spawn-only residency and queue. Omit timeoutMs normally; per-call values below the configured agent timeout floor are ignored. Use top-level agentBudget for bounded calls; the Python guest has no callback-helper tokenBudget API. Host concurrency and settled-usage checks still apply.
17
17
 
18
18
  - Pi children inherit Python and its configured backend, including recursive and alternate-cwd launches. Explicit child kernel selection changes only the child, never this invocation. Claude/Veda and extensions=False reject concrete Fabric kernels; omitted/inherit leaves their harness native. Do not hop interpreters to run this program.
19
19
  - `runner` defaults to configured policy; Pi, Claude, and Veda are available. Only Pi supports recursion. Veda persona/model follow its backend; Claude keys come from `await agents.models(runner="claude")`. Extensions may register more runner ids; requests needing an undeclared runner capability fail before launch. `outcome == "indeterminate"` means Fabric cannot confirm the work ran and never retries it; inspect before re-running.
20
+ - `modelMatch="exact"` (Pi runners only) selects a listed `provider/id` without aliases, closest or fuzzy matching, or alias thinking. Missing, malformed or unlisted models and non-Pi runners are refused before launch. Admission is strict, and a child guard detects session model switches and some rewrites of known API payloads. **This is not a security guarantee or final-dispatch enforcement:** later hooks, unknown API payloads, providers and extension-made calls can route data elsewhere. Attribution may detect drift only after a call; do not rely on this mode to prevent data disclosure. See `docs/agents.md`.
20
21
  - `systemPrompt` is appended to the child's system prompt (Veda gets it as a `<system_instructions>` block); blank is ignored and durable spawn refuses it.
21
- - `agent="name"` fills the request from a Markdown agent file (user `~/.pi/agent/agents`, project `.pi/agents`; project wins): body is `systemPrompt`, plus `model`, `tools`, `thinking` or `effort`, and `runtimes.fabric`. Fields on the call win; an unknown name fails before launch listing the names. `await agents.definitions()` lists them with `scope`, `shadows` and `warnings`.
22
- - Pi models must resolve in the owner's visible registry. `await tools.models()` lists Pi models; `agents.models` uses the requested or configured runner. Use canonical keys; report unresolved/ambiguous choices rather than guessing.
22
+ - `skills` picks the child's Pi skills by name from this session's skills: `False` gives none; `["writing"]` preloads those in full and keeps this session's others listed; `{"preload": ["writing"], "inherit": False}` keeps only the preloaded ones. Omitted keeps Pi's own discovery. An unknown name fails before launch and lists the names. Pi runners only; Claude, Veda and durable spawn refuse it.
23
+ - `agent="name"` fills the request from a Markdown agent file (user `~/.pi/agent/agents`, project `.pi/agents`; project wins): body is `systemPrompt`, plus `model`, `tools`, `thinking` or `effort`, `skills`, `context.skills`, and `runtimes.fabric`. Fields on the call win; an unknown name fails before launch listing the names. `await agents.definitions()` lists them with `scope`, `shadows` and `warnings`.
24
+ - Pi models must resolve in the owner's visible registry. `await tools.models()` lists Pi models; `agents.models` uses the requested or configured runner. Use canonical keys; report unresolved/ambiguous choices rather than guessing. To check one known key without reading the whole list, pass it as `model`: only entries whose `key` equals it exactly and case-sensitively are returned (no alias or fuzzy resolution, `[]` when absent), e.g. `known = await agents.models(runner="pi", model="provider/id")`.
23
25
  - `tools` is a native allowlist, inherited by nested calls for extension-enabled full-code Pi children. Claude maps supported core tools to its native names. `extensions=False` disables Fabric, not ordinary tools.
24
26
  - `cwd` is a real directory, relative to the caller or absolute; symlinks canonicalize. Invalid/non-directory paths fail without fallback. Recursive Pi requests accept cwd too (`agents.run(..., runner="pi", recursive=True, cwd="../other")`). Omission inherits the immediate caller’s effective directory. Project/mesh lineage and kernel/backend inheritance stay with the caller; cwd does not grant project trust, and Pi evaluates the actual target/worktree path under its own rules. Descendant tools are intersected with the inherited optional-tool allowlist, including durable transfer. Cwd is not filesystem isolation.
25
27
  - `worktree=True` creates a retained dedicated Git worktree in the selected repository. Verify canonical repository identity, never infer it from directory naming. Abort with zero changes on mismatch. Partition concurrent edit ownership; never edit shared files concurrently. Inspect and stop active work before cleanup; leave unrelated worktrees alone.
@@ -32,7 +34,7 @@ Request fields include task, agent, name, runner, kernel, transport, model, pers
32
34
 
33
35
  For a long workflow (many agents or beads) whose result you do not need before continuing, call `fabric_exec` with `background: true`: the call returns a task ID, the program keeps running, and its result arrives as a background task event. The user can then steer you while it runs. Do not start the same program again while it runs.
34
36
 
35
- `agents.spawn` returns a handle; `wait`, `status`, `stop`, and `cleanup` take its id. Unread detached results are batched after the current tool turn, or wake idle Main once; concise UI notices appear immediately. `wait`/`join` and terminal `status` acknowledge results and retract pending notifications, even after completion. Running status and UI/list polling do not acknowledge them. Return the relevant outcome to Main from your program; prefer `wait` over status polling. Escape/error parks results until new input. `residency="durable"` is a spawn-only opt-in to outlive Main, requiring trusted mesh and no Schema enforce; unread deliveries and acknowledgments survive reconnects.
37
+ `agents.spawn` returns a handle; `wait`, `status`, `stop`, and `cleanup` take its id. Unread detached results are batched after the current tool turn, or wake idle Main once; concise UI notices appear immediately. `wait`/`join` and terminal `status` acknowledge results and retract pending notifications, even after completion. Running status and UI/list polling do not acknowledge them. Return the relevant outcome to Main from your program; prefer `wait` over status polling. Escape/error parks results until new input. `residency="durable"` is a spawn-only opt-in to outlive Main, requiring trusted mesh and no Schema enforce; unread deliveries and acknowledgments survive reconnects. `spawn` waits inside the call for a free `agents.maxConcurrent` slot; `queue=True` returns at once with `status: "queued"`, and the run starts when a slot frees, even after the program ends. `wait`, `status` and `list` accept the id meanwhile, and `stop` cancels it without launching. Not with `residency="durable"`.
36
38
 
37
39
  ```python
38
40
  handle = await agents.spawn(task="Map the persistence layer.", tools=["read", "grep", "find", "ls"])
@@ -10,10 +10,11 @@ Every method takes a single options object.
10
10
 
11
11
  - `agents.run(args)` runs to completion and returns `FabricAgentResult` with `{ id, runner, kernel?, status, text, value?, error?, usage, turns, toolCalls, runnerSessionId? }`.
12
12
  - `agents.spawn(args)` returns a background `FabricAgentHandle` with an `id`. Then use `agents.wait({ id })`, `agents.status({ id })`, `agents.stop({ id })`.
13
+ - `spawn` waits inside the call for a free `agents.maxConcurrent` slot. `queue: true` returns at once with `status: "queued"`; the run starts when a slot frees, even after the program ends. `wait`, `status` and `list` accept the id meanwhile, and `stop` cancels it without launching. Use it to spawn more children than the limit under a program deadline. Not with `residency: "durable"`.
13
14
  - `agents.list({ scope? })` returns agent participants. `scope` defaults to `"local"`; use `"lineage"` for every agent under the same root across recursive runtimes, or `"project"` for all live project agents. Local entries retain full run detail; remote entries are bounded participant summaries.
14
15
  - `agents.cleanup({ id, deleteBranch? })` returns `{ cleaned }` and removes a worktree branch.
15
16
 
16
- `args` is a `FabricAgentRequest`: `{ task, agent?, name?, runner?, kernel?, transport?, model?, persona?, thinking?, thinkingBounds?, tools?, timeoutMs?, extensions?, recursive?, cwd?, worktree?, worktreeSetup?, seed?, seedMessages?, readOnly?, writableRoots?, shell?, scope?, schema?, systemPrompt? }`. `cwd` is a filesystem path only: absolute values are accepted, relative values resolve from the parent manager cwd, and Fabric reports the canonical directory after resolving symlinks. Invalid or non-directory targets fail without falling back. `persona` selects a Veda persona for that invocation and is rejected for Pi/Claude runners.
17
+ `args` is a `FabricAgentRequest`: `{ task, agent?, name?, runner?, kernel?, transport?, model?, modelMatch?, persona?, thinking?, thinkingBounds?, tools?, timeoutMs?, extensions?, recursive?, cwd?, worktree?, worktreeSetup?, seed?, seedMessages?, readOnly?, writableRoots?, shell?, scope?, schema?, systemPrompt?, skills? }`, plus spawn-only `residency?` and `queue?`. `cwd` is a filesystem path only: absolute values are accepted, relative values resolve from the parent manager cwd, and Fabric reports the canonical directory after resolving symlinks. Invalid or non-directory targets fail without falling back. `persona` selects a Veda persona for that invocation and is rejected for Pi/Claude runners.
17
18
 
18
19
  For Pi leaf or recursive agents, selecting `cwd` neither grants nor requires project trust. Fabric adds no trust gate and passes neither `--approve` nor `--no-approve`; Pi loads `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` under its normal rules, while protected project resources follow Pi's saved decisions and `defaultProjectTrust`. Other runners retain their native startup behavior. Generated worktree paths are evaluated at their own canonical paths.
19
20
 
@@ -21,9 +22,11 @@ For Pi leaf or recursive agents, selecting `cwd` neither grants nor requires pro
21
22
  - `kernel` is `"typescript"`, `"python"`, or `"inherit"`. Omitted/`inherit` takes the caller's `executor.kernel`; a concrete value lets the model or skill choose its strongest language for the **child**. It never switches the current `fabric_exec` program. Concrete values require Pi with Fabric extensions; Claude/Veda/`extensions: false` reject them, while omitted/`inherit` leaves those runners native with no `kernel` in status. Supported handles/results/status expose the resolved language. Workflow, RLM, and council requests forward `kernel` too. Python uses the caller's configured `executor.pythonRuntime` backend (`monty` by default); there is no public per-request backend selector. Monty is sandboxed and fails closed if its optional dependency is missing. CPython requires explicit configuration and outside schema enforce is trusted native code, not QuickJS isolation.
22
23
  - The caller's resolved language and configured Python backend are frozen before worker launch or durable/trajectory transfer. Recursive and alternate-cwd children inherit them through validated worker environment overrides after config merge, not the destination cwd's language defaults. Explicit kernels and inherited Python ensure Fabric is loaded even outside full-code mode. See [execution kernels](../../../../docs/kernels.md).
23
24
  - `transport` is one of `auto`, `process`, `tmux`, `screen`, `localterm`, `herdr` (default `process`). `auto` tries Herdr when the parent runs inside a Herdr workspace, then LocalTerm, tmux, screen, and process.
24
- - Pi `model` values resolve only within the execution owner's visible `tools.models()` / `agents.models({ runner: "pi" })` set; omitted uses `agents.model` or inherits the host model. Explicit values go through the `agents.switchModel` selector resolution: `models.aliases` names, exact matches, then the closest fuzzy match (pi-model-sort recency ties break toward the recently used model). Unresolved values and exhausted aliases fail before launch, and actor defaults or per-activation overrides are revalidated at their actual owner. Catalog-fresh or custom ids must first be visible in that registry. Claude values are `claude/<value>` keys from `agents.models({ runner: "claude" })`; omitted uses `agents.claude.model` or Claude Code's runtime default. Veda model strings continue to pass through to its backend unchanged. `agents.models()` defaults to the configured runner; Claude discovery is a local CLI control handshake and makes no model inference request.
25
+ - Pi `model` values resolve only within the execution owner's visible `tools.models()` / `agents.models({ runner: "pi" })` set; omitted uses `agents.model` or inherits the host model. Explicit values go through the `agents.switchModel` selector resolution: `models.aliases` names, exact matches, then the closest fuzzy match (pi-model-sort recency ties break toward the recently used model). Unresolved values and exhausted aliases fail before launch, and actor defaults or per-activation overrides are revalidated at their actual owner. Catalog-fresh or custom ids must first be visible in that registry. Claude values are `claude/<value>` keys from `agents.models({ runner: "claude" })`; omitted uses `agents.claude.model` or Claude Code's runtime default. Veda model strings continue to pass through to its backend unchanged. `agents.models()` defaults to the configured runner; `agents.models({ runner, model })` returns only the entries whose `key` equals `model` exactly (no alias or fuzzy resolution, `[]` when absent); Claude discovery is a local CLI control handshake and makes no model inference request.
26
+ - `modelMatch: "exact"` (Pi runners only) selects a listed `provider/id` without aliases, closest or fuzzy matching, or alias thinking. Missing, malformed or unlisted models and non-Pi runners are refused before launch; `handoff`, `create`, and actor activations do not accept it. Admission is strict, and a child guard detects session model switches and some rewrites of known API payloads. **This is not a security guarantee or final-dispatch enforcement:** later hooks, unknown API payloads, providers and extension-made calls can route data elsewhere. Attribution may detect drift only after a call; do not rely on this mode to prevent data disclosure. See `docs/agents.md`. Omit `modelMatch` for default resolution.
25
27
  - `systemPrompt` is appended to the child's system prompt (Veda gets it as a `<system_instructions>` block); blank is ignored and durable `spawn` refuses it.
26
- - `agent: "name"` fills the request from a Markdown agent file (user `~/.pi/agent/agents`, project `.pi/agents`; project wins): body is `systemPrompt`, plus `model`, `tools`, `thinking` or `effort`, and `runtimes.fabric`. Fields on the call win; an unknown name fails before launch listing the names. `await agents.definitions()` lists them with `scope`, `shadows` and `warnings`.
28
+ - `skills` picks the child's Pi skills by name from this session's skills: `false` gives none; `["writing"]` preloads those in full and keeps this session's others listed; `{ preload: ["writing"], inherit: false }` keeps only the preloaded ones. Omitted keeps Pi's own discovery. An unknown name fails before launch and lists the names. Pi runners only; Claude, Veda and durable `spawn` refuse it.
29
+ - `agent: "name"` fills the request from a Markdown agent file (user `~/.pi/agent/agents`, project `.pi/agents`; project wins): body is `systemPrompt`, plus `model`, `tools`, `thinking` or `effort`, `skills`, `context.skills`, and `runtimes.fabric`. Fields on the call win; an unknown name fails before launch listing the names. `await agents.definitions()` lists them with `scope`, `shadows` and `warnings`.
27
30
  - `thinking` is the reasoning effort (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`); defaults to `agents.thinking` (`medium`) and is clamped to the model's supported levels (next highest when unsupported). With `thinking.bounds` configured it is first clamped into the child's bounds and the handle reports the original as `requestedThinking`. `thinkingBounds: {min?, max?}` narrows the child's bounds; it must lie inside the caller's bounds or the call fails, and children never widen them.
28
31
  - Extension-enabled Pi children inherit the parent’s full-code mode, including non-recursive leaf runs: `fabric_exec` remains the required outer tool and the optional tool allowlist is enforced on nested Pi/captured-tool calls. `extensions: false` opts out, and a parent outside full-code mode keeps the native surface. Recursive runs additionally receive the delegated `agent` risk; ordinary leaf runs do not. Reload Fabric before launching children to pick up a changed launch policy.
29
32
  - `tools` defaults to `agents.defaultTools`. Claude maps `read→Read`, `grep→Grep`, `find/ls→Glob`, `bash→Bash`, `edit→Edit`, and `write→Write`; other tool names fail before launch.