@volter-ai-dev/supercode-ui 0.1.71 → 0.1.73

package/supervision.d.ts

@@ -0,0 +1,242 @@
+export type ReadStatus = 'ready' | 'loading' | 'error';
+export * from './source-inventory.js';
+export interface TaskRelation {
+  key: string;
+  label: string;
+  available: boolean;
+}
+export interface TaskAttempt {
+  key: string;
+  status: string;
+  profile: string;
+  startedAt: string;
+  endedAt: string;
+  error: string;
+  summary: string;
+  evidence: string;
+  sessionKey: string | null;
+}
+export interface TaskReview {
+  verdict: string;
+  by: string;
+  reason: string;
+  at: string;
+}
+export interface TaskComment {
+  author: string;
+  body: string;
+  at: string;
+}
+export interface WorkflowTask {
+  key: string;
+  id: string;
+  title: string;
+  lane: string;
+  assignee: string;
+  body: string;
+  note: string;
+  dependencies: TaskRelation[];
+  dependents: TaskRelation[];
+  attemptCount?: number;
+  reviewCount?: number;
+  commentCount?: number;
+  attempts: TaskAttempt[];
+  reviews: TaskReview[];
+  comments: TaskComment[];
+}
+export interface WorkflowBoardModel {
+  key: string;
+  title: string;
+  source: string;
+  status: ReadStatus;
+  stale: boolean;
+  total: number;
+  offset: number;
+  hasMore: boolean;
+  tasks: WorkflowTask[];
+}
+export interface JobModel {
+  key: string;
+  id: string;
+  title: string;
+  source: string;
+  harness: string;
+  profile: string;
+  schedule: string;
+  state: string;
+  enabled: boolean | null;
+  nextRunAt: string | null;
+  destination: string | null;
+  channelConnection: string;
+  canPause: boolean;
+  canResume?: boolean;
+  canRun?: boolean;
+  canDelete?: boolean;
+}
+export interface DeliveryModel {
+  state: string;
+  target: string;
+  attempts: number | null;
+  error: string;
+  deliveredAt: string;
+}
+export interface RunModel {
+  key: string;
+  id: string;
+  jobKey: string;
+  startedAt: string;
+  finishedAt: string;
+  execution: string;
+  error: string;
+  sessionKey: string | null;
+  delivery: DeliveryModel | null;
+}
+export interface JobControlResult {
+  key: string;
+  action: 'resume' | 'run' | 'delete';
+  confirmed: boolean;
+  deleted: boolean;
+  requested: boolean;
+}
+export interface JobControlsProps {
+  job: JobModel;
+  stale?: boolean;
+  onControl?(action: 'resume' | 'run' | 'delete', key: string): Promise<JobControlResult>;
+}
+export interface PauseResult {
+  job: JobModel;
+  confirmed: boolean;
+}
+export interface WorkflowBoardProps {
+  board: WorkflowBoardModel;
+  selectedKey?: string | null;
+  onSelect?(key: string | null): void;
+  onOpenSession?(key: string): void;
+  onLoadMore?(): void;
+  initialLayout?: 'board' | 'list';
+}
+export interface TaskCardProps {
+  task: WorkflowTask;
+  onOpen?(key: string, element: HTMLButtonElement): void;
+}
+export interface WorkflowListProps {
+  tasks?: WorkflowTask[];
+  onOpen?: TaskCardProps['onOpen'];
+}
+export interface TaskDetailsProps {
+  task: WorkflowTask;
+  onOpenTask?(key: string): void;
+  onOpenSession?(key: string): void;
+  onClose?(): void;
+}
+export interface DependencyListProps {
+  items?: TaskRelation[];
+  title?: string;
+  onOpen?(key: string): void;
+}
+export interface AttemptTimelineProps {
+  attempts?: TaskAttempt[];
+  onOpenSession?(key: string): void;
+}
+export interface HandoffCardProps {
+  attempt: TaskAttempt;
+}
+export interface ReviewCardProps {
+  review: TaskReview;
+}
+export interface TaskThreadProps {
+  comments?: TaskComment[];
+}
+export interface JobListProps {
+  jobs?: JobModel[];
+  onOpen?(key: string): void;
+}
+export interface JobDetailsProps {
+  job: JobModel;
+}
+export interface JobActionsProps {
+  job: JobModel;
+  stale?: boolean;
+  onPause?(key: string): Promise<PauseResult>;
+}
+export interface RunListProps {
+  runs?: RunModel[];
+  onOpen?(key: string, element: HTMLButtonElement): void;
+}
+export interface RunDetailsProps {
+  run: RunModel;
+  onClose?(): void;
+  onOpenSession?(key: string): void;
+}
+export interface DeliveryStatusProps {
+  delivery: DeliveryModel | null;
+}
+export interface OrchestrationJobsProps {
+  job: JobModel;
+  runs?: RunModel[];
+  status?: ReadStatus;
+  stale?: boolean;
+  selectedKey?: string | null;
+  onSelect?(key: string | null): void;
+  onPause?(key: string): Promise<PauseResult>;
+  onOpenSession?(key: string): void;
+}
+export function projectWorkflow(
+  read: unknown,
+  options?: {
+    sourceKey?: string;
+    title?: string;
+    limit?: number;
+    offset?: number;
+    sessionForAttempt?(attempt: any, task: any, board: any): string | null;
+  },
+): WorkflowBoardModel[];
+export function projectJobs(
+  listing: unknown,
+  options?: { sourceKey?: string; limit?: number; canPause?: boolean },
+): { status: ReadStatus; stale: boolean; total: number; jobs: JobModel[] };
+export function projectRuns(
+  listing: unknown,
+  options?: {
+    sourceKey?: string;
+    limit?: number;
+    sessionForRun?(run: any): string | null;
+    jobKey?: string;
+  },
+): { status: ReadStatus; runs: RunModel[] };
+export interface SupervisionSource {
+  key: string;
+  harness: 'hermes' | 'openclaw' | 'claude-code' | 'orchestrator';
+  home?: string;
+  homes?: Record<string, string>;
+  profile?: string;
+  allowPause?: boolean;
+  allowManage?: boolean;
+}
+export interface SupervisionHost {
+  workflow(
+    sourceKey: string,
+    page?: { offset?: number },
+  ): Promise<WorkflowBoardModel[]>;
+  jobs(sourceKey: string): Promise<ReturnType<typeof projectJobs>>;
+  runs(jobKey: string): Promise<ReturnType<typeof projectRuns>>;
+  pause(jobKey: string): Promise<PauseResult>;
+  control(action: 'resume' | 'run' | 'delete', jobKey: string): Promise<JobControlResult>;
+}
+/** Trusted-host use only. The client must be the native SDK or an equivalent typed adapter. */
+export function createSupervisionHost(options: {
+  client: {
+    workflowLoad(params: any): Promise<any>;
+    listJobs(params: any): Promise<any>;
+    listRuns(params: any): Promise<any>;
+    pauseJob(params: any): Promise<any>;
+    resumeJob?(params: any): Promise<any>;
+    runJob?(params: any): Promise<any>;
+    deleteJob?(params: any): Promise<any>;
+  };
+  sources: SupervisionSource[];
+  allowPause?: boolean;
+  allowManage?: boolean;
+  sessionForRun?(run: any): string | null;
+  sessionForAttempt?(attempt: any, task: any, board: any): string | null;
+}): SupervisionHost;

