@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/run/VariableInspector.tsx

@@ -0,0 +1,198 @@
+// VariableInspector: for each node in execution order, the variables it
+// consumes and produces, so authors can trace data through the flow.
+
+import { ChevronRight } from 'lucide-react'
+import { Button as AriaButton, Disclosure, DisclosureGroup, DisclosurePanel, Heading } from 'react-aria-components'
+import { useRenderCatalog } from '../catalog/RenderCatalog'
+import { DockedPanel } from '../internal/DockedPanel'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import { topologicalOrder } from '../model/graph'
+import type { FlowNode } from '../model/types'
+import { useFlowEditorState } from '../state/editorState'
+
+export type VariableType = 'any' | 'array' | 'number' | 'boolean' | 'string'
+
+export interface InferredVariable {
+  name: string
+  type: VariableType
+}
+
+export interface NodeVariables {
+  inputs: InferredVariable[]
+  outputs: InferredVariable[]
+}
+
+const cfg = (n: FlowNode): Record<string, unknown> => (n.data.config && typeof n.data.config === 'object' ? (n.data.config as Record<string, unknown>) : n.data)
+
+const names = (v: unknown): string[] =>
+  Array.isArray(v) ? v.map((x) => (typeof x === 'string' ? x : x && typeof x === 'object' && typeof (x as { name?: unknown }).name === 'string' ? (x as { name: string }).name : '')).filter(Boolean) : []
+
+const str = (v: unknown, fallback: string) => (typeof v === 'string' && v ? v : fallback)
+
+/** Variables a node consumes and produces, inferred from its kind and configuration. */
+export function inferVariables(node: FlowNode): NodeVariables {
+  const c = cfg(node)
+  switch (node.kind) {
+    case 'start':
+      return { inputs: [], outputs: names(c.inputVariables).map((name) => ({ name, type: 'any' })) }
+    case 'end':
+      return { inputs: names(c.outputs ?? c.outputVariables).map((name) => ({ name, type: 'any' })), outputs: [] }
+    case 'code':
+    case 'compute': {
+      const expr = (c.expression ?? c.root ?? c) as Record<string, unknown>
+      return { inputs: [{ name: str(expr.operation, 'input'), type: 'any' }], outputs: [{ name: str(c.outputVariable, 'result'), type: 'any' }] }
+    }
+    case 'if-else':
+    case 'branch': {
+      const conditions = Array.isArray(c.conditions) ? (c.conditions as Array<Record<string, unknown>>) : []
+      const vars = [...new Set(conditions.map((x) => str(x.variable ?? x.ref, '')).filter(Boolean))]
+      return { inputs: vars.map((name) => ({ name, type: 'any' })), outputs: [{ name: 'true', type: 'boolean' }, { name: 'false', type: 'boolean' }] }
+    }
+    case 'iteration':
+    case 'loop':
+      return { inputs: [{ name: str(c.collection ?? c.iterator, 'items'), type: 'array' }], outputs: [{ name: 'item', type: 'any' }, { name: 'index', type: 'number' }] }
+    case 'answer':
+      return { inputs: [{ name: str(c.templateName, 'template'), type: 'string' }], outputs: names(c.outputs).map((name) => ({ name, type: 'any' })) }
+    default:
+      return { inputs: [], outputs: [] }
+  }
+}
+
+export interface VariableInspectorLabels {
+  title: string
+  close: string
+  inputs: string
+  outputs: string
+  variables: string
+  noVariables: string
+  noNodes: string
+  any: string
+  array: string
+  number: string
+  boolean: string
+  string: string
+}
+
+export const variableInspectorLabels = defineLabels<VariableInspectorLabels>('variable-inspector', {
+  en: {
+    title: 'Variables',
+    close: 'Close variables',
+    inputs: 'Inputs',
+    outputs: 'Outputs',
+    variables: '{count, plural, =0 {no variables} one {# variable} other {# variables}}',
+    noVariables: 'This step neither reads nor writes variables.',
+    noNodes: 'Add steps to the flow to see their variables.',
+    any: 'any',
+    array: 'list',
+    number: 'number',
+    boolean: 'true or false',
+    string: 'text',
+  },
+  'pt-BR': {
+    title: 'Variáveis',
+    close: 'Fechar variáveis',
+    inputs: 'Entradas',
+    outputs: 'Saídas',
+    variables: '{count, plural, =0 {nenhuma variável} one {# variável} other {# variáveis}}',
+    noVariables: 'Este passo não lê nem escreve variáveis.',
+    noNodes: 'Adicione passos ao fluxo para ver suas variáveis.',
+    any: 'qualquer',
+    array: 'lista',
+    number: 'número',
+    boolean: 'verdadeiro ou falso',
+    string: 'texto',
+  },
+  es: {
+    title: 'Variables',
+    close: 'Cerrar variables',
+    inputs: 'Entradas',
+    outputs: 'Salidas',
+    variables: '{count, plural, =0 {sin variables} one {# variable} other {# variables}}',
+    noVariables: 'Este paso no lee ni escribe variables.',
+    noNodes: 'Agregue pasos al flujo para ver sus variables.',
+    any: 'cualquiera',
+    array: 'lista',
+    number: 'número',
+    boolean: 'verdadero o falso',
+    string: 'texto',
+  },
+})
+export const defaultVariableInspectorLabels: VariableInspectorLabels = variableInspectorLabels.bundles.en
+
+export interface VariableInspectorProps {
+  open: boolean
+  onClose: () => void
+  labels?: Partial<VariableInspectorLabels>
+}
+
+export function VariableInspector({ open, onClose, labels }: VariableInspectorProps) {
+  if (!open) return null
+  return <InspectorBody onClose={onClose} labels={labels} />
+}
+
+function InspectorBody({ onClose, labels }: Omit<VariableInspectorProps, 'open'>) {
+  const l = useLabels(variableInspectorLabels, labels)
+  const { locale } = useFlowLocale()
+  const catalog = useRenderCatalog()
+  const nodes = useFlowEditorState((s) => s.nodes)
+  const connectors = useFlowEditorState((s) => s.connectors)
+  const steps = nodes.filter((n) => n.kind !== 'note')
+  const byId = new Map(steps.map((n) => [n.id, n]))
+  const ordered = topologicalOrder(
+    steps.map((n) => n.id),
+    connectors,
+  ).map((id) => byId.get(id)!)
+
+  const varList = (vars: InferredVariable[], heading: string) => (
+    <section className="ty-variables__group">
+      <h4 className="ty-run-subtitle">{heading}</h4>
+      <ul className="ty-variables__list">
+        {vars.map((v) => (
+          <li key={v.name} className="ty-variables__item">
+            <code className="ty-run-mono">{v.name}</code>
+            <span className="ty-variables__type">{l[v.type]}</span>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+
+  return (
+    <DockedPanel title={l.title} onClose={onClose} closeLabel={l.close} className="ty-variables">
+      {ordered.length === 0 ? (
+        <p className="ty-run-empty">{l.noNodes}</p>
+      ) : (
+        <DisclosureGroup allowsMultipleExpanded className="ty-variables__entries">
+          {ordered.map((n) => {
+            const vars = inferVariables(n)
+            const count = vars.inputs.length + vars.outputs.length
+            const Icon = catalog.icon(n.kind)
+            const label = typeof n.data.label === 'string' && n.data.label ? n.data.label : (catalog.entry(n.kind)?.label ?? n.id)
+            return (
+              <Disclosure key={n.id} id={n.id} className="ty-variables__entry">
+                <Heading level={3} className="ty-variables__heading">
+                  <AriaButton slot="trigger" className="ty-variables__trigger">
+                    <ChevronRight className="ty-variables__chevron ty-run-mirror" aria-hidden="true" focusable="false" />
+                    <Icon className="ty-variables__icon" aria-hidden="true" focusable="false" />
+                    <span className="ty-variables__label">{label}</span>
+                    <span className="ty-variables__count">{fill(l.variables, { count }, locale)}</span>
+                  </AriaButton>
+                </Heading>
+                <DisclosurePanel className="ty-variables__panel">
+                  {count === 0 ? (
+                    <p className="ty-run-hint">{l.noVariables}</p>
+                  ) : (
+                    <>
+                      {vars.inputs.length ? varList(vars.inputs, l.inputs) : null}
+                      {vars.outputs.length ? varList(vars.outputs, l.outputs) : null}
+                    </>
+                  )}
+                </DisclosurePanel>
+              </Disclosure>
+            )
+          })}
+        </DisclosureGroup>
+      )}
+    </DockedPanel>
+  )
+}

package/src/flow/run/VersionHistoryPanel.tsx

@@ -0,0 +1,178 @@
+// VersionHistoryPanel: the published versions of a flow, newest first; each
+// can be previewed read-only or restored as the working draft (the host
+// confirms). The live version is marked by a word and a border.
+
+import { useEffect, useState } from 'react'
+import { ActorChip, Button, InlineNotice, Skeleton } from '../../index'
+import { DockedPanel } from '../internal/DockedPanel'
+import { formatDateTime } from '../internal/format'
+import { defineLabels, fill, useFlowLocale, useLabels } from '../internal/labels'
+import type { RunActor } from './types'
+
+export interface FlowVersion {
+  number: number
+  publishedAt: string
+  publishedBy: RunActor
+  nodeCount: number
+  connectorCount: number
+}
+
+export interface VersionHistoryPanelLabels {
+  title: string
+  close: string
+  loading: string
+  error: string
+  retry: string
+  empty: string
+  current: string
+  version: string
+  publishedBy: string
+  counts: string
+  preview: string
+  restore: string
+}
+
+export const versionHistoryPanelLabels = defineLabels<VersionHistoryPanelLabels>('VersionHistoryPanel', {
+  en: {
+    title: 'Versions',
+    close: 'Close versions',
+    loading: 'Loading versions',
+    error: 'Versions could not be loaded: {message}',
+    retry: 'Try again',
+    empty: 'No version has been published yet.',
+    current: 'current',
+    version: 'Version {number, number}',
+    publishedBy: 'Published by',
+    counts: '{nodes, plural, one {# node} other {# nodes}}, {connectors, plural, one {# connector} other {# connectors}}',
+    preview: 'Preview version {number, number}',
+    restore: 'Restore version {number, number}',
+  },
+  'pt-BR': {
+    title: 'Versões',
+    close: 'Fechar versões',
+    loading: 'Carregando versões',
+    error: 'Não foi possível carregar as versões: {message}',
+    retry: 'Tentar de novo',
+    empty: 'Nenhuma versão foi publicada ainda.',
+    current: 'atual',
+    version: 'Versão {number, number}',
+    publishedBy: 'Publicada por',
+    counts: '{nodes, plural, one {# nó} other {# nós}}, {connectors, plural, one {# conexão} other {# conexões}}',
+    preview: 'Ver versão {number, number}',
+    restore: 'Restaurar versão {number, number}',
+  },
+  es: {
+    title: 'Versiones',
+    close: 'Cerrar versiones',
+    loading: 'Cargando versiones',
+    error: 'No se pudieron cargar las versiones: {message}',
+    retry: 'Reintentar',
+    empty: 'Aún no se ha publicado ninguna versión.',
+    current: 'actual',
+    version: 'Versión {number, number}',
+    publishedBy: 'Publicada por',
+    counts: '{nodes, plural, one {# nodo} other {# nodos}}, {connectors, plural, one {# conexión} other {# conexiones}}',
+    preview: 'Ver versión {number, number}',
+    restore: 'Restaurar versión {number, number}',
+  },
+})
+
+export const defaultVersionHistoryPanelLabels: VersionHistoryPanelLabels = versionHistoryPanelLabels.bundles.en
+
+export interface VersionHistoryPanelProps {
+  open: boolean
+  onClose: () => void
+  flowId: string
+  currentVersion: number
+  loadVersions?: (flowId: string) => Promise<FlowVersion[]>
+  onPreview: (version: FlowVersion) => void
+  onRestore: (version: FlowVersion) => void
+  labels?: Partial<VersionHistoryPanelLabels>
+  returnFocusTo?: HTMLElement | null
+}
+
+type State = { kind: 'loading' } | { kind: 'error'; message: string } | { kind: 'ready'; versions: FlowVersion[] }
+
+export function VersionHistoryPanel(props: VersionHistoryPanelProps) {
+  const { open, onClose, flowId, currentVersion, loadVersions, onPreview, onRestore, returnFocusTo } = props
+  const l = useLabels(versionHistoryPanelLabels, props.labels)
+  const { locale } = useFlowLocale()
+  const [state, setState] = useState<State>({ kind: 'loading' })
+  const [attempt, setAttempt] = useState(0)
+
+  useEffect(() => {
+    if (!open) return
+    if (!loadVersions) {
+      setState({ kind: 'ready', versions: [] })
+      return
+    }
+    let live = true
+    setState({ kind: 'loading' })
+    loadVersions(flowId).then(
+      (versions) => live && setState({ kind: 'ready', versions: [...versions].sort((a, b) => b.number - a.number) }),
+      (e: unknown) => live && setState({ kind: 'error', message: e instanceof Error ? e.message : String(e) }),
+    )
+    return () => {
+      live = false
+    }
+  }, [open, flowId, loadVersions, attempt])
+
+  if (!open) return null
+
+  return (
+    <DockedPanel title={l.title} landmark="complementary" onClose={onClose} closeLabel={l.close} returnFocusTo={returnFocusTo ?? null} busy={state.kind === 'loading'} className="ty-versions">
+      <p className="ty-visually-hidden" role="status" aria-live="polite">
+        {state.kind === 'loading' ? l.loading : state.kind === 'error' ? fill(l.error, { message: state.message }, locale) : ''}
+      </p>
+      {state.kind === 'loading' ? (
+        <div aria-busy="true">
+          <Skeleton lines={3} />
+        </div>
+      ) : state.kind === 'error' ? (
+        <InlineNotice
+          tone="danger"
+          urgency="none"
+          actions={
+            <Button variant="secondary" size="compact" onPress={() => setAttempt((a) => a + 1)}>
+              {l.retry}
+            </Button>
+          }
+        >
+          {fill(l.error, { message: state.message }, locale)}
+        </InlineNotice>
+      ) : state.versions.length === 0 ? (
+        <p className="ty-run-empty">{l.empty}</p>
+      ) : (
+        <ul className="ty-versions__list">
+          {state.versions.map((v) => {
+            const current = v.number === currentVersion
+            return (
+              <li key={v.number} className="ty-versions__entry" data-current={current ? 'true' : 'false'}>
+                <div className="ty-versions__head">
+                  <span className="ty-versions__number">{fill(l.version, { number: v.number }, locale)}</span>
+                  {current ? <span className="ty-versions__current">{l.current}</span> : null}
+                </div>
+                <div className="ty-versions__meta">
+                  <span className="ty-visually-hidden">{l.publishedBy}</span>
+                  <ActorChip kind={v.publishedBy.kind} name={v.publishedBy.name} compact {...(v.publishedBy.agentKey ? { agentKey: v.publishedBy.agentKey } : {})} {...(v.publishedBy.model ? { model: v.publishedBy.model } : {})} />
+                  <time dateTime={v.publishedAt}>{formatDateTime(v.publishedAt, locale)}</time>
+                  <span>{fill(l.counts, { nodes: v.nodeCount, connectors: v.connectorCount }, locale)}</span>
+                </div>
+                <div className="ty-versions__actions">
+                  <Button variant="secondary" size="compact" onPress={() => onPreview(v)}>
+                    {fill(l.preview, { number: v.number }, locale)}
+                  </Button>
+                  {current ? null : (
+                    <Button variant="quiet" size="compact" onPress={() => onRestore(v)}>
+                      {fill(l.restore, { number: v.number }, locale)}
+                    </Button>
+                  )}
+                </div>
+              </li>
+            )
+          })}
+        </ul>
+      )}
+    </DockedPanel>
+  )
+}

package/src/flow/run/execution.ts

@@ -0,0 +1,187 @@
+// RunExecutionState: start and stop a run through host transport, follow its
+// event stream and project the events onto FlowEditorState.
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { useOptionalFlowEditorStore, type FlowEditorActions } from '../state/editorState'
+import type { RunEvent, StreamStatus } from './types'
+
+type ProjectionActions = Pick<FlowEditorActions, 'setRunning' | 'setNodeResult' | 'clearNodeResults'>
+
+const num = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) ? v : undefined)
+
+/** Applies one run event to the editor state. Pure apart from the actions it calls. */
+export function applyRunEvent(actions: ProjectionActions, event: RunEvent): void {
+  const e = event as Record<string, unknown> & { type: string }
+  const nodeId = typeof e.nodeId === 'string' ? e.nodeId : null
+  switch (e.type) {
+    case 'run-started':
+      // Never clears results: a suspended run that resumes sends it again.
+      actions.setRunning(true)
+      return
+    case 'node-started':
+      if (nodeId) actions.setNodeResult(nodeId, { status: 'running' })
+      return
+    case 'node-completed':
+    case 'node-restored':
+      if (nodeId) {
+        const durationMs = num(e.durationMs)
+        actions.setNodeResult(nodeId, { status: 'success', data: e.outputs, ...(durationMs !== undefined ? { durationMs } : {}) })
+      }
+      return
+    case 'node-failed':
+      if (nodeId) {
+        const durationMs = num(e.durationMs)
+        actions.setNodeResult(nodeId, { status: 'error', ...(typeof e.error === 'string' ? { error: e.error } : {}), ...(durationMs !== undefined ? { durationMs } : {}) })
+      }
+      return
+    case 'run-completed':
+    case 'run-failed':
+      actions.setRunning(false)
+      return
+    default:
+      return
+  }
+}
+
+/** Clears results and sets not running. */
+export function resetRunProjection(actions: ProjectionActions): void {
+  actions.clearNodeResults()
+  actions.setRunning(false)
+}
+
+const TERMINAL: readonly StreamStatus[] = ['completed', 'failed', 'error']
+
+/**
+ * Applies only the events not yet applied. Clears results only on a genuine
+ * reset (status idle, or the list got shorter: a new run). A terminal stream
+ * status forces not running; it never forces running.
+ */
+export function useRunProjection(events: readonly RunEvent[], streamStatus: StreamStatus, target?: ProjectionActions): void {
+  const store = useOptionalFlowEditorStore()
+  const actions = target ?? store?.actions ?? null
+  const applied = useRef(0)
+  useEffect(() => {
+    if (!actions) return
+    if (streamStatus === 'idle' || events.length < applied.current) {
+      if (applied.current > 0 || streamStatus === 'idle') resetRunProjection(actions)
+      applied.current = 0
+      if (streamStatus === 'idle') return
+    }
+    for (let i = applied.current; i < events.length; i++) applyRunEvent(actions, events[i]!)
+    applied.current = events.length
+    if (TERMINAL.includes(streamStatus)) actions.setRunning(false)
+  }, [events, streamStatus, actions])
+}
+
+export type StartRun = (flowId: string, inputs?: Record<string, unknown>) => Promise<{ id: string }>
+
+export interface RunStreamHandlers {
+  onEvent(event: RunEvent): void
+  onStatus?(status: StreamStatus): void
+  signal: AbortSignal
+}
+
+/** Host transport for the run-event stream; may return a disposer. */
+export type OpenRunStream = (runId: string, handlers: RunStreamHandlers) => void | (() => void)
+
+export type CancelRun = (runId: string) => Promise<void>
+
+export interface FlowExecution {
+  isRunning: boolean
+  start(inputs?: Record<string, unknown>): Promise<void>
+  stop(): Promise<void>
+  runId: string | null
+  streamStatus: StreamStatus
+  /** After stop without cancelRun the run continues server side: say "stopped following". */
+  stopped: null | 'cancelled' | 'stopped-following'
+  events: readonly RunEvent[]
+}
+
+const ENDS = new Set(['run-completed', 'run-failed'])
+
+export function useFlowExecution(flowId: string, startRun: StartRun, openStream: OpenRunStream, cancelRun?: CancelRun): FlowExecution {
+  const [isRunning, setIsRunning] = useState(false)
+  const [runId, setRunId] = useState<string | null>(null)
+  const [events, setEvents] = useState<RunEvent[]>([])
+  const [streamStatus, setStreamStatus] = useState<StreamStatus>('idle')
+  const [stopped, setStopped] = useState<FlowExecution['stopped']>(null)
+  const controller = useRef<AbortController | null>(null)
+  const dispose = useRef<(() => void) | null>(null)
+  const generation = useRef(0)
+  const live = useRef({ startRun, openStream, cancelRun })
+  live.current = { startRun, openStream, cancelRun }
+
+  useRunProjection(events, streamStatus)
+
+  const detach = useCallback(() => {
+    controller.current?.abort()
+    controller.current = null
+    dispose.current?.()
+    dispose.current = null
+  }, [])
+
+  const forget = useCallback(() => {
+    generation.current++
+    detach()
+    setIsRunning(false)
+    setRunId(null)
+    setEvents([])
+    setStreamStatus('idle')
+  }, [detach])
+
+  // A different flow resets everything.
+  useEffect(() => {
+    forget()
+    setStopped(null)
+    return detach
+  }, [flowId, forget, detach])
+
+  const start = useCallback(
+    async (inputs?: Record<string, unknown>) => {
+      detach()
+      const gen = ++generation.current
+      setStopped(null)
+      setEvents([])
+      setStreamStatus('idle')
+      setIsRunning(true)
+      let run: { id: string }
+      try {
+        run = await live.current.startRun(flowId, inputs)
+      } catch (err) {
+        if (gen === generation.current) setIsRunning(false)
+        throw err
+      }
+      if (gen !== generation.current) return
+      setRunId(run.id)
+      const ac = new AbortController()
+      controller.current = ac
+      setStreamStatus('streaming')
+      const off = live.current.openStream(run.id, {
+        signal: ac.signal,
+        onEvent: (event) => {
+          if (gen !== generation.current) return
+          setEvents((prev) => [...prev, event])
+          // Run content decides the end, not the connection.
+          if (ENDS.has(event.type)) setIsRunning(false)
+        },
+        onStatus: (status) => {
+          if (gen !== generation.current) return
+          setStreamStatus(status)
+          if (TERMINAL.includes(status) && status !== 'error') setIsRunning(false)
+        },
+      })
+      if (typeof off === 'function') dispose.current = off
+    },
+    [flowId, detach],
+  )
+
+  const stop = useCallback(async () => {
+    const id = runId
+    const cancel = live.current.cancelRun
+    if (id && cancel) await cancel(id)
+    setStopped(cancel ? 'cancelled' : 'stopped-following')
+    forget()
+  }, [runId, forget])
+
+  return { isRunning, start, stop, runId, streamStatus, stopped, events }
+}

package/src/flow/run/index.ts

@@ -0,0 +1,18 @@
+// @datatechsolutions/tympan/flow: run group barrel.
+export * from './types'
+export * from './lineage'
+export * from './execution'
+export * from './RunStatusMark'
+export * from './ShortId'
+export * from './RunPanel'
+export * from './RunPreviewPanel'
+export * from './RunDrawer'
+export * from './RunTimePanel'
+export * from './RunViews'
+export * from './RunInputDialog'
+export * from './RunReplayDialog'
+export * from './RunRewindDialog'
+export * from './ExecutionTimeline'
+export * from './VariableInspector'
+export * from './VersionHistoryPanel'
+export { sumTokens, countTools, type TokenUsage } from './runData'