repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

refactor(ultra): reduce workflow context and configure fanout tools

af191ea269305885aa1fd49ba3758efe070710c2

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (13)

extensions/ultra/README.md

Modified
146 146 | `ultra.concurrency` | `5` | Max concurrent sub-agents in a `fanout` phase. |
147 147 | `ultra.maxRetries` | `2` | Result-submission reminders after a missing output. |
148 148 | `ultra.subagentExtensions` | `"all"` | Load all, none, or a static extension-name list. |
149 +| `ultra.fanoutToolAllowlist` | core tools | Additional initial tool names allowed in fanout without `writeIsolation`. |
149 150 | `ultra.subagentSkills` | `"all"` | Load host skills into sub-agents, or not. |
150 151 | `ultra.subagentSessionRetention` | `"all"` | Retain parent-linked child sessions; `"none"` is stateless. |
151 152 | `ultra.modelTiers` | built-in tiers | Named model, thinking, and orchestration guidance tiers. |
237 238 Unknown names fail workflow startup.
238 239 A step's `tools` array selects its initial active tools; loaded extensions may register and activate additional tools through their hooks.
239 240 Extension selection is therefore the trust boundary, including for fanout mutation safety.
241 +`ultra.fanoutToolAllowlist` adds names to the default `read`, `grep`, `find`, `ls`, and `bash` list across global and trusted project settings.
242 +For example, `"fanoutToolAllowlist": ["web"]` permits `web` as an initial tool without `writeIsolation`; it does not make `web` available to children or prove the tool cannot write.
243 +Ultra advertises the effective list in the orchestrator's system policy while `run_workflow` is active.
244 +Tools outside that list require a genuine disjoint-ownership declaration in `writeIsolation`; the declaration is not a sandbox.
240 245 Ultra strips its own `run_workflow` tool from the initial set to prevent ordinary recursive orchestration.
241 246 Steps may additionally name validated catalog identities through `dynamicExtensions`; those load after normal extensions from exact run-local hash snapshots.
242 247 Builder steps select all four dynamic-extension tools and receive the complete authoring contract, while consumers receive none of it.

extensions/ultra/__tests__/harness.test.ts

