feat: Task run deep linking (#337)

charlesvien · web-flow · commit e0bd971f6347 · 2025-12-18T12:54:25.000+01:00
diff --git a/apps/array/src/main/services/task-link/service.ts b/apps/array/src/main/services/task-link/service.ts
@@ -12,16 +12,21 @@ export const TaskLinkEvent = {
 } as const;
 
 export interface TaskLinkEvents {
-  [TaskLinkEvent.OpenTask]: { taskId: string };
+  [TaskLinkEvent.OpenTask]: { taskId: string; taskRunId?: string };
+}
+
+export interface PendingDeepLink {
+  taskId: string;
+  taskRunId?: string;
 }
 
 @injectable()
 export class TaskLinkService extends TypedEventEmitter<TaskLinkEvents> {
   /**
-   * Pending task ID that was received before renderer was ready.
+   * Pending deep link that was received before renderer was ready.
    * This handles the case where the app is launched via deep link.
    */
-  private pendingTaskId: string | null = null;
+  private pendingDeepLink: PendingDeepLink | null = null;
 
   constructor(
     @inject(MAIN_TOKENS.DeepLinkService)
@@ -36,8 +41,12 @@ export class TaskLinkService extends TypedEventEmitter<TaskLinkEvents> {
   }
 
   private handleTaskLink(path: string): boolean {
-    // path is just the taskId (e.g., "abc123" from array://task/abc123)
-    const taskId = path.split("/")[0];
+    // path formats:
+    //   "abc123" from array://task/abc123
+    //   "abc123/run/xyz789" from array://task/abc123/run/xyz789
+    const parts = path.split("/");
+    const taskId = parts[0];
+    const taskRunId = parts[1] === "run" ? parts[2] : undefined;
 
     if (!taskId) {
       log.warn("Task link missing task ID");
@@ -48,12 +57,16 @@ export class TaskLinkService extends TypedEventEmitter<TaskLinkEvents> {
     const hasListeners = this.listenerCount(TaskLinkEvent.OpenTask) > 0;
 
     if (hasListeners) {
-      log.info(`Emitting task link event: ${taskId}`);
-      this.emit(TaskLinkEvent.OpenTask, { taskId });
+      log.info(
+        `Emitting task link event: taskId=${taskId}, taskRunId=${taskRunId ?? "none"}`,
+      );
+      this.emit(TaskLinkEvent.OpenTask, { taskId, taskRunId });
     } else {
       // Renderer not ready yet - queue it for later
-      log.info(`Queueing task link (renderer not ready): ${taskId}`);
-      this.pendingTaskId = taskId;
+      log.info(
+        `Queueing task link (renderer not ready): taskId=${taskId}, taskRunId=${taskRunId ?? "none"}`,
+      );
+      this.pendingDeepLink = { taskId, taskRunId };
     }
 
     // Focus the window
@@ -69,15 +82,17 @@ export class TaskLinkService extends TypedEventEmitter<TaskLinkEvents> {
   }
 
   /**
-   * Get and clear any pending task ID.
+   * Get and clear any pending deep link.
    * Called by renderer on mount to handle deep links that arrived before it was ready.
    */
-  public consumePendingTaskId(): string | null {
-    const taskId = this.pendingTaskId;
-    this.pendingTaskId = null;
-    if (taskId) {
-      log.info(`Consumed pending task link: ${taskId}`);
+  public consumePendingDeepLink(): PendingDeepLink | null {
+    const pending = this.pendingDeepLink;
+    this.pendingDeepLink = null;
+    if (pending) {
+      log.info(
+        `Consumed pending task link: taskId=${pending.taskId}, taskRunId=${pending.taskRunId ?? "none"}`,
+      );
     }
-    return taskId;
+    return pending;
   }
 }
diff --git a/apps/array/src/main/trpc/routers/deep-link.ts b/apps/array/src/main/trpc/routers/deep-link.ts
@@ -1,6 +1,7 @@
 import { container } from "../../di/container.js";
 import { MAIN_TOKENS } from "../../di/tokens.js";
 import {
+  type PendingDeepLink,
   TaskLinkEvent,
   type TaskLinkService,
 } from "../../services/task-link/service.js";
@@ -12,7 +13,8 @@ const getService = () =>
 export const deepLinkRouter = router({
   /**
    * Subscribe to task link deep link events.
-   * Emits task ID when array://task/{taskId} is opened.
+   * Emits task ID (and optional task run ID) when array://task/{taskId} or
+   * array://task/{taskId}/run/{taskRunId} is opened.
    */
   onOpenTask: publicProcedure.subscription(async function* (opts) {
     const service = getService();
@@ -25,11 +27,11 @@ export const deepLinkRouter = router({
   }),
 
   /**
-   * Get any pending task ID that arrived before renderer was ready.
+   * Get any pending deep link that arrived before renderer was ready.
    * This handles the case where the app is launched via deep link.
    */
-  getPendingTaskId: publicProcedure.query(() => {
+  getPendingDeepLink: publicProcedure.query((): PendingDeepLink | null => {
     const service = getService();
-    return service.consumePendingTaskId();
+    return service.consumePendingDeepLink();
   }),
 });
diff --git a/apps/array/src/renderer/hooks/useTaskDeepLink.ts b/apps/array/src/renderer/hooks/useTaskDeepLink.ts
@@ -32,16 +32,19 @@ export function useTaskDeepLink() {
   const hasFetchedPending = useRef(false);
 
   const handleOpenTask = useCallback(
-    async (taskId: string) => {
-      log.info(`Opening task from deep link: ${taskId}`);
+    async (taskId: string, taskRunId?: string) => {
+      log.info(
+        `Opening task from deep link: ${taskId}${taskRunId ? `, run: ${taskRunId}` : ""}`,
+      );
 
       try {
         const taskService = get<TaskService>(RENDERER_TOKENS.TaskService);
-        const result = await taskService.openTask(taskId);
+        const result = await taskService.openTask(taskId, taskRunId);
 
         if (!result.success) {
           log.error("Failed to open task from deep link", {
             taskId,
+            taskRunId,
             error: result.error,
             failedStep: result.failedStep,
           });
@@ -66,11 +69,12 @@ export function useTaskDeepLink() {
         // Invalidate to ensure sync with server
         queryClient.invalidateQueries({ queryKey: taskKeys.lists() });
 
-        // Mark as viewed and navigate
         markAsViewed(taskId);
         navigateToTask(task);
 
-        log.info(`Successfully opened task from deep link: ${taskId}`);
+        log.info(
+          `Successfully opened task from deep link: ${taskId}${taskRunId ? `, run: ${taskRunId}` : ""}`,
+        );
       } catch (error) {
         log.error("Unexpected error opening task from deep link:", error);
         toast.error("Failed to open task");
@@ -86,11 +90,12 @@ export function useTaskDeepLink() {
     const fetchPending = async () => {
       hasFetchedPending.current = true;
       try {
-        const pendingTaskId =
-          await trpcVanilla.deepLink.getPendingTaskId.query();
-        if (pendingTaskId) {
-          log.info(`Found pending deep link task: ${pendingTaskId}`);
-          handleOpenTask(pendingTaskId);
+        const pending = await trpcVanilla.deepLink.getPendingDeepLink.query();
+        if (pending) {
+          log.info(
+            `Found pending deep link: taskId=${pending.taskId}, taskRunId=${pending.taskRunId ?? "none"}`,
+          );
+          handleOpenTask(pending.taskId, pending.taskRunId);
         }
       } catch (error) {
         log.error("Failed to check for pending deep link:", error);
@@ -103,9 +108,11 @@ export function useTaskDeepLink() {
   // Subscribe to deep link events (for warm start via deep link)
   trpcReact.deepLink.onOpenTask.useSubscription(undefined, {
     onData: (data) => {
-      log.info(`Received deep link event for task: ${data.taskId}`);
+      log.info(
+        `Received deep link event: taskId=${data.taskId}, taskRunId=${data.taskRunId ?? "none"}`,
+      );
       if (!data?.taskId) return;
-      handleOpenTask(data.taskId);
+      handleOpenTask(data.taskId, data.taskRunId);
     },
   });
 }
diff --git a/apps/array/src/renderer/services/task/service.ts b/apps/array/src/renderer/services/task/service.ts
@@ -67,12 +67,15 @@ export class TaskService {
   }
 
   /**
-   * Open an existing task by ID.
+   * Open an existing task by ID, optionally loading a specific run.
    * If the workspace already exists, just fetches task data.
    * Otherwise runs the full saga to set up the workspace.
    */
-  public async openTask(taskId: string): Promise<CreateTaskResult> {
-    log.info("Opening existing task", { taskId });
+  public async openTask(
+    taskId: string,
+    taskRunId?: string,
+  ): Promise<CreateTaskResult> {
+    log.info("Opening existing task", { taskId, taskRunId });
 
     const posthogClient = useAuthStore.getState().client;
     if (!posthogClient) {
@@ -89,6 +92,14 @@ export class TaskService {
       log.info("Workspace already exists, fetching task only", { taskId });
       try {
         const task = await posthogClient.getTask(taskId);
+
+        // If a specific run was requested, fetch and use it
+        if (taskRunId) {
+          log.info("Fetching specific task run", { taskId, taskRunId });
+          const run = await posthogClient.getTaskRun(taskId, taskRunId);
+          task.latest_run = run;
+        }
+
         return {
           success: true,
           data: {
@@ -112,6 +123,24 @@ export class TaskService {
 
     if (result.success) {
       this.updateStoresOnSuccess(result.data);
+
+      // If a specific run was requested, update the task with that run
+      if (taskRunId && result.data.task) {
+        try {
+          log.info("Fetching specific task run for new workspace", {
+            taskId,
+            taskRunId,
+          });
+          const run = await posthogClient.getTaskRun(taskId, taskRunId);
+          result.data.task.latest_run = run;
+        } catch (error) {
+          log.warn("Failed to fetch specific task run, using latest", {
+            taskId,
+            taskRunId,
+            error,
+          });
+        }
+      }
     }
 
     return result;
