Merge pull request #462 from spacedriveapp/task-metadata-github

jamiepine · web-flow · commit 2876d5a9c2b8 · 2026-03-21T09:58:21.000-07:00
fix: preserve nested task metadata updates
diff --git a/docs/design-docs/task-tracking.md b/docs/design-docs/task-tracking.md
@@ -206,7 +206,7 @@ Arguments:
   status: String (optional)
   priority: String (optional)
   subtasks: JSON (optional, full replacement of subtasks array)
-  metadata: JSON (optional, merged with existing)
+  metadata: JSON (optional, deep-merged with existing; nested objects are merged recursively)
   complete_subtask: i32 (optional, index of subtask to mark complete)
 ```
 
@@ -260,6 +260,25 @@ Each task card shows:
 - Worker status — if in_progress, shows live worker status
 - Metadata badges — GitHub issue/PR links rendered as small icons
 
+Recommended metadata shape for GitHub linkage:
+
+```json
+{
+  "github_issue": {
+    "repo": "spacedriveapp/spacebot",
+    "number": 123,
+    "url": "https://github.com/spacedriveapp/spacebot/issues/123"
+  },
+  "github_pr": {
+    "repo": "spacedriveapp/spacebot",
+    "number": 456,
+    "url": "https://github.com/spacedriveapp/spacebot/pull/456"
+  }
+}
+```
+
+Task metadata updates should deep-merge nested objects so agents and workers can add fields like `url`, `labels`, or `state` later without replacing the rest of the stored GitHub reference.
+
 Clicking a card opens a detail panel (slide-out or modal) with:
 
 - Full description (markdown rendered)
diff --git a/interface/src/routes/AgentTasks.tsx b/interface/src/routes/AgentTasks.tsx
@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
+import { faCodeBranch, faExternalLinkAlt } from "@fortawesome/free-solid-svg-icons";
 import {
   api,
   type TaskItem,
@@ -57,6 +59,122 @@ const PRIORITY_COLORS: Record<
   low: "outline",
 };
 
+interface GithubReference {
+  kind: "issue" | "pr";
+  label: string;
+  url: string | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toSafeExternalUrl(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol === "https:" || parsed.protocol === "http:") {
+      return parsed.toString();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function readGithubReference(
+  value: unknown,
+  kind: GithubReference["kind"],
+): GithubReference | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const number = typeof value.number === "number" ? value.number : null;
+  const repo = typeof value.repo === "string" ? value.repo : null;
+  const url = toSafeExternalUrl(value.url);
+
+  if (number === null && url === null && repo === null) {
+    return null;
+  }
+
+  const noun = kind === "issue" ? "Issue" : "PR";
+  const label = number !== null ? `${noun} #${number}` : repo ? `${noun} ${repo}` : noun;
+
+  return { kind, label, url };
+}
+
+function getGithubReferences(metadata: Record<string, unknown>): GithubReference[] {
+  const references = [
+    readGithubReference(metadata.github_issue, "issue"),
+    readGithubReference(metadata.github_pr, "pr"),
+  ].filter((reference): reference is GithubReference => reference !== null);
+
+  return references;
+}
+
+function GithubMetadataBadges({
+  metadata,
+  references: precomputed,
+  compact = false,
+}: {
+  metadata?: Record<string, unknown>;
+  references?: GithubReference[];
+  compact?: boolean;
+}) {
+  const references = precomputed ?? (metadata ? getGithubReferences(metadata) : []);
+  if (references.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="flex flex-wrap items-center gap-1.5">
+      {references.map((reference) => {
+        const content = (
+          <>
+            <FontAwesomeIcon icon={faCodeBranch} className="text-[10px]" />
+            <span>{reference.label}</span>
+            {reference.url && (
+              <FontAwesomeIcon icon={faExternalLinkAlt} className="text-[9px]" />
+            )}
+          </>
+        );
+
+        const className = compact
+          ? "cursor-pointer hover:border-blue-400/50 hover:text-blue-300"
+          : "cursor-pointer hover:border-blue-400/50 hover:bg-blue-500/20 hover:text-blue-300";
+
+        if (reference.url) {
+          return (
+            <a
+              key={`${reference.kind}-${reference.label}`}
+              href={reference.url}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex"
+              onClick={(event) => event.stopPropagation()}
+            >
+              <Badge variant="blue" size="sm" className={className}>
+                {content}
+              </Badge>
+            </a>
+          );
+        }
+
+        return (
+          <Badge
+            key={`${reference.kind}-${reference.label}`}
+            variant="blue"
+            size="sm"
+          >
+            {content}
+          </Badge>
+        );
+      })}
+    </div>
+  );
+}
+
 export function AgentTasks({ agentId }: { agentId: string }) {
   const queryClient = useQueryClient();
   const { taskEventVersion } = useLiveContext();
@@ -331,6 +449,7 @@ function TaskCard({
             Worker
           </Badge>
         )}
+        <GithubMetadataBadges metadata={task.metadata} compact />
       </div>
 
       {/* Subtask progress bar */}
@@ -577,6 +696,19 @@ function TaskDetailDialog({
             </div>
           )}
 
+          {(() => {
+            const githubRefs = getGithubReferences(task.metadata);
+            if (githubRefs.length === 0) return null;
+            return (
+              <div>
+                <label className="mb-1 block text-xs text-ink-dull">
+                  GitHub Links
+                </label>
+                <GithubMetadataBadges references={githubRefs} />
+              </div>
+            );
+          })()}
+
           {/* Metadata */}
           <div className="grid grid-cols-1 gap-2 text-xs text-ink-dull sm:grid-cols-2">
             <div>Created: {formatTimeAgo(task.created_at)}</div>
diff --git a/prompts/en/tools/task_create_description.md.j2 b/prompts/en/tools/task_create_description.md.j2
@@ -1 +1 @@
-Create a task on the board. The description is the spec — write it as a full markdown document a worker can execute with no conversation context. Include requirements, constraints, file paths, examples, and acceptance criteria. Always pre-fill subtasks as a checklist execution plan. Short title, rich description, concrete subtasks.
+Create a task on the board. The description is the spec — write it as a full markdown document a worker can execute with no conversation context. Include requirements, constraints, file paths, examples, and acceptance criteria. Always pre-fill subtasks as a checklist execution plan. Short title, rich description, concrete subtasks. Use `metadata` for structured external references like GitHub issues or PRs when the user mentions them, for example `{ "github_issue": { "repo": "owner/repo", "number": 123, "url": "https://github.com/owner/repo/issues/123" } }`.
diff --git a/prompts/en/tools/task_update_description.md.j2 b/prompts/en/tools/task_update_description.md.j2
@@ -1 +1 @@
-Update an existing task by task number. Use this to refine the spec as scope evolves — append sections, rewrite requirements, adjust subtasks, change priority. The description is a living document; update it when the user clarifies intent or when you discover new context. Move to `ready` when the spec is complete and the cortex will pick it up for execution. For worker processes, only subtask and metadata updates are allowed.
+Update an existing task by task number. Use this to refine the spec as scope evolves — append sections, rewrite requirements, adjust subtasks, change priority. The description is a living document; update it when the user clarifies intent or when you discover new context. Move to `ready` when the spec is complete and the cortex will pick it up for execution. Use `metadata` to attach or enrich structured external references like GitHub issues and PRs. Metadata updates deep-merge nested objects, so you can safely add fields such as `url`, `number`, `repo`, `labels`, or `state` without replacing sibling fields. For worker processes, only subtask and metadata updates are allowed.
diff --git a/src/tasks/store.rs b/src/tasks/store.rs
@@ -488,13 +488,35 @@ fn merge_json_object(current: Value, patch: Option<Value>) -> Value {
         return current;
     };
 
-    let mut merged = current.as_object().cloned().unwrap_or_default();
-    if let Some(patch_object) = patch.as_object() {
-        for (key, value) in patch_object {
-            merged.insert(key.clone(), value.clone());
-        }
+    // Only apply object patches — ignore scalars/nulls to preserve the
+    // invariant that task metadata is always an object.
+    let Value::Object(patch_object) = patch else {
+        return current;
+    };
+
+    let Value::Object(mut current_object) = current else {
+        return Value::Object(patch_object);
+    };
+
+    for (key, patch_value) in patch_object {
+        let merged_value = match current_object.remove(&key) {
+            Some(current_value) => merge_json_value(current_value, patch_value),
+            None => patch_value,
+        };
+        current_object.insert(key, merged_value);
+    }
+
+    Value::Object(current_object)
+}
+
+fn merge_json_value(current: Value, patch: Value) -> Value {
+    match (current, patch) {
+        (Value::Object(current_object), Value::Object(patch_object)) => merge_json_object(
+            Value::Object(current_object),
+            Some(Value::Object(patch_object)),
+        ),
+        (_, patch_value) => patch_value,
     }
-    Value::Object(merged)
 }
 
 fn parse_subtasks(value: &str) -> Vec<TaskSubtask> {
@@ -695,4 +717,69 @@ mod tests {
             requeued.worker_id
         );
     }
+
+    #[tokio::test]
+    async fn metadata_updates_deep_merge_nested_objects() {
+        let store = setup_store().await;
+        let created = store
+            .create(CreateTaskInput {
+                agent_id: "agent-test".to_string(),
+                title: "github-linked task".to_string(),
+                description: None,
+                status: TaskStatus::Backlog,
+                priority: TaskPriority::Medium,
+                subtasks: Vec::new(),
+                metadata: serde_json::json!({
+                    "github_issue": {
+                        "repo": "spacedriveapp/spacebot",
+                        "number": 123,
+                        "labels": ["bug"],
+                        "state": "open"
+                    },
+                    "source": "github"
+                }),
+                source_memory_id: None,
+                created_by: "branch".to_string(),
+            })
+            .await
+            .expect("task should be created");
+
+        let updated = store
+            .update(
+                "agent-test",
+                created.task_number,
+                UpdateTaskInput {
+                    metadata: Some(serde_json::json!({
+                        "github_issue": {
+                            "url": "https://github.com/spacedriveapp/spacebot/issues/123",
+                            "labels": ["bug", "tasks"]
+                        },
+                        "github_pr": {
+                            "number": 456
+                        }
+                    })),
+                    ..Default::default()
+                },
+            )
+            .await
+            .expect("update should succeed")
+            .expect("task should exist");
+
+        assert_eq!(
+            updated.metadata,
+            serde_json::json!({
+                "github_issue": {
+                    "repo": "spacedriveapp/spacebot",
+                    "number": 123,
+                    "url": "https://github.com/spacedriveapp/spacebot/issues/123",
+                    "labels": ["bug", "tasks"],
+                    "state": "open"
+                },
+                "github_pr": {
+                    "number": 456
+                },
+                "source": "github"
+            })
+        );
+    }
 }
