@wichayutdew/pi-workflows 0.1.1

package/schemas/workflow.schema.json

@@ -0,0 +1,585 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Pi workflow",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "id", "command", "description", "start", "steps"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "command": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/identifier"
+        },
+        {
+          "not": {
+            "enum": [
+              "arminsayshi",
+              "changelog",
+              "clone",
+              "compact",
+              "copy",
+              "debug",
+              "dementedelves",
+              "export",
+              "fork",
+              "hotkeys",
+              "import",
+              "login",
+              "logout",
+              "model",
+              "name",
+              "new",
+              "quit",
+              "reload",
+              "resume",
+              "scoped-models",
+              "session",
+              "settings",
+              "share",
+              "tree",
+              "trust",
+              "workflow-abort",
+              "workflow-list",
+              "workflow-pause",
+              "workflow-reload",
+              "workflow-resume",
+              "workflow-start",
+              "workflow-status"
+            ]
+          }
+        }
+      ]
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "start": {
+      "$ref": "#/$defs/identifier"
+    },
+    "maxStepVisits": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "default": 5
+    },
+    "summaryMaxChars": {
+      "type": "integer",
+      "minimum": 100,
+      "maximum": 50000,
+      "default": 4000
+    },
+    "steps": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "$ref": "#/$defs/identifier"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/step"
+      }
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,63}$"
+    },
+    "resourceName": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_@./:+-]+$"
+    },
+    "subagentRuntimeName": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*(?:\\.[a-z0-9][a-z0-9-]*)*$"
+    },
+    "prompt": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["file"],
+          "properties": {
+            "file": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      ]
+    },
+    "bashRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["executable"],
+      "allOf": [
+        {
+          "not": {
+            "required": ["argsPrefix", "argsPrefixes"]
+          }
+        }
+      ],
+      "properties": {
+        "executable": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_./+-]+$"
+        },
+        "argsPrefix": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\S+$"
+          },
+          "default": []
+        },
+        "argsPrefixes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^\\S+$"
+            }
+          }
+        }
+      }
+    },
+    "bash": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "allow-list"
+              }
+            },
+            "required": ["mode"]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["allow"],
+                "properties": {
+                  "allow": {
+                    "minItems": 1
+                  }
+                }
+              },
+              {
+                "required": ["approvedSources"],
+                "properties": {
+                  "approvedSources": {
+                    "minItems": 1
+                  }
+                }
+              }
+            ]
+          },
+          "else": {
+            "properties": {
+              "allow": {
+                "maxItems": 0
+              },
+              "approvedSources": {
+                "maxItems": 0
+              }
+            }
+          }
+        }
+      ],
+      "properties": {
+        "mode": {
+          "enum": ["deny", "read-only", "allow-list", "unrestricted"]
+        },
+        "allow": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/bashRule"
+          }
+        },
+        "approvedSources": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "verification-worker",
+              "verification-reviewer",
+              "remote-actions"
+            ]
+          }
+        }
+      }
+    },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tools": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.:-]+$"
+          }
+        },
+        "mcp": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.:-]+(?:/[A-Za-z0-9_.:-]+)?$"
+          }
+        },
+        "extensions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/resourceName"
+          }
+        },
+        "skills": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/resourceName"
+          }
+        },
+        "bash": {
+          "$ref": "#/$defs/bash"
+        }
+      }
+    },
+    "requires": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tools": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.:-]+$"
+          }
+        },
+        "extensions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/resourceName"
+          }
+        },
+        "skills": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/resourceName"
+          }
+        }
+      }
+    },
+    "subagentTurnBudget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maxTurns"],
+      "properties": {
+        "maxTurns": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        },
+        "graceTurns": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        }
+      }
+    },
+    "subagentToolBudget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hard"],
+      "properties": {
+        "soft": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100000
+        },
+        "hard": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100000
+        },
+        "block": {
+          "oneOf": [
+            {
+              "const": "*"
+            },
+            {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9_.:-]+$"
+              }
+            }
+          ]
+        }
+      }
+    },
+    "subagent": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/subagentRuntimeName"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "agent": {
+              "$ref": "#/$defs/subagentRuntimeName",
+              "default": "pi-workflows.step"
+            },
+            "context": {
+              "enum": ["fresh", "fork"],
+              "default": "fresh"
+            },
+            "model": {
+              "$ref": "#/$defs/resourceName"
+            },
+            "timeoutMs": {
+              "type": "integer",
+              "minimum": 1000,
+              "maximum": 86400000,
+              "default": 900000
+            },
+            "turnBudget": {
+              "$ref": "#/$defs/subagentTurnBudget"
+            },
+            "toolBudget": {
+              "$ref": "#/$defs/subagentToolBudget"
+            },
+            "artifacts": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        }
+      ]
+    },
+    "subagentCeiling": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "agents",
+        "contexts",
+        "models",
+        "maxTimeoutMs",
+        "maxTurns",
+        "maxGraceTurns",
+        "maxToolCalls",
+        "artifacts"
+      ],
+      "properties": {
+        "agents": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/subagentRuntimeName"
+          }
+        },
+        "contexts": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "enum": ["fresh", "fork"]
+          }
+        },
+        "models": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/resourceName"
+          }
+        },
+        "maxTimeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 86400000
+        },
+        "maxTurns": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        },
+        "maxGraceTurns": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "maxToolCalls": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100000
+        },
+        "artifacts": {
+          "type": "boolean"
+        }
+      }
+    },
+    "permissionCeiling": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tools": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.:-]+$"
+          }
+        },
+        "mcp": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.:-]+(?:/[A-Za-z0-9_.:-]+)?$"
+          }
+        },
+        "extensions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/resourceName"
+          }
+        },
+        "skills": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/resourceName"
+          }
+        },
+        "bash": {
+          "$ref": "#/$defs/bash"
+        },
+        "subagent": {
+          "$ref": "#/$defs/subagentCeiling"
+        }
+      }
+    },
+    "gate": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["submitOutcome", "approvedOutcome", "rejectedOutcome"],
+          "properties": {
+            "provider": {
+              "const": "prompt",
+              "default": "prompt"
+            },
+            "submitOutcome": {
+              "$ref": "#/$defs/identifier"
+            },
+            "approvedOutcome": {
+              "$ref": "#/$defs/identifier"
+            },
+            "rejectedOutcome": {
+              "$ref": "#/$defs/identifier"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "provider",
+            "submitOutcome",
+            "approvedOutcome",
+            "rejectedOutcome"
+          ],
+          "properties": {
+            "provider": {
+              "const": "plannotator"
+            },
+            "submitOutcome": {
+              "$ref": "#/$defs/identifier"
+            },
+            "approvedOutcome": {
+              "$ref": "#/$defs/identifier"
+            },
+            "rejectedOutcome": {
+              "$ref": "#/$defs/identifier"
+            },
+            "timeoutMs": {
+              "type": "integer",
+              "minimum": 1000,
+              "maximum": 30000,
+              "default": 5000
+            }
+          }
+        }
+      ]
+    },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["prompt", "transitions"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "prompt": {
+          "$ref": "#/$defs/prompt"
+        },
+        "subagent": {
+          "$ref": "#/$defs/subagent"
+        },
+        "permissions": {
+          "$ref": "#/$defs/permissions"
+        },
+        "requires": {
+          "$ref": "#/$defs/requires"
+        },
+        "transitions": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "$ref": "#/$defs/identifier"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^(?:\\$done|\\$pause|[a-z][a-z0-9-]{0,63})$"
+          }
+        },
+        "gate": {
+          "$ref": "#/$defs/gate"
+        }
+      }
+    }
+  }
+}

