@lumea-labs/orchestrator 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @lumea-labs/orchestrator
+
+Swarm + workflow primitives — SwarmProvider, RunCard / RunRow / RunDetail / RunKanban, PlanGraph (React Flow), PlanDetail.
+
+## Install
+
+```bash
+npm install @lumea-labs/orchestrator
+```
+
+## Usage
+
+```tsx
+import { /* … */ } from "@lumea-labs/orchestrator";
+```
+
+See the [Lumea Agents repo](https://github.com/Lumea-Technologies/lumea-agents/tree/main/packages/orchestrator) for the full source and a playground example.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { SwarmAdapter, SwarmAgentRef, SwarmArtifact, SwarmArtifactKind, SwarmCapabilities, SwarmCounts, SwarmEvaluation, SwarmLabels, SwarmRun, SwarmRunActivity, SwarmRunEvent, SwarmRunEventKind, SwarmRunStatus, SwarmStartInput, SwarmToolCall, WorkspaceMission, WorkspaceTask, WorkspaceTaskStatus, defaultSwarmLabels, deriveSwarmCapabilities } from './types.js';
+export { SwarmContextValue, SwarmProvider, SwarmProviderProps, useSwarm } from './orchestrator-document.js';
+export { Plan, PlanCheckpoint, PlanDelay, PlanDetailLabels, PlanGraphLabels, PlanQualityGate, PlanTask, PlanTaskRuntime, PlanTaskStatus, RunKanbanLabels, defaultPlanDetailLabels, defaultPlanGraphLabels, defaultRunKanbanLabels } from './plan-types.js';
+export { PlanGraph, PlanGraphProps, PlanGraphTaskRef } from './plan-graph.js';
+export { PlanDetail, PlanDetailBreakdown, PlanDetailBreakdownProps, PlanDetailGraph, PlanDetailGraphProps, PlanDetailHeader, PlanDetailHeaderProps, PlanDetailMasthead, PlanDetailMastheadProps, PlanDetailProps } from './plan-detail.js';
+export { PlanTaskActionConfig, PlanTaskActions, PlanTaskConfirmFn, PlanTaskDetail, PlanTaskDetailProps, PlanTaskDetailVariant } from './plan-task-detail.js';
+export { PlanCheckpointDetail, PlanCheckpointDetailProps, PlanDelayDetail, PlanDelayDetailProps, PlanQualityGateDetail, PlanQualityGateDetailProps } from './plan-node-detail.js';
+export { RunKanban, RunKanbanFilters, RunKanbanFiltersProps, RunKanbanGroupBy, RunKanbanLaneSummary, RunKanbanProps, summariseRunKanbanLanes } from './run-kanban.js';
+export { RunKanbanFilterMenu, RunKanbanFilterMenuProps } from './run-kanban-filter-menu.js';
+export { SwarmStatusPill, SwarmStatusPillProps } from './swarm-status-pill.js';
+export { SwarmAgentBadge, SwarmAgentBadgeProps } from './swarm-agent-badge.js';
+export { SwarmRunCard, SwarmRunCardProps } from './swarm-run-card.js';
+export { SwarmRunRow, SwarmRunRowProps } from './swarm-run-row.js';
+export { SwarmRunList, SwarmRunListProps } from './swarm-run-list.js';
+export { SwarmStatusBar, SwarmStatusBarProps } from './swarm-status-bar.js';
+export { SwarmRunDetail, SwarmRunDetailProps, SwarmRunDetailVariant } from './swarm-run-detail.js';
+export { BuildSwarmRunActivityOptions, SwarmRunActivityStream, SwarmRunActivityStreamProps, buildSwarmRunActivity } from './swarm-run-activity.js';
+export { SwarmRunActivityStreamSkeleton, SwarmRunActivityStreamSkeletonProps, SwarmRunDetailSkeleton, SwarmRunDetailSkeletonProps } from './swarm-skeletons.js';
+export { SwarmTimeline, SwarmTimelineProps } from './swarm-timeline.js';
+export { PlanOnlyTaskShape, RenderLinkArgs, RenderLinkFn, TaskWorkspaceSidebar, TaskWorkspaceSidebarLabels, TaskWorkspaceSidebarProps, defaultTaskWorkspaceSidebarLabels } from './task-workspace-sidebar.js';
+import 'react';

package/dist/index.js

@@ -0,0 +1,93 @@
+import { defaultSwarmLabels, deriveSwarmCapabilities } from "./types";
+import {
+  SwarmProvider,
+  useSwarm
+} from "./orchestrator-document";
+import {
+  defaultPlanGraphLabels,
+  defaultPlanDetailLabels,
+  defaultRunKanbanLabels
+} from "./plan-types";
+import { PlanGraph } from "./plan-graph";
+import {
+  PlanDetail,
+  PlanDetailHeader,
+  PlanDetailMasthead,
+  PlanDetailGraph,
+  PlanDetailBreakdown
+} from "./plan-detail";
+import {
+  PlanTaskDetail
+} from "./plan-task-detail";
+import {
+  PlanCheckpointDetail,
+  PlanQualityGateDetail,
+  PlanDelayDetail
+} from "./plan-node-detail";
+import {
+  RunKanban,
+  RunKanbanFilters,
+  summariseRunKanbanLanes
+} from "./run-kanban";
+import {
+  RunKanbanFilterMenu
+} from "./run-kanban-filter-menu";
+import { SwarmStatusPill } from "./swarm-status-pill";
+import { SwarmAgentBadge } from "./swarm-agent-badge";
+import { SwarmRunCard } from "./swarm-run-card";
+import { SwarmRunRow } from "./swarm-run-row";
+import { SwarmRunList } from "./swarm-run-list";
+import { SwarmStatusBar } from "./swarm-status-bar";
+import {
+  SwarmRunDetail
+} from "./swarm-run-detail";
+import {
+  SwarmRunActivityStream,
+  buildSwarmRunActivity
+} from "./swarm-run-activity";
+import {
+  SwarmRunDetailSkeleton,
+  SwarmRunActivityStreamSkeleton
+} from "./swarm-skeletons";
+import { SwarmTimeline } from "./swarm-timeline";
+import {
+  TaskWorkspaceSidebar,
+  defaultTaskWorkspaceSidebarLabels
+} from "./task-workspace-sidebar";
+export {
+  PlanCheckpointDetail,
+  PlanDelayDetail,
+  PlanDetail,
+  PlanDetailBreakdown,
+  PlanDetailGraph,
+  PlanDetailHeader,
+  PlanDetailMasthead,
+  PlanGraph,
+  PlanQualityGateDetail,
+  PlanTaskDetail,
+  RunKanban,
+  RunKanbanFilterMenu,
+  RunKanbanFilters,
+  SwarmAgentBadge,
+  SwarmProvider,
+  SwarmRunActivityStream,
+  SwarmRunActivityStreamSkeleton,
+  SwarmRunCard,
+  SwarmRunDetail,
+  SwarmRunDetailSkeleton,
+  SwarmRunList,
+  SwarmRunRow,
+  SwarmStatusBar,
+  SwarmStatusPill,
+  SwarmTimeline,
+  TaskWorkspaceSidebar,
+  buildSwarmRunActivity,
+  defaultPlanDetailLabels,
+  defaultPlanGraphLabels,
+  defaultRunKanbanLabels,
+  defaultSwarmLabels,
+  defaultTaskWorkspaceSidebarLabels,
+  deriveSwarmCapabilities,
+  summariseRunKanbanLanes,
+  useSwarm
+};

package/dist/lib/format.d.ts

@@ -0,0 +1,3 @@
+declare function elapsedSeconds(startedAt: string | undefined, finishedAt: string | undefined, now: number): number;
+
+export { elapsedSeconds };

package/dist/lib/format.js

@@ -0,0 +1,9 @@
+function elapsedSeconds(startedAt, finishedAt, now) {
+  if (!startedAt) return 0;
+  const start = new Date(startedAt).getTime();
+  const end = finishedAt ? new Date(finishedAt).getTime() : now;
+  return Math.max(0, (end - start) / 1e3);
+}
+export {
+  elapsedSeconds
+};

package/dist/orchestrator-document.d.ts

@@ -0,0 +1,37 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { SwarmRun, SwarmCounts, SwarmStartInput, SwarmCapabilities, SwarmLabels, SwarmAdapter } from './types.js';
+
+interface SwarmContextValue {
+    state: {
+        runs: SwarmRun[];
+        counts: SwarmCounts;
+        isLoading: boolean;
+        /** Monotonic clock tick — bumped every second so child components
+         *  can recompute live elapsed durations without owning a timer. */
+        now: number;
+    };
+    actions: {
+        refresh: () => Promise<void>;
+        start: (input: SwarmStartInput) => Promise<SwarmRun | null>;
+        cancel: (id: string) => Promise<void>;
+        retry: (id: string) => Promise<SwarmRun | null>;
+        cancelAll: () => Promise<void>;
+        retryFailed: () => Promise<void>;
+    };
+    capabilities: SwarmCapabilities;
+    meta: {
+        labels: SwarmLabels;
+    };
+}
+declare function useSwarm(): SwarmContextValue;
+interface SwarmProviderProps {
+    adapter: SwarmAdapter;
+    labels?: Partial<SwarmLabels>;
+    /** Auto-fetch via `adapter.list()` on mount. Default `true`. */
+    autoLoad?: boolean;
+    children: ReactNode;
+}
+declare function SwarmProvider({ adapter, labels, autoLoad, children, }: SwarmProviderProps): react.JSX.Element;
+
+export { type SwarmContextValue, SwarmProvider, type SwarmProviderProps, useSwarm };

package/dist/orchestrator-document.js

@@ -0,0 +1,122 @@
+"use client";
+import {
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import {
+  defaultSwarmLabels,
+  deriveSwarmCapabilities
+} from "./types";
+const Ctx = createContext(null);
+function useSwarm() {
+  const ctx = use(Ctx);
+  if (!ctx) throw new Error("useSwarm must be used inside <SwarmProvider>");
+  return ctx;
+}
+function SwarmProvider({
+  adapter,
+  labels,
+  autoLoad = true,
+  children
+}) {
+  const merged = useMemo(
+    () => ({ ...defaultSwarmLabels, ...labels }),
+    [labels]
+  );
+  const capabilities = useMemo(() => deriveSwarmCapabilities(adapter), [adapter]);
+  const adapterRef = useRef(adapter);
+  useEffect(() => {
+    adapterRef.current = adapter;
+  });
+  const [runs, setRuns] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const id = window.setInterval(() => setNow(Date.now()), 1e3);
+    return () => window.clearInterval(id);
+  }, []);
+  const refresh = useCallback(async () => {
+    if (!adapterRef.current.list) return;
+    setIsLoading(true);
+    try {
+      const next = await adapterRef.current.list();
+      setRuns(next);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+  useEffect(() => {
+    if (!adapterRef.current.subscribe) {
+      if (autoLoad) void refresh();
+      return;
+    }
+    const off = adapterRef.current.subscribe((next) => setRuns(next));
+    if (autoLoad) void refresh();
+    return off;
+  }, [autoLoad, refresh]);
+  const start = useCallback(
+    async (input) => {
+      if (!adapterRef.current.start) return null;
+      const run = await adapterRef.current.start(input);
+      setRuns((prev) => [run, ...prev.filter((r) => r.id !== run.id)]);
+      return run;
+    },
+    []
+  );
+  const cancel = useCallback(async (id) => {
+    if (!adapterRef.current.cancel) return;
+    await adapterRef.current.cancel(id);
+  }, []);
+  const retry = useCallback(
+    async (id) => {
+      if (!adapterRef.current.retry) return null;
+      const run = await adapterRef.current.retry(id);
+      setRuns((prev) => [run, ...prev.filter((r) => r.id !== run.id)]);
+      return run;
+    },
+    []
+  );
+  const cancelAll = useCallback(async () => {
+    if (!adapterRef.current.cancel) return;
+    const targets = runs.filter((r) => r.status === "running" || r.status === "pending");
+    await Promise.allSettled(targets.map((r) => adapterRef.current.cancel(r.id)));
+  }, [runs]);
+  const retryFailed = useCallback(async () => {
+    if (!adapterRef.current.retry) return;
+    const targets = runs.filter((r) => r.status === "failed");
+    await Promise.allSettled(targets.map((r) => adapterRef.current.retry(r.id)));
+  }, [runs]);
+  const counts = useMemo(() => {
+    const c = {
+      scheduled: 0,
+      pending: 0,
+      running: 0,
+      review: 0,
+      done: 0,
+      failed: 0,
+      cancelled: 0,
+      total: runs.length
+    };
+    for (const r of runs) c[r.status] += 1;
+    return c;
+  }, [runs]);
+  const value = useMemo(
+    () => ({
+      state: { runs, counts, isLoading, now },
+      actions: { refresh, start, cancel, retry, cancelAll, retryFailed },
+      capabilities,
+      meta: { labels: merged }
+    }),
+    [runs, counts, isLoading, now, refresh, start, cancel, retry, cancelAll, retryFailed, capabilities, merged]
+  );
+  return /* @__PURE__ */ React.createElement(Ctx, { value }, children);
+}
+export {
+  SwarmProvider,
+  useSwarm
+};

package/dist/plan-detail.d.ts

@@ -0,0 +1,102 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { PlanGraphTaskRef } from './plan-graph.js';
+import { Plan, PlanTaskRuntime, PlanDetailLabels, PlanGraphLabels } from './plan-types.js';
+import { SwarmAgentRef } from './types.js';
+
+interface PlanDetailHeaderProps {
+    plan: Plan;
+    runtimeByTitle?: Map<string, PlanTaskRuntime>;
+    /** Free-form brief / description band. */
+    briefSlot?: ReactNode;
+    /** Action dock — execute / abort / retry. */
+    actionsSlot?: ReactNode;
+    /** Leading slot in the header row — sits BEFORE the kicker. Use for
+     *  back / re-open buttons that should mirror a sidebar toggle. */
+    headerLeading?: ReactNode;
+    /** Trailing slot in the header row (e.g. id pill). */
+    headerTrailing?: ReactNode;
+    labels?: Partial<PlanDetailLabels>;
+    className?: string;
+}
+declare function PlanDetailHeader({ plan, runtimeByTitle, briefSlot, actionsSlot, headerLeading, headerTrailing, labels, className, }: PlanDetailHeaderProps): react.JSX.Element;
+interface PlanDetailMastheadProps {
+    plan: Plan;
+    runtimeByTitle?: Map<string, PlanTaskRuntime>;
+    briefSlot?: ReactNode;
+    actionsSlot?: ReactNode;
+    /** Leading slot — rendered before the kicker / title block. Use
+     *  for back / re-open buttons that mirror a sidebar toggle. */
+    headerLeading?: ReactNode;
+    headerTrailing?: ReactNode;
+    labels?: Partial<PlanDetailLabels>;
+    className?: string;
+}
+declare function PlanDetailMasthead({ plan, runtimeByTitle, briefSlot, actionsSlot, headerLeading, headerTrailing, labels, className, }: PlanDetailMastheadProps): react.JSX.Element;
+interface PlanDetailGraphProps {
+    plan: Plan;
+    runtimeByTitle?: Map<string, PlanTaskRuntime>;
+    agents?: SwarmAgentRef[];
+    /** Pixel height of the graph container. Default `720`. Ignored when
+     *  `fillHeight` is `true`. */
+    graphHeight?: number;
+    /** When `true`, the graph stretches to fill the available vertical
+     *  space inside a flex container — `flex-1 min-h-0` instead of a
+     *  fixed height. Use this when the parent is a `flex flex-col` and
+     *  you want the graph to grow as siblings collapse (e.g. the
+     *  breakdown section toggling closed). */
+    fillHeight?: boolean;
+    onOpenTask?: (ref: PlanGraphTaskRef) => void;
+    /** Forwarded to `<PlanGraph/>` — the canonical id of the currently
+     *  selected node (`task:<title>` | `cp:<name>` | `qg:<name>` |
+     *  `dl:<name>`). When set, the matching node renders in the strong
+     *  selected state. */
+    selectedNodeId?: string | null;
+    /** Forwarded to `<PlanGraph/>` — when true, the viewport animates
+     *  to centre + zoom on the selected node. */
+    zoomToSelected?: boolean;
+    /** Open callback for non-task nodes — same shape on both sides. */
+    onOpenCheckpoint?: (name: string) => void;
+    onOpenGate?: (name: string) => void;
+    onOpenDelay?: (name: string) => void;
+    graphLabels?: Partial<PlanGraphLabels>;
+    className?: string;
+}
+declare function PlanDetailGraph({ plan, runtimeByTitle, agents, graphHeight, fillHeight, onOpenTask, onOpenCheckpoint, onOpenGate, onOpenDelay, selectedNodeId, zoomToSelected, graphLabels, className, }: PlanDetailGraphProps): react.JSX.Element;
+interface PlanDetailBreakdownProps {
+    plan: Plan;
+    runtimeByTitle?: Map<string, PlanTaskRuntime>;
+    agents?: SwarmAgentRef[];
+    defaultOpen?: boolean;
+    /** Drop the chevron toggle and render the list always-open. */
+    alwaysOpen?: boolean;
+    onOpenTask?: (ref: PlanGraphTaskRef) => void;
+    labels?: Partial<PlanDetailLabels>;
+    className?: string;
+}
+declare function PlanDetailBreakdown({ plan, runtimeByTitle, agents, defaultOpen, alwaysOpen, onOpenTask, labels, className, }: PlanDetailBreakdownProps): react.JSX.Element;
+interface PlanDetailProps {
+    plan: Plan;
+    /** Runtime status overlay, keyed by task title. */
+    runtimeByTitle?: Map<string, PlanTaskRuntime>;
+    agents?: SwarmAgentRef[];
+    /** Brief / description block above the graph. */
+    briefSlot?: ReactNode;
+    /** Action dock — execute / abort / retry. */
+    actionsSlot?: ReactNode;
+    /** Trailing slot in the header (e.g. status pill, mono id). */
+    headerTrailing?: ReactNode;
+    /** Hide the per-task breakdown panel below the graph. */
+    hideBreakdown?: boolean;
+    /** Whether the breakdown starts open. Default true. */
+    defaultBreakdownOpen?: boolean;
+    /** Pixel height for the graph area. Default 720. */
+    graphHeight?: number;
+    onOpenTask?: (ref: PlanGraphTaskRef) => void;
+    labels?: Partial<PlanDetailLabels>;
+    graphLabels?: Partial<PlanGraphLabels>;
+    className?: string;
+}
+declare function PlanDetail({ plan, runtimeByTitle, agents, briefSlot, actionsSlot, headerTrailing, hideBreakdown, defaultBreakdownOpen, graphHeight, onOpenTask, labels, graphLabels, className, }: PlanDetailProps): react.JSX.Element;
+
+export { PlanDetail, PlanDetailBreakdown, type PlanDetailBreakdownProps, PlanDetailGraph, type PlanDetailGraphProps, PlanDetailHeader, type PlanDetailHeaderProps, PlanDetailMasthead, type PlanDetailMastheadProps, type PlanDetailProps };