@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/packages/agentsam-workbench/src/agent/AgentRuntimeField.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useRef, type CSSProperties } from 'react';
+import type {
+  LoadingSceneController,
+  ScenePreset,
+} from '@inneranimalmedia/agentsam-loading-scene';
+import {
+  HyperspaceRenderer,
+  computationalHyperspace,
+} from '@inneranimalmedia/agentsam-loading-scene';
+import {
+  LoadingSceneNarration,
+  useLoadingScene,
+} from '@inneranimalmedia/agentsam-loading-scene/react';
+
+export type AgentRuntimeFieldProps = {
+  controller: LoadingSceneController;
+  preset?: ScenePreset;
+  blocking?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  activeOpacity?: number;
+  passiveOpacity?: number;
+  narration?: boolean;
+  narrationStyle?: CSSProperties;
+};
+
+/**
+ * Reusable workbench runtime surface.
+ *
+ * Product apps own runtime state and event production. This primitive owns the
+ * presentation contract: one persistent semantic scene, task-aware narration,
+ * resize handling and blocking/non-blocking composition.
+ */
+export function AgentRuntimeField({
+  controller,
+  preset = computationalHyperspace,
+  blocking = false,
+  className,
+  style,
+  activeOpacity = 1,
+  passiveOpacity = 0.34,
+  narration = true,
+  narrationStyle,
+}: AgentRuntimeFieldProps) {
+  const scene = useLoadingScene(controller);
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const rendererRef = useRef<HyperspaceRenderer | null>(null);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    const canvas = canvasRef.current;
+    if (!host || !canvas) return;
+
+    const renderer = new HyperspaceRenderer(preset, {
+      canvas,
+      reducedMotion: 'auto',
+    });
+    rendererRef.current = renderer;
+
+    const fit = () => renderer.setSize(host.clientWidth, host.clientHeight);
+    fit();
+
+    const observer =
+      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(fit) : null;
+    observer?.observe(host);
+    renderer.setScene(controller.getScene());
+
+    return () => {
+      observer?.disconnect();
+      renderer.dispose();
+      rendererRef.current = null;
+    };
+  }, [controller, preset]);
+
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer) return;
+
+    renderer.setScene(scene);
+    if (
+      scene.status === 'running' ||
+      scene.status === 'waiting' ||
+      scene.status === 'error'
+    ) {
+      renderer.resume();
+      return;
+    }
+
+    const timeout = window.setTimeout(
+      () => renderer.suspend(),
+      preset.transition.settleMs + 300,
+    );
+    return () => window.clearTimeout(timeout);
+  }, [scene, preset]);
+
+  const active =
+    blocking ||
+    scene.status === 'running' ||
+    scene.status === 'waiting' ||
+    scene.status === 'error';
+
+  return (
+    <div
+      ref={hostRef}
+      data-agent-runtime-field=""
+      aria-hidden={active ? undefined : true}
+      className={className}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: blocking ? 'auto' : 'none',
+        opacity: active ? 1 : 0,
+        transition: 'opacity 500ms ease',
+        background: blocking ? preset.palette.canvas : 'transparent',
+        ...style,
+      }}
+    >
+      <canvas
+        ref={canvasRef}
+        aria-hidden="true"
+        style={{
+          position: 'absolute',
+          inset: 0,
+          width: '100%',
+          height: '100%',
+          opacity: blocking ? activeOpacity : passiveOpacity,
+        }}
+      />
+
+      {active && narration ? (
+        <LoadingSceneNarration
+          controller={controller}
+          preset={preset}
+          align={blocking ? 'center' : 'start'}
+          showStudy
+          showMeta
+          style={{
+            position: 'absolute',
+            left: blocking ? '50%' : 18,
+            top: blocking ? '50%' : 'auto',
+            bottom: blocking ? 'auto' : 18,
+            transform: blocking ? 'translate(-50%, -50%)' : undefined,
+            pointerEvents: 'none',
+            ...narrationStyle,
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}

package/packages/agentsam-workbench/src/agent/Composer.tsx

@@ -1,4 +1,5 @@
 import { useRef, type KeyboardEvent, type ReactNode, type TextareaHTMLAttributes } from 'react';
+import type { AgentRunMode } from '@inneranimalmedia/agentsam-contracts';
 
 export interface AgentComposerProps {
   value: string;
@@ -17,6 +18,8 @@ export interface AgentComposerProps {
   toolbarClassName?: string;
   textareaProps?: Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'onChange' | 'placeholder'>;
   maxHeight?: number;
+  /** Semantic run mode. Hosts own behavior; the primitive exposes it for accessible styling. */
+  runMode?: AgentRunMode;
 }
 
 /**
@@ -43,6 +46,7 @@ export function AgentComposer({
   toolbarClassName,
   textareaProps,
   maxHeight = 220,
+  runMode = 'agent',
 }: AgentComposerProps) {
   const areaRef = useRef<HTMLTextAreaElement>(null);
 
@@ -66,7 +70,12 @@ export function AgentComposer({
   const defaultStop = <button type="button" onClick={() => void onCancel?.()}>Stop</button>;
 
   return (
-    <div className={containerClassName} data-agent-composer="" aria-busy={streaming || undefined}>
+    <div
+      className={containerClassName}
+      data-agent-composer=""
+      data-agent-mode={runMode}
+      aria-busy={streaming || undefined}
+    >
       <textarea
         {...textareaProps}
         ref={areaRef}

package/packages/agentsam-workbench/src/agent/RunMode.ts

@@ -0,0 +1,26 @@
+import type { AgentRunMode } from '@inneranimalmedia/agentsam-contracts';
+
+export type AgentRunModeTone = 'blue' | 'yellow' | 'red' | 'multicolor' | 'green';
+
+export type AgentRunModeProfile = Readonly<{
+  id: AgentRunMode;
+  label: string;
+  description: string;
+  tone: AgentRunModeTone;
+}>;
+
+/**
+ * Presentation metadata for the canonical AgentSam run modes.
+ * Runtime meaning remains owned by @inneranimalmedia/agentsam-contracts.
+ */
+export const AGENT_RUN_MODE_PROFILES: readonly AgentRunModeProfile[] = Object.freeze([
+  { id: 'agent', label: 'Agent', description: 'Execute and open surfaces', tone: 'blue' },
+  { id: 'plan', label: 'Plan', description: 'Design technical plans', tone: 'yellow' },
+  { id: 'debug', label: 'Debug', description: 'Inspect, prove, and fix', tone: 'red' },
+  { id: 'multitask', label: 'Multitask', description: 'Coordinate managed workflows', tone: 'multicolor' },
+  { id: 'ask', label: 'Ask', description: 'Talk and answer questions', tone: 'green' },
+]);
+
+export function agentRunModeProfile(mode: AgentRunMode): AgentRunModeProfile {
+  return AGENT_RUN_MODE_PROFILES.find((profile) => profile.id === mode) ?? AGENT_RUN_MODE_PROFILES[0]!;
+}

package/packages/agentsam-workbench/src/agent/Thread.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, type ReactNode, type UIEvent } from 'react';
+import { useEffect, useRef, type CSSProperties, type ReactNode, type UIEvent } from 'react';
 import type { AgentMessage } from '@inneranimalmedia/agentsam-contracts';
 
 export interface AgentThreadProps {
@@ -8,6 +8,8 @@ export interface AgentThreadProps {
   empty?: ReactNode;
   scrollerClassName?: string;
   listClassName?: string;
+  scrollerStyle?: CSSProperties;
+  listStyle?: CSSProperties;
   stickThreshold?: number;
 }
 
@@ -18,6 +20,8 @@ export function AgentThread({
   empty = null,
   scrollerClassName,
   listClassName,
+  scrollerStyle,
+  listStyle,
   stickThreshold = 80,
 }: AgentThreadProps) {
   const scroller = useRef<HTMLDivElement>(null);
@@ -35,8 +39,19 @@ export function AgentThread({
   }
 
   return (
-    <div ref={scroller} className={scrollerClassName} data-agent-thread="" onScroll={onScroll}>
-      <div className={listClassName}>
+    <div
+      ref={scroller}
+      className={scrollerClassName}
+      data-agent-thread=""
+      onScroll={onScroll}
+      style={
+        scrollerStyle ??
+        (scrollerClassName
+          ? undefined
+          : { minHeight: 0, flex: 1, overflowY: 'auto' })
+      }
+    >
+      <div className={listClassName} style={listStyle}>
         {messages.length === 0
           ? empty
           : messages.map((message, index) =>

package/packages/agentsam-workbench/src/agent/index.ts

@@ -2,6 +2,7 @@ export * from './AgentPanel';
 export * from './Thread';
 export * from './Composer';
 export * from './ModelSelect';
+export * from './RunMode';
 export * from './ToolReceipt';
 export * from './ArtifactCard';
 export * from './ConnectedAgentPanel';
@@ -10,3 +11,5 @@ export * from './MiniAgentSam';
 export * from './ContextualComposer';
 
 export * from './ToolPermissionRequest';
+export * from './AgentConversationSurface';
+export * from './AgentRuntimeField';

package/packages/agentsam-workbench/src/index.ts

@@ -4,3 +4,7 @@ export * from './browser';
 export * from './terminal';
 export * from './projects';
 export * from './timeline';
+
+export * from './manufacturing';
+
+export * from './widgets';

package/packages/agentsam-workbench/src/manufacturing/PreflightIndicator.tsx

@@ -0,0 +1,203 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+export type PreflightStatus =
+  | 'ready'
+  | 'ready_with_warning'
+  | 'ready_with_transform'
+  | 'prepared_for_digitization'
+  | 'needs_variant'
+  | 'unsupported';
+
+export interface PreflightIssueView {
+  code: string;
+  message: string;
+  action?: string | null;
+}
+
+export interface PreflightIndicatorProps {
+  status: PreflightStatus;
+  effectivePpi?: number | null;
+  readyPpi?: number | null;
+  minimumPpi?: number | null;
+  issues?: readonly PreflightIssueView[];
+  actions?: readonly string[];
+  onAction?: (action: string) => void;
+  compact?: boolean;
+  title?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const STATUS_COPY: Record<PreflightStatus, { label: string; tone: string }> = {
+  ready: { label: 'Production ready', tone: 'ready' },
+  ready_with_warning: { label: 'Usable with warning', tone: 'warning' },
+  ready_with_transform: { label: 'Quick fix available', tone: 'transform' },
+  prepared_for_digitization: { label: 'Prepared for digitization', tone: 'handoff' },
+  needs_variant: { label: 'Needs another asset variant', tone: 'error' },
+  unsupported: { label: 'Unsupported for this process', tone: 'error' },
+};
+
+const ACTION_LABELS: Record<string, string> = {
+  trim_alpha: 'Auto-Crop Alpha',
+  vectorize_monochrome: 'Convert to Monochrome Vector',
+  scale_to_safe_zone: 'Scale to Fit Safe Zone',
+  normalize_svg: 'Normalize SVG',
+  outline_text: 'Outline Text',
+  lossless_optimize: 'Optimize Losslessly',
+};
+
+function labelForAction(action: string) {
+  if (ACTION_LABELS[action]) return ACTION_LABELS[action];
+  if (action.startsWith('normalize_color_space:')) return 'Normalize Color';
+  if (action.startsWith('convert:')) return 'Convert Format';
+  if (action.startsWith('rasterize:')) return 'Rasterize for Print';
+  return action
+    .replace(/[:_-]+/g, ' ')
+    .replace(/\b\w/g, (value) => value.toUpperCase());
+}
+
+function qualityPercent(
+  effectivePpi: number | null | undefined,
+  readyPpi: number | null | undefined,
+) {
+  if (!effectivePpi || !readyPpi) return null;
+  return Math.max(0, Math.min(100, (effectivePpi / readyPpi) * 100));
+}
+
+export function PreflightIndicator({
+  status,
+  effectivePpi,
+  readyPpi,
+  minimumPpi,
+  issues = [],
+  actions = [],
+  onAction,
+  compact = false,
+  title = 'Print quality',
+  className,
+  style,
+}: PreflightIndicatorProps) {
+  const state = STATUS_COPY[status];
+  const quality = qualityPercent(effectivePpi, readyPpi);
+  const uniqueActions = [...new Set(actions)];
+
+  return (
+    <section
+      className={className}
+      data-agentsam-preflight=""
+      data-preflight-status={status}
+      data-preflight-tone={state.tone}
+      style={{
+        border: '1px solid var(--agentsam-preflight-border, rgba(90, 92, 98, 0.24))',
+        borderRadius: 12,
+        padding: compact ? 10 : 14,
+        background: 'var(--agentsam-preflight-bg, rgba(255,255,255,0.72))',
+        display: 'grid',
+        gap: compact ? 8 : 10,
+        ...style,
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'baseline',
+          justifyContent: 'space-between',
+          gap: 12,
+        }}
+      >
+        <strong style={{ fontSize: compact ? 12 : 13, fontWeight: 650 }}>{title}</strong>
+        <span
+          data-preflight-state=""
+          style={{
+            fontSize: 11,
+            opacity: 0.72,
+            textAlign: 'right',
+          }}
+        >
+          {state.label}
+        </span>
+      </div>
+
+      {quality != null ? (
+        <div style={{ display: 'grid', gap: 5 }}>
+          <div
+            aria-label={`Effective print resolution ${Math.round(effectivePpi!)} PPI`}
+            role="meter"
+            aria-valuemin={0}
+            aria-valuemax={readyPpi || 300}
+            aria-valuenow={Math.round(effectivePpi!)}
+            style={{
+              height: 5,
+              borderRadius: 999,
+              overflow: 'hidden',
+              background: 'var(--agentsam-preflight-track, rgba(90,92,98,0.14))',
+            }}
+          >
+            <div
+              style={{
+                height: '100%',
+                width: `${quality}%`,
+                borderRadius: 'inherit',
+                background:
+                  status === 'needs_variant' || status === 'unsupported'
+                    ? 'var(--agentsam-preflight-error, #9f4d4d)'
+                    : status === 'ready_with_warning'
+                      ? 'var(--agentsam-preflight-warning, #a87320)'
+                      : 'var(--agentsam-preflight-ready, #54745b)',
+                transition: 'width 120ms ease',
+              }}
+            />
+          </div>
+          <div
+            style={{
+              display: 'flex',
+              gap: 10,
+              fontSize: 11,
+              opacity: 0.72,
+            }}
+          >
+            <span>{Math.round(effectivePpi!)} PPI effective</span>
+            {readyPpi ? <span>{Math.round(readyPpi)} target</span> : null}
+            {minimumPpi && minimumPpi !== readyPpi ? (
+              <span>{Math.round(minimumPpi)} minimum</span>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
+
+      {!compact && issues.length ? (
+        <div style={{ display: 'grid', gap: 4 }}>
+          {issues.slice(0, 3).map((issue) => (
+            <div key={issue.code} style={{ fontSize: 12, lineHeight: 1.35, opacity: 0.82 }}>
+              {issue.message}
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {uniqueActions.length && onAction ? (
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6 }}>
+          {uniqueActions.slice(0, compact ? 2 : 4).map((action) => (
+            <button
+              key={action}
+              type="button"
+              onClick={() => onAction(action)}
+              style={{
+                border: '1px solid var(--agentsam-preflight-button-border, rgba(70,72,76,0.24))',
+                borderRadius: 8,
+                padding: compact ? '5px 8px' : '6px 9px',
+                background: 'var(--agentsam-preflight-button-bg, rgba(255,255,255,0.82))',
+                color: 'inherit',
+                font: 'inherit',
+                fontSize: 11,
+                cursor: 'pointer',
+              }}
+            >
+              {labelForAction(action)}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/packages/agentsam-workbench/src/manufacturing/index.ts

@@ -0,0 +1,2 @@
+export * from './PreflightIndicator';
+export * from './loading';

package/packages/agentsam-workbench/src/manufacturing/loading.ts

@@ -0,0 +1,147 @@
+import type {
+  LoadingSceneController,
+  LoadingSceneSemantic,
+  MetricPointProgress,
+} from '@inneranimalmedia/agentsam-loading-scene';
+
+export type ManufacturingLoadingState =
+  | 'UPLOADING'
+  | 'PREFLIGHT_CHECK'
+  | 'NORMALIZING_COLOR'
+  | 'VECTORIZING'
+  | 'COMPILING_MANUFACTURING'
+  | 'DIGITIZATION_HANDOFF';
+
+export type ReceiptLoadingState =
+  | 'VERIFYING_HASHES'
+  | 'PERSISTING_RECEIPT'
+  | 'CLEANING_WORKSPACE';
+
+interface PipelineStateConfig {
+  semantic: LoadingSceneSemantic;
+  label: string;
+  detail: string;
+}
+
+const MANUFACTURING_STATES: Record<ManufacturingLoadingState, PipelineStateConfig> = {
+  UPLOADING: {
+    semantic: 'asset_ingest',
+    label: 'Ingesting master artwork',
+    detail: 'Raster/vector parser',
+  },
+  PREFLIGHT_CHECK: {
+    semantic: 'preflight',
+    label: 'Evaluating physical print resolution',
+    detail: 'Calculating effective PPI from placement geometry',
+  },
+  NORMALIZING_COLOR: {
+    semantic: 'color_normalization',
+    label: 'Normalizing production color',
+    detail: 'Color profile and transparency normalization',
+  },
+  VECTORIZING: {
+    semantic: 'vectorization',
+    label: 'Tracing production paths',
+    detail: 'Raster boundary to monochrome vector',
+  },
+  COMPILING_MANUFACTURING: {
+    semantic: 'manufacturing_compile',
+    label: 'Compiling manufacturing derivative',
+    detail: 'Provider profile validation and export',
+  },
+  DIGITIZATION_HANDOFF: {
+    semantic: 'digitization_handoff',
+    label: 'Preparing digitization handoff',
+    detail: 'Embroidery source is prepared, not yet a stitch file',
+  },
+};
+
+const RECEIPT_STATES: Record<ReceiptLoadingState, PipelineStateConfig> = {
+  VERIFYING_HASHES: {
+    semantic: 'verification',
+    label: 'Verifying snapshot integrity',
+    detail: 'Pre/post hashes and stale-write evidence',
+  },
+  PERSISTING_RECEIPT: {
+    semantic: 'receipt_persistence',
+    label: 'Persisting receipt envelope',
+    detail: 'agentsam.receipt.v1 to durable catalog storage',
+  },
+  CLEANING_WORKSPACE: {
+    semantic: 'workspace_cleanup',
+    label: 'Cleaning ephemeral workspace',
+    detail: 'Reclaiming local temporary storage',
+  },
+};
+
+export interface PipelineTransitionOptions {
+  label?: string;
+  detail?: string;
+  progress?: number | null;
+  metricPoints?: MetricPointProgress;
+}
+
+function createController<TState extends string>(
+  controller: LoadingSceneController,
+  states: Record<TState, PipelineStateConfig>,
+  operationId: string,
+) {
+  let started = false;
+  let completed = false;
+
+  function transitionTo(state: TState, options: PipelineTransitionOptions = {}) {
+    const config = states[state];
+    if (!config || completed) return;
+
+    const payload = {
+      operationId,
+      semantic: config.semantic,
+      label: options.label || config.label,
+      detail: options.detail || config.detail,
+      progress: options.progress,
+      metricPoints: options.metricPoints,
+    };
+
+    if (!started) {
+      controller.start({ ...payload, scope: 'asset' });
+      started = true;
+      return;
+    }
+
+    controller.activity(payload);
+  }
+
+  return {
+    transitionTo,
+    complete() {
+      if (!started || completed) return;
+      completed = true;
+      controller.complete(operationId);
+    },
+    fail(detail?: string) {
+      if (!started || completed) return;
+      completed = true;
+      controller.fail(operationId, detail);
+    },
+    destroy() {
+      if (started && !completed) controller.complete(operationId);
+      completed = true;
+    },
+  };
+}
+
+export function createManufacturingLoadingController(
+  controller: LoadingSceneController,
+  { operationId = 'manufacturing-preflight' }: { operationId?: string } = {},
+) {
+  return createController(controller, MANUFACTURING_STATES, operationId);
+}
+
+export function createReceiptPipelineLoadingController(
+  controller: LoadingSceneController,
+  { operationId = 'receipt-pipeline' }: { operationId?: string } = {},
+) {
+  return createController(controller, RECEIPT_STATES, operationId);
+}
+
+export { MANUFACTURING_STATES, RECEIPT_STATES };

package/packages/agentsam-workbench/src/widgets/BuiltinWidget.tsx

@@ -0,0 +1,22 @@
+import { CountdownWidget } from './CountdownWidget';
+
+export interface BuiltinWidgetProps {
+  widgetId: string;
+  compact?: boolean;
+  configuration?: Record<string, unknown>;
+}
+
+export function BuiltinWidget({
+  widgetId,
+  compact = false,
+  configuration = {},
+}: BuiltinWidgetProps) {
+  if (widgetId === 'countdown') {
+    const requested = Number(configuration.durationMs);
+    const durationMs = Number.isFinite(requested) && requested > 0
+      ? requested
+      : 5 * 60_000;
+    return <CountdownWidget durationMs={durationMs} compact={compact} />;
+  }
+  return null;
+}