@talgent/workbench-ui 0.0.0 → 0.2.0

package/lib/use-work-trace.ts

@@ -0,0 +1,175 @@
+import { useEffect, useMemo, useRef } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { traceClient } from "./client";
+import { buildTraceMetricsDiagnostics, traceMetricKinds } from "./trace-view-model";
+
+const terminalTraceGracePollCount = 3;
+const traceRefreshIntervalMs = 10000;
+const terminalTraceGracePollIntervalMs = traceRefreshIntervalMs;
+export function useWorkTrace({ projectId, agentWorkId, workCreatedAt = null, isWorkTerminal = false, isWorkLifecyclePending = false, workLifecycleGeneration = 0 }: {
+  projectId?: string | null; agentWorkId?: string | null; workCreatedAt?: Date | null;
+  isWorkTerminal?: boolean; isWorkLifecyclePending?: boolean; workLifecycleGeneration?: number;
+}) {
+  // A Work without a Project is read by its own identity.
+  const enabled = Boolean(agentWorkId);
+  const terminalKey = useRef<string | null>(null);
+  const currentKey = `${agentWorkId}:${workLifecycleGeneration}`;
+  const activeTraceSeenRef = useRef(false);
+  const terminalGraceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const terminalGracePollsRemainingRef = useRef(0);
+  const shouldQueryTrace = enabled && !isWorkLifecyclePending && !isWorkTerminal;
+  const {
+    data,
+    error,
+    isError,
+    isLoading,
+    isFetching,
+    dataUpdatedAt,
+    refetch,
+  } = useQuery({
+    queryKey: ["trace-metrics", projectId, agentWorkId, workCreatedAt?.getTime() ?? 0],
+    queryFn: async () => {
+      if (!agentWorkId) {
+        return { buckets: [], totals: [] };
+      }
+
+      const metricWindow = workMetricsWindow(new Date(), workCreatedAt);
+      return traceClient.getSessionTraceMetrics({
+        projectId: projectId ?? "", agentWorkId,
+        startTime: timestampFromDate(metricWindow.start),
+        endTime: timestampFromDate(metricWindow.end),
+        stepSeconds: metricWindow.stepSeconds,
+        metricKinds: [...traceMetricKinds],
+      });
+    },
+    enabled: shouldQueryTrace,
+    retry: false,
+    refetchInterval: shouldQueryTrace ? traceRefreshIntervalMs : false,
+    refetchOnWindowFocus: false,
+  });
+  const latestRefetchRef = useRef(refetch);
+  const latestTraceStateRef = useRef({
+    enabled,
+    agentWorkId: agentWorkId ?? null,
+    isWorkLifecyclePending,
+    isWorkTerminal,
+  });
+  const diagnostics = useMemo(() => buildTraceMetricsDiagnostics(data ?? { buckets: [], totals: [] }), [data]);
+  const { summary } = diagnostics;
+
+  useEffect(() => {
+    latestRefetchRef.current = refetch;
+    latestTraceStateRef.current = {
+      enabled,
+      agentWorkId: agentWorkId ?? null,
+      isWorkLifecyclePending,
+      isWorkTerminal,
+    };
+  }, [enabled, isWorkLifecyclePending, isWorkTerminal, refetch, agentWorkId]);
+
+  useEffect(() => {
+    return () => {
+      if (terminalGraceTimerRef.current) {
+        clearTimeout(terminalGraceTimerRef.current);
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    activeTraceSeenRef.current = false;
+    terminalGracePollsRemainingRef.current = 0;
+    if (terminalGraceTimerRef.current) {
+      clearTimeout(terminalGraceTimerRef.current);
+      terminalGraceTimerRef.current = null;
+    }
+  }, [agentWorkId]);
+
+  useEffect(() => {
+    if (!shouldQueryTrace) {
+      return;
+    }
+
+    activeTraceSeenRef.current = true;
+    terminalKey.current = null;
+    terminalGracePollsRemainingRef.current = 0;
+    if (terminalGraceTimerRef.current) {
+      clearTimeout(terminalGraceTimerRef.current);
+      terminalGraceTimerRef.current = null;
+    }
+  }, [shouldQueryTrace]);
+
+  useEffect(() => {
+    if (!enabled || !agentWorkId || isWorkLifecyclePending || !isWorkTerminal || terminalKey.current === currentKey) {
+      return;
+    }
+
+    const shouldGracePoll = activeTraceSeenRef.current;
+    terminalKey.current = currentKey;
+    if (isError) {
+      return;
+    }
+    void refetch().then((result) => {
+      if (!result.isError && shouldGracePoll) {
+        scheduleTerminalGracePolling(latestRefetchRef, latestTraceStateRef, terminalGraceTimerRef, terminalGracePollsRemainingRef);
+      }
+    });
+  }, [enabled, isError, isWorkLifecyclePending, isWorkTerminal, currentKey, refetch, agentWorkId]);
+
+  return { data, error, isError, isLoading, isFetching, dataUpdatedAt, refetch, diagnostics, summary };
+}
+
+function scheduleTerminalGracePolling(
+  latestRefetchRef: { current: () => Promise<{ isError: boolean }> },
+  latestTraceStateRef: {
+    current: {
+      enabled: boolean;
+      agentWorkId: string | null;
+      isWorkLifecyclePending: boolean;
+      isWorkTerminal: boolean;
+    };
+  },
+  terminalGraceTimerRef: { current: ReturnType<typeof setTimeout> | null },
+  terminalGracePollsRemainingRef: { current: number },
+) {
+  if (terminalGraceTimerRef.current) {
+    clearTimeout(terminalGraceTimerRef.current);
+  }
+
+  terminalGracePollsRemainingRef.current = terminalTraceGracePollCount;
+  const poll = () => {
+    if (terminalGracePollsRemainingRef.current <= 0) {
+      return;
+    }
+
+    terminalGraceTimerRef.current = setTimeout(() => {
+      terminalGraceTimerRef.current = null;
+      const state = latestTraceStateRef.current;
+      if (!state.enabled || !state.agentWorkId || state.isWorkLifecyclePending || !state.isWorkTerminal) {
+        terminalGracePollsRemainingRef.current = 0;
+        return;
+      }
+
+      void latestRefetchRef.current().then((result) => {
+        if (result.isError) {
+          terminalGracePollsRemainingRef.current = 0;
+          return;
+        }
+
+        terminalGracePollsRemainingRef.current -= 1;
+        poll();
+      });
+    }, terminalTraceGracePollIntervalMs);
+  };
+
+  poll();
+}
+
+export function workMetricsWindow(now: Date, workCreatedAt: Date | null): { start: Date; end: Date; stepSeconds: number } {
+  const end = new Date(now.getTime() + 60_000);
+  const fallbackStart = new Date(now.getTime() - 30 * 24 * 60 * 60_000);
+  const start = workCreatedAt && Number.isFinite(workCreatedAt.getTime())
+    ? new Date(workCreatedAt.getTime() - 60_000)
+    : fallbackStart;
+  return { start, end, stepSeconds: 3600 };
+}

package/lib/user-display.ts

@@ -0,0 +1,49 @@
+export type UserDisplaySource = {
+  userId?: string;
+  displayName?: string;
+  primaryEmail?: string;
+  avatarUrl?: string;
+};
+
+export function isUnsafeIdentityText(value: string | undefined, userId?: string): boolean {
+  const text = value?.trim() ?? "";
+  const id = userId?.trim() ?? "";
+  if (!text) return false;
+  if (id && text === id) return true;
+  if (/^oidc:/i.test(text) || text.includes("#")) return true;
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(text)) return true;
+  if (/^sub[-_:]/i.test(text)) return true;
+  return false;
+}
+
+export function safeDisplayName(value: string | undefined, userId?: string, fallback = "User"): string {
+  const text = value?.trim() ?? "";
+  if (!text || isUnsafeIdentityText(text, userId)) {
+    return fallback;
+  }
+  return text;
+}
+
+export function displayNameForPerson(person: UserDisplaySource | undefined, fallback = "User"): string {
+  return safeDisplayName(person?.displayName, person?.userId, fallback);
+}
+
+export function safeEmail(value: string | undefined): string {
+  const email = value?.trim() ?? "";
+  return email.includes("@") && !isUnsafeIdentityText(email) ? email : "";
+}
+
+export function safeAvatarUrl(value: string | undefined): string {
+  const url = value?.trim() ?? "";
+  if (!url || isUnsafeIdentityText(url)) return "";
+  return /^https?:\/\//i.test(url) || url.startsWith("/") ? url : "";
+}
+
+export function avatarInitial(name: string, email = "", fallback = "U"): string {
+  return (name.trim() || email.trim() || fallback).charAt(0).toUpperCase();
+}
+
+/** A User Directory person's name as shown: their display name, else username. */
+export function personName(user: { userId: string; username: string; displayName: string }) {
+  return safeDisplayName(user.displayName, user.userId, user.username || "Someone");
+}

package/lib/work-conversation.ts

@@ -0,0 +1,118 @@
+import { equals } from "@bufbuild/protobuf";
+import { UnifiedMessageKind, UnifiedMessageSchema, type UnifiedMessage } from "@talgent/workbench-contracts/dispatcher/public/v1/unified_message_pb";
+
+export interface WorkTurn {
+  key: string;
+  turnId: string;
+  messages: readonly UnifiedMessage[];
+}
+
+interface ConversationSnapshot {
+  turns: readonly WorkTurn[];
+  count: number;
+  textBytes: number;
+  newUserId?: string;
+  olderEvicted: boolean;
+}
+
+const emptySnapshot: ConversationSnapshot = { turns: [], count: 0, textBytes: 0, olderEvicted: false };
+
+// The view owns a bounded message window. A frame updates only its actual turn;
+// it does not reinterpret or sort the complete transcript on every delivery.
+export class WorkConversation {
+  private messages = new Map<string, UnifiedMessage>();
+  private turns = new Map<string, WorkTurn>();
+  private order: UnifiedMessage[] = [];
+  private listeners = new Set<() => void>();
+  private snapshot = emptySnapshot;
+  private bytes = 0;
+
+  constructor(private workId: string, private limit = 500, private byteLimit = 8 * 1024 * 1024) {}
+  getSnapshot = () => this.snapshot;
+  has = (id: string) => this.messages.has(id);
+  getOldest = () => this.order[0];
+  getNewest = () => this.order.at(-1);
+  subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+
+  add(messages: readonly UnifiedMessage[], source: "live" | "replay" | "history" | "older") {
+    let olderEvicted = source === "older" ? false : this.snapshot.olderEvicted;
+    let changed = olderEvicted !== this.snapshot.olderEvicted;
+    let newUserId = this.snapshot.newUserId;
+    for (const message of messages) {
+      // The root Agent's messages only: process diagnostics carry no Agent and stay out.
+      if (message.agentWorkId !== this.workId || message.agent !== "" || !message.id || !message.payload.case) continue;
+      const previous = this.messages.get(message.id);
+      // A history request may finish after a newer live version of the same ID.
+      if (previous && (source === "history" || source === "older")) continue;
+      if (previous && equals(UnifiedMessageSchema, previous, message)) continue;
+      if (previous) this.remove(previous);
+      this.messages.set(message.id, message);
+      this.bytes += textBytes(message);
+      insert(this.order, message);
+      const key = turnKey(message);
+      const turn = this.turns.get(key);
+      const items = turn ? turn.messages.slice() : [];
+      insert(items, message);
+      this.turns.set(key, { key, turnId: message.turnId, messages: items });
+      if (!previous && source === "live" && message.kind === UnifiedMessageKind.USER) newUserId = message.id;
+      changed = true;
+    }
+    if (!changed) return;
+    // ponytail: retain one oversized original message intact; a future lazy
+    // text-body contract is required to bound that single-message case too.
+    while (this.order.length > 1 && (this.order.length > this.limit || this.bytes > this.byteLimit)) {
+      this.remove(source === "older" ? this.order[this.order.length - 1] : this.order[0]);
+      if (source !== "older") olderEvicted = true;
+    }
+    const keys = new Set(this.order.map(turnKey));
+    this.snapshot = { turns: [...keys].map(key => this.turns.get(key)!), count: this.messages.size, textBytes: this.bytes, newUserId, olderEvicted };
+    this.listeners.forEach(listener => listener());
+  }
+
+  private remove(message: UnifiedMessage) {
+    this.messages.delete(message.id);
+    this.bytes -= textBytes(message);
+    const index = this.order.findIndex(item => item.id === message.id);
+    if (index >= 0) this.order.splice(index, 1);
+    const key = turnKey(message);
+    const turn = this.turns.get(key);
+    if (!turn) return;
+    const messages = turn.messages.filter(item => item.id !== message.id);
+    if (messages.length) this.turns.set(key, { ...turn, messages });
+    else this.turns.delete(key);
+  }
+}
+
+function turnKey(message: UnifiedMessage) {
+  // A missing native association is displayed independently, never attached
+  // to the nearest user input or assigned a fabricated turn identity.
+  return message.turnId ? `turn:${message.turnId}` : `message:${message.id}`;
+}
+
+function insert(messages: UnifiedMessage[], message: UnifiedMessage) {
+  let low = 0, high = messages.length;
+  while (low < high) {
+    const middle = (low + high) >>> 1;
+    if (compare(message, messages[middle]) < 0) high = middle; else low = middle + 1;
+  }
+  messages.splice(low, 0, message);
+}
+
+function compare(a: UnifiedMessage, b: UnifiedMessage) {
+  const seconds = (a.timestamp?.seconds ?? 0n) - (b.timestamp?.seconds ?? 0n);
+  if (seconds !== 0n) return seconds < 0n ? -1 : 1;
+  const nanos = (a.timestamp?.nanos ?? 0) - (b.timestamp?.nanos ?? 0);
+  return nanos || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+
+// Account for retained strings without allocating a second serialized body.
+function textBytes(message: UnifiedMessage) {
+  let characters = message.id.length + message.agentWorkId.length + message.turnId.length + (message.agent?.length ?? 0);
+  const payload = message.payload;
+  if (payload.case === "message") {
+    for (const block of payload.value.content) characters += block.text.length + block.mimeType.length;
+  } else if (payload.case) {
+    for (const value of Object.values(payload.value)) if (typeof value === "string") characters += value.length;
+  }
+  return characters * 2;
+}

package/lib/work-file-service.ts

@@ -0,0 +1,118 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { WorkFileAccessDisposition, WorkFileKind, type WorkFile } from "@talgent/workbench-contracts/agent/public/v1/work_file_pb";
+import { useCurrentUser } from "./account-service";
+import { workFileClient } from "./client";
+import { NameTakenError } from "./name-taken-error";
+import type { PreviewVerdict } from "../components/preview/preview-verdict";
+import { previewVerdict } from "./preview-verdict";
+
+// A Personal Work's files, by their position: Work, kind and name. Its owner
+// and Work Share holders read them; only the owner changes them.
+export type WorkFileRef = Pick<WorkFile, "kind" | "name">;
+
+export function workFileKey(file: WorkFileRef) {
+  return `${file.kind === WorkFileKind.ARTIFACT ? "artifact" : "attachment"}/${file.name}`;
+}
+
+export function workFilesQueryKey(workId: string | undefined, userId?: string) {
+  return ["work-files", userId ?? "", workId] as const;
+}
+
+export function useWorkFiles(workId: string | undefined) {
+  const userId = useCurrentUser().data?.user?.id;
+  return useQuery({
+    queryKey: workFilesQueryKey(workId, userId),
+    queryFn: async ({ signal }) => (await workFileClient.listWorkFiles({ workId: workId! }, { signal })).files,
+    enabled: Boolean(workId && userId),
+    retry: false,
+    refetchOnWindowFocus: false,
+    refetchInterval: 5000,
+  });
+}
+
+/** A short-lived link for one read of the file, saved or shown inline. */
+export async function workFileAccessLink(workId: string, file: WorkFileRef, download: boolean) {
+  const resp = await workFileClient.createWorkFileAccessLink({
+    workId, kind: file.kind, name: file.name,
+    disposition: download ? WorkFileAccessDisposition.DOWNLOAD : WorkFileAccessDisposition.PREVIEW,
+  });
+  if (!resp.accessUrl) throw new Error("The file link is missing.");
+  return resp.accessUrl;
+}
+
+export function useDownloadWorkFile(workId: string) {
+  return useMutation({
+    mutationFn: async (file: WorkFileRef) => {
+      const url = await workFileAccessLink(workId, file, true);
+      window.open(url, "_blank", "noopener,noreferrer");
+      return url;
+    },
+  });
+}
+
+/** How Storage shows the file, through Agent. */
+export async function workFilePreview(workId: string, file: WorkFileRef): Promise<PreviewVerdict> {
+  return previewVerdict((await workFileClient.getWorkFilePreview({ workId, kind: file.kind, name: file.name })).preview);
+}
+
+/** Asks for the file's Preview Copy when it needs one. */
+export async function requestWorkFilePreview(workId: string, file: WorkFileRef): Promise<PreviewVerdict> {
+  return previewVerdict((await workFileClient.requestWorkFilePreview({ workId, kind: file.kind, name: file.name })).preview);
+}
+
+// Creates the Attachment, or replaces the one of the same name when replace
+// is set. Storage never renames or replaces on its own: a taken name is
+// refused with NameTakenError.
+export async function uploadWorkAttachment(workId: string, file: File, replace = false, fetchImpl: typeof fetch = fetch) {
+  let uploadUrl: string;
+  try {
+    // An unknown type stays undeclared, so Storage infers it from the name.
+    uploadUrl = (await workFileClient.createWorkAttachmentUpload({ workId, name: file.name, replace, contentType: file.type })).uploadUrl;
+  } catch (error) {
+    if (error instanceof ConnectError && error.code === Code.AlreadyExists) throw new NameTakenError(file.name);
+    throw error;
+  }
+  if (!uploadUrl) throw new Error("upload target is missing");
+  const upload = await fetchImpl(uploadUrl, { method: "PUT", headers: file.type ? { "content-type": file.type } : undefined, body: file });
+  if (upload.status === 409) throw new NameTakenError(file.name);
+  if (!upload.ok) throw new Error(`upload failed: ${upload.status}`);
+  return file.name;
+}
+
+export function useUploadWorkAttachment(workId: string | undefined) {
+  const queryClient = useQueryClient();
+  const userId = useCurrentUser().data?.user?.id;
+  return useMutation({
+    mutationFn: ({ file, replace = false }: { file: File; replace?: boolean }) => {
+      if (!workId) throw new Error("The Work is required.");
+      return uploadWorkAttachment(workId, file, replace);
+    },
+    onSuccess: () => { void queryClient.invalidateQueries({ queryKey: workFilesQueryKey(workId, userId) }); },
+  });
+}
+
+// The owner's changes to the Work's files; each refreshes the file list.
+function useWorkFileMutation<T, R>(workId: string, change: (input: T) => Promise<R>) {
+  const queryClient = useQueryClient();
+  const userId = useCurrentUser().data?.user?.id;
+  return useMutation({ mutationFn: change, onSuccess: () => { void queryClient.invalidateQueries({ queryKey: workFilesQueryKey(workId, userId) }); } });
+}
+
+export function useRenameWorkAttachment(workId: string) {
+  return useWorkFileMutation(workId, ({ name, newName }: { name: string; newName: string }) => workFileClient.renameWorkAttachment({ workId, name, newName }));
+}
+
+// Deleting a file ends its share links.
+export function useDeleteWorkFile(workId: string) {
+  return useWorkFileMutation(workId, (file: WorkFileRef) => workFileClient.deleteWorkFile({ workId, kind: file.kind, name: file.name }));
+}
+
+export function useCreateWorkFileShareLink(workId: string) {
+  return useWorkFileMutation(workId, async (file: WorkFileRef) => (await workFileClient.createWorkFileShareLink({ workId, kind: file.kind, name: file.name })).shareLink);
+}
+
+// Stopping sharing ends every Share Link of the file.
+export function useStopWorkFileSharing(workId: string) {
+  return useWorkFileMutation(workId, (file: WorkFileRef) => workFileClient.stopWorkFileSharing({ workId, kind: file.kind, name: file.name }));
+}

package/lib/work-model.ts

@@ -0,0 +1,38 @@
+import { create } from "@bufbuild/protobuf";
+import { ModelVendor, WorkModelOptionSchema, type WorkModelOption, type WorkModelSelection } from "@talgent/workbench-contracts/agent/public/v1/model_pb";
+
+// What a Work's conversation uses for its model: a Model Configuration the
+// platform provides, or, on a Managed Computer, the machine's own Claude login.
+
+/** A model a new Work may start on. */
+export type StartModel = { configurationId: string; machineLogin: boolean; name: string; vendor: ModelVendor; thinkingLevels: string[]; defaultThinkingLevel: string };
+
+export const machineLoginName = "This machine's Claude login";
+
+/** The Agent Harness's thinking levels. The machine's Claude login has no
+ * Model Template, so it offers all of them and none is the default. */
+const harnessThinkingLevels = ["low", "medium", "high", "xhigh", "max"];
+
+export const machineLoginModel: StartModel = { configurationId: "", machineLogin: true, name: machineLoginName, vendor: ModelVendor.ANTHROPIC, thinkingLevels: harnessThinkingLevels, defaultThinkingLevel: "" };
+
+/** The models a new Work may start on its Computer: the provided Model
+ * Configurations, and on a Managed Computer first its own Claude login, the
+ * default there. */
+export function startModels(provided: WorkModelOption[], managed: boolean): StartModel[] {
+  const configurations = provided.map(option => ({ configurationId: option.configurationId, machineLogin: false, name: option.name, vendor: option.vendor, thinkingLevels: option.thinkingLevels, defaultThinkingLevel: option.defaultThinkingLevel }));
+  return managed ? [machineLoginModel, ...configurations] : configurations;
+}
+
+/** A start model's identity among the choices. */
+export const startModelKey = (model: StartModel) => model.machineLogin ? "machine-login" : model.configurationId;
+
+/** The model selection a start request carries. */
+export const startModelSelection = (model: StartModel) => model.machineLogin ? { machineLogin: true } : { configurationId: model.configurationId };
+
+const machineLoginOption = create(WorkModelOptionSchema, { name: machineLoginName, vendor: machineLoginModel.vendor, thinkingLevels: harnessThinkingLevels });
+
+/** How a Work's model is presented: the machine's Claude login, or its Model
+ * Configuration as currently provided, none when withdrawn. */
+export function workModelOption(model?: WorkModelSelection, option?: WorkModelOption): WorkModelOption | undefined {
+  return model?.machineLogin ? machineLoginOption : option;
+}

package/lib/work-notices.ts

@@ -0,0 +1,23 @@
+import type { StreamDiagnosticFrame } from "@talgent/workbench-contracts/streamgateway/public/v1/streamgateway_pb";
+import { notify } from "./notifications";
+
+// Model provider refusals the Harness or a SubAgent recovers from are told live
+// as notices, never kept in the Work Message Stream. Reasons mirror the
+// Dispatcher's command.Notice* vocabulary documented on StreamDiagnosticFrame;
+// delivery diagnostics are connection state and stay silent.
+const providerNotices: Record<string, { title: string; description: string }> = {
+  model_rate_limited: { title: "Model provider rate limited", description: "The model provider is limiting requests for this Work." },
+  model_unavailable: { title: "Model provider unavailable", description: "The model provider could not handle a request for this Work." },
+};
+
+export function notifyWorkNotice(workId: string, diagnostic: StreamDiagnosticFrame) {
+  // A reply delivered after its request closed, as when its turn was cancelled.
+  if (diagnostic.reason === "interaction_closed") {
+    notify(`interaction-closed:${workId}`, "warning", "Request already closed", diagnostic.message || "The request you answered had already closed, so your answer was not used.");
+    return;
+  }
+  const notice = providerNotices[diagnostic.reason];
+  if (!notice) return;
+  // One notice per Work: a burst of refusals replaces it instead of stacking.
+  notify(`model-provider:${workId}`, "warning", notice.title, diagnostic.message || notice.description);
+}

package/lib/work-progress.ts

@@ -0,0 +1,41 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+export interface WorkProgress {
+  updatedAt: Date;
+  items: Array<{ content: string; status: string; activeForm?: string }>;
+}
+
+interface ProtoWorkProgressLike {
+  items?: Array<{
+    content?: string;
+    status?: string;
+    activeForm?: string;
+  }>;
+  updatedAt?: Timestamp;
+}
+
+export function adaptWorkProgress(progress: ProtoWorkProgressLike | undefined): WorkProgress | null {
+  if (!progress?.items || progress.items.length === 0) {
+    return null;
+  }
+
+  const items = progress.items.flatMap((item): WorkProgress["items"] => {
+    if (!item.content) {
+      return [];
+    }
+    return [{
+      content: item.content,
+      status: item.status || "pending",
+      ...(item.activeForm ? { activeForm: item.activeForm } : {}),
+    }];
+  });
+
+  if (items.length === 0) {
+    return null;
+  }
+
+  return {
+    updatedAt: progress.updatedAt ? timestampDate(progress.updatedAt) : new Date(0),
+    items,
+  };
+}