feat(gastown): First-class Bead Artifacts — flexible outputs beyond just PRs

[jrf0110]

Summary

Currently, Gastown agents can only formally express one type of work output: a Pull Request URL, which is hardcoded into the review_metadata.pr_url column.

Agents often produce many other types of outputs during their work. A polecat might create a GitHub Issue for tech debt, write a discovery document, generate a preview deployment URL, or spawn follow-up beads.

We should introduce Bead Artifacts as first-class entities. A bead can have zero or more artifacts of various types, providing a structured, queryable record of everything an agent produced.

Motivation

• Rich Workspaces: A bead becomes a workspace of outputs, not just a state machine tracking a single PR.
• Visibility: The UI can aggregate and display all artifacts generated by a convoy (e.g., "This convoy produced 3 PRs, 2 Issues, and 1 Architecture Doc").
• Mayor Intelligence: The Mayor can query structured artifacts (e.g., "Give me all preview links generated yesterday").
• Workflow Triggers (Future): Artifacts can act as outputs that trigger downstream workflows (e.g., a preview_url artifact triggers a Lighthouse testing workflow).

Design

1. SQLite Schema (bead_artifacts)

Instead of overloading beads.metadata, create a dedicated table in the TownDO to make artifacts fully queryable.

CREATE TABLE IF NOT EXISTS bead_artifacts (
  artifact_id TEXT PRIMARY KEY,
  bead_id TEXT NOT NULL REFERENCES beads(bead_id) ON DELETE CASCADE,
  type TEXT NOT NULL,       -- e.g., 'pull_request', 'issue', 'document', 'preview_url', 'bead', 'other'
  label TEXT NOT NULL,      -- Human readable: "Auth Fix PR", "Tech Debt Ticket", "Vercel Preview"
  url TEXT,                 -- External link or internal routing path
  metadata TEXT DEFAULT '{}', -- JSON for extra context
  created_by_agent_id TEXT, -- agent_id that created it
  created_at TEXT NOT NULL
);

CREATE INDEX idx_bead_artifacts_bead_id ON bead_artifacts(bead_id);

2. Agent Tools

Provide a way for agents to explicitly attach artifacts to their work.

Option A: New Tool (gt_attach_artifact)

gt_attach_artifact: tool({
  description: "Attach an output artifact (like a PR, Issue, or Document URL) to your current bead.",
  args: { 
    type: z.enum(["pull_request", "issue", "bead", "document", "preview_url", "other"]),
    url: z.string(),
    label: z.string().describe("A short, human-readable name for the artifact")
  },
  // ...
})

Option B: Extend gt_done (Recommended for final outputs)
Extend the gt_done tool arguments to accept an optional array of artifacts alongside the summary:

{
  "summary": "Fixed the login bug and created an issue for the tech debt.",
  "artifacts": [
    { "type": "issue", "url": "https://github.com/...", "label": "Tech debt issue" }
  ]
}

Agents can use both: gt_attach_artifact during execution, and the artifacts array in gt_done for final outputs.

3. UI / UX Updates

• Bead Detail Page: Add a dedicated "Artifacts" section. Render nicely formatted cards based on the type (e.g., GitHub icon for PRs/Issues, Vercel/globe icon for previews, document icon for docs).
• Convoy View: Aggregate and display all artifacts from child beads in the convoy summary.
• Deprecate pr_url: Migrate the UI to use the bead_artifacts table instead of review_metadata.pr_url. (A migration script will need to backfill existing pr_urls into the new table).

Acceptance Criteria

• bead_artifacts table added to TownDO SQLite schema with Zod definitions.
• gt_attach_artifact tool added for all agents (Polecat, Refinery, Mayor).
• gt_done tool updated to accept an optional artifacts array.
• TownDO RPC endpoints created for fetching artifacts for a bead/convoy.
• UI updated to display Bead Artifacts on the Bead Detail and Convoy pages.
• Data migration to move existing review_metadata.pr_url entries into bead_artifacts.
• Reconciler logic updated to check bead_artifacts for PR URLs when polling for PR status (replacing the old review_metadata.pr_url check).

References

• feat(gastown): Workflows — visual DAG builder with scheduled and event-triggered execution #1943 - Workflows (Artifacts can serve as outputs for workflow triggers).