@agimon-ai/doompi-workflow 0.0.1-alpha.37 → 0.0.1-alpha.39

package/src/types/webWorkflowTerminal.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+
+/** Segment this package's API is mounted under, below /api/plugin/. */
+export const WORKFLOW_API_BASE_PATH = 'workflow';
+
+/** 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/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,145 @@
+/**
+ * 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[];
+}
+
+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/web/ArtifactsPane.tsx

@@ -0,0 +1,433 @@
+import { Badge, Button, EmptyState, Markdown } from '@agimon-ai/doompi-web-components';
+import type { TransientTab, WebPluginSlotProps } from '@agimon-ai/doompi-web-contracts';
+import { useEffect, useState } from 'react';
+import type { WorkflowRunView } from '../src/types/webWorkflows.ts';
+import type {
+  WorkflowArtifactContentResponse,
+  WorkflowArtifactsResponse,
+  WorkflowArtifactView,
+} from '../src/types/webWorkflowTerminal.ts';
+import { artifactContentUrl, fetchArtifact, fetchArtifacts } from './terminalApi.ts';
+
+const TAB_ID_PREFIX = 'workflows-artifact-';
+const BYTES_PER_UNIT = 1024;
+const UNITS = ['B', 'KB', 'MB'] as const;
+
+function formatSize(bytes: number | undefined): string {
+  if (bytes === undefined) return '';
+  let value = bytes;
+  let unit = 0;
+  while (value >= BYTES_PER_UNIT && unit < UNITS.length - 1) {
+    value /= BYTES_PER_UNIT;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : value.toFixed(1)} ${UNITS[unit]}`;
+}
+
+function formatWhen(iso: string | undefined): string {
+  if (iso === undefined) return '';
+  const parsed = Date.parse(iso);
+  if (!Number.isFinite(parsed)) return '';
+  return new Date(parsed).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+}
+
+const STATE_GLYPH: Readonly<Record<WorkflowArtifactView['state'], { glyph: string; className: string }>> = {
+  written: { glyph: '✓', className: 'text-doom-green' },
+  empty: { glyph: '○', className: 'text-doom-yellow' },
+  pending: { glyph: '○', className: 'text-doom-faint' },
+  unreadable: { glyph: '!', className: 'text-doom-red' },
+};
+
+function parseDelimited(text: string, delimiter: ',' | '\t'): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let cell = '';
+  let quoted = false;
+  for (let index = 0; index <= text.length && rows.length < 500; index += 1) {
+    const character = text[index] ?? '\n';
+    if (quoted) {
+      if (character === '"' && text[index + 1] === '"') {
+        cell += '"';
+        index += 1;
+      } else if (character === '"') {
+        quoted = false;
+      } else {
+        cell += character;
+      }
+    } else if (character === '"' && cell === '') {
+      quoted = true;
+    } else if (character === delimiter) {
+      row.push(cell);
+      cell = '';
+    } else if (character === '\n') {
+      row.push(cell.replace(/\r$/, ''));
+      rows.push(row);
+      row = [];
+      cell = '';
+    } else {
+      cell += character;
+    }
+  }
+  return rows;
+}
+
+function DelimitedPreview({ text, delimiter }: { text: string; delimiter: ',' | '\t' }) {
+  const rows = parseDelimited(text, delimiter);
+  const [head = [], ...body] = rows;
+  return (
+    <div className="overflow-auto">
+      <table data-testid="artifact-table" className="min-w-full border-collapse font-mono text-[11px]">
+        <thead className="sticky top-0 bg-doom-panel text-doom-hi">
+          <tr>
+            {head.map((cell, index) => (
+              <th key={index} className="border border-doom-border px-2 py-1.5 text-left font-bold">
+                {cell}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {body.map((cells, rowIndex) => (
+            <tr key={rowIndex}>
+              {cells.map((cell, cellIndex) => (
+                <td key={cellIndex} className="border border-doom-border px-2 py-1 align-top text-doom-text">
+                  {cell}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+/** Keeps a newly built viewer compatible while an older hub process is restarting. */
+function previewMimeType(content: WorkflowArtifactContentResponse): string {
+  if (content.mimeType !== undefined) return content.mimeType;
+  const extension = content.path.split('.').pop()?.toLowerCase();
+  if (extension === 'md' || extension === 'markdown') return 'text/markdown';
+  if (extension === 'json') return 'application/json';
+  if (extension === 'csv') return 'text/csv';
+  if (extension === 'tsv') return 'text/tab-separated-values';
+  if (extension === 'html' || extension === 'htm') return 'text/html';
+  if (extension === 'pdf') return 'application/pdf';
+  if (['bmp', 'gif', 'ico', 'jpeg', 'jpg', 'png', 'svg', 'webp'].includes(extension ?? '')) return 'image/unknown';
+  if (['aac', 'm4a', 'mp3', 'oga', 'ogg', 'wav'].includes(extension ?? '')) return 'audio/unknown';
+  if (['mov', 'mp4', 'ogv', 'webm'].includes(extension ?? '')) return 'video/unknown';
+  return content.text === undefined ? 'application/octet-stream' : 'text/plain';
+}
+
+function ArtifactPreview({
+  content,
+  rawUrl,
+  raw,
+}: {
+  content: WorkflowArtifactContentResponse;
+  rawUrl: string;
+  raw: boolean;
+}) {
+  const text = content.text ?? '';
+  const mimeType = previewMimeType(content);
+  if (content.size === 0) {
+    return (
+      <EmptyState
+        data-testid="artifact-empty"
+        title="this artifact is empty"
+        description="The workflow created the file but did not write any content."
+      />
+    );
+  }
+  if (mimeType === 'text/markdown') {
+    return raw ? (
+      <pre
+        data-testid="artifact-raw"
+        className="whitespace-pre-wrap break-words font-mono text-[11px] leading-[17px] text-doom-text"
+      >
+        {text}
+      </pre>
+    ) : (
+      <div data-testid="artifact-markdown" className="max-w-5xl text-[13px] text-doom-text">
+        <Markdown text={text} />
+      </div>
+    );
+  }
+  if (mimeType === 'application/json') {
+    let formatted = text;
+    try {
+      formatted = JSON.stringify(JSON.parse(text) as unknown, null, 2);
+    } catch {
+      // An incomplete file remains useful as literal text while a workflow writes it.
+    }
+    return (
+      <pre className="whitespace-pre-wrap break-words font-mono text-[11px] leading-[17px] text-doom-text">
+        {formatted}
+      </pre>
+    );
+  }
+  if (mimeType === 'text/csv' || mimeType === 'text/tab-separated-values') {
+    return <DelimitedPreview text={text} delimiter={mimeType === 'text/csv' ? ',' : '\t'} />;
+  }
+  if (mimeType === 'text/html') {
+    return (
+      <iframe
+        data-testid="artifact-html"
+        title={content.path}
+        sandbox=""
+        referrerPolicy="no-referrer"
+        srcDoc={text}
+        className="min-h-[520px] w-full rounded bg-white"
+      />
+    );
+  }
+  if (mimeType.startsWith('image/')) {
+    return (
+      <img
+        data-testid="artifact-image"
+        src={rawUrl}
+        alt={content.path}
+        className="max-h-full max-w-full object-contain"
+      />
+    );
+  }
+  if (mimeType === 'application/pdf') {
+    return <object data-testid="artifact-pdf" data={rawUrl} type="application/pdf" className="min-h-[600px] w-full" />;
+  }
+  if (mimeType.startsWith('audio/')) {
+    return <audio data-testid="artifact-audio" src={rawUrl} controls preload="metadata" className="w-full" />;
+  }
+  if (mimeType.startsWith('video/')) {
+    return (
+      <video data-testid="artifact-video" src={rawUrl} controls preload="metadata" className="max-h-full max-w-full" />
+    );
+  }
+  if (content.text !== undefined) {
+    return (
+      <pre className="whitespace-pre-wrap break-words font-mono text-[11px] leading-[17px] text-doom-text">{text}</pre>
+    );
+  }
+  return (
+    <EmptyState title="preview unavailable" description="Download this artifact to open it with a local application." />
+  );
+}
+
+/** One artifact, read-only, in its own tab. */
+export function artifactTab(run: WorkflowRunView, path: string): TransientTab {
+  return {
+    id: `${TAB_ID_PREFIX}${run.workspace}-${run.runKey}-${path}`.replace(/[^\w-]+/g, '-'),
+    label: path.split('/').pop() ?? path,
+    panel: (props: WebPluginSlotProps) => (
+      <ArtifactViewerPanel {...props} workspace={run.workspace} runKey={run.runKey} path={path} />
+    ),
+  };
+}
+
+/**
+ * One artifact's text.
+ *
+ * Read-only and reloadable: a run keeps writing while somebody is reading, and
+ * the file on the next read is the one that matters.
+ */
+export function ArtifactViewerPanel({
+  workspace,
+  runKey,
+  path,
+}: WebPluginSlotProps & { workspace: string; runKey: string; path: string }) {
+  const [content, setContent] = useState<WorkflowArtifactContentResponse>();
+  const [error, setError] = useState<string>();
+  const [reloads, setReloads] = useState(0);
+  const [raw, setRaw] = useState(false);
+
+  useEffect(() => {
+    let live = true;
+    void fetchArtifact(workspace, runKey, path).then((result) => {
+      if (!live) return;
+      if ('error' in result) {
+        setError(result.error);
+        setContent(undefined);
+        return;
+      }
+      setError(undefined);
+      setContent(result.artifact);
+    });
+    return () => {
+      live = false;
+    };
+  }, [workspace, runKey, path, reloads]);
+
+  const rawUrl = artifactContentUrl(workspace, runKey, path);
+  const downloadUrl = artifactContentUrl(workspace, runKey, path, true);
+  const mimeType = content === undefined ? undefined : previewMimeType(content);
+  const isMarkdown = mimeType === 'text/markdown';
+
+  return (
+    <div data-testid="artifact-viewer" className="flex min-h-0 flex-1 flex-col px-[26px] py-[18px]">
+      <div className="flex items-center gap-2.5 pb-3">
+        <span className="truncate text-[12px] font-bold text-doom-hi">{path}</span>
+        <Badge size="xs">{mimeType ?? 'artifact'}</Badge>
+        <span className="text-[9px] text-doom-faint">
+          {content === undefined ? '' : `${formatSize(content.size)} · written ${formatWhen(content.modifiedAt)}`}
+        </span>
+        <span className="min-w-0 flex-1" />
+        {isMarkdown ? (
+          <div className="flex items-center">
+            <Button
+              variant={raw ? 'outline' : 'primary'}
+              size="xs"
+              data-testid="artifact-rendered-toggle"
+              onClick={() => setRaw(false)}
+            >
+              rendered
+            </Button>
+            <Button
+              variant={raw ? 'primary' : 'outline'}
+              size="xs"
+              data-testid="artifact-raw-toggle"
+              onClick={() => setRaw(true)}
+            >
+              raw
+            </Button>
+          </div>
+        ) : null}
+        <Button asChild variant="ghost" size="xs">
+          <a data-testid="artifact-download" href={downloadUrl} download>
+            download
+          </a>
+        </Button>
+        <Button
+          variant="ghost"
+          size="xs"
+          data-testid="artifact-reload"
+          onClick={() => setReloads((count) => count + 1)}
+        >
+          reload
+        </Button>
+      </div>
+      <div className="min-h-0 flex-1 overflow-auto rounded-md border border-doom-border bg-doom-deep p-4">
+        {error !== undefined ? (
+          <span data-testid="artifact-error" className="text-[10px] text-doom-yellow">
+            {error}
+          </span>
+        ) : content === undefined ? (
+          <span className="text-[10px] text-doom-faint">loading preview</span>
+        ) : (
+          <ArtifactPreview content={content} rawUrl={rawUrl} raw={raw} />
+        )}
+      </div>
+      {content?.truncated === true ? (
+        <span className="pt-2 text-[9px] text-doom-faint">
+          this preview shows the first {formatSize(content.text?.length)}; download the artifact for the complete file
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * The run directory, as the run pane's second tab.
+ *
+ * The workflow's own declaration leads, in the order it was written and
+ * including entries no job has produced yet, because the declaration is what
+ * the run is for. What the folder holds besides that follows.
+ */
+export function ArtifactsPane({ run, onOpen }: { run: WorkflowRunView; onOpen: (path: string) => void }) {
+  const [listing, setListing] = useState<WorkflowArtifactsResponse>();
+  const [error, setError] = useState<string>();
+
+  useEffect(() => {
+    let live = true;
+    const read = (): void => {
+      void fetchArtifacts(run.workspace, run.runKey).then((result) => {
+        if (!live) return;
+        if ('error' in result) {
+          setError(result.error);
+          return;
+        }
+        setError(undefined);
+        setListing(result.artifacts);
+      });
+    };
+    read();
+    // A running workflow writes while the pane is open; a settled one cannot,
+    // so it is read once and left alone.
+    if (run.stage !== 'running') return;
+    const timer = setInterval(read, 5_000);
+    return () => {
+      live = false;
+      clearInterval(timer);
+    };
+  }, [run.workspace, run.runKey, run.stage]);
+
+  const declared = listing?.artifacts.filter((entry) => entry.declared) ?? [];
+  const found = listing?.artifacts.filter((entry) => !entry.declared) ?? [];
+
+  const Row = ({ entry }: { entry: WorkflowArtifactView }) => {
+    const glyph = STATE_GLYPH[entry.state];
+    const openable = entry.kind === 'file' && entry.state !== 'pending';
+    return (
+      <button
+        type="button"
+        data-testid={`artifact-row-${entry.path}`}
+        data-artifact-state={entry.state}
+        disabled={!openable}
+        onClick={() => onOpen(entry.path)}
+        className={`flex flex-col gap-0.5 px-3 py-1.5 text-left ${openable ? 'cursor-pointer hover:bg-doom-panel' : 'cursor-default'}`}
+      >
+        <span className="flex min-w-0 items-center gap-2">
+          <span className={`w-3 shrink-0 text-[10px] ${glyph.className}`}>{glyph.glyph}</span>
+          <span className={`truncate text-[11px] ${entry.state === 'pending' ? 'text-doom-dim' : 'text-doom-hi'}`}>
+            {entry.path}
+          </span>
+          {entry.producedBy.length === 0 ? null : (
+            <Badge size="xs" tone="violet" className="shrink-0">
+              {entry.producedBy.join(', ')}
+            </Badge>
+          )}
+          <span className="min-w-0 flex-1" />
+          <span className="shrink-0 text-[9px] text-doom-faint">
+            {entry.state === 'pending'
+              ? 'not written yet'
+              : `${formatSize(entry.size)} · ${formatWhen(entry.modifiedAt)}`}
+          </span>
+        </span>
+        {entry.description === '' ? null : (
+          <span className="truncate pl-5 text-[9px] text-doom-faint">{entry.description}</span>
+        )}
+      </button>
+    );
+  };
+
+  return (
+    <div data-testid="artifacts-pane" className="flex min-h-0 flex-1 flex-col">
+      {error !== undefined ? (
+        <EmptyState className="py-4" title="the run directory cannot be read" description={error} />
+      ) : null}
+      {declared.length === 0 && found.length === 0 && error === undefined ? (
+        <EmptyState className="py-4" title="nothing in the run directory yet" />
+      ) : null}
+      {declared.length === 0 ? null : (
+        <>
+          <span className="px-3 pb-1 pt-2 text-[9px] font-bold tracking-[0.14em] text-doom-faint">
+            DECLARED · {listing?.description || 'run-directory'}
+          </span>
+          {declared.map((entry) => (
+            <Row key={entry.path} entry={entry} />
+          ))}
+        </>
+      )}
+      {found.length === 0 ? null : (
+        <>
+          <span className="px-3 pb-1 pt-3 text-[9px] font-bold tracking-[0.14em] text-doom-faint">
+            ALSO IN THE FOLDER
+          </span>
+          {found.map((entry) => (
+            <Row key={entry.path} entry={entry} />
+          ))}
+        </>
+      )}
+      {listing === undefined ? null : (
+        <span className="truncate px-3 py-2 text-[9px] text-doom-faint">{listing.runDir}</span>
+      )}
+    </div>
+  );
+}