package/supervision.mjs

@@ -0,0 +1,349 @@
+/** Bounded, renderer-free projections over the native SDK's workflow/jobs/runs readers. */
+export { SOURCE_SECTIONS, projectSourceInventory, projectMemoryMatches, createSourceInventoryHost, projectApprovals, createApprovalHost, projectRuntimeState } from './source-inventory.mjs';
+const text = (value, max = 4000) =>
+  typeof value === 'string'
+    ? value.length > max
+      ? `${value.slice(0, max - 1)}…`
+      : value
+    : '';
+const array = (value) => (Array.isArray(value) ? value : []);
+const values = (value) =>
+  value && typeof value === 'object' ? Object.values(value) : [];
+const key = (...parts) =>
+  parts.map((part) => encodeURIComponent(String(part))).join(':');
+export function projectWorkflow(
+  read,
+  {
+    sourceKey = 'source',
+    title = 'Workflow',
+    limit = 100,
+    offset = 0,
+    sessionForAttempt,
+  } = {},
+) {
+  limit = Number.isFinite(limit)
+    ? Math.max(1, Math.min(500, Math.floor(limit)))
+    : 100;
+  offset = Number.isSafeInteger(offset) && offset >= 0 ? offset : 0;
+  const boards = values(read?.workflow?.boards).slice(0, 100);
+  return boards.map((board) => {
+    const all = values(board.tasks),
+      page = all.slice(offset, offset + limit);
+    const taskKey = (id) => key(sourceKey, board.slug, id);
+    return {
+      key: key(sourceKey, board.slug),
+      title: text(board.name || board.slug || title, 200),
+      source: sourceKey,
+      status: 'ready',
+      stale: false,
+      total: all.length,
+      offset,
+      hasMore: offset + page.length < all.length,
+      tasks: page.map((task) => ({
+        key: taskKey(task.id),
+        id: text(task.id, 200),
+        title: text(task.title, 500),
+        lane:
+          text(
+            task.lane === 'unknown'
+              ? task.residue?.status || task.lane
+              : task.lane,
+            100,
+          ) || 'unknown',
+        assignee: text(task.assignee, 200) || 'Unassigned',
+        body: text(task.body),
+        note: text(task.result, 500),
+        dependencies: array(board.dependencies)
+          .filter((edge) => edge.child === task.id)
+          .slice(0, 100)
+          .map((edge) => ({
+            key: taskKey(edge.parent),
+            label: text(board.tasks?.[edge.parent]?.title || edge.parent, 500),
+            available: all.some((t) => t.id === edge.parent),
+          })),
+        dependents: array(board.dependencies)
+          .filter((edge) => edge.parent === task.id)
+          .slice(0, 100)
+          .map((edge) => ({
+            key: taskKey(edge.child),
+            label: text(board.tasks?.[edge.child]?.title || edge.child, 500),
+            available: all.some((t) => t.id === edge.child),
+          })),
+        attemptCount: array(task.attempts).length,
+        reviewCount: array(task.reviews).length,
+        commentCount: array(task.comments).length,
+        attempts: array(task.attempts)
+          .slice(-50)
+          .reverse()
+          .map((attempt) => ({
+            key: text(attempt.id, 200),
+            status: text(attempt.status, 100),
+            profile: text(attempt.profile, 200),
+            startedAt: text(attempt.started_at, 100),
+            endedAt: text(attempt.ended_at, 100),
+            error: text(attempt.error),
+            summary: text(attempt.handoff?.summary),
+            evidence:
+              attempt.handoff?.metadata == null
+                ? ''
+                : text(JSON.stringify(attempt.handoff.metadata, null, 2)),
+            sessionKey: sessionForAttempt?.(attempt, task, board) || null,
+          })),
+        reviews: array(task.reviews)
+          .slice(-50)
+          .reverse()
+          .map((review) => ({
+            verdict: text(review.verdict, 100),
+            by: text(review.by, 200),
+            reason: text(review.reason),
+            at: text(review.at, 100),
+          })),
+        comments: array(task.comments)
+          .slice(-50)
+          .map((comment) => ({
+            author: text(comment.author, 200),
+            body: text(comment.body),
+            at: text(comment.at, 100),
+          })),
+      })),
+    };
+  });
+}
+export function projectJobs(
+  listing,
+  { sourceKey = 'source', limit = 100, canPause = false } = {},
+) {
+  limit = Number.isFinite(limit)
+    ? Math.max(1, Math.min(500, Math.floor(limit)))
+    : 100;
+  const unreadable = array(listing?.sources).some(
+    (source) => source.state === 'unreadable',
+  );
+  return {
+    status: unreadable ? 'error' : 'ready',
+    stale: unreadable,
+    total: array(listing?.jobs).length,
+    jobs: array(listing?.jobs)
+      .slice(0, limit)
+      .map((job) => ({
+        key: key(
+          sourceKey,
+          job.harness,
+          job.profile || '',
+          job.session_id || '',
+          job.id,
+        ),
+        id: text(job.id, 200),
+        title: text(job.name || job.title || text(job.payload?.text, 120).split('\n')[0], 120) || 'Scheduled task',
+        source: sourceKey,
+        harness: text(job.harness, 100),
+        profile: text(job.profile, 200),
+        schedule: text(job.schedule?.display, 500) || 'Unknown schedule',
+        state: text(job.state, 100) || 'unknown',
+        enabled: typeof job.enabled === 'boolean' ? job.enabled : null,
+        nextRunAt: text(job.next_run_at, 100) || null,
+        destination: text(job.deliver?.target, 500) || null,
+        channelConnection: 'Unknown',
+        canPause:
+          !unreadable &&
+          canPause &&
+          ['hermes', 'openclaw', 'orchestrator'].includes(job.harness) &&
+          job.enabled === true,
+      })),
+  };
+}
+export function projectRuns(
+  listing,
+  { sourceKey = 'source', limit = 100, sessionForRun, jobKey } = {},
+) {
+  limit = Number.isFinite(limit)
+    ? Math.max(1, Math.min(500, Math.floor(limit)))
+    : 100;
+  return {
+    status: array(listing?.sources).some(
+      (source) => source.state === 'unreadable',
+    )
+      ? 'error'
+      : 'ready',
+    runs: array(listing?.runs)
+      .slice(0, limit)
+      .map((run) => ({
+        key: key(sourceKey, run.harness, run.id),
+        id: text(run.id, 200),
+        jobKey: jobKey || key(sourceKey, run.harness, '', '', run.job_id),
+        startedAt: text(run.started_at || run.claimed_at, 100),
+        finishedAt: text(run.finished_at, 100),
+        execution: text(run.status, 100) || 'unknown',
+        error: text(run.error),
+        sessionKey: sessionForRun?.(run) || null,
+        delivery:
+          run.delivery == null
+            ? null
+            : {
+                state: text(run.delivery.state, 100) || 'unknown',
+                target: text(run.delivery.target, 500),
+                attempts:
+                  Number.isSafeInteger(run.delivery.attempts) &&
+                  run.delivery.attempts >= 0
+                    ? run.delivery.attempts
+                    : null,
+                error: text(run.delivery.last_error),
+                deliveredAt: text(run.delivery.delivered_at, 100),
+              },
+      })),
+  };
+}
+
+/** Trusted-host binding: sources, native ids, homes and write policy never come from browser intents. */
+export function createSupervisionHost({
+  client,
+  sources,
+  allowPause = false,
+  allowManage = false,
+  sessionForRun,
+  sessionForAttempt,
+}) {
+  const sourceMap = new Map(sources.map((source) => [source.key, source]));
+  if (sourceMap.size !== sources.length)
+    throw new Error('Source keys must be unique');
+  const jobs = new Map();
+  const reads = new Map();
+  const sourceFor = (sourceKey) => {
+    const source = sourceMap.get(sourceKey);
+    if (!source) throw new Error('Unknown source');
+    return source;
+  };
+  return {
+    async workflow(sourceKey, page = {}) {
+      const source = sourceFor(sourceKey);
+      if (source.harness !== 'hermes' || !source.home)
+        throw new Error('Workflow reading is unavailable for this source');
+      const offset =
+        Number.isSafeInteger(page.offset) && page.offset >= 0 ? page.offset : 0;
+      return projectWorkflow(
+        await client.workflowLoad({ from: 'hermes', home: source.home }),
+        { sourceKey, offset, sessionForAttempt },
+      );
+    },
+    async jobs(sourceKey) {
+      const source = sourceFor(sourceKey);
+      const revision = (reads.get(sourceKey) || 0) + 1;
+      reads.set(sourceKey, revision);
+      // Revoke the previous observation before reading: a failed or superseded
+      // refresh must not leave an old mutation capability usable.
+      for (const [id, value] of jobs)
+        if (value.source.key === sourceKey) jobs.delete(id);
+      const listing = await client.listJobs({
+        harness: source.harness,
+        homes: source.homes,
+        profile: source.profile,
+      });
+      if (reads.get(sourceKey) !== revision)
+        throw new Error('Job read was superseded; refresh its source');
+      const projection = projectJobs(listing, {
+        sourceKey,
+        canPause: allowPause && source.allowPause === true,
+      });
+      projection.jobs.forEach((job, index) => {
+        const native = listing.jobs[index];
+        const store = listing.sources?.find(
+          (store) =>
+            store.harness === native.harness &&
+            (store.profile || null) === (native.profile || null),
+        );
+        const nativeHome =
+          ['hermes', 'orchestrator'].includes(native.harness) &&
+          /[\\/]cron[\\/]jobs\.json$/.test(store?.path || '')
+            ? store.path.replace(/[\\/]cron[\\/]jobs\.json$/, '')
+            : null;
+        const homes = nativeHome
+          ? { ...source.homes, ...(native.harness === 'orchestrator' ? { orchestrator: nativeHome } : { hermes: `${nativeHome}/state.db` }) }
+          : source.homes;
+        const ambiguous = listing.jobs.some(
+            (other) =>
+              other !== native &&
+              other.harness === native.harness &&
+              other.id === native.id &&
+              (!native.profile || !other.profile || other.profile === native.profile),
+          );
+        job.canPause = job.canPause && !ambiguous && typeof client.pauseJob === 'function';
+        const controlled = allowManage && source.allowManage === true && !projection.stale && !ambiguous && ['hermes', 'openclaw', 'orchestrator'].includes(native.harness);
+        job.canResume = !!(controlled && native.enabled === false && typeof client.resumeJob === 'function');
+        job.canRun = !!(controlled && native.enabled === true && typeof client.runJob === 'function');
+        job.canDelete = !!(controlled && typeof client.deleteJob === 'function');
+        jobs.set(job.key, { source, native, current: job, homes, ambiguous });
+      });
+      return projection;
+    },
+    async runs(jobKey) {
+      const job = jobs.get(jobKey);
+      if (!job) throw new Error('Unknown job; refresh its source');
+      if (job.ambiguous)
+        throw new Error('Run history is ambiguous across native profiles');
+      if (!['hermes', 'openclaw', 'orchestrator'].includes(job.native.harness))
+        throw new Error('Run history is unavailable for this source');
+      return projectRuns(
+        await client.listRuns({
+          harness: job.native.harness,
+          job: job.native.id,
+          homes: job.homes,
+          limit: 100,
+        }),
+        { sourceKey: job.source.key, sessionForRun, jobKey },
+      );
+    },
+    async control(action, jobKey) {
+      const job = jobs.get(jobKey);
+      const capability = { resume: 'canResume', run: 'canRun', delete: 'canDelete' }[action];
+      if (!capability || !job?.current[capability] || !allowManage || job.source.allowManage !== true)
+        throw new Error('This control is unavailable for the selected job');
+      const result = await client[`${action}Job`]({ harness: job.native.harness, id: job.native.id,
+        homes: job.source.homes, profile: job.native.profile || job.source.profile });
+      if (result.verb !== action || result.id !== job.native.id ||
+        (action === 'delete' ? result.deleted !== true || result.job != null :
+          result.job?.id !== job.native.id || result.job?.harness !== job.native.harness ||
+          (result.job?.profile || null) !== (job.native.profile || null) ||
+          (action === 'resume' && result.job?.enabled !== true)))
+        throw new Error(`The source did not confirm ${action}`);
+      if (action === 'delete') {
+        // The same native job can appear in both an aggregate and a profile
+        // source. Revoke every cached alias of the confirmed deletion.
+        for (const [key, cached] of jobs)
+          if (cached.native.harness === job.native.harness && cached.native.id === job.native.id &&
+            (cached.native.profile || null) === (job.native.profile || null)) jobs.delete(key);
+      }
+      // A run receipt means queued/requested, never completed execution.
+      return { key: jobKey, action, confirmed: true, deleted: action === 'delete', requested: action === 'run' };
+    },
+    async pause(jobKey) {
+      const job = jobs.get(jobKey);
+      if (
+        !job?.current.canPause ||
+        !allowPause ||
+        job.source.allowPause !== true
+      )
+        throw new Error('Pause is unavailable for this source');
+      const result = await client.pauseJob({
+        harness: job.native.harness,
+        id: job.native.id,
+        homes: job.source.homes,
+        profile: job.native.profile || job.source.profile,
+      });
+      if (
+        result.verb !== 'pause' ||
+        result.id !== job.native.id ||
+        result.job?.id !== job.native.id ||
+        result.job?.harness !== job.native.harness ||
+        result.job?.enabled !== false ||
+        (result.job?.profile || null) !== (job.native.profile || null)
+      )
+        throw new Error('The source did not confirm the paused job');
+      const updated = projectJobs(
+        { jobs: [result.job], sources: [] },
+        { sourceKey: job.source.key },
+      ).jobs[0];
+      jobs.set(jobKey, { ...job, native: result.job, current: updated });
+      return { job: updated, confirmed: true };
+    },
+  };
+}