@larkup/workspace-app 0.0.0-stage → 0.1.0

package/src/lib/constants/tools.ts

@@ -0,0 +1,178 @@
+import { Search, Table, BarChart3, Code2, Files, FileEdit, FileDown } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+
+export type Tool = {
+  id: string;
+  name: string;
+  description: string;
+  icon: LucideIcon;
+  plugin?: boolean;
+};
+
+/**
+ * Chat-facing behavior for every first-party tool. Keep tool progress copy and
+ * presentation decisions here so adding a tool does not require scattered
+ * name checks throughout the chat UI.
+ */
+export type ChatToolPlacement = 'source' | 'web-search' | 'visualization' | 'media' | 'inline';
+
+export type ChatToolResultView =
+  | 'none'
+  | 'data-table'
+  | 'sandbox'
+  | 'corpus'
+  | 'document-edit'
+  | 'file-export'
+  | 'signature'
+  | 'image-analysis'
+  | 'media';
+
+export interface ChatToolBehavior {
+  placement: ChatToolPlacement;
+  pendingLabel?: string;
+  resultView: ChatToolResultView;
+  compactResult?: boolean;
+  /** Keep quick operations moving without implying a measurable percentage. */
+  showProgressBar?: boolean;
+}
+
+export const CHAT_TOOL_BEHAVIORS: Record<string, ChatToolBehavior> = {
+  searchKnowledgeBase: { placement: 'source', resultView: 'none' },
+  // Renders through the generic output.ui.kind:'citations' contract
+  // (message-item.tsx / chat-citations.tsx), same as any other tool --
+  // nothing video-specific is hardcoded in the placement/resultView here.
+  queryVideoKnowledge: {
+    placement: 'inline',
+    pendingLabel: 'Reviewing the video…',
+    resultView: 'none',
+  },
+  queryVideoEvidence: {
+    placement: 'inline',
+    pendingLabel: 'Reviewing indexed video context…',
+    // Generic structured rows are rendered through ChatDataTable. Ordinary
+    // evidence results have no rows and remain citation/answer driven.
+    resultView: 'data-table',
+    compactResult: false,
+  },
+  inspectVideoKnowledge: {
+    placement: 'inline',
+    pendingLabel: 'Checking the relevant moment…',
+    resultView: 'none',
+  },
+  webSearch: { placement: 'web-search', resultView: 'none' },
+  presentMedia: { placement: 'media', resultView: 'media' },
+  queryTabularData: {
+    placement: 'inline',
+    pendingLabel: 'Checking data…',
+    resultView: 'data-table',
+    compactResult: true,
+    showProgressBar: false,
+  },
+  generateVisualization: {
+    placement: 'visualization',
+    pendingLabel: 'Preparing chart…',
+    resultView: 'none',
+  },
+  createDataExport: {
+    placement: 'inline',
+    pendingLabel: 'Preparing file…',
+    resultView: 'file-export',
+    showProgressBar: false,
+  },
+  executeAnalysis: {
+    placement: 'inline',
+    pendingLabel: 'Running analysis…',
+    resultView: 'sandbox',
+  },
+  analyzeCorpusWithCode: {
+    placement: 'inline',
+    pendingLabel: 'Analyzing documents…',
+    resultView: 'sandbox',
+  },
+  getIndexedData: {
+    placement: 'inline',
+    pendingLabel: 'Checking documents…',
+    resultView: 'corpus',
+  },
+  analyzeImageDeeply: {
+    placement: 'inline',
+    pendingLabel: 'Analyzing image…',
+    resultView: 'image-analysis',
+  },
+  fillDocumentForm: {
+    placement: 'inline',
+    pendingLabel: 'Updating document…',
+    resultView: 'document-edit',
+  },
+  editDocument: {
+    placement: 'inline',
+    pendingLabel: 'Updating document…',
+    resultView: 'document-edit',
+  },
+  requestDocumentSignature: {
+    placement: 'inline',
+    pendingLabel: 'Preparing signature…',
+    resultView: 'signature',
+  },
+};
+
+const FALLBACK_CHAT_TOOL_BEHAVIOR: ChatToolBehavior = {
+  placement: 'inline',
+  pendingLabel: 'Working…',
+  resultView: 'none',
+};
+
+export function getChatToolBehavior(toolId: string): ChatToolBehavior {
+  return CHAT_TOOL_BEHAVIORS[toolId] ?? FALLBACK_CHAT_TOOL_BEHAVIOR;
+}
+
+export const BUILT_IN_TOOLS: Tool[] = [
+  {
+    id: 'searchKnowledgeBase',
+    name: 'Semantic Search',
+    description: 'Search the RAG knowledge base for text.',
+    icon: Search,
+  },
+  {
+    id: 'queryTabularData',
+    name: 'Tabular Data Query',
+    description: 'Filter, group, and aggregate tabular data.',
+    icon: Table,
+  },
+  {
+    id: 'generateVisualization',
+    name: 'Generate Charts',
+    description: 'Create interactive charts from Assistant results.',
+    icon: BarChart3,
+  },
+  {
+    id: 'createDataExport',
+    name: 'Export Answer',
+    description: 'Create a downloadable Excel, CSV, or PDF file from an Assistant result.',
+    icon: FileDown,
+  },
+  {
+    id: 'executeAnalysis',
+    name: 'Python Sandbox',
+    description: 'Execute Python code for complex analysis.',
+    icon: Code2,
+  },
+  {
+    id: 'getIndexedData',
+    name: 'Indexed Data',
+    description: 'List and filter source documents.',
+    icon: Files,
+  },
+  {
+    id: 'analyzeCorpusWithCode',
+    name: 'Corpus Analysis',
+    description: 'Run code against the full indexed corpus.',
+    icon: Code2,
+  },
+  {
+    id: 'fillDocumentForm',
+    name: 'Form Filler',
+    description: 'Fill forms in the active document.',
+    icon: FileEdit,
+  },
+];