Modified
220 220 runner.emitBeforeAgentStart("prompt", undefined, {
221 221 cwd: t?.cwd ?? process.cwd(),
223 - const policy = async () =>
224 - (await emit()).systemPromptOptions.sections.ultra_model_tier_policy;
225 - expect(await policy()).toBeUndefined();
223 + const policy = async () => (await emit()).systemPromptOptions.sections;
224 + expect((await policy()).ultra_model_tier_policy).toBeUndefined();
225 + expect((await policy()).ultra_fanout_tool_policy).toBeUndefined();
226 226 const [extension] = runner.extensions;
227 227 await extension.commands
228 228 .get("ultra")
229 229 .handler("", runner.createCommandContext());
230 - expect(await policy()).toBe(modelTierPrompt(DEFAULT_MODEL_TIERS));
230 + expect((await policy()).ultra_model_tier_policy).toBe(
231 + modelTierPrompt(DEFAULT_MODEL_TIERS),
232 + );
233 + expect((await policy()).ultra_fanout_tool_policy).toContain(
234 + "read, grep, find, ls, bash",
235 + );
231 236 writeFileSync(
232 237 join(t.cwd, ".pi", "settings.json"),
233 238 JSON.stringify({
234 239 ultra: {
240 + fanoutToolAllowlist: ["web"],
235 241 modelTiers: {
236 242 large: { instructions: "Architecture only." },
237 243 fast_extract: {
246 252 const updated = await policy();
247 - expect(updated).toContain("Architecture only.");
248 - expect(updated).not.toContain(DEFAULT_MODEL_TIERS.large.instructions);
249 - expect(updated).toContain(
253 + expect(updated.ultra_model_tier_policy).toContain("Architecture only.");
254 + expect(updated.ultra_model_tier_policy).not.toContain(
255 + DEFAULT_MODEL_TIERS.large.instructions,
256 + );
257 + expect(updated.ultra_model_tier_policy).toContain(
250 258 "- fast_extract: custom/extractor; low; Select for literal extraction.",
252 - expect(updated?.match(/# ultra model tier policy/g)).toHaveLength(1);
260 + expect(
261 + updated.ultra_model_tier_policy?.match(/# ultra model tier policy/g),
262 + ).toHaveLength(1);
263 + expect(updated.ultra_fanout_tool_policy).toContain("bash, web");
253 264 writeFileSync(
254 265 join(t.cwd, ".pi", "settings.json"),
255 266 JSON.stringify({ ultra: { enabled: false } }),
257 - expect(await policy()).toBeUndefined();
268 + expect((await policy()).ultra_model_tier_policy).toBeUndefined();
269 + expect((await policy()).ultra_fanout_tool_policy).toBeUndefined();
260 272 it("rejects unknown tiers before either surface starts work", async () => {

extensions/ultra/__tests__/prompt.test.ts

Modified
5 5 import { describe, expect, it } from "vitest";
6 6 import { VALIDATOR_CONTRACT_VERSION } from "../dynamic-contract.ts";
7 7 import { resolveSelector, resolveTemplate } from "../interp.ts";
8 +import { DEFAULT_FANOUT_TOOLS } from "../settings.ts";
8 9 import {
9 10 compileSchema,
10 11 DYNAMIC_EXTENSION_TOOL_NAMES,
120 121 const reference = fs.readFileSync(SPEC_FORMAT_PATH, "utf8");
121 122 const schema = JSON.stringify(WorkflowSpecSchema);
122 123 for (const term of [
123 - "exact key in top-level schemas",
124 124 "{PHASE.results[].FIELD}",
125 125 "{PHASE.results[].FIELD[]}",
126 - '{EXPR | where FIELD == \\"VALUE\\"}',
126 + '{EXPR | where FIELD == "VALUE"}',
127 127 "{EXPR | groupBy FIELD}",
128 - "single brace-wrapped selector",
129 - "Every listed tool must be available",
130 - "Loaded extensions may activate additional tools",
131 - "read, grep, find, ls, and bash",
132 - "forbid mutation",
128 + "single-selector grammar",
129 + "every listed tool must be available",
130 + "loaded extensions remain trusted to activate additional tools",
131 + "prompt must instruct the agent not to mutate anything",
134 - expect(schema).toContain(term);
133 + expect(reference).toContain(term);
134 + for (const tool of DEFAULT_FANOUT_TOOLS)
135 + expect(reference).toContain(`\`${tool}\``);
136 + expect(reference).toContain("ultra.fanoutToolAllowlist");
137 + expect(schema).toContain('"required":["id","kind","step"]');
138 + expect(schema).toContain('"required":["id","kind","over","step"]');
135 139 for (const tool of DYNAMIC_EXTENSION_TOOL_NAMES) {
136 140 expect(prompt).toContain(tool);
137 141 expect(reference).toContain(tool);

extensions/ultra/__tests__/settings.test.ts

Modified
1 1 import { describe, expect, it } from "vitest";
2 2 import {
3 + DEFAULT_FANOUT_TOOLS,
3 4 DEFAULT_MODEL_TIERS,
4 5 effectiveModelTiers,
6 + fanoutToolPolicyPrompt,
5 7 loadUltraSettings,
6 8 mergeUltraSettings,
7 9 modelTierPrompt,
17 19 concurrency: 5,
18 20 maxRetries: 2,
19 21 subagentExtensions: "all",
22 + fanoutToolAllowlist: DEFAULT_FANOUT_TOOLS,
20 23 subagentSkills: "all",
21 24 subagentSessionRetention: "all",
22 25 modelTiers: DEFAULT_MODEL_TIERS,
52 +describe("fanoutToolAllowlist setting", () => {
53 + it("adds names from global and project settings without replacing defaults", () => {
54 + const settings = loadUltraSettings({
55 + global: { ultra: { fanoutToolAllowlist: ["web", "web"] } },
56 + project: { ultra: { fanoutToolAllowlist: ["search", "web"] } },
57 + });
58 + expect(settings.fanoutToolAllowlist).toEqual([
59 + ...DEFAULT_FANOUT_TOOLS,
60 + "web",
61 + "search",
62 + ]);
63 + expect(fanoutToolPolicyPrompt(settings.fanoutToolAllowlist)).toContain(
64 + "bash, web, search",
65 + );
66 + });
68 + it.each(["web", [""], [" web"], [4], ["web", null]])(
69 + "rejects invalid configured lists: %j",
70 + (value) => {
71 + expect(() =>
72 + loadUltraSettings({
73 + global: { ultra: { fanoutToolAllowlist: value } },
74 + }),
75 + ).toThrow(/ultra.fanoutToolAllowlist/);
76 + },
77 + );
78 +});
49 80 describe("subagentExtensions setting", () => {
50 81 it('defaults to "all"', () => {
51 82 expect(ULTRA_DEFAULTS.subagentExtensions).toBe("all");
226 257 const prompt = modelTierPrompt(tiers);
227 - expect(prompt).toContain(
228 - "tier: model; default thinkingLevel; orchestrator-only selection guidance.",
229 - );
230 258 for (const instruction of [
231 - "select by residual judgement; default to small; use tiny only when context determines the result.",
232 - "count unresolved decisions/dependencies and downstream consequence.",
233 - "decompose only when it reduces decisions, context, or error propagation more than handoff overhead.",
234 - "credit structured upstream judgement; verify when risk warrants.",
235 - "manage context windows: minimum sufficient context; progressive disclosure.",
236 - "choose least fitting tier; lower wins ties; add verification when one child is insufficient.",
237 - "ask user about missing decisions; encode missing child evidence/authority as a blocker; never guess with higher tier.",
259 + "Orchestrator only.",
260 + "default thinkingLevel",
261 + "Default small; tiny only for determined outcomes.",
262 + "Choose lowest adequate tier; lower wins ties.",
263 + "residual decisions, dependencies, ambiguity, and consequence",
264 + "credit upstream findings",
265 + "outweigh handoffs",
266 + "minimum sufficient context",
267 + "verify proportionately to risk",
268 + "Ask user for missing decisions",
269 + "missing child evidence or authority as blockers",
270 + "not reasons to escalate tiers",
239 272 expect(prompt).toContain(instruction);
481 514 concurrency: 9,
482 515 maxRetries: 4,
483 516 subagentExtensions: "all",
517 + fanoutToolAllowlist: DEFAULT_FANOUT_TOOLS,
484 518 subagentSkills: "all",
485 519 subagentSessionRetention: "all",
486 520 modelTiers: {
528 562 concurrency: 10,
529 563 maxRetries: 9,
530 564 subagentExtensions: "all",
565 + fanoutToolAllowlist: DEFAULT_FANOUT_TOOLS,
531 566 subagentSkills: "all",
532 567 subagentSessionRetention: "all",
533 568 modelTiers: {

extensions/ultra/__tests__/spec.test.ts

Modified
224 +describe("fanout initial tool policy", () => {
225 + const spec = () => ({
226 + name: "research",
227 + phases: [
229 + id: "shop",
230 + kind: "fanout",
231 + over: ["one", "two"],
232 + step: { summary: "Research", prompt: "Do not mutate.", tools: ["web"] },
233 + },
234 + ],
235 + });
237 + it("rejects names outside the default list without labeling them mutating", () => {
238 + expect(() => parseWorkflow(spec())).toThrow(
239 + /fanout phase "shop" selects tools outside the fanout allowlist without writeIsolation: web\. Allowed initial tools: read, grep, find, ls, bash/,
240 + );
241 + });
243 + it("accepts configured names but still rejects other unlisted names", () => {
244 + expect(() => parseWorkflow(spec(), ["read", "web"])).not.toThrow();
245 + const unlisted = spec();
246 + unlisted.phases[0].step.tools = ["web", "other"];
247 + expect(() => parseWorkflow(unlisted, ["read", "web"])).toThrow(
248 + /outside the fanout allowlist without writeIsolation: other/,
249 + );
250 + });
252 + it("accepts other names with genuine writeIsolation or in a single phase", () => {
253 + const isolated = {
254 + ...spec(),
255 + phases: [{ ...spec().phases[0], writeIsolation: "Separate owners." }],
256 + };
257 + expect(() => parseWorkflow(isolated)).not.toThrow();
258 + const single = {
259 + ...spec(),
260 + phases: [{ ...spec().phases[0], kind: "single" }],
261 + };
262 + expect(() => parseWorkflow(single)).not.toThrow();
263 + });
264 +});
224 266 describe("missingWorkflowTools", () => {
225 267 it("returns every distinct unavailable step tool in stable order", () => {
226 268 const spec = parseWorkflow(validSpec());

extensions/ultra/__tests__/wire.test.ts

Modified
1053 1053 expect(out.args).toEqual({ base: "dev" });
1056 + it("applies the same configured fanout policy to inline and saved specs", () => {
1057 + const raw = {
1058 + name: "research",
1059 + phases: [
1061 + id: "shop",
1062 + kind: "fanout",
1063 + over: ["one"],
1064 + step: { summary: "Search", prompt: "Do not mutate.", tools: ["web"] },
1065 + },
1066 + ],
1067 + };
1068 + const saved: DiscoveredWorkflow = {
1069 + name: raw.name,
1070 + source: "project",
1071 + path: "/project/research.json",
1072 + spec: raw as unknown as WorkflowSpec,
1073 + };
1074 + for (const input of [{ spec: raw }, { name: raw.name }]) {
1075 + expect(() => resolveWorkflowInput(input, [saved])).toThrow(
1076 + /outside the fanout allowlist/,
1077 + );
1078 + expect(() =>
1079 + resolveWorkflowInput(input, [saved], undefined, ["read", "web"]),
1080 + ).not.toThrow();
1082 + });
1056 1084 it("throws with the available names for an unknown name", () => {
1057 1085 expect(() => resolveWorkflowInput({ name: "missing" }, list)).toThrow(
1058 1086 /ultra-review|audit/,

extensions/ultra/implementation.ts

Modified
358 358 details: initialReducerState(),
361 - const { spec, args } = resolveWorkflowInput(params, discover(ctx.cwd));
361 + const { spec, args } = resolveWorkflowInput(
362 + params,
363 + discover(ctx.cwd),
364 + undefined,
365 + cfg.fanoutToolAllowlist,
366 + );
362 367 const extensions = resolveSubagentExtensions(cfg.subagentExtensions);
363 368 const error = workflowError(spec, extensions, cfg);
364 369 if (error) throw new Error(error);
446 451 { name: parsed.name, args: parsed.args },
447 452 discovered,
448 453 parsed.rest,
454 + cfg.fanoutToolAllowlist,
450 456 } catch (err) {
451 457 ctx.ui.notify(

extensions/ultra/index.ts

Modified
14 14 import { formatUltraResultMarkdown } from "./result.ts";
15 15 import {
16 16 effectiveModelTiers,
17 + fanoutToolPolicyPrompt,
17 18 loadUltraSettings,
18 19 modelTierPrompt,
19 20 } from "./settings.ts";
92 93 if (!settings.enabled) return;
93 94 event.systemPromptOptions.sections.ultra_model_tier_policy =
94 95 modelTierPrompt(effectiveModelTiers(settings, ctx.model?.provider));
96 + event.systemPromptOptions.sections.ultra_fanout_tool_policy =
97 + fanoutToolPolicyPrompt(settings.fanoutToolAllowlist);
97 100 pi.registerCommand("ultra", {

extensions/ultra/prompts/references/spec-format.md

Modified
7 7 ## machine-readable contract
9 -- the active `run_workflow` tool exposes the complete `WorkflowSpecSchema` for inline `spec` values.
10 -- that schema is the source for field names, requiredness, types, unions, and field descriptions.
11 -- `parseWorkflow()` remains the source for semantic checks and applies to saved and inline specs alike.
12 -- this reference avoids repeating the structural schema; it documents execution semantics, authoring rules, and valid examples.
9 +- [`spec.ts`](../../spec.ts) defines the `WorkflowSpecSchema` used by the active `run_workflow` tool and by `parseWorkflow()` for saved and inline specs.
10 +- that schema is the sole source for field names, requiredness, types, unions, and concise field hints; consult it for exact structure.
11 +- `parseWorkflow()` adds semantic checks; this reference documents execution semantics, authoring rules, and valid examples without maintaining a second schema.
14 13 - `args` may declare `params`, an ordered list of input names.
15 14 - `/ultra run <name> tokA tokB` maps tokens positionally; the last declared parameter absorbs remaining tokens as free text.
52 51 ### fan-out mutation ownership
54 -- without `writeIsolation`, a `fanout` step's initial tools must stay within Pi's core set: `read`, `grep`, `find`, `ls`, and `bash`.
53 +- without `writeIsolation`, a `fanout` step's initial tools must be in the effective `ultra fanout tool policy` system section (defaults: `read`, `grep`, `find`, `ls`, `bash`; `ultra.fanoutToolAllowlist` adds names).
55 54 - the prompt must instruct the agent not to mutate anything.
56 -- with `writeIsolation`, mutating tools are allowed; the non-empty rationale and prompt must assign disjoint ownership to every item.
57 -- Ultra trusts that declaration and does not constrain paths or arbitrary custom mutators.
55 +- other initial tools require `writeIsolation` with a genuine non-empty ownership rationale assigning disjoint work to every item; do not invent ownership just to pass validation.
56 +- the allowlist classifies tool names, not capabilities; Ultra trusts isolation declarations and does not sandbox paths or arbitrary custom mutators.
58 57 - loaded extensions remain trusted to activate additional tools.
59 58 - every listed tool must be available to sub-agents or Ultra refuses to start the workflow.

extensions/ultra/prompts/ultra-authoring/SKILL.md

Modified
60 60 all listed tools must be available to children or Ultra refuses to start.
61 61 loaded extensions may activate additional tools.
62 -without `writeIsolation`, a fanout step uses only `read`, `grep`, `find`, `ls`, and
63 -`bash`, and its prompt forbids mutation.
64 -with `writeIsolation`, the prompt assigns disjoint ownership to every fanout item.
62 +without `writeIsolation`, a fanout step may select only the initial tools listed in the current `ultra fanout tool policy` system section, and its prompt forbids mutation.
63 +other initial tools require `writeIsolation` with genuine disjoint ownership assigned to every fanout item; do not invent ownership to bypass validation.
65 64 every child returns one JSON object through `structured_output`.
67 66 ## use dynamic extensions

extensions/ultra/settings.ts

Modified
14 14 "max",
15 15 ] as const satisfies readonly Parameters<ExtensionAPI["setThinkingLevel"]>[0][];
17 +export const DEFAULT_FANOUT_TOOLS = ["read", "grep", "find", "ls", "bash"];
17 19 export interface ModelTier {
18 20 /** null selects the session model. */
19 21 model: string | null;
79 81 * default), none (`"none"`), or one static list of sibling pi-ext names.
80 82 * `step.tools` selects the initial tools; loaded extensions may change them. */
81 83 subagentExtensions: "none" | "all" | string[];
84 + /** Additional initial tools permitted in fanout without writeIsolation, merged with defaults. */
85 + fanoutToolAllowlist: string[];
82 86 /** Load host skills into sub-agents (`"all"`, default) or omit them (`"none"`). */
83 87 subagentSkills: "none" | "all";
84 88 /** Retain parent-linked sub-agent sessions, or run them entirely in memory. */
99 103 concurrency: 5,
100 104 maxRetries: 2,
101 105 subagentExtensions: "all",
106 + fanoutToolAllowlist: [...DEFAULT_FANOUT_TOOLS],
102 107 subagentSkills: "all",
103 108 subagentSessionRetention: "all",
104 109 modelTiers: DEFAULT_MODEL_TIERS,
178 183 return out;
186 +export function fanoutToolPolicyPrompt(allowed: readonly string[]): string {
187 + return `Fanout without writeIsolation: initial tools allowed: ${allowed.join(", ")}. Other initial tools require genuine disjoint ownership declared in writeIsolation. Without it, child prompts must forbid mutation. Tool availability is checked separately.`;
181 190 /** The sole tier rubric, rendered from the effective settings for each agent turn. */
182 191 export function modelTierPrompt(tiers: ModelTiers): string {
183 192 return [
184 193 "# ultra model tier policy",
185 - "tier: model; default thinkingLevel; orchestrator-only selection guidance.",
186 - "select by residual judgement; default to small; use tiny only when context determines the result.",
187 - "count unresolved decisions/dependencies and downstream consequence.",
188 - "decompose only when it reduces decisions, context, or error propagation more than handoff overhead.",
189 - "credit structured upstream judgement; verify when risk warrants.",
190 - "manage context windows: minimum sufficient context; progressive disclosure.",
191 - "choose least fitting tier; lower wins ties; add verification when one child is insufficient.",
192 - "ask user about missing decisions; encode missing child evidence/authority as a blocker; never guess with higher tier.",
194 + "Orchestrator only. Rows: tier: model; default thinkingLevel; selection guidance.",
195 + "Default small; tiny only for determined outcomes. Choose lowest adequate tier; lower wins ties.",
196 + "Judge residual decisions, dependencies, ambiguity, and consequence; credit upstream findings.",
197 + "Decompose only when reduced decisions, context, or error propagation outweigh handoffs.",
198 + "Use minimum sufficient context; verify proportionately to risk, adding a check when one child is insufficient.",
199 + "Ask user for missing decisions; report missing child evidence or authority as blockers, not reasons to escalate tiers.",
193 200 ...Object.entries(tiers).map(
194 201 ([name, tier]) =>
195 202 `- ${name}: ${tier.model ?? "session model"}; ${tier.thinkingLevel}; ${tier.instructions}`,
224 231 .filter(Boolean),
234 + if (ultra.fanoutToolAllowlist !== undefined) {
235 + if (
236 + !Array.isArray(ultra.fanoutToolAllowlist) ||
237 + ultra.fanoutToolAllowlist.some(
238 + (value) => typeof value !== "string" || !value || /\s/u.test(value),
241 + throw new Error(
242 + "ultra.fanoutToolAllowlist must be an array of non-empty tool names without whitespace.",
243 + );
244 + out.fanoutToolAllowlist = [...new Set(ultra.fanoutToolAllowlist)];
227 246 if (ultra.subagentSkills === "none" || ultra.subagentSkills === "all")
228 247 out.subagentSkills = ultra.subagentSkills;
302 321 : p.subagentExtensions === "none" || p.subagentExtensions === "all"
303 322 ? p.subagentExtensions
304 323 : into.subagentExtensions,
324 + fanoutToolAllowlist: [
325 + ...new Set([
326 + ...into.fanoutToolAllowlist,
327 + ...(p.fanoutToolAllowlist ?? []),
328 + ]),
329 + ],
305 330 subagentSkills:
306 331 p.subagentSkills === "none" || p.subagentSkills === "all"
307 332 ? p.subagentSkills

extensions/ultra/spec.ts

Modified
6 6 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
7 7 import { Type } from "typebox";
8 8 import { Compile } from "typebox/compile";
9 -import { THINKING_LEVELS } from "./settings.ts";
9 +import { DEFAULT_FANOUT_TOOLS, THINKING_LEVELS } from "./settings.ts";
11 11 // ---------------------------------------------------------------------------
12 12 // Schemas (TypeBox -> JSON Schema fragments)
13 13 // ---------------------------------------------------------------------------
15 -const INTERPOLATION_GRAMMAR =
16 - "Closed grammar: {args.NAME}, {item}, {PHASE.results}, {PHASE.failures}, " +
17 - '{PHASE.results[].FIELD}, {PHASE.results[].FIELD[]}, {EXPR | where FIELD}, {EXPR | where FIELD == "VALUE"}, or {EXPR | groupBy FIELD}.';
18 -const SELECTOR_GUIDANCE = `Use exactly one single brace-wrapped selector. ${INTERPOLATION_GRAMMAR}`;
20 15 export const DYNAMIC_EXTENSION_TOOL_NAMES = [
21 16 "search_dynamic_extensions",
22 17 "create_dynamic_extension",
24 19 "validate_dynamic_extension",
25 20 ] as const;
27 -const READ_ONLY_FANOUT_TOOLS = new Set(["read", "grep", "find", "ls", "bash"]);
29 22 /** Any object accepted as an inline JSON Schema (TypeBox-compatible). */
30 23 const JsonSchemaObject = Type.Object(
38 31 /** Full `ThinkingLevel` union. */
39 32 export const ThinkingLevelSchema = StringEnum(THINKING_LEVELS, {
40 - description:
41 - "Reasoning budget: off, minimal, low, medium, high, xhigh, or max. " +
42 - "Omit to use the configured tier default; explicit values override it. " +
43 - "max is the highest opt-in level and requires model support.",
33 + description: "Overrides the tier default; max requires model support.",
46 36 /** A step's `schema` is either a named reference (string) or an inline object. */
47 37 const StepSchemaRef = Type.Union(
49 39 Type.String({
50 - description:
51 - "A named output schema reference: use the exact key in top-level schemas, not a JSON Schema type or label.",
40 + description: "Key in top-level schemas.",
53 42 JsonSchemaObject,
56 - description:
57 - "Constrains the JSON object returned by this step. Use an exact named reference or an inline JSON Schema object.",
45 + description: "Named or inline output schema.",
63 51 summary: Type.String({
64 52 minLength: 1,
65 - description: `One short progress-UI sentence describing this sub-agent's task. May embed the same grammar tokens as prompt. Summary interpolation renders objects as short labels and arrays as counts; prompts retain compact JSON. ${INTERPOLATION_GRAMMAR}`,
53 + description: "Progress label; supports prompt interpolation.",
67 55 prompt: Type.String({
68 56 description:
69 - `Sub-agent instruction. May embed grammar tokens in text; {item} is meaningful only in fanout. ${INTERPOLATION_GRAMMAR} ` +
70 - "Do not use literal braces for any other purpose.",
57 + "Child assignment; use only supported interpolation tokens in braces.",
72 59 tools: Type.Optional(
73 60 Type.Array(Type.String(), {
74 61 description:
75 - "Sub-agent initial tool set. Every listed tool must be available or Ultra refuses to start. Loaded extensions may activate additional tools. Fanout without writeIsolation may initially select only read, grep, find, ls, and bash, and its prompt must forbid mutation; writeIsolation allows disjoint mutating work.",
62 + "Initial child tools; fanout without writeIsolation uses the ultra fanout tool policy allowlist.",
78 65 model: Type.Optional(
79 66 Type.String({
80 67 description:
81 - "Model provider/id or any configured tier name from the Ultra model tier policy. Set deliberately for every authored step; tiers supply model and default thinkingLevel.",
68 + "Provider/model or configured tier; omitted uses session model.",
84 71 thinkingLevel: Type.Optional(ThinkingLevelSchema),
90 77 "Stable dynamic-extension catalog names, loaded in declared order.",
92 79 Type.String({
93 - description: `${SELECTOR_GUIDANCE} The resolved value must be an array of stable catalog names.`,
80 + description: "One selector resolving to catalog names.",
105 92 additionalProperties: false,
106 - description:
107 - "One sub-agent invocation. Every step must return a JSON object; schema makes its output shape stable.",
93 + description: "One child returning a JSON object.",
115 101 description: "Literal items for one fanout agent per array element.",
117 103 Type.String({
118 - description: `${SELECTOR_GUIDANCE} Use args or prior phase results/failures; the resolved value must be an array.`,
104 + description: "One selector resolving to an array.",
127 113 const PhaseIdSchema = Type.String({
128 114 pattern: "^[A-Za-z_][A-Za-z0-9_]*$",
129 - description:
130 - "Unique interpolation identifier for this phase. The reserved identifier args is forbidden.",
115 + description: "Unique phase ID; args is reserved.",
133 118 const WhenSchema = Type.Optional(
134 119 Type.String({
135 - description: `${SELECTOR_GUIDANCE} Use args or prior phase results/failures; false, null, undefined, an empty string, or an empty array skips the phase.`,
120 + description: "One selector; false or empty skips the phase.",
138 123 const ConcurrencySchema = Type.Optional(
149 134 id: PhaseIdSchema,
150 135 kind: Type.Literal("single", {
151 - description:
152 - "Run one synthesis, judge, or writing step. Any over value is ignored.",
136 + description: "One child; over is ignored.",
154 138 when: WhenSchema,
155 139 over: Type.Optional(OverSchema),
164 148 id: PhaseIdSchema,
165 149 kind: Type.Literal("fanout", {
166 - description:
167 - "Run one sub-agent per over item; read-only unless writeIsolation declares disjoint mutation ownership.",
150 + description: "One child per over item; read-only without writeIsolation.",
169 152 when: WhenSchema,
170 153 over: OverSchema,
173 156 writeIsolation: Type.Optional(
174 157 Type.String({
175 158 minLength: 1,
176 - description:
177 - "Why each fanout item owns disjoint mutation work. Required when mutating tools are selected.",
159 + description: "Disjoint mutation ownership per item.",
182 - description:
183 - "A phase that invokes parallel sub-agents. It is read-only unless writeIsolation declares disjoint ownership.",
164 + description: "Parallel children; read-only unless ownership is declared.",
206 187 params: Type.Optional(
207 188 Type.Array(Type.String({ pattern: "^[A-Za-z_][A-Za-z0-9_]*$" }), {
208 189 description:
209 - "Ordered positional input names exposed as {args.NAME}; the last name absorbs remaining command text.",
190 + "Positional input names; last absorbs remaining command text.",
225 206 phases: Type.Array(PhaseSchema, {
226 207 minItems: 1,
227 - description:
228 - "Ordered phases. Prompts and selectors may reference only prior phases; return runs after all phases.",
208 + description: "Ordered phases; references target prior phases only.",
230 210 return: Type.Optional(
231 211 Type.String({
232 - description: `${SELECTOR_GUIDANCE} Use args or any completed phase results/failures; the selected value may have any type.`,
212 + description: "One selector for the returned value.",
235 215 report: Type.Optional(
236 216 Type.String({
237 - description: `${SELECTOR_GUIDANCE} Selects the report rendered for humans and included in the model-facing result; the selected value may have any type.`,
217 + description:
218 + "One selector for the human report, also returned to the model.",
242 223 description:
243 - "Inline declarative workflow spec. Follow every field description; malformed semantic references fail before agents run.",
224 + "Inline workflow. Read ultra-authoring before constructing a spec; invalid references fail before execution.",
298 279 * the workflow schema. THROWS (never returns) on invalid input, surfacing the
299 280 * underlying TypeBox error message. Returns the typed spec on success.
301 -export function parseWorkflow(json: unknown): WorkflowSpec {
282 +export function parseWorkflow(
283 + json: unknown,
284 + fanoutToolAllowlist: readonly string[] = DEFAULT_FANOUT_TOOLS,
285 +): WorkflowSpec {
302 286 let value: unknown = json;
303 287 if (typeof json === "string") {
354 338 if (phase.kind === "fanout" && phase.writeIsolation === undefined) {
355 - const mutating = [...tools].filter(
356 - (tool) => !READ_ONLY_FANOUT_TOOLS.has(tool),
357 - );
358 - if (mutating.length > 0) {
339 + const allowed = new Set(fanoutToolAllowlist);
340 + const outsideAllowlist = [...tools].filter((tool) => !allowed.has(tool));
341 + if (outsideAllowlist.length > 0) {
359 342 throw new Error(
360 - `Invalid workflow spec: fanout phase "${phase.id}" selects mutating tools without writeIsolation: ${mutating.join(", ")}.`,
343 + `Invalid workflow spec: fanout phase "${phase.id}" selects tools outside the fanout allowlist without writeIsolation: ${outsideAllowlist.join(", ")}. Allowed initial tools: ${fanoutToolAllowlist.join(", ")}. Use allowed tools, declare genuine disjoint ownership with writeIsolation, or configure ultra.fanoutToolAllowlist.`,

extensions/ultra/wire.ts

Modified
309 309 input: WorkflowInput,
310 310 discovered: readonly DiscoveredWorkflow[],
311 311 rest?: string,
312 + fanoutToolAllowlist?: readonly string[],
312 313 ): ResolvedWorkflow {
313 314 if (input.spec !== undefined) {
314 - return { spec: parseWorkflow(input.spec), args: input.args };
315 + return {
316 + spec: parseWorkflow(input.spec, fanoutToolAllowlist),
317 + args: input.args,
318 + };
316 320 if (input.name) {
317 321 const found = discovered.find((w) => w.name === input.name);
325 329 // malformed file still lists in the picker) — `/ultra run <name>` then fails
326 330 // fast with parseWorkflow's TypeBox path error instead of crashing the
327 331 // engine mid-run on a raw, unvalidated object.
328 - const spec = parseWorkflow(found.spec);
332 + const spec = parseWorkflow(found.spec, fanoutToolAllowlist);
329 333 let args = input.args;
330 334 // Positional fallback: a bare `/ultra run <name> <tok...>` line (no JSON args
331 335 // object) maps to the spec's declared `args.params` in order.