repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

fix(ultra): expose inline workflow schema

ccf9d13a6dcea4deb4b9e7fd590bdf5b86183e12

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare 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
11 +**Roadmap:** None
13 +**Phase:** Single-plan implementation
15 +---
17 +## Task 1: Expose the workflow schema
19 +**Files:**
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`:
28 +```ts
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)),
33 +);
34 +```
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:
45 +```ts
46 +spec: Type.Optional(Type.Unknown()),
47 +```
49 +with:
51 +```ts
52 +spec: Type.Optional(WorkflowSpecSchema),
53 +```
55 +- [x] **Step 4: Run the focused test and verify GREEN**
57 +Run: `mise run test -- extensions/ultra/__tests__/harness.test.ts`
58 +Expected: PASS.
60 +- [x] **Step 5: Run verification**
62 +Run:
64 +```text
65 +mise run test -- extensions/ultra
66 +mise run check
67 +```
69 +Expected: both commands pass without warnings or errors.
71 +- [x] **Step 6: Commit**
73 +```text
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"
76 +```

extensions/ultra/__tests__/harness.test.ts

Modified
5 5 type TestSession,
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)),
43 + );
44 + });

extensions/ultra/index.ts

Modified
52 52 type DiscoveredWorkflow,
53 53 discoverWorkflows,
54 54 type WorkflowSpec,
55 + WorkflowSpecSchema,
55 56 } from "./spec.ts";
56 57 import { renderUltraResult, UltraOverlayComponent } from "./ui.ts";
57 58 import {
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(
266 267 Type.Boolean({