@tomako/tools-runtime 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomako/tools-runtime",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Shared interactive tools runtime for Tomako-FE workspace dialogs and Tomako-SEO tool pages",
   "type": "module",
   "exports": {
@@ -31,6 +31,7 @@
     "./components/tools/engine/package-widget-runtime": "./src/components/tools/engine/package-widget-runtime.tsx",
     "./components/tools/engine/package-widget": "./src/components/tools/engine/package-widget.tsx",
     "./components/tools/engine/result-view": "./src/components/tools/engine/result-view.tsx",
+    "./components/tools/engine/task-recovery": "./src/components/tools/engine/task-recovery.ts",
     "./components/tools/engine/use-legacy-llm-task": "./src/components/tools/engine/use-legacy-llm-task.ts",
     "./components/tools/engine/use-tool-task": "./src/components/tools/engine/use-tool-task.ts",
     "./components/tools/market-forecast-report": "./src/components/tools/market-forecast-report.tsx",

package/src/components/tools/engine/package-widget-runtime.tsx

@@ -72,7 +72,7 @@ export function PackageWidgetRuntime({
 }) {
   const locale = useLocale() as AppLocale;
   const t = useTranslations("toolsPages.engine");
-  const { state, start, reset } = useToolTask(pkg, locale);
+  const { state, start, reset, recoveredValues } = useToolTask(pkg, locale);
   const resultRef = useRef<HTMLElement | null>(null);
   const artifactRegistrationRef = useRef<string | null>(null);
   const { brief: activityBrief } = useToolHandoff();
@@ -85,6 +85,10 @@ export function PackageWidgetRuntime({
     DEFAULT_DIRECT_MODEL_OPTION,
   );
 
+  useEffect(() => {
+    if (recoveredValues) setValues(recoveredValues);
+  }, [recoveredValues]);
+
   const busy = state.phase === "submitting" || state.phase === "running";
   const isWorkspace = variant === "workspace";
 

package/src/components/tools/engine/task-recovery.test.ts

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import {
+  clearToolTaskRecovery,
+  persistToolTaskRecovery,
+  readToolTaskRecovery,
+  toolTaskRecoveryStorageKey,
+} from "./task-recovery";
+
+function memoryStorage() {
+  const values = new Map<string, string>();
+  return {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => values.set(key, value),
+    removeItem: (key: string) => values.delete(key),
+  };
+}
+
+describe("tool task recovery", () => {
+  it("restores task identity and input without storing server result data", () => {
+    const storage = memoryStorage();
+    persistToolTaskRecovery(
+      "competitor-analysis",
+      "llm-0123456789abcdef",
+      { url: "https://example.com" },
+      1_000,
+      storage,
+    );
+
+    assert.deepEqual(
+      readToolTaskRecovery("competitor-analysis", {
+        nowMs: 2_000,
+        storage,
+      }),
+      {
+        version: 1,
+        taskId: "llm-0123456789abcdef",
+        input: { url: "https://example.com" },
+        startedAtMs: 1_000,
+      },
+    );
+    assert.equal(
+      storage.getItem(toolTaskRecoveryStorageKey("competitor-analysis"))?.includes("result"),
+      false,
+    );
+  });
+
+  it("removes expired or invalid recovery records", () => {
+    const storage = memoryStorage();
+    persistToolTaskRecovery("cold-start", "llm-task", { audience: "founders" }, 1_000, storage);
+    assert.equal(
+      readToolTaskRecovery("cold-start", { nowMs: 10_000, ttlMs: 100, storage }),
+      null,
+    );
+    assert.equal(storage.getItem(toolTaskRecoveryStorageKey("cold-start")), null);
+  });
+
+  it("clears recovery on an explicit reset", () => {
+    const storage = memoryStorage();
+    persistToolTaskRecovery("email-template-generator", "llm-task", {}, 1_000, storage);
+    clearToolTaskRecovery("email-template-generator", storage);
+    assert.equal(readToolTaskRecovery("email-template-generator", { storage }), null);
+  });
+});

package/src/components/tools/engine/task-recovery.ts

@@ -0,0 +1,109 @@
+export const TOOL_TASK_RECOVERY_TTL_MS = 24 * 60 * 60 * 1000;
+
+export type ToolTaskRecovery<TInput = unknown> = {
+  version: 1;
+  taskId: string;
+  input: TInput;
+  startedAtMs: number;
+};
+
+type RecoveryStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+
+function browserSessionStorage(): RecoveryStorage | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function toolTaskRecoveryStorageKey(slug: string): string {
+  return `tomako.tool-task.${slug.trim().toLowerCase()}.v1`;
+}
+
+/** Persist only task identity and user input; auth and result data stay server-owned. */
+export function persistToolTaskRecovery<TInput>(
+  slug: string,
+  taskId: string,
+  input: TInput,
+  startedAtMs = Date.now(),
+  storage: RecoveryStorage | null = browserSessionStorage(),
+): ToolTaskRecovery<TInput> | null {
+  if (!storage || !slug.trim() || !taskId.trim()) return null;
+  const recovery: ToolTaskRecovery<TInput> = {
+    version: 1,
+    taskId: taskId.trim(),
+    input,
+    startedAtMs,
+  };
+  try {
+    storage.setItem(toolTaskRecoveryStorageKey(slug), JSON.stringify(recovery));
+    return recovery;
+  } catch {
+    return null;
+  }
+}
+
+export function readToolTaskRecovery<TInput>(
+  slug: string,
+  options: {
+    ttlMs?: number;
+    nowMs?: number;
+    storage?: RecoveryStorage | null;
+    parseInput?: (input: unknown) => TInput | null;
+  } = {},
+): ToolTaskRecovery<TInput> | null {
+  const storage = options.storage === undefined
+    ? browserSessionStorage()
+    : options.storage;
+  if (!storage || !slug.trim()) return null;
+  const key = toolTaskRecoveryStorageKey(slug);
+  try {
+    const raw = storage.getItem(key);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<ToolTaskRecovery<unknown>>;
+    const nowMs = options.nowMs ?? Date.now();
+    const ttlMs = options.ttlMs ?? TOOL_TASK_RECOVERY_TTL_MS;
+    if (
+      parsed.version !== 1 ||
+      typeof parsed.taskId !== "string" ||
+      !parsed.taskId.trim() ||
+      typeof parsed.startedAtMs !== "number" ||
+      !Number.isFinite(parsed.startedAtMs) ||
+      parsed.startedAtMs > nowMs + 60_000 ||
+      nowMs - parsed.startedAtMs > ttlMs
+    ) {
+      storage.removeItem(key);
+      return null;
+    }
+    const input = options.parseInput
+      ? options.parseInput(parsed.input)
+      : (parsed.input as TInput);
+    if (input === null) {
+      storage.removeItem(key);
+      return null;
+    }
+    return {
+      version: 1,
+      taskId: parsed.taskId.trim(),
+      input,
+      startedAtMs: parsed.startedAtMs,
+    };
+  } catch {
+    storage.removeItem(key);
+    return null;
+  }
+}
+
+export function clearToolTaskRecovery(
+  slug: string,
+  storage: RecoveryStorage | null = browserSessionStorage(),
+) {
+  if (!storage || !slug.trim()) return;
+  try {
+    storage.removeItem(toolTaskRecoveryStorageKey(slug));
+  } catch {
+    // Recovery is best effort and must never block a user reset.
+  }
+}

package/src/components/tools/engine/use-legacy-llm-task.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 
 import {
   watchLlmTask,
@@ -41,7 +41,11 @@ export function useLegacyLlmTaskWatch<TResult>() {
       taskId: string,
       pollOnce: (taskId: string) => Promise<LlmTaskWatchPollOutcome>,
       handlers: LegacyTaskWatchHandlers<TResult>,
-      options?: { pollIntervalMs?: number; graceWindowMs?: number },
+      options?: {
+        pollIntervalMs?: number;
+        graceWindowMs?: number;
+        startedAtMs?: number;
+      },
     ) => {
       stop();
       stopRef.current = watchLlmTask({
@@ -55,10 +59,19 @@ export function useLegacyLlmTaskWatch<TResult>() {
         isCancelled: () => cancelledRef.current,
         pollIntervalMs: options?.pollIntervalMs,
         graceWindowMs: options?.graceWindowMs,
+        startedAtMs: options?.startedAtMs,
       });
     },
     [stop],
   );
 
-  return { start, stop, isCancelled: () => cancelledRef.current };
+  const isCancelled = useCallback(() => cancelledRef.current, []);
+
+  // Consumers legitimately use the controller as an effect dependency. Keep
+  // its identity stable so a state update does not run their cleanup and stop
+  // the task watcher that was just started.
+  return useMemo(
+    () => ({ start, stop, isCancelled }),
+    [isCancelled, start, stop],
+  );
 }

package/src/components/tools/engine/use-tool-task.ts

@@ -15,6 +15,11 @@ import {
   submitPackageTask,
 } from "../../../host/client";
 import { watchLlmTask } from "../../../host/client";
+import {
+  clearToolTaskRecovery,
+  persistToolTaskRecovery,
+  readToolTaskRecovery,
+} from "./task-recovery";
 
 export type EngineErrorCode =
   | "validation"
@@ -47,6 +52,7 @@ export function useToolTask<TResult = unknown>(
   locale: AppLocale,
 ) {
   const [state, setState] = useState<ToolTaskState<TResult>>({ phase: "idle" });
+  const [recoveredValues, setRecoveredValues] = useState<FormValues | null>(null);
   const cancelledRef = useRef(false);
   const stopWatchRef = useRef<(() => void) | null>(null);
   const lastSnapshotRef = useRef<{ status: string; error?: string }>({
@@ -61,11 +67,76 @@ export function useToolTask<TResult = unknown>(
     };
   }, []);
 
+  const startAgentWatch = useCallback((taskId: string, startedAtMs?: number) => {
+    if (pkg.runtime.lane !== "agent") return;
+    const runtime = pkg.runtime;
+    setState({ phase: "running", taskId, status: startedAtMs ? "RESTORING" : "PENDING" });
+    stopWatchRef.current = watchLlmTask({
+      taskId,
+      startedAtMs,
+      pollIntervalMs: runtime.watch?.pollIntervalMs,
+      graceWindowMs: runtime.watch?.graceWindowMs,
+      isCancelled: () => cancelledRef.current,
+      pollOnce: async (id: string) => {
+        const snapshot = await fetchPackageTask<TResult>(pkg, id);
+        lastSnapshotRef.current = { status: snapshot.status, error: snapshot.error };
+        if (snapshot.data) {
+          return { settled: true, kind: "success", data: snapshot.data };
+        }
+        if (snapshot.status === "FAILED") {
+          return { settled: true, kind: "error", category: "task" };
+        }
+        if (snapshot.status === "RESULT_INVALID") {
+          return { settled: true, kind: "error", category: "schema" };
+        }
+        return { settled: false, pendingWriteback: true };
+      },
+      handlers: {
+        onStatus: (status: string) => {
+          setState((prev) =>
+            prev.phase === "running" ? { ...prev, status } : prev,
+          );
+        },
+        onSuccess: (data: TResult) => {
+          setState({ phase: "done", taskId, data: data as TResult });
+        },
+        onError: (category: string) => {
+          const { status, error } = lastSnapshotRef.current;
+          let code: EngineErrorCode;
+          if (category === "timeout") {
+            code =
+              status === "SUCCEEDED" || status === "AWAITING_RESULT"
+                ? "resultWritebackMissing"
+                : "resultTimeout";
+          } else if (category === "schema") {
+            code =
+              error === "wrong_result_type"
+                ? "wrongResultType"
+                : "invalidResultSchema";
+          } else {
+            code = "taskFailed";
+          }
+          setState({ phase: "error", code, taskId });
+        },
+      },
+    });
+  }, [pkg]);
+
+  useEffect(() => {
+    if (pkg.runtime.lane !== "agent") return;
+    const recovered = readToolTaskRecovery<FormValues>(pkg.meta.slug);
+    if (!recovered) return;
+    setRecoveredValues(recovered.input);
+    startAgentWatch(recovered.taskId, recovered.startedAtMs);
+  }, [pkg.meta.slug, pkg.runtime.lane, startAgentWatch]);
+
   const reset = useCallback(() => {
     stopWatchRef.current?.();
     stopWatchRef.current = null;
+    clearToolTaskRecovery(pkg.meta.slug);
+    setRecoveredValues(null);
     setState({ phase: "idle" });
-  }, []);
+  }, [pkg.meta.slug]);
 
   const start = useCallback(
     async (values: FormValues, options?: { directModel?: string }) => {
@@ -137,59 +208,12 @@ export function useToolTask<TResult = unknown>(
       }
 
       if (cancelledRef.current) return;
-      setState({ phase: "running", taskId, status: "PENDING" });
-
-      stopWatchRef.current = watchLlmTask({
-        taskId,
-        pollIntervalMs: pkg.runtime.watch?.pollIntervalMs,
-        graceWindowMs: pkg.runtime.watch?.graceWindowMs,
-        isCancelled: () => cancelledRef.current,
-        pollOnce: async (id: string) => {
-          const snapshot = await fetchPackageTask<TResult>(pkg, id);
-          lastSnapshotRef.current = { status: snapshot.status, error: snapshot.error };
-          if (snapshot.data) {
-            return { settled: true, kind: "success", data: snapshot.data };
-          }
-          if (snapshot.status === "FAILED") {
-            return { settled: true, kind: "error", category: "task" };
-          }
-          if (snapshot.status === "RESULT_INVALID") {
-            return { settled: true, kind: "error", category: "schema" };
-          }
-          return { settled: false, pendingWriteback: true };
-        },
-        handlers: {
-          onStatus: (status: string) => {
-            setState((prev) =>
-              prev.phase === "running" ? { ...prev, status } : prev,
-            );
-          },
-          onSuccess: (data: TResult) => {
-            setState({ phase: "done", taskId, data: data as TResult });
-          },
-          onError: (category: string) => {
-            const { status, error } = lastSnapshotRef.current;
-            let code: EngineErrorCode;
-            if (category === "timeout") {
-              code =
-                status === "SUCCEEDED" || status === "AWAITING_RESULT"
-                  ? "resultWritebackMissing"
-                  : "resultTimeout";
-            } else if (category === "schema") {
-              code =
-                error === "wrong_result_type"
-                  ? "wrongResultType"
-                  : "invalidResultSchema";
-            } else {
-              code = "taskFailed";
-            }
-            setState({ phase: "error", code, taskId });
-          },
-        },
-      });
+      const startedAtMs = Date.now();
+      persistToolTaskRecovery(pkg.meta.slug, taskId, values, startedAtMs);
+      startAgentWatch(taskId, startedAtMs);
     },
-    [locale, pkg],
+    [locale, pkg, startAgentWatch],
   );
 
-  return { state, start, reset } as const;
+  return { state, start, reset, recoveredValues } as const;
 }

package/src/features/tools/app-store-screenshot-generator/widget/app-store-screenshot-generator.tsx

@@ -84,6 +84,13 @@ import type {
     OutputLanguageKey,
     StyleKey
 } from "./types";
+import {
+    clearToolTaskRecovery,
+    persistToolTaskRecovery,
+    readToolTaskRecovery,
+} from "../../../../components/tools/engine/task-recovery";
+
+const RECOVERY_SLUG = "app-store-screenshot-generator";
 
 export function AppStoreScreenshotGenerator() {
   const locale = useLocale();
@@ -114,6 +121,21 @@ export function AppStoreScreenshotGenerator() {
   const [logoDragActive, setLogoDragActive] = useState(false);
   const { brief: activityBrief } = useToolHandoff();
 
+  useEffect(() => {
+    const recovered = readToolTaskRecovery(RECOVERY_SLUG, {
+      parseInput: (value) => {
+        const parsed = appStoreScreenshotGeneratorInputSchema.safeParse(value);
+        return parsed.success ? parsed.data : null;
+      },
+    });
+    if (!recovered) return;
+    setDraft(recovered.input);
+    setScreenshotReferences(recovered.input.screenshotReferences);
+    void runGeneration(recovered.input, recovered.taskId, recovered.startedAtMs);
+    // Restore only once for this mounted tool route.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   useEffect(() => {
     if (!activityBrief || busy || !output) return;
     publishActivityArtifact(
@@ -179,8 +201,16 @@ export function AppStoreScreenshotGenerator() {
       return;
     }
 
+    await runGeneration(parsed.data);
+  }
+
+  async function runGeneration(
+    input: AppStoreScreenshotGeneratorInput,
+    recoveredTaskId?: string,
+    recoveredStartedAtMs?: number,
+  ) {
     try {
-      setDraft(parsed.data);
+      setDraft(input);
       setBusy(true);
       setOutput(null);
       setSelectedId(null);
@@ -190,16 +220,16 @@ export function AppStoreScreenshotGenerator() {
       setGenerationProgress({
         phase: "submitting",
         completedCount: 0,
-        totalCount: expectedAssetCount(parsed.data),
+        totalCount: expectedAssetCount(input),
         failedCount: 0,
-        estimatedRemainingSeconds: initialEstimatedSeconds(parsed.data),
+        estimatedRemainingSeconds: initialEstimatedSeconds(input),
       });
       requestAnimationFrame(() => {
         resultRef.current?.scrollIntoView({ behavior: "smooth", block: "center" });
       });
 
       const generated = await generateStoreAssets(
-        parsed.data,
+        input,
         locale,
         (progress) => {
           const parsedProgressOutput = appStoreScreenshotGeneratorOutputSchema.safeParse(
@@ -226,11 +256,18 @@ export function AppStoreScreenshotGenerator() {
           updateGenerationProgress({
             phase: "planning",
             completedCount: 0,
-            totalCount: expectedAssetCount(parsed.data),
+            totalCount: expectedAssetCount(input),
             failedCount: 0,
-            estimatedRemainingSeconds: initialEstimatedSeconds(parsed.data),
+            estimatedRemainingSeconds: initialEstimatedSeconds(input),
           });
         },
+        {
+          taskId: recoveredTaskId,
+          startedAtMs: recoveredStartedAtMs,
+          onTaskSubmitted: (taskId, startedAtMs) => {
+            persistToolTaskRecovery(RECOVERY_SLUG, taskId, input, startedAtMs);
+          },
+        },
       );
       const parsedOutput = appStoreScreenshotGeneratorOutputSchema.safeParse(generated.output);
 
@@ -286,6 +323,7 @@ export function AppStoreScreenshotGenerator() {
   }
 
   function reset() {
+    clearToolTaskRecovery(RECOVERY_SLUG);
     setOutput(null);
     setSelectedId(null);
     setLightboxIndex(null);

package/src/features/tools/app-store-screenshot-generator/widget/generation.test.ts

@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { registerToolsRuntimeHostClient } from "../../../../host/client";
+import type { AppStoreScreenshotAgentResult } from "../../../../lib/tools/app-store-screenshot-generator-schema";
+
+import { waitForAgentResult } from "./generation";
+
+const prompt = "Generate a cohesive app store screenshot set from the supplied product UI. ".repeat(4);
+
+function agentResult(
+  assetCount: number,
+  reportStatus: AppStoreScreenshotAgentResult["reportStatus"] = "partial",
+): AppStoreScreenshotAgentResult {
+  return {
+    promptId: "tools.app-store-screenshot-generator.agent",
+    promptVersion: "2026-07-03.2",
+    reportStatus,
+    summary: `${assetCount} screenshots planned`,
+    prompt,
+    assets: Array.from({ length: assetCount }, (_, index) => ({
+      id: `asset-${index + 1}`,
+      platform: "apple" as const,
+      format: "iphone" as const,
+      title: `Screenshot ${index + 1}`,
+      width: 1290,
+      height: 2796,
+      slot: index + 1,
+      setSize: 10,
+      imageTaskId: `image-task-${index + 1}`,
+    })),
+    failures: [],
+    totalAssets: 10,
+    completedAssets: assetCount,
+    failedAssets: 0,
+  };
+}
+
+function registerTaskSequence(
+  responses: Array<{
+    status: string;
+    data: AppStoreScreenshotAgentResult | null;
+    errorCode?: "task_failed";
+    error?: string;
+  }>,
+) {
+  let calls = 0;
+  registerToolsRuntimeHostClient({
+    fetchAppStoreScreenshotSetTask: async () => {
+      const response = responses[Math.min(calls, responses.length - 1)];
+      calls += 1;
+      return response;
+    },
+  });
+  return () => calls;
+}
+
+const fastPolling = { pollIntervalMs: 0, timeoutMs: 1_000 };
+
+describe("waitForAgentResult", () => {
+  it("keeps following after the first partial batch until the expected asset count arrives", async () => {
+    const firstBatch = agentResult(4);
+    const completeBatch = agentResult(10);
+    const calls = registerTaskSequence([
+      { status: "SUCCEEDED", data: firstBatch },
+      { status: "SUCCEEDED", data: completeBatch },
+    ]);
+    const progressCounts: number[] = [];
+
+    const result = await waitForAgentResult(
+      "task-expected-count",
+      (progress) => progressCounts.push(progress.assets.length),
+      10,
+      fastPolling,
+    );
+
+    assert.equal(calls(), 2);
+    assert.deepEqual(progressCounts, [4, 10]);
+    assert.equal(result.assets.length, 10);
+    assert.equal(result.reportStatus, "partial");
+  });
+
+  it("stops on an explicit final snapshot even when it has fewer assets than expected", async () => {
+    const firstBatch = agentResult(4);
+    const finalBatch = agentResult(4, "final");
+    const calls = registerTaskSequence([
+      { status: "SUCCEEDED", data: firstBatch },
+      { status: "SUCCEEDED", data: finalBatch },
+    ]);
+
+    const result = await waitForAgentResult(
+      "task-final",
+      () => undefined,
+      10,
+      fastPolling,
+    );
+
+    assert.equal(calls(), 2);
+    assert.equal(result.reportStatus, "final");
+    assert.equal(result.assets.length, 4);
+  });
+
+  it("returns the last usable partial snapshot when the task fails terminally", async () => {
+    const firstBatch = agentResult(4);
+    const calls = registerTaskSequence([
+      { status: "RUNNING", data: firstBatch },
+      {
+        status: "FAILED",
+        data: null,
+        errorCode: "task_failed",
+        error: "background follower failed",
+      },
+    ]);
+
+    const result = await waitForAgentResult(
+      "task-terminal",
+      () => undefined,
+      10,
+      fastPolling,
+    );
+
+    assert.equal(calls(), 2);
+    assert.equal(result.reportStatus, "partial");
+    assert.equal(result.assets.length, 4);
+  });
+});