package/src/lib/error-formatter.ts

@@ -0,0 +1,30 @@
+export function formatErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+
+  // Provider SDKs sometimes echo the submitted key or a URL-encoded request
+  // URL in authentication failures. Besides being unreadable, that can expose
+  // credential material in a toast. Keep the actionable part instead.
+  if (
+    normalized.includes('authentication failed') ||
+    normalized.includes('invalid api key') ||
+    normalized.includes('invalid api_key') ||
+    normalized.includes('invalid token') ||
+    normalized.includes('unauthorized') ||
+    normalized.includes('status code 401')
+  ) {
+    return 'Authentication failed. Check the API key for the selected provider.';
+  }
+
+  if (message.includes('Is the docker daemon running?')) {
+    return 'Docker is not running. Please make sure the Docker daemon is started.';
+  }
+
+  if (message.includes('fetch failed') || message.includes('Failed to fetch')) {
+    return 'Network error. Please check your connection and try again.';
+  }
+
+  // Add more common error mappings here as needed
+
+  return message;
+}

package/src/lib/jobs-client.ts

@@ -0,0 +1,27 @@
+import { workspaceUrl, workspaceFetch as fetch } from '../host';
+import type { CrawlJob } from '@larkup/core/types';
+
+export interface JobsResponse {
+  jobs: CrawlJob[];
+  configured: boolean;
+}
+
+export async function fetchJobsWithSync(url: string): Promise<JobsResponse> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error('Could not load jobs.');
+  const { jobs, configured } = (await response.json()) as JobsResponse;
+  if (!Array.isArray(jobs)) throw new Error('Could not load jobs.');
+  const active = jobs.filter((job) => job.status === 'running' || job.status === 'queued');
+  if (active.length === 0) return { jobs, configured };
+
+  const advanced = await Promise.all(
+    active.map((job) =>
+      fetch(workspaceUrl(`/api/jobs/${job.id}`))
+        .then((result) => result.json())
+        .then((result) => result.job as CrawlJob)
+        .catch(() => job),
+    ),
+  );
+  const advancedById = new Map(advanced.map((job) => [job.id, job]));
+  return { jobs: jobs.map((job) => advancedById.get(job.id) ?? job), configured };
+}

package/src/lib/media/pdf.ts

