repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(ultra): plan infinite step runtime

9a630f50b87f90f10fd0655e2ddf66f40527c332

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/plans/2026-07-13-ultra-infinite-step-runtime.md

Added
new file mode 100644
1 +# Ultra Infinite Step Runtime Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Remove every Ultra-owned step timeout while preserving explicit workflow cancellation.
7 +**Architecture:** Delete timeout fields at the workflow and settings boundaries, then replace the runner's timer race with an abort-only race. Keep phase sequencing and concurrency unchanged.
9 +**Tech Stack:** TypeScript, TypeBox, Vitest, Mise
11 +**Roadmap:** None
13 +**Phase:** Single-plan implementation
15 +---
17 +## Task 1: Remove Timeout Configuration
19 +**Files:**
21 +- Modify: `extensions/ultra/__tests__/settings.test.ts`
22 +- Modify: `extensions/ultra/__tests__/spec.test.ts`
23 +- Modify: `extensions/ultra/settings.ts`
24 +- Modify: `extensions/ultra/spec.ts`
25 +- Modify: `extensions/ultra/index.ts`
27 +- [ ] **Step 1: Write failing boundary tests**
29 +Remove `defaultTimeoutMs` from every expected settings object and input fixture in `settings.test.ts`.
30 +Add this parser test in `spec.test.ts`:
32 +```ts
33 +it("rejects removed step timeout fields", () => {
34 + const s = validSpec();
35 + s.phases[0].step.timeoutMs = 1000;
36 + expect(() => parseWorkflow(s)).toThrow(/timeoutMs/i);
37 +});
38 +```
40 +- [ ] **Step 2: Run tests and verify RED**
42 +Run:
44 +```text
45 +mise run test -- extensions/ultra/__tests__/settings.test.ts extensions/ultra/__tests__/spec.test.ts
46 +```
48 +Expected: failures because settings still expose `defaultTimeoutMs` and workflow steps still accept `timeoutMs`.
50 +- [ ] **Step 3: Delete timeout configuration**
52 +Delete `defaultTimeoutMs` from `UltraSettings`, `ULTRA_DEFAULTS`, `pickUltra`, and `mergeUltraSettings` in `settings.ts`.
53 +Delete `timeoutMs` from `StepSchema` and make that object reject unknown fields:
55 +```ts
56 +export const StepSchema = Type.Object(
57 + {
58 + prompt: Type.String(),
59 + tools: Type.Optional(Type.Array(Type.String())),
60 + model: Type.Optional(Type.String()),
61 + thinkingLevel: Type.Optional(ThinkingLevelSchema),
62 + schema: Type.Optional(StepSchemaRef),
63 + },
64 + { additionalProperties: false },
65 +);
66 +```
68 +Delete `defaultTimeoutMs: cfg.defaultTimeoutMs` from `buildStepRunner()` in `index.ts`.
70 +- [ ] **Step 4: Run tests and verify GREEN**
72 +Run the Task 1 test command again.
73 +Expected: both files pass.
75 +## Task 2: Replace Timer Races With Cancellation-Only Races
77 +**Files:**
79 +- Modify: `extensions/ultra/__tests__/runner.test.ts`
80 +- Modify: `extensions/ultra/runner.ts`
82 +- [ ] **Step 1: Write failing runner tests**
84 +Delete `defaultTimeoutMs` from `baseOpts()` and both `makeStepRunner()` fixtures.
85 +Replace each timeout test with a deferred completion test that waits past a short test-only delay, verifies the run remains pending, then resolves it successfully.
86 +Keep the existing mid-run and already-aborted tests, but remove their `defaultTimeoutMs` overrides.
87 +Update the fake-session `hang` comment to mention cancellation only.
89 +Use this deferred pattern for the tool-less path:
91 +```ts
92 +let finish!: (value: CompleteResponse) => void;
93 +const completeFn = vi.fn(
94 + () =>
95 + new Promise<CompleteResponse>((resolve) => {
96 + finish = resolve;
97 + }),
98 +);
99 +const pending = runStep(
100 + toollessStep,
101 + makeCtx(),
102 + makeDrivers({ completeFn }),
103 + baseOpts(),
105 +let settled = false;
106 +void pending.finally(() => {
107 + settled = true;
108 +});
109 +await new Promise((resolve) => setTimeout(resolve, 20));
110 +expect(settled).toBe(false);
111 +finish({ text: "{ \"verdict\": \"ok\" }" });
112 +await expect(pending).resolves.toEqual({ ok: true, value: { verdict: "ok" } });
113 +```
115 +Use this deferred pattern for the tool-using path:
117 +```ts
118 +let release!: () => void;
119 +const harness = makeSessionHarness({
120 + drive: async ({ emit, callStructured }) => {
121 + await new Promise<void>((resolve) => {
122 + release = resolve;
123 + });
124 + await callStructured({ verdict: "ok" });
125 + emit({ type: "agent_end", messages: [], willRetry: false });
126 + },
127 +});
128 +const pending = runStep(
129 + toolStep,
130 + makeCtx(),
131 + makeDrivers({ sessionFactory: harness.factory }),
132 + baseOpts(),
134 +let settled = false;
135 +void pending.finally(() => {
136 + settled = true;
137 +});
138 +await new Promise((resolve) => setTimeout(resolve, 20));
139 +expect(settled).toBe(false);
140 +release();
141 +await expect(pending).resolves.toEqual({ ok: true, value: { verdict: "ok" } });
142 +```
144 +- [ ] **Step 2: Run runner tests and verify RED**
146 +Run:
148 +```text
149 +mise run test -- extensions/ultra/__tests__/runner.test.ts
150 +```
152 +Expected: deferred runs settle as `timeout` because the old runtime receives no default timeout and schedules an immediate timer.
154 +- [ ] **Step 3: Implement abort-only execution**
156 +Delete `defaultTimeoutMs` from `BaseStepOptions`.
157 +Replace `GuardOutcome` and `raceGuards()` with an abort-only outcome and helper:
159 +```ts
160 +type GuardOutcome<T> =
161 + | { outcome: "done"; value: T; error?: unknown }
162 + | { outcome: "aborted" };
164 +async function raceAbort<T>(
165 + work: (signal: AbortSignal | undefined) => Promise<T>,
166 + externalSignal: AbortSignal | undefined,
167 +): Promise<GuardOutcome<T>> {
168 + if (externalSignal?.aborted) return { outcome: "aborted" };
170 + const workP = work(externalSignal).then(
171 + (value) => ({ outcome: "done", value }) as GuardOutcome<T>,
172 + (error) =>
173 + ({ outcome: "done", value: undefined as T, error }) as GuardOutcome<T>,
174 + );
175 + if (!externalSignal) return workP;
177 + let onAbort!: () => void;
178 + const aborted = new Promise<GuardOutcome<T>>((resolve) => {
179 + onAbort = () => resolve({ outcome: "aborted" });
180 + externalSignal.addEventListener("abort", onAbort, { once: true });
181 + });
182 + try {
183 + return await Promise.race([workP, aborted]);
184 + } finally {
185 + externalSignal.removeEventListener("abort", onAbort);
188 +```
190 +Delete timeout resolution and parameters throughout `runStep()`, `runCompleteStep()`, `CompleteAttemptInput`, `completeAttempt()`, and `runToolStep()`.
191 +Use `raceAbort(..., opts.signal)` in both execution paths.
192 +Delete the timeout outcome branch and retain the aborted branch.
193 +Keep `live.abort()` when a tool session returns the aborted outcome.
194 +Update timeout-specific runner comments.
196 +- [ ] **Step 4: Run runner tests and verify GREEN**
198 +Run the Task 2 test command again.
199 +Expected: all runner tests pass.
201 +## Task 3: Remove Timeout Vocabulary And Documentation
203 +**Files:**
205 +- Modify: `extensions/ultra/progress.ts`
206 +- Modify: `extensions/ultra/__tests__/progress.test.ts`
207 +- Modify: `extensions/ultra/__tests__/ui.test.ts`
208 +- Modify: `extensions/ultra/__tests__/wire.test.ts`
209 +- Modify: `extensions/ultra/README.md`
210 +- Modify: `extensions/ultra/skills/authoring-workflows/references/spec-format.md`
212 +- [ ] **Step 1: Remove timeout-only fixtures and tokens**
214 +Delete `"timeout"` from the progress reducer's dropped-status set.
215 +Change timeout fixture statuses and reasons in progress, UI, and wire tests to `"dropped"` or a provider failure reason while retaining their assertions about dropped rendering and result formatting.
216 +Delete the `ultra.defaultTimeoutMs` settings row from `README.md`.
217 +Delete the `timeoutMs` step row from `spec-format.md`.
219 +- [ ] **Step 2: Prove no timeout machinery remains**
221 +Run:
223 +```text
224 +rg -n 'defaultTimeoutMs|timeoutMs|reason: "timeout"|status: "timeout"|outcome: "timeout"' extensions/ultra
225 +```
227 +Expected: no output and exit code 1.
229 +- [ ] **Step 3: Run Ultra checks**
231 +Run:
233 +```text
234 +mise run test -- extensions/ultra
235 +mise run lint
236 +mise run check
237 +```
239 +Expected: all tests, formatting, lint, typecheck, skill checks, and static extension checks pass.
241 +- [ ] **Step 4: Commit the implementation**
243 +```text
244 +git add extensions/ultra
245 +git commit -m "fix(ultra): remove subagent timeouts"
246 +```
248 +Stage only `extensions/ultra`; preserve unrelated dirty work.