@fungi.computer/trellis 0.2.1 → 0.2.3

package/src/runs/output-preview.tsx

@@ -0,0 +1,181 @@
+import * as z from "zod";
+import { useEffect, useState } from "react";
+import type { Json } from "@fungi.computer/braid";
+import type { RunStep } from "./run-state.js";
+import { versionRelativeTime } from "../history/relative-time.js";
+
+export type ReadMedia = (path: string, signal: AbortSignal) => Promise<Blob>;
+
+const mediaSchema = z.object({
+  destination: z.object({ path: z.string().startsWith("/").min(2).max(4096) }),
+  format: z.enum(["png", "jpeg", "gif", "webp", "mp4"]),
+});
+const messageSchema = z.object({ message: z.string() });
+
+/** Read one Computer file through the admitted reader into an object URL while mounted. */
+function useMediaPreview(path: string | undefined, readMedia?: ReadMedia) {
+  const [preview, setPreview] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  useEffect(() => {
+    setPreview(null);
+    setFailed(false);
+    if (!path || !readMedia) return;
+    const controller = new AbortController();
+    let url: string | undefined;
+    void readMedia(path, controller.signal).then(
+      (blob) => {
+        if (controller.signal.aborted) return;
+        url = URL.createObjectURL(blob);
+        setPreview(url);
+      },
+      () => {
+        if (!controller.signal.aborted) setFailed(true);
+      },
+    );
+    return () => {
+      controller.abort();
+      if (url) URL.revokeObjectURL(url);
+    };
+  }, [path, readMedia]);
+  return { preview, failed };
+}
+
+/** A small still of what a step made, for the leading edge of its timeline row. */
+export function MediaThumb({
+  media,
+  readMedia,
+}: {
+  media: Readonly<{ path: string; format: "fungi:image" | "fungi:video" }>;
+  readMedia?: ReadMedia | undefined;
+}) {
+  const { preview } = useMediaPreview(media.path, readMedia);
+  return (
+    <span className="wf-thumb" aria-hidden="true">
+      {preview === null ? null : media.format === "fungi:video" ? (
+        <video src={preview} muted preload="metadata" />
+      ) : (
+        <img src={preview} alt="" />
+      )}
+    </span>
+  );
+}
+
+/** Only the existing admitted Computer reader resolves media; result strings are never URLs. */
+export function OutputPreview({
+  value,
+  format,
+  readMedia,
+}: {
+  value: Json;
+  format?: string | undefined;
+  readMedia?: ReadMedia | undefined;
+}) {
+  const media = mediaSchema.safeParse(value);
+  const text = z.string().safeParse(value);
+  const path = media.success
+    ? media.data.destination.path
+    : text.success && ["fungi:image", "fungi:video"].includes(format ?? "")
+      ? text.data
+      : undefined;
+  const video = media.success
+    ? media.data.format === "mp4"
+    : format === "fungi:video";
+  const { preview, failed } = useMediaPreview(path, readMedia);
+  return (
+    <div className="wf-output-preview">
+      {preview ? (
+        video ? (
+          <video src={preview} controls aria-label="Step video output" />
+        ) : (
+          <img src={preview} alt="Step image output" />
+        )
+      ) : (
+        <pre>{text.success ? text.data : JSON.stringify(value, null, 2)}</pre>
+      )}
+      {path && !preview ? (
+        <p className="wf-muted">
+          {failed || !readMedia ? "Preview unavailable." : "Loading preview…"}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+export function OutputError({ error }: { error: Json }) {
+  const message = messageSchema.safeParse(error);
+  const text = z.string().safeParse(error);
+  return (
+    <p role="alert">
+      {message.success
+        ? message.data.message
+        : text.success
+          ? text.data
+          : JSON.stringify(error, null, 2)}
+    </p>
+  );
+}
+
+/** Shared result presentation for graph cards and the step list. */
+export function StepOutput({
+  step,
+  formats,
+  readMedia,
+}: {
+  step: RunStep;
+  formats?: Readonly<Record<string, string | undefined>>;
+  readMedia?: ReadMedia | undefined;
+}) {
+  const review = "reviewOutput" in step ? step.reviewOutput : undefined;
+  const recordedAt =
+    review && "recordedAt" in review ? review.recordedAt : undefined;
+  const decision =
+    review?.choice === "approved"
+      ? "Approved"
+      : review?.choice === "rejected"
+        ? "Rejected"
+        : review?.choice;
+  return (
+    <div className="wf-step-output">
+      {review ? (
+        <div>
+          <strong>
+            {decision}
+            {review.note ? `: ${review.note}` : ""}
+          </strong>
+          {recordedAt !== undefined ? (
+            <>
+              {" · "}
+              <time dateTime={new Date(recordedAt).toISOString()}>
+                {versionRelativeTime(new Date(recordedAt).toISOString())}
+              </time>
+            </>
+          ) : null}
+          <OutputPreview
+            value={review.value}
+            format={formats?.[review.choice]}
+            readMedia={readMedia}
+          />
+        </div>
+      ) : null}
+      {step.output !== undefined && review === undefined
+        ? Object.entries(step.output).map(([port, value]) => (
+            <div key={port}>
+              <strong>{port}</strong>
+              <OutputPreview
+                value={value}
+                format={formats?.[port]}
+                readMedia={readMedia}
+              />
+            </div>
+          ))
+        : null}
+      {step.state === "failed" ? (
+        <OutputError
+          error={step.errorMessage ?? step.refusal ?? "This step failed."}
+        />
+      ) : null}
+      {step.state === "complete" && step.output === undefined ? (
+        <p className="wf-muted">No output was recorded for this step.</p>
+      ) : null}
+    </div>
+  );
+}

package/src/runs/public.ts

@@ -0,0 +1,5 @@
+/** The existing Trellis run/step presentation, shared by first-party callers. */
+export { RunTimeline } from "./run-timeline.js";
+export { OutputError } from "./output-preview.js";
+export { runStatusSchema, runSteps, terminal } from "./run-state.js";
+export { timelineItems } from "./timeline-items.js";

package/src/runs/review-dock.tsx

@@ -0,0 +1,147 @@
+import * as S from "effect/Schema";
+import { fillReviewText, reviewAnswerSchema } from "@fungi.computer/braid";
+import { Input } from "@fungi.computer/caps/components/input";
+import { useState } from "react";
+import { Button } from "@fungi.computer/caps/components/button";
+import type { WorkflowClient } from "../workflow-client.js";
+import { stepPosition, type Review } from "./run-state.js";
+import { OutputPreview, type ReadMedia } from "./output-preview.js";
+import { NodeStatus } from "./node-status.js";
+/** The question a run is waiting on, docked where a composer sits. */
+export function ReviewDock({
+  runId,
+  review,
+  detail,
+  choices,
+  format,
+  readMedia,
+  answerReview,
+  onAnswered,
+}: {
+  runId: string;
+  review: Review;
+  /** The review node's line about where the run is, before its placeholders are filled. */
+  detail?: string | undefined;
+  choices?: readonly { id: string; label: string; description?: string }[];
+  format?: string;
+  readMedia?: ReadMedia;
+  answerReview: WorkflowClient["answerReview"];
+  onAnswered: () => void;
+}) {
+  const [note, setNote] = useState("");
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  async function answer(answer: typeof reviewAnswerSchema.Type) {
+    const decoded = S.decodeUnknownOption(reviewAnswerSchema)(answer, {
+      onExcessProperty: "error",
+    });
+    if (decoded._tag === "None") {
+      setError(
+        new Error(
+          "The review answer is invalid. Shorten your note and try again.",
+        ),
+      );
+      return;
+    }
+    setSending(true);
+    setError(null);
+    try {
+      const result = await answerReview({
+        runId,
+        nodeId: review.nodeId,
+        iteration: review.iteration,
+        answer: decoded.value,
+      });
+      if (result === "accepted") onAnswered();
+      else setError(new Error(result));
+    } catch (cause) {
+      setError(new Error("Could not send your answer. Try again.", { cause }));
+    } finally {
+      setSending(false);
+    }
+  }
+  const position = stepPosition(review);
+  const fill = (text: string | undefined) =>
+    text === undefined ? undefined : fillReviewText(text, position);
+  const where = fill(detail);
+  const choiceFor = (id: string) => choices?.find((choice) => choice.id === id);
+  const options = review.choices?.length
+    ? review.choices.map((id) => ({
+        id,
+        label: choiceFor(id)?.label ?? id,
+        description: fill(choiceFor(id)?.description),
+        answer: (): typeof reviewAnswerSchema.Type =>
+          note.length ? { choice: id, note } : { choice: id },
+      }))
+    : [
+        {
+          id: "approved",
+          label: "Approve",
+          description: undefined,
+          answer: (): typeof reviewAnswerSchema.Type => ({ approved: true }),
+        },
+        {
+          id: "rejected",
+          label: "Reject",
+          description: undefined,
+          answer: (): typeof reviewAnswerSchema.Type => ({ approved: false }),
+        },
+      ];
+  return (
+    <section className="wf-dock" aria-label="Review">
+      {review.show.length > 0 ? (
+        <div className="wf-dock-media">
+          {review.show.map((value, index) => (
+            <OutputPreview
+              key={index}
+              value={value}
+              format={index === 0 ? format : undefined}
+              readMedia={readMedia}
+            />
+          ))}
+        </div>
+      ) : null}
+      <div className="wf-dock-body">
+        <div className="wf-dock-waiting">
+          <NodeStatus state="waiting" label="Waiting on you" />
+        </div>
+        <h3>{review.title}</h3>
+        {where === undefined ? null : (
+          <p className="wf-dock-where wf-muted">{where}</p>
+        )}
+        <ul className="wf-dock-choices">
+          {options.map((option, index) => (
+            <li key={option.id}>
+              <Button
+                className="wf-dock-key"
+                variant={index === 0 ? "primary" : "outline"}
+                disabled={sending}
+                onClick={() => {
+                  void answer(option.answer());
+                }}
+              >
+                {option.label}
+              </Button>
+              {option.description === undefined ? null : (
+                <span className="wf-muted">{option.description}</span>
+              )}
+            </li>
+          ))}
+        </ul>
+        {review.choices?.length ? (
+          <Input
+            className="wf-dock-note"
+            aria-label="Note"
+            placeholder="Add a note (optional)"
+            value={note}
+            disabled={sending}
+            onChange={(event) => {
+              setNote(event.target.value);
+            }}
+          />
+        ) : null}
+        {error ? <p role="alert">{error.message}</p> : null}
+      </div>
+    </section>
+  );
+}

package/src/runs/run-state.ts

@@ -0,0 +1,187 @@
+import * as z from "zod";
+import * as S from "effect/Schema";
+import { resultRowSchemaV1 } from "@fungi.computer/agar";
+import { runOutcomeSchema } from "@fungi.computer/workflows-wire";
+import { loopPositionSchema } from "@fungi.computer/braid";
+const nodeStateSchema = z.enum([
+  "queued",
+  "running",
+  "waiting",
+  "complete",
+  "failed",
+  "skipped",
+]);
+const event = z.object({
+  nodeId: z.string(),
+  graphId: z.string().optional(),
+  iteration: z.string(),
+  /** Which Map item and Repeat try the runtime ran this in; decoded where it is shown. */
+  position: z.json().optional(),
+  state: nodeStateSchema,
+  attempt: z.number(),
+  recordedAt: z.number().int().nonnegative().optional(),
+  durationMs: z.number().optional(),
+  costMilliunits: z.number().optional(),
+  output: z.record(z.string(), z.json()).optional(),
+  /** How the App says this finished call reads; decoded where it is shown. */
+  row: z.json().optional(),
+  refusal: z.string().optional(),
+  errorMessage: z.string().max(1024).optional(),
+});
+const reviewSchema = z.object({
+  nodeId: z.string(),
+  iteration: z.string(),
+  position: z.json().optional(),
+  title: z.string(),
+  show: z.array(z.json()),
+  choices: z.array(z.string()).optional(),
+});
+export const runStatusSchema = z.object({
+  runId: z.string(),
+  planDigest: z.string(),
+  outcome: runOutcomeSchema,
+  title: z.string(),
+  events: z.array(event),
+  reviews: z.array(z.object({ review: reviewSchema, status: z.string() })),
+  status: z.string(),
+  output: z.json(),
+  error: z.json(),
+});
+export type RunStatus = z.output<typeof runStatusSchema>;
+export type Review = z.output<typeof reviewSchema>;
+export type NodeState = z.output<typeof nodeStateSchema> | "cancelled";
+/** Owner cancellation stops unfinished presentation without rewriting recorded events. */
+function runNodeState(
+  state: NodeState,
+  outcome: RunStatus["outcome"],
+): NodeState {
+  return outcome === "cancelled" &&
+    ["queued", "running", "waiting"].includes(state)
+    ? "cancelled"
+    : state;
+}
+export const terminal = (status: string) =>
+  ["complete", "errored", "failed", "terminated", "cancelled"].includes(status);
+/** Collapse each iteration/attempt to its latest event before summing facts. */
+export function runProgress(
+  events: RunStatus["events"],
+  outcome: RunStatus["outcome"] = "active",
+) {
+  const latest = new Map<string, RunStatus["events"][number]>();
+  const nodes: Record<string, NodeState> = {};
+  for (const event of events) {
+    latest.set(
+      `${event.nodeId}:${event.iteration}:${String(event.attempt)}`,
+      event,
+    );
+    nodes[event.nodeId] = runNodeState(event.state, outcome);
+  }
+  const recorded = [...latest.values()];
+  return {
+    nodes,
+    durationMs: recorded.some((e) => e.durationMs !== undefined)
+      ? recorded.reduce((sum, e) => sum + (e.durationMs ?? 0), 0)
+      : null,
+    costMilliunits: recorded.some((e) => e.costMilliunits !== undefined)
+      ? recorded.reduce((sum, e) => sum + (e.costMilliunits ?? 0), 0)
+      : null,
+  };
+}
+
+/** Latest lifecycle fact per graph node and iteration; each Map item keeps its own result. */
+export function runSteps(
+  events: RunStatus["events"],
+  outcome: RunStatus["outcome"],
+  reviews: RunStatus["reviews"] = [],
+) {
+  const latest = new Map<string, RunStatus["events"][number]>();
+  for (const event of events)
+    latest.set(
+      JSON.stringify([event.graphId ?? null, event.nodeId, event.iteration]),
+      event,
+    );
+  return [...latest.values()].map((event) => {
+    const reviewOutput = recordedReviewOutput(event, reviews);
+    const state = runNodeState(event.state, outcome);
+    if (reviewOutput === undefined) return { ...event, state };
+    return { ...event, state, reviewOutput };
+  });
+}
+
+const reviewOutputSchema = z.object({ choice: z.string(), note: z.string() });
+function recordedReviewOutput(
+  event: RunStatus["events"][number],
+  reviews: RunStatus["reviews"],
+) {
+  if (event.state !== "complete" || event.output === undefined) return;
+  const review = reviews.find(
+    ({ review }) =>
+      review.nodeId === event.nodeId && review.iteration === event.iteration,
+  );
+  if (review === undefined) return;
+  const answer = reviewOutputSchema.safeParse(event.output);
+  if (!answer.success) return;
+  const choices = review.review.choices ?? ["approved", "rejected"];
+  if (!choices.includes(answer.data.choice)) return;
+  const chosenOutput = Object.entries(event.output).find(
+    ([port]) => port === answer.data.choice,
+  );
+  if (chosenOutput === undefined) return;
+  return {
+    ...answer.data,
+    value: chosenOutput[1],
+    recordedAt: event.recordedAt,
+  };
+}
+
+export type RunStep = ReturnType<typeof runSteps>[number];
+
+/** The App's own reading of a finished step, when it declared one and it decodes. */
+export function stepRow(step: Readonly<{ row?: unknown }>) {
+  if (step.row === undefined) return undefined;
+  const decoded = S.decodeUnknownOption(resultRowSchemaV1)(step.row);
+  return decoded._tag === "Some" ? decoded.value : undefined;
+}
+
+/** Where the runtime ran a step or review; no position when it is unreadable. */
+export function stepPosition(step: Readonly<{ position?: unknown }>) {
+  if (step.position === undefined) return [];
+  const decoded = S.decodeUnknownOption(loopPositionSchema)(step.position);
+  return decoded._tag === "Some" ? decoded.value : [];
+}
+
+/** Which part of the Runs list a run belongs in. */
+export function runSection(run: RunStatus | undefined) {
+  if (run === undefined) return "running" as const;
+  if (run.outcome !== "active" || terminal(run.status))
+    return "finished" as const;
+  return run.reviews.some(({ status }) => status === "pending")
+    ? ("needs-you" as const)
+    : ("running" as const);
+}
+
+/** The bead a run wears in the list. */
+export function runBeadState(run: RunStatus | undefined): NodeState {
+  const section = runSection(run);
+  if (section === "needs-you") return "waiting";
+  if (section === "running") return "running";
+  if (run?.outcome === "cancelled") return "cancelled";
+  return run !== undefined &&
+    ["errored", "failed", "terminated"].includes(run.status)
+    ? "failed"
+    : "complete";
+}
+
+/** One plain line for the list: the open question, else the newest thing an App did. */
+export function runLatestLine(run: RunStatus | undefined) {
+  if (run === undefined) return undefined;
+  const pending = run.reviews.find(({ status }) => status === "pending");
+  if (run.outcome === "active" && pending) return pending.review.title;
+  for (const event of [...run.events].reverse()) {
+    const row = stepRow(event);
+    if (row) return row.title;
+  }
+  if (run.outcome === "cancelled") return "Cancelled";
+  if (["errored", "failed", "terminated"].includes(run.status)) return "Failed";
+  return runSection(run) === "finished" ? "Finished" : "Running";
+}

package/src/runs/run-timeline.css

@@ -0,0 +1,46 @@
+/* Steps are Parakeet call rows (Caps Disclosure + Status) at body size. */
+.wf-timeline {
+  --caps-disclosure-font-size: var(--text-sm);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+}
+.wf-step {
+  display: grid;
+  gap: var(--spacing-2xs);
+  min-width: 0;
+  padding-block: var(--spacing-2xs);
+  border-bottom: 1px solid
+    color-mix(in oklab, var(--color-base-content) 8%, transparent);
+}
+/* Muted details read at the row's own size, as in the tool timeline. */
+.wf-timeline .wf-muted {
+  font-size: inherit;
+  color: color-mix(in oklab, var(--color-base-content) 62%, transparent);
+}
+/* The quiet "Open in <App>" action trails its row, outside the toggle; the
+   action column is reserved on every row so beads line up. */
+.wf-step-row {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 7.5rem;
+  align-items: center;
+  gap: var(--spacing-xs);
+  min-width: 0;
+}
+.wf-step-row[data-open] {
+  align-items: start;
+}
+.wf-step-open {
+  justify-self: end;
+}
+@media (max-width: 720px) {
+  /* A phone keeps the title whole: the action sits under it, no thumbnail. */
+  .wf-step-row {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .wf-step-open {
+    justify-self: start;
+    margin-inline-start: var(--spacing-xl);
+  }
+}