@agimon-ai/doompi-workflow 0.0.1-alpha.7 → 0.0.1-alpha.71

package/package.json

@@ -1,13 +1,41 @@
 {
   "name": "@agimon-ai/doompi-workflow",
-  "version": "0.0.1-alpha.7",
-  "description": "Doompi workflow execution and monitoring integration",
+  "version": "0.0.1-alpha.71",
+  "description": "GitHub Actions-style workflow graphs, artifacts, recovery, and asynchronous runs for DoomPi.",
+  "keywords": [
+    "ai",
+    "automation",
+    "coding-agent",
+    "developer-tools",
+    "doompi",
+    "github-actions",
+    "pi-extension",
+    "pi-package",
+    "workflow",
+    "workflow-orchestration"
+  ],
   "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/doompi/issues"
+  },
   "license": "MIT",
   "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/doompi.git",
+    "directory": "packages/minor/doompi-workflow"
+  },
   "files": [
     "dist",
-    "skills"
+    "llms.txt",
+    "README.md",
+    "src/prompts",
+    "skills/workflow-recovery/SKILL.md",
+    "src/web",
+    "src/extensions/web.ts",
+    "src/types/webWorkflows.ts",
+    "src/types/webWorkflowTerminal.ts",
+    "!src/web/**/*.stories.tsx"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
@@ -19,16 +47,16 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
-    "./extensions/dispatcher": {
-      "types": "./dist/extensions/dispatcher.d.mts",
-      "import": "./dist/extensions/dispatcher.mjs",
-      "require": "./dist/extensions/dispatcher.cjs"
-    },
     "./extensions/pi": {
       "types": "./dist/extensions/pi.d.mts",
       "import": "./dist/extensions/pi.mjs",
       "require": "./dist/extensions/pi.cjs"
     },
+    "./extensions/server": {
+      "types": "./dist/extensions/server.d.mts",
+      "import": "./dist/extensions/server.mjs",
+      "require": "./dist/extensions/server.cjs"
+    },
     "./package.json": "./package.json",
     "./skills/workflow-recovery/SKILL.md": "./skills/workflow-recovery/SKILL.md"
   },