package/src/command-names.ts

@@ -0,0 +1,46 @@
+export const HARNESS_COMMAND_NAMES = [
+  'workflow-abort',
+  'workflow-list',
+  'workflow-pause',
+  'workflow-reload',
+  'workflow-resume',
+  'workflow-start',
+  'workflow-status',
+] as const;
+
+/**
+ * Interactive commands handled by Pi before extension command dispatch.
+ * Hidden diagnostic commands are included because an alias cannot reach them.
+ */
+export const PI_BUILTIN_COMMAND_NAMES = [
+  'arminsayshi',
+  'changelog',
+  'clone',
+  'compact',
+  'copy',
+  'debug',
+  'dementedelves',
+  'export',
+  'fork',
+  'hotkeys',
+  'import',
+  'login',
+  'logout',
+  'model',
+  'name',
+  'new',
+  'quit',
+  'reload',
+  'resume',
+  'scoped-models',
+  'session',
+  'settings',
+  'share',
+  'tree',
+  'trust',
+] as const;
+
+export const RESERVED_COMMAND_NAMES = new Set<string>([
+  ...HARNESS_COMMAND_NAMES,
+  ...PI_BUILTIN_COMMAND_NAMES,
+]);

package/src/commands.ts

@@ -0,0 +1,80 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from '@earendil-works/pi-coding-agent';
+
+export interface WorkflowCommandController {
+  workflowIds(): string[];
+  list(ctx: ExtensionCommandContext): Promise<void>;
+  start(
+    workflowId: string,
+    input: string,
+    ctx: ExtensionCommandContext,
+  ): Promise<void>;
+  pause(reason: string, ctx: ExtensionCommandContext): Promise<void>;
+  resume(ctx: ExtensionCommandContext): Promise<void>;
+  abort(reason: string, ctx: ExtensionCommandContext): Promise<void>;
+  reload(ctx: ExtensionCommandContext): Promise<void>;
+  status(ctx: ExtensionCommandContext): Promise<void>;
+}
+
+function splitFirst(value: string): [string, string] {
+  const trimmed = value.trim();
+  const separator = trimmed.search(/\s/);
+  if (separator === -1) return [trimmed, ''];
+  return [trimmed.slice(0, separator), trimmed.slice(separator).trim()];
+}
+
+export function registerHarnessCommands(
+  pi: ExtensionAPI,
+  controller: WorkflowCommandController,
+): void {
+  pi.registerCommand('workflow-list', {
+    description: 'List loaded declarative workflows',
+    handler: async (_args, ctx) => controller.list(ctx),
+  });
+
+  pi.registerCommand('workflow-start', {
+    description: 'Start a workflow: /workflow-start <id> [input]',
+    getArgumentCompletions: (prefix) => {
+      const items = controller
+        .workflowIds()
+        .filter((id) => id.startsWith(prefix))
+        .map((id) => ({ value: id, label: id }));
+      return items.length > 0 ? items : null;
+    },
+    handler: async (args, ctx) => {
+      const [workflowId, input] = splitFirst(args);
+      if (!workflowId) {
+        ctx.ui.notify('Usage: /workflow-start <id> [input]', 'warning');
+        return;
+      }
+      await controller.start(workflowId, input, ctx);
+    },
+  });
+
+  pi.registerCommand('workflow-pause', {
+    description: 'Pause the active workflow without losing its checkpoint',
+    handler: async (reason, ctx) => controller.pause(reason.trim(), ctx),
+  });
+
+  pi.registerCommand('workflow-resume', {
+    description: 'Reload configuration and resume the paused workflow',
+    handler: async (_args, ctx) => controller.resume(ctx),
+  });
+
+  pi.registerCommand('workflow-abort', {
+    description: 'Abort the active workflow',
+    handler: async (reason, ctx) => controller.abort(reason.trim(), ctx),
+  });
+
+  pi.registerCommand('workflow-reload', {
+    description: 'Reload workflow files while no workflow is running',
+    handler: async (_args, ctx) => controller.reload(ctx),
+  });
+
+  pi.registerCommand('workflow-status', {
+    description: 'Open the active workflow status board',
+    handler: async (_args, ctx) => controller.status(ctx),
+  });
+}