@principal-ai/subsystems-react 0.38.0 → 0.40.0

package/src/components/maintain-events/MaintainEventLog.tsx

@@ -0,0 +1,152 @@
+/**
+ * MaintainEventLog — presentational live event log for an OpenCode agent run.
+ *
+ * Renders one row per event as `time type — summary`, with a header carrying
+ * title / agent / session id / status / counts. Subsystems Studio's
+ * `MaintainEventsView` owns the RPC + subscription wiring and feeds the
+ * resulting state in as props; keeping the wiring out of this component lets it
+ * render in Storybook and embed in the subsystem graph sidebar.
+ */
+
+import { useEffect, useRef, type CSSProperties } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+
+export interface MaintainEventLogEvent {
+  at: number;
+  type: string;
+  sessionId?: string;
+  summary: string;
+}
+
+export interface MaintainEventLogProps {
+  title?: string;
+  agent?: string;
+  sessionId?: string;
+  status: string;
+  events: MaintainEventLogEvent[];
+  total: number;
+  error?: string | null;
+  /** Shown before a session id is known. @default 'Waiting for OpenCode session…' */
+  waitingLabel?: string;
+  /** Shown once a session exists but no events have arrived. @default 'Waiting for SSE events…' */
+  emptyLabel?: string;
+  /** Keep the log pinned to the newest event. @default true */
+  autoScroll?: boolean;
+  /** Render the title/status header above the log. @default true */
+  showHeader?: boolean;
+}
+
+function formatTime(at: number): string {
+  return new Date(at).toLocaleTimeString(undefined, {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+}
+
+export function MaintainEventLog({
+  title,
+  agent,
+  sessionId,
+  status,
+  events,
+  total,
+  error,
+  waitingLabel = 'Waiting for OpenCode session…',
+  emptyLabel = 'Waiting for SSE events…',
+  autoScroll = true,
+  showHeader = true,
+}: MaintainEventLogProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const logRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (!autoScroll) return;
+    const el = logRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [autoScroll, events.length]);
+
+  if (!sessionId) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          color: muted,
+          fontFamily: theme.fonts.body,
+          fontSize: theme.fontSizes[1],
+        }}
+      >
+        {waitingLabel}
+      </div>
+    );
+  }
+
+  const wrap: CSSProperties = {
+    height: '100%',
+    display: 'flex',
+    flexDirection: 'column',
+    padding: 20,
+    color: theme.colors.text,
+    fontFamily: theme.fonts.body,
+    boxSizing: 'border-box',
+  };
+
+  return (
+    <div style={wrap}>
+      {showHeader ? (
+        <div style={{ marginBottom: 12 }}>
+          <div style={{ fontSize: theme.fontSizes[3], fontWeight: 650 }}>
+            {title ?? 'Maintain events'}
+          </div>
+          <div style={{ marginTop: 4, fontSize: theme.fontSizes[0], color: muted }}>
+            {agent ? `${agent} · ` : null}
+            {sessionId}
+            {' · '}
+            <span style={{ fontWeight: 600 }}>{status}</span>
+            {' · '}
+            {total} events
+            {events.length < total ? ` (showing last ${events.length})` : null}
+          </div>
+          {error ? (
+            <div style={{ marginTop: 8, color: theme.colors.error, fontSize: theme.fontSizes[0] }}>
+              {error}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+      <div
+        ref={logRef}
+        style={{
+          flex: 1,
+          minHeight: 0,
+          overflow: 'auto',
+          borderRadius: 8,
+          border: `1px solid ${theme.colors.border ?? 'rgba(255,255,255,0.12)'}`,
+          background: 'rgba(0,0,0,0.25)',
+          padding: '10px 12px',
+          fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+          fontSize: theme.fontSizes[0],
+          lineHeight: 1.45,
+        }}
+      >
+        {events.length === 0 ? (
+          <div style={{ color: muted }}>{emptyLabel}</div>
+        ) : (
+          events.map((ev, i) => (
+            <div key={`${ev.at}-${ev.type}-${i}`} style={{ marginBottom: 6 }}>
+              <span style={{ color: muted }}>{formatTime(ev.at)}</span>{' '}
+              <span style={{ color: theme.colors.primary ?? '#8fd' }}>{ev.type}</span>
+              {ev.summary && ev.summary !== ev.type ? <span> — {ev.summary}</span> : null}
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/maintain-events/MaintainLivePanel.tsx

@@ -0,0 +1,99 @@
+/**
+ * MaintainLivePanel — a collapsible, half-height panel that overlays the graph
+ * canvas and streams a live agent run's events. Subsystems Studio supplies the
+ * state (status/events/total/error) and renders it through
+ * `SubsystemComponentGraph`'s `liveEvents` prop; collapsing leaves just the
+ * header bar so the graph stays readable.
+ */
+
+import { useState } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import { MaintainEventLog, type MaintainEventLogProps } from './MaintainEventLog';
+
+export interface MaintainLivePanelProps extends MaintainEventLogProps {
+  /** Start collapsed (header only). @default false */
+  defaultCollapsed?: boolean;
+}
+
+const HEADER_HEIGHT = 36;
+
+export function MaintainLivePanel({
+  title,
+  agent,
+  sessionId,
+  status,
+  events,
+  total,
+  error,
+  defaultCollapsed = false,
+}: MaintainLivePanelProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const border = theme.colors.border ?? 'rgba(255,255,255,0.12)';
+  const [collapsed, setCollapsed] = useState(defaultCollapsed);
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom: 0,
+        height: collapsed ? HEADER_HEIGHT : '50%',
+        zIndex: 5,
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.colors.backgroundSecondary ?? theme.colors.background,
+        borderTop: `1px solid ${border}`,
+        boxShadow: '0 -8px 24px rgba(0,0,0,0.35)',
+        overflow: 'hidden',
+      }}
+    >
+      <button
+        type="button"
+        onClick={() => setCollapsed((c) => !c)}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 8,
+          height: HEADER_HEIGHT,
+          flexShrink: 0,
+          padding: '0 12px',
+          border: 'none',
+          borderBottom: collapsed ? 'none' : `1px solid ${border}`,
+          background: 'transparent',
+          color: theme.colors.text,
+          fontFamily: theme.fonts.body,
+          fontSize: theme.fontSizes[0],
+          cursor: 'pointer',
+          textAlign: 'left',
+        }}
+      >
+        {collapsed ? <ChevronUp size={14} /> : <ChevronDown size={14} />}
+        <span style={{ fontWeight: 600 }}>Live events</span>
+        {agent ? <span style={{ color: muted }}>{agent}</span> : null}
+        {status ? <span style={{ color: muted }}>· {status}</span> : null}
+        {total > 0 ? <span style={{ color: muted }}>· {total} events</span> : null}
+        <span style={{ flex: 1 }} />
+        {sessionId ? (
+          <span style={{ color: muted, fontFamily: theme.fonts.monospace }}>{sessionId}</span>
+        ) : null}
+      </button>
+      {!collapsed ? (
+        <div style={{ flex: 1, minHeight: 0 }}>
+          <MaintainEventLog
+            title={title}
+            agent={agent}
+            sessionId={sessionId}
+            status={status}
+            events={events}
+            total={total}
+            error={error}
+            showHeader={false}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/maintain-events/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Maintain event log — presentational live OpenCode agent-run event feed.
+ */
+export { MaintainEventLog } from './MaintainEventLog';
+export type {
+  MaintainEventLogEvent,
+  MaintainEventLogProps,
+} from './MaintainEventLog';
+export { MaintainLivePanel } from './MaintainLivePanel';
+export type { MaintainLivePanelProps } from './MaintainLivePanel';

package/src/graphify/consolidated.ts

@@ -240,6 +240,14 @@ export interface GraphifyStoreDetail {
    * system (db/service; carries no `process`).
    */
   storage?: 'memory' | 'disk' | 'external';
+  /**
+   * The type of the retained state itself — a store declares its type the way
+   * every other declaration does (`Map<string, FeedState>`, `Set<Listener>`,
+   * a table's row type). Orthogonal to `storage`.
+   */
+  valueType?: string;
+  /** Backing edge target for `valueType`, when the graph has one. */
+  valueTypeRef?: GraphifyReferenceInfo;
 }
 
 /** A standalone method selected from its owning class. */

package/src/graphify/construct.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from 'bun:test';
 import type { GraphifyEdge, GraphifyNode } from './types';
-import { inferConstructFromGraphify, constructsMatch } from './construct';
+import {
+	inferConstructFromGraphify,
+	constructsMatch,
+	resolveConstructMatch,
+} from './construct';
 
 function node(
 	id: string,
@@ -106,3 +110,59 @@ describe('constructsMatch', () => {
 		expect(constructsMatch('function', 'class')).toBe(false);
 	});
 });
+
+describe('resolveConstructMatch', () => {
+	test('structural match is enough (no augmentation)', () => {
+		expect(resolveConstructMatch('function', 'function')).toEqual({
+			match: true,
+		});
+	});
+
+	test('plain mismatch without augmentation stays a hard failure', () => {
+		expect(resolveConstructMatch('function', 'class')).toEqual({
+			match: false,
+		});
+	});
+
+	test('unknown without augmentation is unconfirmed, not a mismatch', () => {
+		expect(resolveConstructMatch('store', 'unknown')).toEqual({ match: null });
+	});
+
+	test('accepted augmentation confirms a claim Graphify infers differently', () => {
+		expect(resolveConstructMatch('store', 'function', 'store')).toEqual({
+			match: true,
+			augmentedBy: 'store',
+		});
+	});
+
+	test('accepted augmentation confirms a claim Graphify leaves unknown', () => {
+		expect(resolveConstructMatch('interface', 'unknown', 'interface')).toEqual({
+			match: true,
+			augmentedBy: 'interface',
+		});
+	});
+
+	test('augmentation only confirms its own claim, not a different one', () => {
+		expect(resolveConstructMatch('store', 'function', 'module')).toEqual({
+			match: false,
+		});
+		expect(resolveConstructMatch('store', 'unknown', 'module')).toEqual({
+			match: null,
+		});
+	});
+
+	test('blank augmentation is ignored', () => {
+		expect(resolveConstructMatch('store', 'function', '  ')).toEqual({
+			match: false,
+		});
+	});
+
+	test('external / missing claimed still short-circuits to match', () => {
+		expect(resolveConstructMatch('external', 'function')).toEqual({
+			match: true,
+		});
+		expect(resolveConstructMatch(undefined, 'unknown')).toEqual({
+			match: true,
+		});
+	});
+});

package/src/graphify/construct.ts

@@ -118,3 +118,36 @@ export function constructsMatch(
 	if (TYPE_FAMILY.has(claimed)) return inferred === 'type';
 	return claimed === inferred;
 }
+
+export interface ConstructCheckOutcome {
+	/** true = confirmed, false = known mismatch, null = unconfirmed (needs agent). */
+	match: boolean | null;
+	/** Confirming construct from an accepted augmentation, when that is what confirmed it. */
+	augmentedBy?: string;
+}
+
+/**
+ * Resolve a claimed construct against Graphify's inferred construct, allowing an
+ * accepted, agent-confirmed augmentation to stand in for Graphify when it is
+ * silent (`unknown`) or when it disagrees.
+ *
+ * Graphify's inferred construct is a *structural hint*, never ground truth: its
+ * vocabulary (`class | function | method | type | module | unknown`) has no
+ * `store` or `custom_entity`, and a call-style accessor label biases it to
+ * `function`. When source-reading confirms the model's claim, that confirmation
+ * (recorded as an accepted augmentation) wins over the hint.
+ */
+export function resolveConstructMatch(
+	claimed: string | undefined,
+	inferred: InferredGraphifyConstruct,
+	augmentedConstruct?: string | null,
+): ConstructCheckOutcome {
+	const aug = augmentedConstruct?.trim();
+	if (!claimed || claimed === 'external') return { match: true };
+	const augConfirms = !!aug && aug === claimed;
+	if (inferred === 'unknown') {
+		return augConfirms ? { match: true, augmentedBy: aug } : { match: null };
+	}
+	if (constructsMatch(claimed, inferred)) return { match: true };
+	return augConfirms ? { match: true, augmentedBy: aug } : { match: false };
+}

package/src/graphify/index.ts

@@ -61,8 +61,13 @@ export {
 export type {
 	InferredGraphifyConstruct,
 	InferConstructFromGraphifyResult,
+	ConstructCheckOutcome,
+} from './construct';
+export {
+	inferConstructFromGraphify,
+	constructsMatch,
+	resolveConstructMatch,
 } from './construct';
-export { inferConstructFromGraphify, constructsMatch } from './construct';
 export type {
   GraphifyInferredSignature,
   ClaimedSignature,

package/src/index.ts

@@ -16,6 +16,14 @@ export type {
   SessionEventFeedRow,
 } from './components/session-events';
 
+// Maintain event log — presentational live OpenCode agent-run event feed
+export { MaintainEventLog, MaintainLivePanel } from './components/maintain-events';
+export type {
+  MaintainEventLogEvent,
+  MaintainEventLogProps,
+  MaintainLivePanelProps,
+} from './components/maintain-events';
+
 // Graphify integration types (graph.json data model)
 export type {
   JsonValue,
@@ -62,6 +70,7 @@ export {
   symbolLabelVariants,
   inferConstructFromGraphify,
   constructsMatch,
+  resolveConstructMatch,
   extractNamedTypes,
   extractGraphifySignature,
   compareSignatures,

package/src/stories/MaintainEvents/MaintainEventLog.stories.tsx

@@ -0,0 +1,66 @@
+/**
+ * Maintain Event Log — presentational live agent-run event feed.
+ *
+ * The `Live` story replays a fixture derived from a real OpenCode V2 agent
+ * session (`packages/subsystems-core/src/opencode/__fixtures__/session-events.json`),
+ * mapped to the live-feed vocabulary (`session.next.*` / `session.status`) and
+ * summarized the same way the host's `/api/event` subscription is
+ * (`summarizeEvent` in `subsystems-studio/src/bun/opencode-v2-live.ts`).
+ */
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import {
+  MaintainEventLog,
+  type MaintainEventLogEvent,
+} from '../../components/maintain-events';
+import liveEvents from '../data/maintain-live-events.json';
+
+const events = liveEvents as MaintainEventLogEvent[];
+
+const meta = {
+  title: 'Agent Sessions/Maintain Event Log',
+  component: MaintainEventLog,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div
+          style={{
+            height: '100vh',
+            background: defaultEditorTheme.colors.background,
+            color: defaultEditorTheme.colors.text,
+          }}
+        >
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+  args: {
+    title: 'Maintain events',
+    agent: 'construct-verifier',
+    sessionId: 'ses_056b1f037ffeu1d00DzvJBrHq9',
+    status: 'running',
+    events,
+    total: events.length,
+  },
+} satisfies Meta<typeof MaintainEventLog>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Live: Story = {};
+
+export const WaitingForSession: Story = {
+  args: { sessionId: undefined, events: [], total: 0, status: 'starting' },
+};
+
+export const WaitingForEvents: Story = {
+  args: { events: [], total: 0 },
+};
+
+export const WithError: Story = {
+  args: { error: 'live event stream dropped — reconnecting and reconciling with server state' },
+};

package/src/stories/MaintainEvents/MaintainLivePanel.stories.tsx

@@ -0,0 +1,77 @@
+/**
+ * Maintain Live Panel — the collapsible half-height live-agent-run panel that
+ * `SubsystemComponentGraph` renders over its canvas via the `liveEvents` prop.
+ *
+ * The fixture replays a real OpenCode V2 agent session
+ * (`packages/subsystems-core/src/opencode/__fixtures__/session-events.json`),
+ * mapped to the live-feed vocabulary and summarized like the host's
+ * `/api/event` subscription.
+ */
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import {
+  MaintainLivePanel,
+  type MaintainEventLogEvent,
+} from '../../components/maintain-events';
+import liveEvents from '../data/maintain-live-events.json';
+
+const events = liveEvents as MaintainEventLogEvent[];
+
+const meta = {
+  title: 'Agent Sessions/Maintain Live Panel',
+  component: MaintainLivePanel,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div
+          style={{
+            position: 'relative',
+            height: '100vh',
+            overflow: 'hidden',
+            background: defaultEditorTheme.colors.background,
+            color: defaultEditorTheme.colors.text,
+          }}
+        >
+          <div
+            style={{
+              position: 'absolute',
+              inset: 0,
+              display: 'grid',
+              placeItems: 'center',
+              color: defaultEditorTheme.colors.textMuted,
+              fontFamily: defaultEditorTheme.fonts.monospace,
+              fontSize: 13,
+            }}
+          >
+            graph canvas
+          </div>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+  args: {
+    title: 'Maintain events',
+    agent: 'construct-verifier',
+    sessionId: 'ses_056b1f037ffeu1d00DzvJBrHq9',
+    status: 'running',
+    events,
+    total: events.length,
+  },
+} satisfies Meta<typeof MaintainLivePanel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Expanded: Story = {};
+
+export const Collapsed: Story = {
+  args: { defaultCollapsed: true },
+};
+
+export const WaitingForEvents: Story = {
+  args: { events: [], total: 0 },
+};