@@ -0,0 +1,57 @@
+import * as pdfjsLib from 'pdfjs-dist';
+
+export async function extractImagesFromPDF(
+  file: File,
+): Promise<{ base64: string; pageNumber: number; index: number }[]> {
+  pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
+    'pdfjs-dist/build/pdf.worker.min.mjs',
+    import.meta.url,
+  ).toString();
+
+  const arrayBuffer = await file.arrayBuffer();
+  const pdf = await pdfjsLib.getDocument({ data: new Uint8Array(arrayBuffer) }).promise;
+  const numPages = pdf.numPages;
+  const images: { base64: string; pageNumber: number; index: number }[] = [];
+
+  let imageIndex = 0;
+  const toDataUrl = (source: HTMLCanvasElement) => {
+    const maxDimension = 1_600;
+    const scale = Math.min(1, maxDimension / Math.max(source.width, source.height));
+    if (scale === 1) return source.toDataURL('image/jpeg', 0.86);
+
+    const resized = document.createElement('canvas');
+    resized.width = Math.max(1, Math.round(source.width * scale));
+    resized.height = Math.max(1, Math.round(source.height * scale));
+    resized.getContext('2d')?.drawImage(source, 0, 0, resized.width, resized.height);
+    return resized.toDataURL('image/jpeg', 0.86);
+  };
+
+  for (let i = 1; i <= numPages; i++) {
+    try {
+      const page = await pdf.getPage(i);
+      // A PDF page is a composite visual: diagrams are commonly vector
+      // drawings, while their caption, legend, and table may be text or
+      // separate XObjects. Indexing XObjects individually loses that context
+      // and makes image zero (often a cover) look like the best preview.
+      // One crisp rendered page preserves the complete source relationship.
+      const baseViewport = page.getViewport({ scale: 1 });
+      const desiredLongestEdge = 1_600;
+      const scale = Math.min(
+        2.5,
+        Math.max(1, desiredLongestEdge / Math.max(baseViewport.width, baseViewport.height)),
+      );
+      const viewport = page.getViewport({ scale });
+      const canvas = document.createElement('canvas');
+      canvas.width = Math.max(1, Math.round(viewport.width));
+      canvas.height = Math.max(1, Math.round(viewport.height));
+      const ctx = canvas.getContext('2d');
+      if (!ctx) continue;
+      await page.render({ canvas, viewport }).promise;
+      images.push({ base64: toDataUrl(canvas), pageNumber: i, index: imageIndex++ });
+    } catch (err) {
+      console.error(`Error processing page ${i}`, err);
+    }
+  }
+
+  return images;
+}

package/src/lib/media/progress.ts