@@ -36,25 +64,37 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "zod": "4.4.3",
-    "@agimon-ai/workflow-mcp": "0.22.16",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.7",
-    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.7"
+    "@agimon-ai/workflow-mcp": "0.23.19",
+    "@deepseek-ai/cordis": "4.0.2",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "hono": "4.13.5",
+    "typebox": "1.3.25",
+    "zod": "4.5.4",
+    "@agimon-ai/doompi-minor-mode": "0.0.1-alpha.70",
+    "@agimon-ai/doompi-core": "0.0.1-alpha.70",
+    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.68",
+    "@agimon-ai/doompi-web-components": "0.0.1-alpha.29",
+    "@agimon-ai/doompi-ui": "0.0.1-alpha.70",
+    "@agimon-ai/doompi-web-security": "0.0.1-alpha.31"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@earendil-works/pi-tui": "0.84.1",
-    "@types/node": "26.1.1",
-    "@vitest/coverage-v8": "4.1.10",
-    "tsdown": "0.22.14",
-    "typescript": "6.0.3",
-    "vitest": "4.1.10",
-    "@agimon-ai/doompi-ui": "0.0.1-alpha.7"
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@tanstack/react-store": "0.11.1",
+    "@tanstack/store": "0.11.1",
+    "@types/node": "26.4.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "@vitest/coverage-v8": "5.0.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@earendil-works/pi-tui": "0.84.1"
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -67,6 +107,30 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "doompiServer": {
+    "entry": "./src/extensions/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": [
+      "global",
+      "workspace",
+      "session"
+    ],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/api-contracts.mjs"
+    }
+  },
+  "doompiWeb": {
+    "pluginId": "workflows",
+    "channels": [
+      "workflow_runs",
+      "workflow_catalog"
+    ],
+    "client": "./src/extensions/web.ts",
+    "scopes": [
+      "session"
+    ]
+  },
   "pi": {
     "extensions": [
       "./dist/extensions/pi.mjs"
@@ -75,7 +139,7 @@
   "scripts": {
     "build": "tsdown",
     "test": "vitest --run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p src/web/tsconfig.json",
     "lint": "oxlint . && oxfmt . --check",
     "fixcode": "oxlint . --fix && oxfmt ."
   }

package/src/extensions/web.ts

@@ -0,0 +1,80 @@
+import { defineWebPlugin } from '@agimon-ai/doompi-core/web';
+
+import { WorkflowsActivitySection } from '../web/components/WorkflowsActivitySection';
+import { workflowsTab } from '../web/components/WorkflowsPanel';
+import { WorkflowToolMessage } from '../web/components/WorkflowToolMessage';
+import { openCatalog, openWorkflowCatalogForContext, workflowCatalogChannel } from '../web/stores/catalogStore';
+import { workflowRunsChannel, workflows } from '../web/stores/workflowsStore';
+
+const WORKFLOWS_GROUP = { key: 'w', label: 'workflows', detail: 'multi-step agent runs' };
+
+const workflowActivitySource = {
+  subscribe(listener: () => void) {
+    const subscription = workflows.store.subscribe(listener);
+    return () => subscription.unsubscribe();
+  },
+  isActive(sessionId: string | null) {
+    return workflows.select(workflows.store.state, sessionId).runs.some((run) => run.stage === 'running');
+  },
+};
+
+/** The named export the generated plugin registry imports. */
+export const webPlugin = defineWebPlugin({
+  id: 'workflows',
+  session: {
+    // No declared tab: the runs surface is a panel the reader opens from the
+    // dock's workflows group, and closes when they are done with it.
+    channels: [workflowRunsChannel, workflowCatalogChannel],
+    contextActions: [
+      {
+        id: 'launch-workflow',
+        label: 'Launch Workflow',
+        detail: 'Choose a workflow, review its inputs, then launch it.',
+        kinds: ['work-item'],
+        order: 20,
+        run: (context) => openWorkflowCatalogForContext(context, workflowsTab),
+      },
+    ],
+    minorModes: [{ name: 'workflow', keys: 'w e', widgetKey: 'workflow-mcp-progress', order: 50 }],
+    activityGroups: [
+      {
+        name: 'workflows',
+        keys: 'w r',
+        widgetKeys: ['workflow-mcp-progress', 'workflow-mcp-follow'],
+        activeSource: workflowActivitySource,
+        transientTab: workflowsTab,
+        order: 30,
+      },
+    ],
+    // Same name as the group: the dock renders this inside it, in place of the
+    // widget's bare presence signal.
+    activitySections: [{ id: 'workflows', component: WorkflowsActivitySection }],
+    // The workflow tools' timeline cards, the web half of src/tui/workflow/workflowToolRender.ts.
+    toolRenderers: [{ tools: ['list_workflows', 'launch_workflow', 'workflow_run'], message: WorkflowToolMessage }],
+    // The TUI's SPC w r, w l and w e; recovery (w c) is a TUI-only overlay, so
+    // it has no cockpit key yet.
+    leaderBindings: [
+      {
+        id: 'doom-workflow.manage',
+        path: [WORKFLOWS_GROUP, { key: 'r', label: 'runs', detail: 'runs in this session' }],
+        run: (context) => context.openTransientTab(workflowsTab()),
+      },
+      {
+        id: 'doom-workflow.catalog',
+        path: [WORKFLOWS_GROUP, { key: 'l', label: 'launch', detail: 'pick a workflow and launch it' }],
+        run: (context) => {
+          if (context.sessionId !== null) openCatalog(context.sessionId);
+          context.openTransientTab(workflowsTab());
+        },
+      },
+      {
+        id: 'doom-workflow.toggle',
+        path: [
+          WORKFLOWS_GROUP,
+          { key: 'e', label: 'toggle', detail: 'give the agent workflow tools or take them back' },
+        ],
+        command: 'minor workflow',
+      },
+    ],
+  },
+});

package/src/prompts/doompi-author-workflow/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: doompi-author-workflow
+description: Author DoomPi workflow definitions. Use when creating or changing a *.workflow.yml graph, arranging job dependencies and host-executed steps, or deciding how a command requiring a TTY should run.
+---
+
+# Author DoomPi workflows
+
+Create a `*.workflow.yml` file and keep its graph explicit:
+
+```yaml
+name: verify
+
+jobs:
+  test:
+    steps:
+      - name: Run tests
+        run: pnpm test
+
+  summarize:
+    needs: test
+    steps:
+      - name: Record result
+        run: node scripts/write-verification-summary.mjs
+```
+
+`needs` expresses job ordering. Keep steps small enough that failure evidence identifies the command that needs attention. Use runner-specific `interactiveRun` configuration when a command genuinely requires a TTY.
+
+Every `run` command executes on the workflow host with that process's environment and privileges. There is no VM, container, or sandbox. Review workflow changes as executable code, avoid embedding secrets, and make retry-sensitive external side effects explicit.
+
+Before relying on the graph, enable Workflow mode, discover it with `list_workflows`, launch a disposable run, and inspect job and step status with `workflow_run`. Test a failure path when recovery behavior matters.

package/src/prompts/doompi-use-workflow/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: doompi-use-workflow
+description: Use DoomPi workflows. Use when discovering or launching workflows, monitoring or controlling asynchronous runs, interpreting terminal notifications, or recovering a failed run safely.
+---
+
+# Use DoomPi workflows
+
+Enable model-visible Workflow tools with `SPC w e`. In a non-interactive harness, set `WORKFLOW_MCP_MODE=on` before starting the session.
+
+Use the tools in this order:
+
+1. `list_workflows` discovers available workflow definitions.
+2. `launch_workflow` registers and starts a run. A successful launch response does not mean the jobs have finished.
+3. `workflow_run` inspects status, follows progress, or applies a supported control action.
+4. Wait for a terminal notification and verify the final job and step states before reporting success.
+
+In the TUI, `SPC w l` lists the repository's workflows and launches the one under the cursor with `r`, `SPC w r` inspects this session's runs, and `SPC w c` opens recovery. The root session can launch. Child sessions can inspect the catalog but do not receive an unrestricted workflow factory.
+
+Recover only a record already in a terminal failure state. Inspect its evidence first, then use the package's `workflow-recovery` runtime skill for the repair workflow. Recovery atomically adopts eligible work, but it cannot make non-idempotent external side effects safe or guarantee that in-process work survives parent shutdown.
+
+Workflow steps and model-backed repair can consume provider quota and repeat external effects. Do not relaunch or replay a run merely because progress is quiet. Inspect live ownership and persisted state first.

package/src/types/webWorkflowTerminal.ts

@@ -0,0 +1,96 @@
+/**
+ * The wire contract between this package's hub API and its cockpit client:
+ * one run's terminal, and the files its run directory holds.
+ *
+ * Both halves of the cockpit import these names, so the route strings and the
+ * event names live here rather than being spelled twice.
+ */
+
+import { DOOM_HUB_API_SESSION_QUERY_PARAM } from '@agimon-ai/doompi-core/package-api';
+
+/** Segment this package's API is mounted under, below /api/plugin/. */
+export const WORKFLOW_API_BASE_PATH = 'workflow';
+/** Host query parameter that selects the focused session's hub API bundle. */
+export const WORKFLOW_HUB_SESSION_QUERY_PARAM = DOOM_HUB_API_SESSION_QUERY_PARAM;
+
+/** The SSE event name the screen stream writes. */
+export const WORKFLOW_SCREEN_EVENT = 'screen';
+
+/** Where a run's routes live, below the mount every hub-scoped package API shares. */
+export function workflowRunPath(workspace: string, runKey: string): string {
+  return `/api/global/plugin/${WORKFLOW_API_BASE_PATH}/runs/${encodeURIComponent(workspace)}/${encodeURIComponent(runKey)}`;
+}
+
+/** What a surface may do with one run's terminal, and why anything is missing. */
+export interface WorkflowTerminalCapabilitiesView {
+  readable: boolean;
+  writable: boolean;
+  resizable: boolean;
+  reason?: string;
+}
+
+/** One frame of a run's terminal, as the stream pushes it. */
+export interface WorkflowScreenEvent {
+  /** The visible screen, newest line last, carrying the colour the run printed. */
+  lines: string[];
+  capabilities: WorkflowTerminalCapabilitiesView;
+  /** True once the run has settled, after which the stream ends. */
+  ended?: boolean;
+}
+
+/** Answer to taking or releasing the keyboard for one run. */
+export interface WorkflowControlResponse {
+  /** True when this caller now holds the keyboard. */
+  held: boolean;
+  /** The token later writes must carry; absent when control was refused or released. */
+  token?: string;
+  /** Why control was refused, worded for a reader. */
+  reason?: string;
+}
+
+/** Answer after a settled run and its directory have been permanently removed. */
+export interface WorkflowDeleteResponse {
+  deleted: true;
+}
+
+/** How a declared run-directory entry compares with what is on disk. */
+export type WorkflowArtifactState = 'written' | 'empty' | 'pending' | 'unreadable';
+
+/** One file or directory in a run's own folder. */
+export interface WorkflowArtifactView {
+  /** Path relative to the run directory, which is also the read route's parameter. */
+  path: string;
+  kind: 'file' | 'directory';
+  /** What the workflow says this file is for; empty for a file it never declared. */
+  description: string;
+  /** The jobs the workflow says write it. */
+  producedBy: string[];
+  /** True when the workflow's run-directory block names this entry. */
+  declared: boolean;
+  state: WorkflowArtifactState;
+  /** Bytes on disk, absent until the file exists. */
+  size?: number;
+  /** ISO 8601 of the last write, absent until the file exists. */
+  modifiedAt?: string;
+}
+
+export interface WorkflowArtifactsResponse {
+  /** Absolute path of the run's own directory, which the reader may want to open. */
+  runDir: string;
+  /** What the workflow says the directory is for. */
+  description: string;
+  artifacts: WorkflowArtifactView[];
+}
+
+/** One artifact's metadata and optional text, as the viewer tab reads it. */
+export interface WorkflowArtifactContentResponse {
+  path: string;
+  size: number;
+  modifiedAt: string;
+  /** Media type inferred from the file extension by the trusted hub. Absent on older hubs. */
+  mimeType?: string;
+  /** Present for text formats; binary files are streamed from the raw route instead. */
+  text?: string;
+  /** True when textual content was longer than the reader's byte budget. */
+  truncated: boolean;
+}

package/src/types/webWorkflows.ts

@@ -0,0 +1,150 @@
+/**
+ * Workflow run view types shared by this package's hub channel and its web
+ * plugin. The shapes mirror what the embedded workflow-mcp engine records;
+ * the cockpit renders them as 'workflow_runs' channel payloads.
+ */
+
+/** workflow-mcp's own stage vocabulary; the registry bucket a run record sits in. */
+export type WorkflowStage = 'running' | 'completed' | 'error';
+
+/** workflow-mcp's terminal outcome for a finished run. */
+export type WorkflowOutcome = 'success' | 'skipped' | 'failed' | 'interrupted';
+
+/** Job and step states as workflow-mcp records them in the progress log. */
+export type WorkflowProgressState =
+  | 'running'
+  | 'completed'
+  | 'skipped'
+  | 'failed'
+  | 'pause_requested'
+  | 'paused'
+  | 'resumed';
+
+export interface WorkflowStepView {
+  name: string;
+  status: WorkflowProgressState;
+  /** Why the step is in its state, when the engine recorded one (e.g. a skip condition). */
+  reason?: string;
+  /** ISO 8601 of the step's first running event. */
+  startedAt?: string;
+  /** ISO 8601 of the step's terminal event. */
+  endedAt?: string;
+}
+
+/** 'pre' and 'post' are the engine's pseudo-jobs for its pre:/post: blocks. */
+export type WorkflowJobPhase = 'pre' | 'job' | 'post';
+
+export interface WorkflowJobView {
+  name: string;
+  phase: WorkflowJobPhase;
+  status: WorkflowProgressState;
+  reason?: string;
+  /** Position among the run's jobs, when the engine recorded one. */
+  index?: number;
+  total?: number;
+  startedAt?: string;
+  endedAt?: string;
+  steps: WorkflowStepView[];
+}
+
+/** The job and step a run is on right now; drives the NOW breadcrumb. */
+export interface WorkflowPosition {
+  job: string;
+  step?: string;
+  index?: number;
+  total?: number;
+}
+
+/**
+ * One workflow run of a session, read from workflow-mcp's registry: the
+ * run.json record plus the folded progress.ndjson job tree.
+ */
+export interface WorkflowRunView {
+  /** Registry identity within its workspace; unique per workspace+stage. */
+  runKey: string;
+  workspace: string;
+  displayName: string;
+  workflowName?: string;
+  workflowPath: string;
+  stage: WorkflowStage;
+  outcome?: WorkflowOutcome;
+  /** Present while the engine is pausing or paused; absent for plain running. */
+  executionState?: 'running' | 'pause_requested' | 'paused' | 'resume_requested';
+  /** The prompt the run was launched with, when one was recorded. */
+  prompt?: string;
+  /** ISO 8601, from the run record. */
+  startedAt: string;
+  finishedAt?: string;
+  /** Failure cause with ANSI escapes stripped, present when the run errored. */
+  errorMessage?: string;
+  /** The job the engine blamed for the failure, when it recorded one. */
+  failedJob?: string;
+  /** True when reconciliation decided the recorded pid is no longer alive. */
+  stale?: boolean;
+  staleReason?: string;
+  worktreeBranch?: string;
+  position?: WorkflowPosition;
+  jobs: WorkflowJobView[];
+}
+
+/** What the workflow runs channel publishes for one session. */
+export interface WorkflowRunsPayload {
+  runs: WorkflowRunView[];
+}
+
+export const WORKFLOW_RUNS_TYPE = 'workflow_runs';
+
+/**
+ * One workflow the session's directory can launch, as the catalog drawer
+ * lists it: the engine's own catalog entry plus the parsed detail the drawer
+ * unfolds and the launch dialog turns into fields.
+ */
+export interface WorkflowCatalogEntryView {
+  /** Absolute path, the row's stable identity. */
+  path: string;
+  relativePath: string;
+  name: string;
+  description: string;
+  tags: string[];
+  /** The trigger names the file declares, such as workflow_dispatch. */
+  triggers: string[];
+  inputs: WorkflowCatalogInputView[];
+  jobs: WorkflowCatalogJobView[];
+  artifacts: WorkflowCatalogArtifactView[];
+  /** Absent when the workflow names no runner map, which means any runner will do. */
+  runners?: string[];
+  /** Set when the file could not be parsed; the row shows this instead of guessing. */
+  error?: string;
+}
+
+export interface WorkflowCatalogInputView {
+  name: string;
+  description?: string;
+  required?: boolean;
+  default?: string;
+  type?: string;
+  options?: string[];
+}
+
+export interface WorkflowCatalogJobView {
+  name: string;
+  steps: string[];
+}
+
+export interface WorkflowCatalogArtifactView {
+  path: string;
+  kind: 'file' | 'directory';
+  description: string;
+  producedBy: string[];
+}
+
+/** What the catalog channel publishes for one session. */
+export interface WorkflowCatalogPayload {
+  /** The directory the catalog was read from, which is the session's own. */
+  cwd: string;
+  workflows: WorkflowCatalogEntryView[];
+  /** Present when the directory could not be read at all. */
+  warning?: string;
+}
+
+export const WORKFLOW_CATALOG_TYPE = 'workflow_catalog';

package/src/web/LICENSE

@@ -0,0 +1,29 @@
+The DoomPi Web License
+
+Copyright (c) 2026 Agimon Pty Ltd
+
+With regard to the DoomPi Web Software:
+
+This software and associated documentation files (the "Software") may be
+used, free of charge, by any person or entity, for any purpose, including
+production and commercial use. You may copy the Software as reasonably
+necessary to install, run, develop against, test, and back it up. You are
+free to modify the Software for your own use and to publish patches to the
+Software. You agree that the licensor retains all right, title, and interest
+in and to the Software, and that your modifications and patches may only be
+used, copied, modified, displayed, distributed, or otherwise exploited
+together with the Software. You are not granted any other rights beyond what
+is expressly stated herein. Subject to the foregoing, it is forbidden to
+publish, distribute, sublicense, and/or sell the Software or any copy of it,
+or to offer the Software to third parties as a hosted or managed service.
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.