diff --git a/src/tools/task_update.rs b/src/tools/task_update.rs
@@ -101,7 +101,7 @@ impl Tool for TaskUpdateTool {
                             "required": ["title", "completed"]
                         }
                     },
-                    "metadata": { "type": "object", "description": "Metadata object merged with current metadata" },
+                    "metadata": { "type": "object", "description": "Metadata object deep-merged with current metadata" },
                     "complete_subtask": { "type": "integer", "description": "Subtask index to mark complete" }
                 },
                 "required": ["task_number"]
@@ -135,7 +135,7 @@ impl Tool for TaskUpdateTool {
                             "required": ["title", "completed"]
                         }
                     },
-                    "metadata": { "type": "object", "description": "Metadata object merged with current metadata" },
+                    "metadata": { "type": "object", "description": "Metadata object deep-merged with current metadata" },
                     "complete_subtask": { "type": "integer", "description": "Subtask index to mark complete" },
                     "worker_id": { "type": "string", "description": "Optional worker ID to bind to this task" },
                     "approved_by": { "type": "string", "description": "Optional approver identifier" }

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Create a task on the board. The description is the spec — write it as a full markdown document a worker can execute with no conversation context. Include requirements, constraints, file paths, examples, and acceptance criteria. Always pre-fill subtasks as a checklist execution plan. Short title, rich description, concrete subtasks.`
	`1`	+Create a task on the board. The description is the spec — write it as a full markdown document a worker can execute with no conversation context. Include requirements, constraints, file paths, examples, and acceptance criteria. Always pre-fill subtasks as a checklist execution plan. Short title, rich description, concrete subtasks. Use `metadata` for structured external references like GitHub issues or PRs when the user mentions them, for example `{ "github_issue": { "repo": "owner/repo", "number": 123, "url": "https://github.com/owner/repo/issues/123" } }`.
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		-Update an existing task by task number. Use this to refine the spec as scope evolves — append sections, rewrite requirements, adjust subtasks, change priority. The description is a living document; update it when the user clarifies intent or when you discover new context. Move to `ready` when the spec is complete and the cortex will pick it up for execution. For worker processes, only subtask and metadata updates are allowed.
	`1`	+Update an existing task by task number. Use this to refine the spec as scope evolves — append sections, rewrite requirements, adjust subtasks, change priority. The description is a living document; update it when the user clarifies intent or when you discover new context. Move to `ready` when the spec is complete and the cortex will pick it up for execution. Use `metadata` to attach or enrich structured external references like GitHub issues and PRs. Metadata updates deep-merge nested objects, so you can safely add fields such as `url`, `number`, `repo`, `labels`, or `state` without replacing sibling fields. For worker processes, only subtask and metadata updates are allowed.