@@ -0,0 +1,209 @@
+export interface MediaProgressStep {
+  stage: string;
+  status: 'waiting' | 'running' | 'completed' | 'skipped' | 'failed';
+  percent?: number;
+  current?: number;
+  total?: number;
+  unit?: string;
+  estimatedRemainingSeconds?: number;
+  elapsedSeconds?: number;
+  sequence?: number;
+  message?: string;
+  startedAt?: string;
+  updatedAt?: string;
+  finishedAt?: string;
+}
+
+/** Use the current attempt rather than the original upload time after a retry. */
+export function mediaProcessingStartedAt(asset: {
+  createdAt: string;
+  processingStartedAt?: string;
+}): string {
+  return asset.processingStartedAt ?? asset.createdAt;
+}
+
+/** Returns the completed attempt duration when both persisted timestamps exist. */
+export function completedMediaProcessingSeconds(asset: {
+  processingStatus: string;
+  processingStartedAt?: string;
+  processingSteps?: MediaProgressStep[];
+}): number | null {
+  if (asset.processingStatus !== 'completed' || !asset.processingStartedAt) return null;
+
+  const startedAt = Date.parse(asset.processingStartedAt);
+  if (!Number.isFinite(startedAt)) return null;
+
+  const completedSteps =
+    asset.processingSteps
+      ?.map((step) => Date.parse(step.finishedAt ?? ''))
+      .filter(Number.isFinite) ?? [];
+  if (completedSteps.length === 0) return null;
+  const finishedAt = Math.max(...completedSteps);
+  if (!Number.isFinite(finishedAt) || finishedAt < startedAt) return null;
+  return Math.round((finishedAt - startedAt) / 1_000);
+}
+
+const STAGE_LABELS: Record<string, string> = {
+  download: 'Download',
+  prepare: 'Cloud video preparation',
+  extract: 'Media extraction',
+  transcribe: 'Speech timeline',
+  vision: 'Visual analysis',
+  synthesize: 'Knowledge notes',
+  index: 'Search indexing',
+};
+
+/** The most recently updated running stage is the primary visible work. */
+export function primaryRunningMediaStep<T extends MediaProgressStep>(
+  steps: T[] | undefined,
+): T | undefined {
+  return steps
+    ?.filter((step) => step.status === 'running')
+    .reduce<T | undefined>((latest, step) => {
+      if (!latest) return step;
+      const latestAt = Date.parse(latest.updatedAt ?? latest.startedAt ?? '');
+      const stepAt = Date.parse(step.updatedAt ?? step.startedAt ?? '');
+      if (!Number.isFinite(latestAt)) return step;
+      return Number.isFinite(stepAt) && stepAt >= latestAt ? step : latest;
+    }, undefined);
+}
+
+export function mediaStepProgress(step: MediaProgressStep | undefined): number | null {
+  if (!step) return null;
+  if (typeof step.percent === 'number' && Number.isFinite(step.percent)) {
+    return Math.max(0, Math.min(100, step.percent));
+  }
+  if (typeof step.current === 'number' && typeof step.total === 'number' && step.total > 0) {
+    return Math.max(0, Math.min(100, (step.current / step.total) * 100));
+  }
+  return null;
+}
+
+/** Keep sub-percent worker movement visible without noisy trailing zeroes. */
+export function formatMediaProgressPercent(value: number): string {
+  const bounded = Math.max(0, Math.min(100, Number.isFinite(value) ? value : 0));
+  const rounded = Math.round(bounded * 10) / 10;
+  return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+}
+
+/** Return the latest bounded worker measurement for this indexing attempt. */
+export function smoothMediaProcessingProgress(
+  asset: {
+    processingProgress?: number;
+    processingStatus: string;
+    processingPaused?: boolean;
+    durationSecs?: number;
+    processingSteps?: MediaProgressStep[];
+  },
+  _now = Date.now(),
+): number {
+  const reported = Math.max(0, Math.min(100, asset.processingProgress ?? 0));
+  if (asset.processingStatus === 'completed') return 100;
+  return reported;
+}
+
+/**
+ * Ease confirmed jumps and keep a slow asymptotic trickle while fresh worker
+ * heartbeats prove the job is active. It can approach, but never claim, 99%.
+ */
+export function advanceMediaProcessingProgress(
+  displayed: number,
+  confirmed: number,
+  elapsedMs: number,
+  workerActive = false,
+): number {
+  const current = Math.max(0, Math.min(100, displayed));
+  const target = Math.max(0, Math.min(100, confirmed));
+  const boundedElapsed = Math.max(0, elapsedMs);
+  if (target > current) {
+    const maximumAdvance = boundedElapsed * 0.002;
+    return Math.round(Math.min(target, current + maximumAdvance) * 1_000) / 1_000;
+  }
+  if (!workerActive || current >= 99) return current;
+  const trickle = (99 - current) * (1 - Math.exp(-boundedElapsed / 1_000_000));
+  return Math.round(Math.min(99, current + trickle) * 1_000) / 1_000;
+}
+
+/** A running step without fresh worker telemetry is waiting, not progressing. */
+export function isMediaStepTelemetryStale(
+  step: MediaProgressStep | undefined,
+  now = Date.now(),
+  maxAgeMs = 20_000,
+): boolean {
+  if (!step || step.status !== 'running') return false;
+  const timestamp = Date.parse(step.updatedAt ?? step.startedAt ?? '');
+  return Number.isFinite(timestamp) && now - timestamp > maxAgeMs;
+}
+
+/**
+ * Reserve “Finalizing” for the last local publishing step. Visual analysis can
+ * legitimately spend time at 99% while building its search vectors, so calling
+ * that finalization would promise an imminent completion that is not true.
+ */
+export function isFinalizingMediaStep(step: MediaProgressStep | undefined): boolean {
+  const progress = mediaStepProgress(step);
+  return (
+    step?.status === 'running' && step.stage === 'index' && progress !== null && progress >= 98
+  );
+}
+
+/** A factual label for the active unit of work, separate from weighted overall progress. */
+export function describeActiveMediaStep(step: MediaProgressStep | undefined): string | null {
+  if (!step) return null;
+  const label = STAGE_LABELS[step.stage] ?? step.stage;
+  const progress = mediaStepProgress(step);
+  const count =
+    typeof step.current === 'number' && typeof step.total === 'number' && step.total > 0
+      ? `${step.current} / ${step.total}${step.unit ? ` ${step.unit}` : ''}`
+      : null;
+  if (progress === null) return `${label} · active request in progress`;
+  if (isFinalizingMediaStep(step)) {
+    return `${label} · finalizing verified results`;
+  }
+  return [label, count, `${Math.round(progress)}% this step`].filter(Boolean).join(' · ');
+}
+
+/**
+ * Estimate only countable work. A percentage-only ETA becomes misleading when
+ * a remote worker has reported an optimistic progress band but is still
+ * waiting on a model request.
+ */
+export function estimateMediaStepRemainingSeconds(
+  step: MediaProgressStep | undefined,
+  now = Date.now(),
+): number | null {
+  if (
+    Number.isFinite(step?.estimatedRemainingSeconds) &&
+    (step?.estimatedRemainingSeconds ?? 0) > 5
+  ) {
+    const updatedAt = Date.parse(step?.updatedAt ?? '');
+    if (!Number.isFinite(updatedAt) || isMediaStepTelemetryStale(step, now)) return null;
+    const sinceUpdate = Math.max(0, (now - updatedAt) / 1_000);
+    const remaining = Math.round((step?.estimatedRemainingSeconds ?? 0) - sinceUpdate);
+    // Never park at one second after a forecast has expired. Wait for the next
+    // measured worker update and display no ETA in the meantime.
+    return remaining > 0 ? remaining : null;
+  }
+  if (
+    !step?.startedAt ||
+    !Number.isFinite(step.current) ||
+    !Number.isFinite(step.total) ||
+    step.current === undefined ||
+    step.total === undefined ||
+    step.current < 2 ||
+    step.total <= step.current
+  ) {
+    return null;
+  }
+
+  const startedAt = new Date(step.startedAt).getTime();
+  if (!Number.isFinite(startedAt)) return null;
+  const elapsedSeconds = Math.max(0, (now - startedAt) / 1_000);
+  if (elapsedSeconds < 5) return null;
+
+  const remainingSeconds = Math.round(
+    (elapsedSeconds / step.current) * (step.total - step.current),
+  );
+  // A clearly unreasonable estimate is less useful than no estimate.
+  return remainingSeconds > 0 && remainingSeconds <= 12 * 60 * 60 ? remainingSeconds : null;
+}

