pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search fix(ultra): expose inline workflow schema
ccf9d13a6dcea4deb4b9e7fd590bdf5b86183e12
Oliver Jan Krylow <oliver@bugabinga.net > · 16 Jul 2026
unsigned
Browse files Compare with HEAD
Changed files (3) docs/super/plans/2026-07-17-ultra-tool-schema.md Added new file mode 100644 1 + #
Ultra Tool Schema 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:** Expose Ultra's real inline workflow schema to calling agents.
7 + **Architecture:** Reuse the exported runtime `WorkflowSpecSchema` directly in the registered tool contract. Keep `parseWorkflow` as runtime validation and lock the shared schema identity with a harness regression.
9 + **Tech Stack:** TypeScript, TypeBox, Vitest, Pi extension test harness
13 + **Phase:** Single-plan implementation
17 + ##
Task 1: Expose the workflow schema 21 + - Modify: `extensions/ultra/__tests__/harness.test.ts`
22 + - Modify: `extensions/ultra/index.ts`
24 + - [x] **Step 1: Write the failing harness test**
26 + Import `WorkflowSpecSchema`, retrieve the registered `workflow` tool, and compare the JSON-serializable registered `spec` property schema with `WorkflowSpecSchema`:
29 + const tool
= extension.tools.
get (
"workflow" )?.definition;
30 + expect (tool).
toBeDefined ();
31 + expect (
JSON .
parse (
JSON .
stringify (tool?.parameters.properties.spec))).
toEqual (
32 + JSON .
parse (
JSON .
stringify (WorkflowSpecSchema)),
36 + - [x] **Step 2: Run the test and verify RED**
38 + Run: `mise run test -- extensions/ultra/__tests__/harness.test.ts`
39 + Expected: FAIL because the registered `spec` schema is currently unrestricted.
41 + - [x] **Step 3: Reuse the runtime schema in the tool contract**
43 + Import `WorkflowSpecSchema` as a value from `spec.ts` and replace:
46 + spec : Type.
Optional (Type.
Unknown ()),
52 + spec : Type.
Optional (WorkflowSpecSchema),
55 + - [x] **Step 4: Run the focused test and verify GREEN**
57 + Run: `mise run test -- extensions/ultra/__tests__/harness.test.ts`
60 + - [x] **Step 5: Run verification**
65 + mise run test -- extensions/ultra
69 + Expected: both commands pass without warnings or errors.
71 + - [x] **Step 6: Commit**
74 + git add extensions/ultra/index.ts extensions/ultra/__tests__/harness.test.ts docs/super/plans/2026-07-17-ultra-tool-schema.md
75 + git commit -m "fix(ultra): expose inline workflow schema"
extensions/ultra/__tests__/harness.test.ts Modified 6 6 } from
"@marcfargas/pi-test-harness" ;
7 7 import { afterEach, describe, expect, it }
from "vitest" ;
8 + import { WorkflowSpecSchema }
from "../spec.ts" ;
9 10 let t
: TestSession | undefined ;
30 31 expect (extension.commands.
has (
"ultra" )).
toBe (
true );
31 32 expect (extension.commands.
has (
"ultra-runs" )).
toBe (
true );
35 + it (
"exposes the runtime workflow schema to tool callers" ,
async ()
=> {
36 + t
= await createTestSession ({ extensions: [
ultraPath ()] });
37 + const [extension]
= t.session.extensionRunner.extensions;
38 + const tool
= extension.tools.
get (
"workflow" ).definition;
39 + const specSchema
= tool.parameters.properties.spec;
41 + expect (
JSON .
parse (
JSON .
stringify (specSchema))).
toEqual (
42 + JSON .
parse (
JSON .
stringify (WorkflowSpecSchema)),
extensions/ultra/index.ts Modified 52 52 type DiscoveredWorkflow ,
55 56 } from
"./spec.ts" ;
56 57 import { renderUltraResult, UltraOverlayComponent }
from "./ui.ts" ;
260 261 description :
"Name of a saved workflow (project / global / bundled)." ,
263 - spec : Type.
Optional (Type.
Unknown ()),
264 + spec : Type.
Optional (WorkflowSpecSchema),
264 265 args : Type.
Optional (Type.
Record (Type.
String (), Type.
Unknown ())),
265 266 background : Type.
Optional (