package/src/lib/media/source-selection.ts

@@ -0,0 +1,47 @@
+export interface RemoteMediaEstimate {
+  originalUrl: string;
+  durationSecs?: number;
+  singleItemDurationSecs?: number;
+  singleItemUrl?: string;
+  entryCount?: number;
+}
+
+export function selectedRemoteDuration(
+  estimates: RemoteMediaEstimate[] | null,
+  singleItem: boolean,
+): number {
+  return (
+    estimates?.reduce(
+      (total, estimate) =>
+        total +
+        (singleItem
+          ? (estimate.singleItemDurationSecs ??
+            ((estimate.entryCount ?? 1) <= 1 ? estimate.durationSecs : 0) ??
+            0)
+          : (estimate.durationSecs ?? 0)),
+      0,
+    ) ?? 0
+  );
+}
+
+export function selectedRemoteUrls(
+  urls: string[],
+  estimates: RemoteMediaEstimate[] | null,
+  singleItem: boolean,
+): string[] {
+  if (!singleItem) return urls;
+  const estimateByUrl = new Map(estimates?.map((estimate) => [estimate.originalUrl, estimate]));
+  return urls.map((url) => {
+    const inspectedUrl = estimateByUrl.get(url)?.singleItemUrl;
+    if (inspectedUrl) return inspectedUrl;
+    try {
+      const parsed = new URL(url);
+      if (parsed.hostname.includes('youtube.com')) {
+        parsed.searchParams.delete('list');
+        parsed.searchParams.delete('index');
+        return parsed.toString();
+      }
+    } catch {}
+    return url;
+  });
+}

package/src/lib/media/tool-indexing-estimate.ts

@@ -0,0 +1,39 @@
+export interface ToolIndexingEstimateVariant {
+  processingSecondsPerSourceMinute: number;
+  maxProcessingSecondsPerSourceMinute?: number;
+  fixedOverheadSeconds?: number;
+  maxFixedOverheadSeconds?: number;
+  creditsPerSourceMinute: number;
+}
+
+export function calculateToolIndexingEstimate(
+  estimate: ToolIndexingEstimateVariant | undefined,
+  sourceDurationSecs?: number,
+) {
+  if (!estimate) return null;
+  const sourceMinutes = Math.max(0, (sourceDurationSecs ?? 0) / 60);
+  const displayDuration = sourceMinutes > 0 ? Math.max(sourceMinutes, 0.1) : 1;
+  const minimumMinutes = Math.max(
+    1,
+    Math.ceil(
+      ((estimate.fixedOverheadSeconds ?? 0) +
+        estimate.processingSecondsPerSourceMinute * displayDuration) /
+        60,
+    ),
+  );
+  const maximumMinutes = Math.max(
+    minimumMinutes,
+    Math.ceil(
+      ((estimate.maxFixedOverheadSeconds ?? estimate.fixedOverheadSeconds ?? 0) +
+        (estimate.maxProcessingSecondsPerSourceMinute ??
+          estimate.processingSecondsPerSourceMinute) *
+          displayDuration) /
+        60,
+    ),
+  );
+  return {
+    minimumMinutes,
+    maximumMinutes,
+    credits: Math.max(1, Math.ceil(estimate.creditsPerSourceMinute * displayDuration)),
+  };
+}

package/src/lib/media/video-intelligence-capacity.ts

@@ -0,0 +1 @@
+export * from '@larkup/core/video-intelligence-capacity';

package/src/lib/media/video-runtime-scope.ts

@@ -0,0 +1 @@
+export * from '@larkup/core/video-runtime-scope';

package/src/lib/shared/error-formatter.ts

@@ -0,0 +1 @@
+export * from '@larkup/core/error-formatter';

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/source.css

@@ -0,0 +1 @@
+@source "./**/*.{ts,tsx}";

package/src/storage.ts

@@ -0,0 +1,16 @@
+import * as idb from 'idb-keyval';
+import { workspaceStorageScope } from './host';
+const scoped = (key: IDBValidKey) =>
+  workspaceStorageScope() ? `${workspaceStorageScope()}:${String(key)}` : key;
+export const get = <T = any>(key: IDBValidKey) => idb.get<T>(scoped(key));
+export const set = <T>(key: IDBValidKey, value: T) => idb.set(scoped(key), value);
+export const del = (key: IDBValidKey) => idb.del(scoped(key));
+export async function keys(): Promise<IDBValidKey[]> {
+  const all = await idb.keys();
+  const prefix = workspaceStorageScope();
+  return prefix
+    ? all
+        .filter((key) => typeof key === 'string' && key.startsWith(prefix + ':'))
+        .map((key) => String(key).slice(prefix.length + 1))
+    : all;
+}

package/src/store/chat-store.ts

@@ -0,0 +1,19 @@
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface ChatStore {
+  selectedModel: string;
+  setSelectedModel: (model: string) => void;
+}
+
+export const useChatStore = create<ChatStore>()(
+  persist(
+    (set) => ({
+      selectedModel: '',
+      setSelectedModel: (model) => set({ selectedModel: model }),
+    }),
+    {
+      name: 'larkup-chat-store',
+    },
+  ),
+);