The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
External object references across issue surfaces (#8512)
Dotta2dbaf4a7fa59
diff --git a/cli/src/__tests__/worktree.test.ts b/cli/src/__tests__/worktree.test.tsindex 0ac73ce692..bc23cf4de2 100644--- a/cli/src/__tests__/worktree.test.ts+++ b/cli/src/__tests__/worktree.test.ts@@ -874,7 +874,7 @@ describe("worktree helpers", () => {}});- it("reseed preserves the current worktree ports, instance id, and branding", async () => {+ itEmbeddedPostgres("reseed preserves the current worktree ports, instance id, and branding", async () => {const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-reseed-"));const repoRoot = path.join(tempRoot, "repo");const sourceRoot = path.join(tempRoot, "source");diff --git a/doc/plans/2026-04-24-external-object-reference-backfill.md b/doc/plans/2026-04-24-external-object-reference-backfill.mdnew file mode 100644index 0000000000..02b8e86730--- /dev/null+++ b/doc/plans/2026-04-24-external-object-reference-backfill.md@@ -0,0 +1,28 @@+# External Object Reference Backfill++## Purpose++Backfill existing issue titles, descriptions, comments, and documents into `external_object_mentions` after the Phase 3 detector registry and mention sync service exist.++## Command Shape++Add a command parallel to the internal issue-reference backfill:++```sh+pnpm external-objects:backfill+pnpm external-objects:backfill -- --company <company-id>+pnpm external-objects:backfill -- --dry-run+```++## Required Behavior++- Scan issue title and description sources, issue comments, and issue documents through the same external-object mention sync service used by write hooks.+- Preserve company boundaries: every scan query, mention upsert, object upsert, and dry-run summary must include `company_id`.+- Use shared URL extraction and canonicalization helpers so raw URLs, URL userinfo, query strings, and fragments are never persisted.+- Replace mentions per source instead of appending, using the same source key shape as live write sync.+- Report counts by company, source kind, provider key, object type, skipped userinfo URLs, and unresolved URLs.+- Default to a non-interactive safe run; `--dry-run` must avoid writes while still reporting what would change.++## Phase 3 Hook++The command should be implemented only after the detector registry can classify URLs and the service can upsert mentions/placeholders consistently. Until then, Phase 2 owns the schema and shared helpers that make the command safe.diff --git a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md b/doc/plugins/PLUGIN_AUTHORING_GUIDE.mdindex 5f8380f7b1..b541ff5caa 100644--- a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md+++ b/doc/plugins/PLUGIN_AUTHORING_GUIDE.md@@ -12,6 +12,9 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec i- Plugin UI runs as same-origin JavaScript inside the main Paperclip app.- Worker-side host APIs are capability-gated.- Plugin UI is not sandboxed by manifest capabilities.+- External object reference providers are trusted-install only in the MVP.+ Capabilities gate provider detection/resolution and host API calls, but they+ are not a sandbox boundary for untrusted marketplace code.- Plugin database migrations are restricted to a host-derived plugin namespace.- Plugin-managed surfaces are first-class records (agents, projects, routines, andskills) rather than private plugin-only state.@@ -22,6 +25,29 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec ibuilding custom versions.- `ctx.assets` is not supported in the current runtime.+## External object reference providers++Plugins can contribute provider-neutral object reference detection and status+resolution for URLs and future explicit links. Declare `objectReferences` in the+manifest and add at least `external.objects.detect` and `external.objects.read`.++```ts+objectReferences: [+ {+ providerKey: "mocktracker",+ displayName: "Mock Tracker",+ objectTypes: ["ticket"],+ urlPatterns: ["https://mock.example/tickets/:id"],+ },+],+```++Implement `onDetectExternalObjects()` in the worker to recognize sanitized URL+candidates and return provider-stable identities. Implement+`onResolveExternalObject()` to return normalized board-safe status metadata.+Paperclip owns inline markdown rendering; plugins must not return React, HTML,+or `dangerouslySetInnerHTML` content for inline references.+## Scaffold a pluginUse the CLI scaffold command:diff --git a/packages/db/src/external-objects-schema.test.ts b/packages/db/src/external-objects-schema.test.tsnew file mode 100644index 0000000000..897a98d726--- /dev/null+++ b/packages/db/src/external-objects-schema.test.ts@@ -0,0 +1,47 @@+import { getTableConfig } from "drizzle-orm/pg-core";+import { describe, expect, it } from "vitest";+import { externalObjectMentions } from "./schema/external_object_mentions.js";+import { externalObjects } from "./schema/external_objects.js";++function indexColumns(table: Parameters<typeof getTableConfig>[0], indexName: string): string[] {+ const index = getTableConfig(table).indexes.find((candidate) => candidate.config.name === indexName);+ if (!index) return [];+ return index.config.columns.map((column) => (column as { name: string }).name);+}++describe("external object reference schema", () => {+ it("scopes external object uniqueness by company", () => {+ expect(indexColumns(externalObjects, "external_objects_company_external_id_uq")).toEqual([+ "company_id",+ "provider_key",+ "object_type",+ "external_id",+ ]);+ expect(indexColumns(externalObjects, "external_objects_company_identity_uq")).toEqual([+ "company_id",+ "provider_key",+ "object_type",+ "canonical_identity_hash",+ ]);+ });++ it("indexes status, refresh scheduling, source issue, and object lookups by company", () => {+ expect(indexColumns(externalObjects, "external_objects_company_provider_status_idx")).toEqual([+ "company_id",+ "provider_key",+ "status_category",+ ]);+ expect(indexColumns(externalObjects, "external_objects_company_refresh_idx")).toEqual([+ "company_id",+ "next_refresh_at",+ ]);+ expect(indexColumns(externalObjectMentions, "external_object_mentions_company_source_issue_idx")).toEqual([+ "company_id",+ "source_issue_id",+ ]);+ expect(indexColumns(externalObjectMentions, "external_object_mentions_company_object_idx")).toEqual([+ "company_id",+ "object_id",+ ]);+ });+});diff --git a/packages/db/src/migrations/0106_external_object_references.sql b/packages/db/src/migrations/0106_external_object_references.sqlnew file mode 100644index 0000000000..070a36b452--- /dev/null+++ b/packages/db/src/migrations/0106_external_object_references.sql@@ -0,0 +1,106 @@+CREATE TABLE IF NOT EXISTS "external_objects" (+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,+ "company_id" uuid NOT NULL,+ "provider_key" text NOT NULL,+ "plugin_id" uuid,+ "object_type" text NOT NULL,+ "external_id" text NOT NULL,+ "sanitized_canonical_url" text,+ "canonical_identity_hash" text,+ "display_title" text,+ "status_key" text,+ "status_label" text,+ "status_category" text DEFAULT 'unknown' NOT NULL,+ "status_tone" text DEFAULT 'neutral' NOT NULL,+ "liveness" text DEFAULT 'unknown' NOT NULL,+ "is_terminal" boolean DEFAULT false NOT NULL,+ "data" jsonb DEFAULT '{}'::jsonb NOT NULL,+ "remote_version" text,+ "etag" text,+ "last_resolved_at" timestamp with time zone,+ "last_changed_at" timestamp with time zone,+ "last_error_at" timestamp with time zone,+ "next_refresh_at" timestamp with time zone,+ "last_error_code" text,+ "last_error_message" text,+ "created_at" timestamp with time zone DEFAULT now() NOT NULL,+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL+);+--> statement-breakpoint+CREATE TABLE IF NOT EXISTS "external_object_mentions" (+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,+ "company_id" uuid NOT NULL,+ "source_issue_id" uuid NOT NULL,+ "source_kind" text NOT NULL,+ "source_record_id" uuid,+ "document_key" text,+ "property_key" text,+ "matched_text_redacted" text,+ "sanitized_display_url" text,+ "canonical_identity_hash" text,+ "canonical_identity" jsonb,+ "object_id" uuid,+ "provider_key" text,+ "detector_key" text,+ "object_type" text,+ "confidence" text DEFAULT 'exact' NOT NULL,+ "created_by_plugin_id" uuid,+ "created_at" timestamp with time zone DEFAULT now() NOT NULL,+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL+);+--> statement-breakpoint+DO $$ BEGIN+ ALTER TABLE "external_objects" ADD CONSTRAINT "external_objects_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;+EXCEPTION+ WHEN duplicate_object THEN null;+END $$;+--> statement-breakpoint+DO $$ BEGIN+ ALTER TABLE "external_objects" ADD CONSTRAINT "external_objects_plugin_id_plugins_id_fk" FOREIGN KEY ("plugin_id") REFERENCES "public"."plugins"("id") ON DELETE set null ON UPDATE no action;+EXCEPTION+ WHEN duplicate_object THEN null;+END $$;+--> statement-breakpoint+DO $$ BEGIN+ ALTER TABLE "external_object_mentions" ADD CONSTRAINT "external_object_mentions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;+EXCEPTION+ WHEN duplicate_object THEN null;+END $$;+--> statement-breakpoint+DO $$ BEGIN+ ALTER TABLE "external_object_mentions" ADD CONSTRAINT "external_object_mentions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;+EXCEPTION+ WHEN duplicate_object THEN null;+END $$;+--> statement-breakpoint+DO $$ BEGIN+ ALTER TABLE "external_object_mentions" ADD CONSTRAINT "external_object_mentions_object_id_external_objects_id_fk" FOREIGN KEY ("object_id") REFERENCES "public"."external_objects"("id") ON DELETE set null ON UPDATE no action;+EXCEPTION+ WHEN duplicate_object THEN null;+END $$;+--> statement-breakpoint+DO $$ BEGIN+ ALTER TABLE "external_object_mentions" ADD CONSTRAINT "external_object_mentions_created_by_plugin_id_plugins_id_fk" FOREIGN KEY ("created_by_plugin_id") REFERENCES "public"."plugins"("id") ON DELETE set null ON UPDATE no action;+EXCEPTION+ WHEN duplicate_object THEN null;+END $$;+--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "external_objects_company_provider_object_idx" ON "external_objects" USING btree ("company_id","provider_key","object_type");+--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "external_objects_company_provider_status_idx" ON "external_objects" USING btree ("company_id","provider_key","status_category");+--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "external_objects_company_refresh_idx" ON "external_objects" USING btree ("company_id","next_refresh_at");+--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "external_objects_company_external_id_uq" ON "external_objects" USING btree ("company_id","provider_key","object_type","external_id");+--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "external_objects_company_identity_uq" ON "external_objects" USING btree ("company_id","provider_key","object_type","canonical_identity_hash");+--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "external_object_mentions_company_source_issue_idx" ON "external_object_mentions" USING btree ("company_id","source_issue_id");+--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "external_object_mentions_company_object_idx" ON "external_object_mentions" USING btree ("company_id","object_id");+--> statement-breakpoint+CREATE INDEX IF NOT EXISTS "external_object_mentions_company_provider_idx" ON "external_object_mentions" USING btree ("company_id","provider_key","object_type");+--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "external_object_mentions_company_source_record_uq" ON "external_object_mentions" USING btree ("company_id","source_issue_id","source_kind","source_record_id","document_key","property_key","canonical_identity_hash") WHERE "source_record_id" is not null and "canonical_identity_hash" is not null;+--> statement-breakpoint+CREATE UNIQUE INDEX IF NOT EXISTS "external_object_mentions_company_source_null_record_uq" ON "external_object_mentions" USING btree ("company_id","source_issue_id","source_kind","document_key","property_key","canonical_identity_hash") WHERE "source_record_id" is null and "canonical_identity_hash" is not null;diff --git a/packages/db/src/migrations/0107_external_object_display_metadata.sql b/packages/db/src/migrations/0107_external_object_display_metadata.sqlnew file mode 100644index 0000000000..3888f9ea1f--- /dev/null+++ b/packages/db/src/migrations/0107_external_object_display_metadata.sql@@ -0,0 +1,5 @@+ALTER TABLE "external_objects" ADD COLUMN IF NOT EXISTS "display_key" text;+--> statement-breakpoint+ALTER TABLE "external_objects" ADD COLUMN IF NOT EXISTS "icon_key" text;+--> statement-breakpoint+ALTER TABLE "external_objects" ADD COLUMN IF NOT EXISTS "status_icon_key" text;diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.jsonindex ae94c3645b..06099862a1 100644--- a/packages/db/src/migrations/meta/_journal.json+++ b/packages/db/src/migrations/meta/_journal.json@@ -743,6 +743,20 @@"when": 1781902000000,"tag": "0105_instance_scoped_environments","breakpoints": true+ },+ {+ "idx": 106,+ "version": "7",+ "when": 1781902100000,+ "tag": "0106_external_object_references",+ "breakpoints": true+ },+ {+ "idx": 107,+ "version": "7",+ "when": 1782165200000,+ "tag": "0107_external_object_display_metadata",+ "breakpoints": true}]}diff --git a/packages/db/src/schema/external_object_mentions.ts b/packages/db/src/schema/external_object_mentions.tsnew file mode 100644index 0000000000..95cb8e9c80--- /dev/null+++ b/packages/db/src/schema/external_object_mentions.ts@@ -0,0 +1,61 @@+import { sql } from "drizzle-orm";+import { index, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";+import type { ExternalObjectMentionConfidence, ExternalObjectMentionSourceKind } from "@paperclipai/shared";+import { companies } from "./companies.js";+import { externalObjects } from "./external_objects.js";+import { issues } from "./issues.js";+import { plugins } from "./plugins.js";++export const externalObjectMentions = pgTable(+ "external_object_mentions",+ {+ id: uuid("id").primaryKey().defaultRandom(),+ companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),+ sourceIssueId: uuid("source_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),+ sourceKind: text("source_kind").$type<ExternalObjectMentionSourceKind>().notNull(),+ sourceRecordId: uuid("source_record_id"),+ documentKey: text("document_key"),+ propertyKey: text("property_key"),+ matchedTextRedacted: text("matched_text_redacted"),+ sanitizedDisplayUrl: text("sanitized_display_url"),+ canonicalIdentityHash: text("canonical_identity_hash"),+ canonicalIdentity: jsonb("canonical_identity").$type<Record<string, unknown>>(),+ objectId: uuid("object_id").references(() => externalObjects.id, { onDelete: "set null" }),+ providerKey: text("provider_key"),+ detectorKey: text("detector_key"),+ objectType: text("object_type"),+ confidence: text("confidence").$type<ExternalObjectMentionConfidence>().notNull().default("exact"),+ createdByPluginId: uuid("created_by_plugin_id").references(() => plugins.id, { onDelete: "set null" }),+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),+ },+ (table) => ({+ companySourceIssueIdx: index("external_object_mentions_company_source_issue_idx").on(+ table.companyId,+ table.sourceIssueId,+ ),+ companyObjectIdx: index("external_object_mentions_company_object_idx").on(table.companyId, table.objectId),+ companyProviderIdx: index("external_object_mentions_company_provider_idx").on(+ table.companyId,+ table.providerKey,+ table.objectType,+ ),+ companySourceMentionWithRecordUq: uniqueIndex("external_object_mentions_company_source_record_uq").on(+ table.companyId,+ table.sourceIssueId,+ table.sourceKind,+ table.sourceRecordId,+ table.documentKey,+ table.propertyKey,+ table.canonicalIdentityHash,+ ).where(sql`${table.sourceRecordId} is not null and ${table.canonicalIdentityHash} is not null`),+ companySourceMentionWithoutRecordUq: uniqueIndex("external_object_mentions_company_source_null_record_uq").on(+ table.companyId,+ table.sourceIssueId,+ table.sourceKind,+ table.documentKey,+ table.propertyKey,+ table.canonicalIdentityHash,+ ).where(sql`${table.sourceRecordId} is null and ${table.canonicalIdentityHash} is not null`),+ }),+);diff --git a/packages/db/src/schema/external_objects.ts b/packages/db/src/schema/external_objects.tsnew file mode 100644index 0000000000..867702987d--- /dev/null+++ b/packages/db/src/schema/external_objects.ts@@ -0,0 +1,77 @@+import {+ boolean,+ index,+ jsonb,+ pgTable,+ text,+ timestamp,+ uniqueIndex,+ uuid,+} from "drizzle-orm/pg-core";+import type {+ ExternalObjectLivenessState,+ ExternalObjectStatusCategory,+ ExternalObjectStatusTone,+} from "@paperclipai/shared";+import { companies } from "./companies.js";+import { plugins } from "./plugins.js";++export const externalObjects = pgTable(+ "external_objects",+ {+ id: uuid("id").primaryKey().defaultRandom(),+ companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),+ providerKey: text("provider_key").notNull(),+ pluginId: uuid("plugin_id").references(() => plugins.id, { onDelete: "set null" }),+ objectType: text("object_type").notNull(),+ externalId: text("external_id").notNull(),+ sanitizedCanonicalUrl: text("sanitized_canonical_url"),+ canonicalIdentityHash: text("canonical_identity_hash"),+ displayKey: text("display_key"),+ iconKey: text("icon_key"),+ displayTitle: text("display_title"),+ statusKey: text("status_key"),+ statusLabel: text("status_label"),+ statusIconKey: text("status_icon_key"),+ statusCategory: text("status_category").$type<ExternalObjectStatusCategory>().notNull().default("unknown"),+ statusTone: text("status_tone").$type<ExternalObjectStatusTone>().notNull().default("neutral"),+ liveness: text("liveness").$type<ExternalObjectLivenessState>().notNull().default("unknown"),+ isTerminal: boolean("is_terminal").notNull().default(false),+ data: jsonb("data").$type<Record<string, unknown>>().notNull().default({}),+ remoteVersion: text("remote_version"),+ etag: text("etag"),+ lastResolvedAt: timestamp("last_resolved_at", { withTimezone: true }),+ lastChangedAt: timestamp("last_changed_at", { withTimezone: true }),+ lastErrorAt: timestamp("last_error_at", { withTimezone: true }),+ nextRefreshAt: timestamp("next_refresh_at", { withTimezone: true }),+ lastErrorCode: text("last_error_code"),+ lastErrorMessage: text("last_error_message"),+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),+ },+ (table) => ({+ companyProviderObjectIdx: index("external_objects_company_provider_object_idx").on(+ table.companyId,+ table.providerKey,+ table.objectType,+ ),+ companyProviderStatusIdx: index("external_objects_company_provider_status_idx").on(+ table.companyId,+ table.providerKey,+ table.statusCategory,+ ),+ companyRefreshIdx: index("external_objects_company_refresh_idx").on(table.companyId, table.nextRefreshAt),+ companyExternalIdUq: uniqueIndex("external_objects_company_external_id_uq").on(+ table.companyId,+ table.providerKey,+ table.objectType,+ table.externalId,+ ),+ companyCanonicalIdentityUq: uniqueIndex("external_objects_company_identity_uq").on(+ table.companyId,+ table.providerKey,+ table.objectType,+ table.canonicalIdentityHash,+ ),+ }),+);diff --git a/packages/db/src/schema/index.ts b/packages/db/src/schema/index.tsindex cda88aedbe..5b2d9e1a49 100644--- a/packages/db/src/schema/index.ts+++ b/packages/db/src/schema/index.ts@@ -36,6 +36,8 @@ export { issueWatchdogs } from "./issue_watchdogs.js";export { issuePlanDecompositions } from "./issue_plan_decompositions.js";export { issueRecoveryActions } from "./issue_recovery_actions.js";export { issueReferenceMentions } from "./issue_reference_mentions.js";+export { externalObjects } from "./external_objects.js";+export { externalObjectMentions } from "./external_object_mentions.js";export { issueRelations } from "./issue_relations.js";export { routines, routineRevisions, routineTriggers, routineRuns } from "./routines.js";export { issueWorkProducts } from "./issue_work_products.js";diff --git a/packages/plugins/sdk/README.md b/packages/plugins/sdk/README.mdindex 020b0b8ded..3a8b866d14 100644--- a/packages/plugins/sdk/README.md+++ b/packages/plugins/sdk/README.md@@ -341,6 +341,10 @@ Declare in `manifest.capabilities`. Grouped by scope:| | `telemetry.track` || | `database.namespace.migrate` || | `database.namespace.write` |+| | `external.objects.detect` |+| | `external.objects.read` |+| | `external.objects.write` |+| | `external.objects.refresh` || **Instance** | `instance.settings.register` || | `plugin.state.read` || | `plugin.state.write` |@@ -372,6 +376,42 @@ Declare in `manifest.capabilities`. Grouped by scope:Full list in code: import `PLUGIN_CAPABILITIES` from `@paperclipai/plugin-sdk`.+### External Object Reference Providers++Trusted connector plugins can declare generic external object providers in the+manifest. The host owns URL scanning, sanitized canonical URLs, core storage,+normalized status rendering, and issue/comment/document write durability. The+plugin only identifies provider-owned objects and resolves board-safe status+metadata.++```ts+objectReferences: [+ {+ providerKey: "mocktracker",+ displayName: "Mock Tracker",+ objectTypes: ["ticket"],+ urlPatterns: ["https://mock.example/tickets/:id"],+ refreshPolicy: { defaultTtlSeconds: 300, staleAfterSeconds: 1800 },+ },+],+capabilities: ["external.objects.detect", "external.objects.read"],+```++Implement `onDetectExternalObjects()` to map sanitized URL candidates to+`providerKey`, `objectType`, provider-stable `externalId`, and optional display+metadata such as `displayKey`/`iconKey`. Implement `onResolveExternalObject()`+to return a normalized snapshot with `statusCategory`, `statusTone`,+`statusLabel`, optional `statusIconKey`, board-safe `data`, and freshness+metadata. Slow or failing plugins are isolated: Paperclip logs the failure and+continues saving the source issue, comment, or document.++MVP security posture: provider plugins are trusted installs. Manifest+capabilities gate host APIs and provider invocation paths, but they are not a+sandbox boundary for untrusted marketplace code. Plugin UI is same-origin+JavaScript and must not be mounted inline in markdown; inline external-object+rendering uses host-owned metadata only. Treat untrusted providers as future work+that requires worker sandboxing plus isolated plugin UI.+### Restricted Database NamespaceTrusted orchestration plugins can declare a host-owned PostgreSQL namespace:diff --git a/packages/plugins/sdk/src/define-plugin.ts b/packages/plugins/sdk/src/define-plugin.tsindex e13b939acf..b0e4ecff6e 100644--- a/packages/plugins/sdk/src/define-plugin.ts+++ b/packages/plugins/sdk/src/define-plugin.ts@@ -62,6 +62,12 @@ import type {PluginEnvironmentResumeLeaseParams,PluginEnvironmentValidateConfigParams,PluginEnvironmentValidationResult,+ DetectExternalObjectsParams,+ DetectExternalObjectsResult,+ ResolveExternalObjectParams,+ PluginExternalObjectResolveResult,+ RefreshExternalObjectsParams,+ RefreshExternalObjectsResult,} from "./protocol.js";// ---------------------------------------------------------------------------@@ -243,6 +249,39 @@ export interface PluginDefinition {* access, capabilities, and checkout policy.*/onApiRequest?(input: PluginApiRequestInput): Promise<PluginApiResponse>;++ /**+ * Called when Paperclip scans issue/comment/document content and asks this+ * plugin whether any sanitized URL candidates belong to its external object+ * providers. The host has already stripped URL userinfo, query strings, and+ * fragments unless provider-safe identity components were explicitly hashed.+ *+ * Requires `external.objects.detect`.+ */+ onDetectExternalObjects?(+ params: DetectExternalObjectsParams,+ ): Promise<DetectExternalObjectsResult>;++ /**+ * Called when Paperclip needs the current normalized status for one external+ * object owned by a manifest-declared provider.+ *+ * Requires `external.objects.read`.+ */+ onResolveExternalObject?(+ params: ResolveExternalObjectParams,+ ): Promise<PluginExternalObjectResolveResult>;++ /**+ * Optional batch resolver used by providers that can refresh many objects+ * more efficiently than individual `onResolveExternalObject` calls.+ *+ * Requires `external.objects.refresh`.+ */+ onRefreshExternalObjects?(+ params: RefreshExternalObjectsParams,+ ): Promise<RefreshExternalObjectsResult>;+/*** Called to validate provider-specific configuration for a plugin-hosted* environment driver.diff --git a/packages/plugins/sdk/src/index.ts b/packages/plugins/sdk/src/index.tsindex 63ec9c7023..1339edeafc 100644--- a/packages/plugins/sdk/src/index.ts+++ b/packages/plugins/sdk/src/index.ts@@ -155,6 +155,17 @@ export type {PluginPerformActionActorContext,PluginPerformActionContext,ExecuteToolParams,+ PluginExternalObjectUrlCandidate,+ PluginExternalObjectSourceContext,+ DetectExternalObjectsParams,+ PluginExternalObjectDetection,+ DetectExternalObjectsResult,+ PluginExternalObjectRecordSnapshot,+ ResolveExternalObjectParams,+ PluginExternalObjectResolvedSnapshot,+ PluginExternalObjectResolveResult,+ RefreshExternalObjectsParams,+ RefreshExternalObjectsResult,PluginEnvironmentDiagnostic,PluginEnvironmentDriverBaseParams,PluginEnvironmentValidateConfigParams,@@ -313,6 +324,8 @@ export type {PluginApiRouteDeclaration,PluginLocalFolderDeclaration,PluginCompanySettings,+ PluginObjectReferenceRefreshPolicy,+ PluginObjectReferenceProviderDeclaration,PluginRecord,PluginDatabaseNamespaceRecord,PluginMigrationRecord,diff --git a/packages/plugins/sdk/src/protocol.ts b/packages/plugins/sdk/src/protocol.tsindex a3925049a7..c56a0dd23e 100644--- a/packages/plugins/sdk/src/protocol.ts+++ b/packages/plugins/sdk/src/protocol.ts@@ -40,6 +40,11 @@ import type {Goal,PluginLocalFolderDeclaration,PrincipalPermissionGrant,+ ExternalObjectStatusCategory,+ ExternalObjectStatusTone,+ ExternalObjectLivenessState,+ ExternalObjectMentionConfidence,+ ExternalObjectMentionSourceKind,} from "@paperclipai/shared";export type { PluginLauncherRenderContextSnapshot } from "@paperclipai/shared";@@ -432,6 +437,113 @@ export interface ExecuteToolParams {runContext: ToolRunContext;}+export interface PluginExternalObjectUrlCandidate {+ sanitizedCanonicalUrl: string;+ sanitizedDisplayUrl: string;+ canonicalIdentityHash: string;+ canonicalIdentity: Record<string, unknown>;+ redactedMatchedText: string;+}++export interface PluginExternalObjectSourceContext {+ companyId: string;+ sourceIssueId: string;+ sourceKind: ExternalObjectMentionSourceKind;+ sourceRecordId: string | null;+ documentKey: string | null;+ propertyKey: string | null;+}++export interface DetectExternalObjectsParams {+ companyId: string;+ urls: PluginExternalObjectUrlCandidate[];+ sourceContext: PluginExternalObjectSourceContext;+}++export interface PluginExternalObjectDetection {+ urlIdentityHash: string;+ providerKey: string;+ objectType: string;+ externalId: string;+ displayKey?: string | null;+ iconKey?: string | null;+ displayTitle?: string | null;+ confidence?: ExternalObjectMentionConfidence;+}++export interface DetectExternalObjectsResult {+ detections: PluginExternalObjectDetection[];+}++export interface PluginExternalObjectRecordSnapshot {+ id: string;+ companyId: string;+ providerKey: string;+ objectType: string;+ externalId: string;+ sanitizedCanonicalUrl: string | null;+ canonicalIdentityHash: string | null;+ displayKey: string | null;+ iconKey: string | null;+ displayTitle: string | null;+ statusKey: string | null;+ statusLabel: string | null;+ statusIconKey: string | null;+ statusCategory: ExternalObjectStatusCategory;+ statusTone: ExternalObjectStatusTone;+ liveness: ExternalObjectLivenessState;+ isTerminal: boolean;+ data: Record<string, unknown>;+ remoteVersion: string | null;+ etag: string | null;+}++export interface ResolveExternalObjectParams {+ companyId: string;+ providerKey: string;+ objectType: string;+ externalId: string;+ object: PluginExternalObjectRecordSnapshot;+}++export interface PluginExternalObjectResolvedSnapshot {+ displayKey?: string | null;+ iconKey?: string | null;+ displayTitle?: string | null;+ statusKey?: string | null;+ statusLabel?: string | null;+ statusIconKey?: string | null;+ statusCategory: ExternalObjectStatusCategory;+ statusTone: ExternalObjectStatusTone;+ isTerminal?: boolean;+ data?: Record<string, unknown>;+ remoteVersion?: string | null;+ etag?: string | null;+ ttlSeconds?: number;+}++export type PluginExternalObjectResolveResult =+ | { ok: true; snapshot: PluginExternalObjectResolvedSnapshot }+ | {+ ok: false;+ liveness: Extract<ExternalObjectLivenessState, "auth_required" | "unreachable">;+ errorCode: string;+ errorMessage?: string | null;+ retryAfterSeconds?: number;+ };++export interface RefreshExternalObjectsParams {+ companyId: string;+ objects: PluginExternalObjectRecordSnapshot[];+}++export interface RefreshExternalObjectsResult {+ results: Array<{+ objectId: string;+ result: PluginExternalObjectResolveResult;+ }>;+}+export interface PluginEnvironmentDiagnostic {severity: "info" | "warning" | "error";message: string;@@ -604,6 +716,18 @@ export interface HostToWorkerMethods {performAction: [params: PerformActionParams, result: unknown];/** @see PLUGIN_SPEC.md §13.10 */executeTool: [params: ExecuteToolParams, result: ToolResult];+ detectExternalObjects: [+ params: DetectExternalObjectsParams,+ result: DetectExternalObjectsResult,+ ];+ resolveExternalObject: [+ params: ResolveExternalObjectParams,+ result: PluginExternalObjectResolveResult,+ ];+ refreshExternalObjects: [+ params: RefreshExternalObjectsParams,+ result: RefreshExternalObjectsResult,+ ];environmentValidateConfig: [params: PluginEnvironmentValidateConfigParams,result: PluginEnvironmentValidationResult,@@ -659,6 +783,9 @@ export const HOST_TO_WORKER_OPTIONAL_METHODS: readonly HostToWorkerMethodName[]"getData","performAction","executeTool",+ "detectExternalObjects",+ "resolveExternalObject",+ "refreshExternalObjects","environmentValidateConfig","environmentProbe","environmentAcquireLease",diff --git a/packages/plugins/sdk/src/types.ts b/packages/plugins/sdk/src/types.tsindex 1951205526..e449252cc6 100644--- a/packages/plugins/sdk/src/types.ts+++ b/packages/plugins/sdk/src/types.ts@@ -84,6 +84,8 @@ export type {PluginDatabaseDeclaration,PluginApiRouteDeclaration,PluginApiRouteCompanyResolution,+ PluginObjectReferenceRefreshPolicy,+ PluginObjectReferenceProviderDeclaration,PluginRecord,PluginDatabaseNamespaceRecord,PluginMigrationRecord,diff --git a/packages/plugins/sdk/src/worker-rpc-host.ts b/packages/plugins/sdk/src/worker-rpc-host.tsindex cbb223d96c..cded95a82d 100644--- a/packages/plugins/sdk/src/worker-rpc-host.ts+++ b/packages/plugins/sdk/src/worker-rpc-host.ts@@ -82,6 +82,9 @@ import type {PluginPerformActionActorContext,PluginPerformActionContext,ExecuteToolParams,+ DetectExternalObjectsParams,+ ResolveExternalObjectParams,+ RefreshExternalObjectsParams,PluginEnvironmentAcquireLeaseParams,PluginEnvironmentDestroyLeaseParams,PluginEnvironmentExecuteParams,@@ -1351,6 +1354,12 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostcase "executeTool":return handleExecuteTool(params as ExecuteToolParams);+ case "detectExternalObjects":+ return handleDetectExternalObjects(params as DetectExternalObjectsParams);+ case "resolveExternalObject":+ return handleResolveExternalObject(params as ResolveExternalObjectParams);+ case "refreshExternalObjects":+ return handleRefreshExternalObjects(params as RefreshExternalObjectsParams);case "environmentValidateConfig":return handleEnvironmentValidateConfig(params as PluginEnvironmentValidateConfigParams);@@ -1409,6 +1418,9 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostif (plugin.definition.onHealth) supportedMethods.push("health");if (plugin.definition.onShutdown) supportedMethods.push("shutdown");if (plugin.definition.onApiRequest) supportedMethods.push("handleApiRequest");+ if (plugin.definition.onDetectExternalObjects) supportedMethods.push("detectExternalObjects");+ if (plugin.definition.onResolveExternalObject) supportedMethods.push("resolveExternalObject");+ if (plugin.definition.onRefreshExternalObjects) supportedMethods.push("refreshExternalObjects");if (plugin.definition.onEnvironmentValidateConfig) supportedMethods.push("environmentValidateConfig");if (plugin.definition.onEnvironmentProbe) supportedMethods.push("environmentProbe");if (plugin.definition.onEnvironmentAcquireLease) supportedMethods.push("environmentAcquireLease");@@ -1588,6 +1600,27 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHostreturn entry.fn(params.parameters, params.runContext);}+ async function handleDetectExternalObjects(params: DetectExternalObjectsParams) {+ if (!plugin.definition.onDetectExternalObjects) {+ throw methodNotImplemented("detectExternalObjects");+ }+ return plugin.definition.onDetectExternalObjects(params);+ }++ async function handleResolveExternalObject(params: ResolveExternalObjectParams) {+ if (!plugin.definition.onResolveExternalObject) {+ throw methodNotImplemented("resolveExternalObject");+ }+ return plugin.definition.onResolveExternalObject(params);+ }++ async function handleRefreshExternalObjects(params: RefreshExternalObjectsParams) {+ if (!plugin.definition.onRefreshExternalObjects) {+ throw methodNotImplemented("refreshExternalObjects");+ }+ return plugin.definition.onRefreshExternalObjects(params);+ }+function methodNotImplemented(method: string): Error & { code: number } {return Object.assign(new Error(`${method} is not implemented by this plugin`),diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.tsindex 954fa76a9d..040dc348f5 100644--- a/packages/shared/src/constants.ts+++ b/packages/shared/src/constants.ts@@ -358,6 +358,53 @@ export const DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES = [export type DocumentAnnotationAnchorConfidence =(typeof DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES)[number];+export const EXTERNAL_OBJECT_STATUS_CATEGORIES = [+ "unknown",+ "open",+ "waiting",+ "running",+ "succeeded",+ "failed",+ "blocked",+ "closed",+ "archived",+ "auth_required",+ "unreachable",+] as const;+export type ExternalObjectStatusCategory = (typeof EXTERNAL_OBJECT_STATUS_CATEGORIES)[number];++export const EXTERNAL_OBJECT_STATUS_TONES = [+ "neutral",+ "info",+ "success",+ "warning",+ "danger",+ "muted",+] as const;+export type ExternalObjectStatusTone = (typeof EXTERNAL_OBJECT_STATUS_TONES)[number];++export const EXTERNAL_OBJECT_LIVENESS_STATES = [+ "unknown",+ "fresh",+ "stale",+ "auth_required",+ "unreachable",+] as const;+export type ExternalObjectLivenessState = (typeof EXTERNAL_OBJECT_LIVENESS_STATES)[number];++export const EXTERNAL_OBJECT_MENTION_SOURCE_KINDS = [+ "title",+ "description",+ "comment",+ "document",+ "property",+ "plugin",+] as const;+export type ExternalObjectMentionSourceKind = (typeof EXTERNAL_OBJECT_MENTION_SOURCE_KINDS)[number];++export const EXTERNAL_OBJECT_MENTION_CONFIDENCES = ["exact", "likely", "possible"] as const;+export type ExternalObjectMentionConfidence = (typeof EXTERNAL_OBJECT_MENTION_CONFIDENCES)[number];+export const ISSUE_EXECUTION_POLICY_MODES = ["normal", "auto"] as const;export type IssueExecutionPolicyMode = (typeof ISSUE_EXECUTION_POLICY_MODES)[number];@@ -677,6 +724,7 @@ export const LIVE_EVENT_TYPES = ["heartbeat.run.log","agent.status","activity.logged",+ "external_object.updated","plugin.ui.updated","plugin.worker.crashed","plugin.worker.restarted",@@ -851,6 +899,10 @@ export const PLUGIN_CAPABILITIES = ["telemetry.track","database.namespace.migrate","database.namespace.write",+ "external.objects.detect",+ "external.objects.read",+ "external.objects.write",+ "external.objects.refresh",// Plugin State"plugin.state.read","plugin.state.write",diff --git a/packages/shared/src/external-objects-server.ts b/packages/shared/src/external-objects-server.tsnew file mode 100644index 0000000000..f323ba3e5e--- /dev/null+++ b/packages/shared/src/external-objects-server.ts@@ -0,0 +1,217 @@+import { createHash } from "node:crypto";+import { parseIssueReferenceHref } from "./issue-references.js";+import type {+ ExternalObjectCanonicalIdentity,+ ExternalObjectCanonicalUrl,+ ExternalObjectMentionSource,+ ExternalObjectUrlCanonicalizationOptions,+ ExternalObjectUrlMatch,+} from "./external-objects.js";++const EXTERNAL_URL_TOKEN_RE = /https?:\/\/[^\s<>()]+/gi;++function preserveNewlinesAsWhitespace(value: string) {+ return value.replace(/[^\n]/g, " ");+}++function stripMarkdownCode(markdown: string): string {+ if (!markdown) return "";++ let output = "";+ let index = 0;++ while (index < markdown.length) {+ const remaining = markdown.slice(index);+ const fenceMatch = /^(?:```+|~~~+)/.exec(remaining);+ const atLineStart = index === 0 || markdown[index - 1] === "\n";++ if (atLineStart && fenceMatch) {+ const fence = fenceMatch[0]!;+ const blockStart = index;+ index += fence.length;+ while (index < markdown.length && markdown[index] !== "\n") index += 1;+ if (index < markdown.length) index += 1;++ while (index < markdown.length) {+ const lineStart = index === 0 || markdown[index - 1] === "\n";+ if (lineStart && markdown.startsWith(fence, index)) {+ index += fence.length;+ while (index < markdown.length && markdown[index] !== "\n") index += 1;+ if (index < markdown.length) index += 1;+ break;+ }+ index += 1;+ }++ output += preserveNewlinesAsWhitespace(markdown.slice(blockStart, index));+ continue;+ }++ if (markdown[index] === "`") {+ let tickCount = 1;+ while (index + tickCount < markdown.length && markdown[index + tickCount] === "`") {+ tickCount += 1;+ }+ const fence = "`".repeat(tickCount);+ const inlineStart = index;+ index += tickCount;+ const closeIndex = markdown.indexOf(fence, index);+ if (closeIndex === -1) {+ output += markdown.slice(inlineStart, inlineStart + tickCount);+ index = inlineStart + tickCount;+ continue;+ }+ index = closeIndex + tickCount;+ output += preserveNewlinesAsWhitespace(markdown.slice(inlineStart, index));+ continue;+ }++ output += markdown[index]!;+ index += 1;+ }++ return output;+}++function trimTrailingPunctuation(token: string): string {+ let trimmed = token;+ while (trimmed.length > 0) {+ const last = trimmed[trimmed.length - 1]!;+ if (!".,!?;:".includes(last) && last !== ")" && last !== "]") break;++ if (+ (last === ")" && (trimmed.match(/\(/g)?.length ?? 0) >= (trimmed.match(/\)/g)?.length ?? 0))+ || (last === "]" && (trimmed.match(/\[/g)?.length ?? 0) >= (trimmed.match(/\]/g)?.length ?? 0))+ ) {+ break;+ }+ trimmed = trimmed.slice(0, -1);+ }+ return trimmed;+}++function sha256Hex(value: string): string {+ return createHash("sha256").update(value).digest("hex");+}++function stableStringify(value: unknown): string {+ if (Array.isArray(value)) {+ return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;+ }+ if (value && typeof value === "object") {+ const record = value as Record<string, unknown>;+ return `{${Object.keys(record)+ .sort()+ .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)+ .join(",")}}`;+ }+ return JSON.stringify(value);+}++function normalizePathname(pathname: string): string {+ return pathname || "/";+}++export function findExternalObjectUrlMatches(markdown: string): ExternalObjectUrlMatch[] {+ if (!markdown) return [];++ const scrubbed = stripMarkdownCode(markdown);+ const matches: ExternalObjectUrlMatch[] = [];+ let match: RegExpExecArray | null;+ const re = new RegExp(EXTERNAL_URL_TOKEN_RE);++ while ((match = re.exec(scrubbed)) !== null) {+ const matchedText = trimTrailingPunctuation(match[0]);+ if (!matchedText || parseIssueReferenceHref(matchedText)) continue;++ matches.push({+ index: match.index,+ length: matchedText.length,+ matchedText,+ });+ }++ return matches;+}++export function canonicalizeExternalObjectUrl(+ value: string,+ options: ExternalObjectUrlCanonicalizationOptions = {},+): ExternalObjectCanonicalUrl | null {+ let url: URL;+ try {+ url = new URL(value.trim());+ } catch {+ return null;+ }++ if (url.protocol !== "http:" && url.protocol !== "https:") return null;+ if (url.username || url.password) return null;++ const scheme = url.protocol === "https:" ? "https" : "http";+ const path = normalizePathname(url.pathname);+ const sanitizedCanonicalUrl = `${scheme}://${url.host.toLowerCase()}${path}`;+ const identityQueryParams = new Set(options.identityQueryParams ?? []);+ const queryParamHashes: Record<string, string> = {};++ for (const key of [...identityQueryParams].sort()) {+ const values = url.searchParams.getAll(key);+ if (values.length === 0) continue;+ queryParamHashes[key] = sha256Hex(values.join("\u0000"));+ }++ const canonicalIdentity: ExternalObjectCanonicalIdentity = {+ scheme,+ host: url.host.toLowerCase(),+ path,+ ...(Object.keys(queryParamHashes).length > 0 ? { queryParamHashes } : {}),+ };++ return {+ sanitizedCanonicalUrl,+ sanitizedDisplayUrl: sanitizedCanonicalUrl,+ canonicalIdentity,+ canonicalIdentityHash: sha256Hex(stableStringify(canonicalIdentity)),+ redactedMatchedText: sanitizedCanonicalUrl,+ };+}++export function extractExternalObjectCanonicalUrls(+ markdown: string,+ options: ExternalObjectUrlCanonicalizationOptions = {},+): ExternalObjectCanonicalUrl[] {+ const seen = new Set<string>();+ const ordered: ExternalObjectCanonicalUrl[] = [];++ for (const match of findExternalObjectUrlMatches(markdown)) {+ const canonical = canonicalizeExternalObjectUrl(match.matchedText, options);+ if (!canonical || seen.has(canonical.canonicalIdentityHash)) continue;+ seen.add(canonical.canonicalIdentityHash);+ ordered.push(canonical);+ }++ return ordered;+}++export function buildExternalObjectScopedIdentityKey(args: {+ companyId: string;+ providerKey: string;+ objectType: string;+ canonicalIdentityHash: string;+}): string {+ return [args.companyId, args.providerKey, args.objectType, args.canonicalIdentityHash].join(":");+}++export function buildExternalObjectMentionSourceKey(source: Required<Pick<+ ExternalObjectMentionSource,+ "companyId" | "sourceIssueId" | "sourceKind"+>> & ExternalObjectMentionSource): string {+ return [+ source.companyId,+ source.sourceIssueId,+ source.sourceKind,+ source.sourceRecordId ?? "",+ source.documentKey ?? "",+ source.propertyKey ?? "",+ ].join(":");+}diff --git a/packages/shared/src/external-objects.test.ts b/packages/shared/src/external-objects.test.tsnew file mode 100644index 0000000000..aa55bd97d9--- /dev/null+++ b/packages/shared/src/external-objects.test.ts@@ -0,0 +1,126 @@+import { describe, expect, it } from "vitest";+import { formatExternalObjectMentionSourceLabel } from "./external-objects.js";+import {+ buildExternalObjectMentionSourceKey,+ buildExternalObjectScopedIdentityKey,+ canonicalizeExternalObjectUrl,+ extractExternalObjectCanonicalUrls,+ findExternalObjectUrlMatches,+} from "./external-objects-server.js";+import { externalObjectProviderKeySchema, externalObjectTypeSchema } from "./validators/external-object.js";++describe("external object references", () => {+ it("extracts external urls without changing internal issue reference behavior", () => {+ expect(+ findExternalObjectUrlMatches(+ "See PAP-1, /issues/PAP-2, https://paperclip.ing/PAP/issues/PAP-3, and https://github.com/acme/app/pull/4.",+ ),+ ).toEqual([{ index: 70, length: 34, matchedText: "https://github.com/acme/app/pull/4" }]);+ });++ it("ignores urls inside inline and fenced code", () => {+ const markdown = [+ "Use https://github.com/acme/app/pull/1 here.",+ "`https://github.com/acme/app/pull/2` should not count.",+ "```",+ "https://github.com/acme/app/pull/3",+ "```",+ ].join("\n");++ expect(findExternalObjectUrlMatches(markdown).map((match) => match.matchedText)).toEqual([+ "https://github.com/acme/app/pull/1",+ ]);+ });++ it("canonicalizes urls by stripping query and fragment by default", () => {+ expect(canonicalizeExternalObjectUrl("HTTPS://GitHub.com/acme/app/pull/1?token=secret#discussion")).toMatchObject({+ sanitizedCanonicalUrl: "https://github.com/acme/app/pull/1",+ sanitizedDisplayUrl: "https://github.com/acme/app/pull/1",+ redactedMatchedText: "https://github.com/acme/app/pull/1",+ canonicalIdentity: {+ scheme: "https",+ host: "github.com",+ path: "/acme/app/pull/1",+ },+ });+ });++ it("rejects urls with userinfo", () => {+ expect(canonicalizeExternalObjectUrl("https://token:[email protected]/acme/app/pull/1")).toBeNull();+ });++ it("hashes provider-required query identity values without storing plaintext", () => {+ const first = canonicalizeExternalObjectUrl("https://deploy.test/run?id=secret-run&token=drop", {+ identityQueryParams: ["id"],+ });+ const second = canonicalizeExternalObjectUrl("https://deploy.test/run?id=secret-run&token=other", {+ identityQueryParams: ["id"],+ });++ expect(first?.sanitizedCanonicalUrl).toBe("https://deploy.test/run");+ expect(first?.canonicalIdentity.queryParamHashes?.id).toHaveLength(64);+ expect(first?.canonicalIdentity.queryParamHashes?.id).not.toContain("secret-run");+ expect(second?.canonicalIdentityHash).toBe(first?.canonicalIdentityHash);+ });++ it("dedupes extracted canonical urls by canonical identity", () => {+ expect(+ extractExternalObjectCanonicalUrls(+ "https://github.com/acme/app/pull/1?token=a and https://github.com/acme/app/pull/1#discussion",+ ).map((entry) => entry.sanitizedCanonicalUrl),+ ).toEqual(["https://github.com/acme/app/pull/1"]);+ });++ it("includes company id in scoped object identity keys", () => {+ const base = {+ providerKey: "github",+ objectType: "pull_request",+ canonicalIdentityHash: "hash",+ };++ expect(buildExternalObjectScopedIdentityKey({ companyId: "company-a", ...base })).not.toBe(+ buildExternalObjectScopedIdentityKey({ companyId: "company-b", ...base }),+ );+ });++ it("builds source keys for replacing mentions from the same source", () => {+ const oldMentionSource = buildExternalObjectMentionSourceKey({+ companyId: "company-a",+ sourceIssueId: "issue-1",+ sourceKind: "comment",+ sourceRecordId: "comment-1",+ });+ const newMentionSource = buildExternalObjectMentionSourceKey({+ companyId: "company-a",+ sourceIssueId: "issue-1",+ sourceKind: "comment",+ sourceRecordId: "comment-1",+ });+ const anotherCompanySource = buildExternalObjectMentionSourceKey({+ companyId: "company-b",+ sourceIssueId: "issue-1",+ sourceKind: "comment",+ sourceRecordId: "comment-1",+ });++ expect(newMentionSource).toBe(oldMentionSource);+ expect(anotherCompanySource).not.toBe(oldMentionSource);+ });++ it("formats stable source labels", () => {+ expect(formatExternalObjectMentionSourceLabel({ sourceKind: "title" })).toBe("Title");+ expect(formatExternalObjectMentionSourceLabel({ sourceKind: "document", documentKey: "plan" })).toBe(+ "Document: plan",+ );+ expect(formatExternalObjectMentionSourceLabel({ sourceKind: "property", propertyKey: "pr" })).toBe(+ "Property: pr",+ );+ });++ it("validates provider keys and object types", () => {+ expect(externalObjectProviderKeySchema.parse("github.enterprise")).toBe("github.enterprise");+ expect(externalObjectTypeSchema.parse("pull_request")).toBe("pull_request");+ expect(externalObjectProviderKeySchema.safeParse("GitHub").success).toBe(false);+ expect(externalObjectTypeSchema.safeParse("pull-request").success).toBe(false);+ });+});diff --git a/packages/shared/src/external-objects.ts b/packages/shared/src/external-objects.tsnew file mode 100644index 0000000000..a9953c4e3f--- /dev/null+++ b/packages/shared/src/external-objects.ts@@ -0,0 +1,52 @@+import type { ExternalObjectMentionSourceKind } from "./constants.js";++export interface ExternalObjectUrlMatch {+ index: number;+ length: number;+ matchedText: string;+}++export interface ExternalObjectCanonicalIdentity {+ scheme: "http" | "https";+ host: string;+ path: string;+ queryParamHashes?: Record<string, string>;+}++export interface ExternalObjectUrlCanonicalizationOptions {+ identityQueryParams?: readonly string[];+}++export interface ExternalObjectCanonicalUrl {+ sanitizedCanonicalUrl: string;+ sanitizedDisplayUrl: string;+ canonicalIdentity: ExternalObjectCanonicalIdentity;+ canonicalIdentityHash: string;+ redactedMatchedText: string;+}++export interface ExternalObjectMentionSource {+ companyId?: string;+ sourceIssueId?: string;+ sourceKind: ExternalObjectMentionSourceKind;+ sourceRecordId?: string | null;+ documentKey?: string | null;+ propertyKey?: string | null;+}++export function formatExternalObjectMentionSourceLabel(source: ExternalObjectMentionSource): string {+ switch (source.sourceKind) {+ case "title":+ return "Title";+ case "description":+ return "Description";+ case "comment":+ return "Comment";+ case "document":+ return source.documentKey ? `Document: ${source.documentKey}` : "Document";+ case "property":+ return source.propertyKey ? `Property: ${source.propertyKey}` : "Property";+ case "plugin":+ return "Plugin";+ }+}diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex 319f484f9f..b42f0bdd58 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -92,6 +92,11 @@ export {DOCUMENT_ANNOTATION_THREAD_STATUSES,DOCUMENT_ANNOTATION_ANCHOR_STATES,DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES,+ EXTERNAL_OBJECT_STATUS_CATEGORIES,+ EXTERNAL_OBJECT_STATUS_TONES,+ EXTERNAL_OBJECT_LIVENESS_STATES,+ EXTERNAL_OBJECT_MENTION_SOURCE_KINDS,+ EXTERNAL_OBJECT_MENTION_CONFIDENCES,ISSUE_EXECUTION_POLICY_MODES,ISSUE_EXECUTION_STAGE_TYPES,ISSUE_MONITOR_SCHEDULED_BY,@@ -217,6 +222,11 @@ export {type DocumentAnnotationThreadStatus,type DocumentAnnotationAnchorState,type DocumentAnnotationAnchorConfidence,+ type ExternalObjectStatusCategory,+ type ExternalObjectStatusTone,+ type ExternalObjectLivenessState,+ type ExternalObjectMentionSourceKind,+ type ExternalObjectMentionConfidence,type IssueExecutionPolicyMode,type IssueExecutionStageType,type IssueMonitorScheduledBy,@@ -522,6 +532,11 @@ export type {DocumentTextRange,UpdateDocumentAnnotationThreadRequest,AttachmentArtifactWorkProductMetadata,+ ExternalObject,+ ExternalObjectMention,+ ExternalObjectMentionGroup,+ ExternalObjectSummary,+ ExternalObjectSummaryItem,Issue,IssueAssigneeAdapterOverrides,IssueBlockerAttention,@@ -786,6 +801,8 @@ export type {PluginDatabaseDeclaration,PluginApiRouteCompanyResolution,PluginApiRouteDeclaration,+ PluginObjectReferenceRefreshPolicy,+ PluginObjectReferenceProviderDeclaration,PaperclipPluginManifestV1,PluginRecord,PluginDatabaseNamespaceRecord,@@ -829,6 +846,15 @@ export {type VerifyDocumentAnchorSelectorResult,} from "./document-anchors.js";+export {+ formatExternalObjectMentionSourceLabel,+ type ExternalObjectCanonicalIdentity,+ type ExternalObjectCanonicalUrl,+ type ExternalObjectMentionSource,+ type ExternalObjectUrlCanonicalizationOptions,+ type ExternalObjectUrlMatch,+} from "./external-objects.js";+export {sidebarOrderPreferenceSchema,upsertSidebarOrderPreferenceSchema,@@ -924,11 +950,24 @@ export {feedbackTargetTypeSchema,feedbackTraceStatusSchema,feedbackVoteValueSchema,+ externalObjectStatusCategorySchema,+ externalObjectStatusToneSchema,+ externalObjectLivenessStateSchema,+ externalObjectMentionSourceKindSchema,+ externalObjectMentionConfidenceSchema,+ externalObjectProviderKeySchema,+ externalObjectTypeSchema,+ externalObjectCanonicalIdentitySchema,+ externalObjectMentionSourceSchema,upsertIssueFeedbackVoteSchema,type CreateCompany,type UpdateCompany,type UpdateCompanyBranding,type UpsertIssueFeedbackVote,+ type ExternalObjectCanonicalIdentityInput,+ type ExternalObjectMentionSourceInput,+ type ExternalObjectProviderKeyInput,+ type ExternalObjectTypeInput,environmentDriverSchema,environmentStatusSchema,environmentLeaseStatusSchema,diff --git a/packages/shared/src/types/external-object.ts b/packages/shared/src/types/external-object.tsnew file mode 100644index 0000000000..feca7de9cd--- /dev/null+++ b/packages/shared/src/types/external-object.ts@@ -0,0 +1,93 @@+import type {+ ExternalObjectLivenessState,+ ExternalObjectMentionConfidence,+ ExternalObjectMentionSourceKind,+ ExternalObjectStatusCategory,+ ExternalObjectStatusTone,+} from "../constants.js";++export interface ExternalObject {+ id: string;+ companyId: string;+ providerKey: string;+ pluginId: string | null;+ objectType: string;+ externalId: string;+ sanitizedCanonicalUrl: string | null;+ canonicalIdentityHash: string | null;+ displayKey?: string | null;+ iconKey?: string | null;+ displayTitle: string | null;+ statusKey: string | null;+ statusLabel: string | null;+ statusIconKey?: string | null;+ statusCategory: ExternalObjectStatusCategory;+ statusTone: ExternalObjectStatusTone;+ liveness: ExternalObjectLivenessState;+ isTerminal: boolean;+ data: Record<string, unknown>;+ remoteVersion: string | null;+ etag: string | null;+ lastResolvedAt: string | null;+ lastChangedAt: string | null;+ lastErrorAt: string | null;+ nextRefreshAt: string | null;+ lastErrorCode: string | null;+ lastErrorMessage: string | null;+ createdAt: string;+ updatedAt: string;+}++export interface ExternalObjectMention {+ id: string;+ companyId: string;+ sourceIssueId: string;+ sourceKind: ExternalObjectMentionSourceKind;+ sourceRecordId: string | null;+ documentKey: string | null;+ propertyKey: string | null;+ matchedTextRedacted: string | null;+ sanitizedDisplayUrl: string | null;+ canonicalIdentityHash: string | null;+ canonicalIdentity: Record<string, unknown> | null;+ objectId: string | null;+ providerKey: string | null;+ detectorKey: string | null;+ objectType: string | null;+ confidence: ExternalObjectMentionConfidence;+ createdByPluginId: string | null;+ createdAt: string;+ updatedAt: string;+}++export interface ExternalObjectMentionGroup {+ object: ExternalObject | null;+ mentions: ExternalObjectMention[];+ mentionCount: number;+ sourceLabels: string[];+}++export interface ExternalObjectSummaryItem {+ id: string;+ providerKey: string;+ objectType: string;+ displayKey?: string | null;+ iconKey?: string | null;+ displayTitle: string | null;+ statusIconKey?: string | null;+ statusCategory: ExternalObjectStatusCategory;+ statusTone: ExternalObjectStatusTone;+ liveness: ExternalObjectLivenessState;+ isTerminal: boolean;+}++export interface ExternalObjectSummary {+ total: number;+ byStatusCategory: Record<string, number>;+ byLiveness: Record<string, number>;+ highestSeverity: ExternalObjectStatusTone;+ staleCount: number;+ authRequiredCount: number;+ unreachableCount: number;+ objects: ExternalObjectSummaryItem[];+}diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex 5354d5ea4f..fb358d4b6a 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -265,6 +265,14 @@ export type {CompanyArtifactSource,CompanyArtifactsResponse,} from "./artifact.js";++export type {+ ExternalObject,+ ExternalObjectMention,+ ExternalObjectMentionGroup,+ ExternalObjectSummary,+ ExternalObjectSummaryItem,+} from "./external-object.js";export type {Issue,IssueWorkMode,@@ -551,6 +559,8 @@ export type {PluginDatabaseDeclaration,PluginApiRouteCompanyResolution,PluginApiRouteDeclaration,+ PluginObjectReferenceRefreshPolicy,+ PluginObjectReferenceProviderDeclaration,PaperclipPluginManifestV1,PluginRecord,PluginDatabaseNamespaceRecord,diff --git a/packages/shared/src/types/instance.ts b/packages/shared/src/types/instance.tsindex e4a2db9172..e308e0e2ab 100644--- a/packages/shared/src/types/instance.ts+++ b/packages/shared/src/types/instance.ts@@ -53,6 +53,7 @@ export interface InstanceExperimentalSettings {enableIssuePlanDecompositions: boolean;enableExperimentalFileViewer: boolean;enableCloudSync: boolean;+ enableExternalObjects: boolean;autoRestartDevServerWhenIdle: boolean;enableIssueGraphLivenessAutoRecovery: boolean;issueGraphLivenessAutoRecoveryLookbackHours: number;diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.tsindex 366a60ba63..20ea2c2ece 100644--- a/packages/shared/src/types/plugin.ts+++ b/packages/shared/src/types/plugin.ts@@ -504,6 +504,31 @@ export interface PluginApiRouteDeclaration {companyResolution?: PluginApiRouteCompanyResolution;}+export interface PluginObjectReferenceRefreshPolicy {+ /** Default freshness window for resolved objects from this provider. */+ defaultTtlSeconds?: number;+ /** UI-visible staleness window. Core still stores liveness separately from remote status. */+ staleAfterSeconds?: number;+}++export interface PluginObjectReferenceProviderDeclaration {+ /** Stable provider key such as "github", "linear", or "mocktracker". */+ providerKey: string;+ /** Human-readable provider name shown in operator-facing surfaces. */+ displayName: string;+ /** Provider object types this plugin can detect and resolve. */+ objectTypes: string[];+ /**+ * Human-readable URL patterns this provider recognizes.+ * These are metadata for operators and docs; workers still perform detection.+ */+ urlPatterns?: string[];+ /** Optional default refresh behavior for this provider. */+ refreshPolicy?: PluginObjectReferenceRefreshPolicy;+ /** Optional webhook endpoint keys declared under `webhooks` that can refresh these objects. */+ webhookEndpointKeys?: string[];+}+// ---------------------------------------------------------------------------// Plugin Manifest V1// ---------------------------------------------------------------------------@@ -570,6 +595,8 @@ export interface PaperclipPluginManifestV1 {skills?: PluginManagedSkillDeclaration[];/** Trusted local folders this plugin can configure and access by stable key. */localFolders?: PluginLocalFolderDeclaration[];+ /** External object reference providers this plugin contributes. */+ objectReferences?: PluginObjectReferenceProviderDeclaration[];/*** Legacy top-level launcher declarations.* Prefer `ui.launchers` for new manifests.diff --git a/packages/shared/src/validators/external-object.ts b/packages/shared/src/validators/external-object.tsnew file mode 100644index 0000000000..33ae0ce490--- /dev/null+++ b/packages/shared/src/validators/external-object.ts@@ -0,0 +1,38 @@+import { z } from "zod";+import {+ EXTERNAL_OBJECT_LIVENESS_STATES,+ EXTERNAL_OBJECT_MENTION_CONFIDENCES,+ EXTERNAL_OBJECT_MENTION_SOURCE_KINDS,+ EXTERNAL_OBJECT_STATUS_CATEGORIES,+ EXTERNAL_OBJECT_STATUS_TONES,+} from "../constants.js";++export const externalObjectStatusCategorySchema = z.enum(EXTERNAL_OBJECT_STATUS_CATEGORIES);+export const externalObjectStatusToneSchema = z.enum(EXTERNAL_OBJECT_STATUS_TONES);+export const externalObjectLivenessStateSchema = z.enum(EXTERNAL_OBJECT_LIVENESS_STATES);+export const externalObjectMentionSourceKindSchema = z.enum(EXTERNAL_OBJECT_MENTION_SOURCE_KINDS);+export const externalObjectMentionConfidenceSchema = z.enum(EXTERNAL_OBJECT_MENTION_CONFIDENCES);+export const externalObjectProviderKeySchema = z.string().trim().min(1).max(80).regex(/^[a-z][a-z0-9_.-]*$/);+export const externalObjectTypeSchema = z.string().trim().min(1).max(80).regex(/^[a-z][a-z0-9_]*$/);++export const externalObjectCanonicalIdentitySchema = z+ .object({+ scheme: z.enum(["http", "https"]),+ host: z.string().trim().min(1),+ path: z.string().trim().min(1),+ queryParamHashes: z.record(z.string().regex(/^[a-f0-9]{64}$/)).optional(),+ })+ .strict();++export const externalObjectMentionSourceSchema = z+ .object({+ sourceKind: externalObjectMentionSourceKindSchema,+ documentKey: z.string().trim().min(1).optional().nullable(),+ propertyKey: z.string().trim().min(1).optional().nullable(),+ })+ .strict();++export type ExternalObjectCanonicalIdentityInput = z.infer<typeof externalObjectCanonicalIdentitySchema>;+export type ExternalObjectMentionSourceInput = z.infer<typeof externalObjectMentionSourceSchema>;+export type ExternalObjectProviderKeyInput = z.infer<typeof externalObjectProviderKeySchema>;+export type ExternalObjectTypeInput = z.infer<typeof externalObjectTypeSchema>;diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex 6323a7dc88..b04e1533d7 100644--- a/packages/shared/src/validators/index.ts+++ b/packages/shared/src/validators/index.ts@@ -59,6 +59,22 @@ export {updateResourceMembershipSchema,type UpdateResourceMembership,} from "./resource-memberships.js";++export {+ externalObjectStatusCategorySchema,+ externalObjectStatusToneSchema,+ externalObjectLivenessStateSchema,+ externalObjectMentionSourceKindSchema,+ externalObjectMentionConfidenceSchema,+ externalObjectProviderKeySchema,+ externalObjectTypeSchema,+ externalObjectCanonicalIdentitySchema,+ externalObjectMentionSourceSchema,+ type ExternalObjectCanonicalIdentityInput,+ type ExternalObjectMentionSourceInput,+ type ExternalObjectProviderKeyInput,+ type ExternalObjectTypeInput,+} from "./external-object.js";export {companySkillSourceTypeSchema,companySkillTrustLevelSchema,diff --git a/packages/shared/src/validators/instance.ts b/packages/shared/src/validators/instance.tsindex 66119debf6..986d0a3525 100644--- a/packages/shared/src/validators/instance.ts+++ b/packages/shared/src/validators/instance.ts@@ -47,6 +47,7 @@ export const instanceExperimentalSettingsSchema = z.object({enableIssuePlanDecompositions: z.boolean().default(false),enableExperimentalFileViewer: z.boolean().default(false),enableCloudSync: z.boolean().default(false),+ enableExternalObjects: z.boolean().default(false),autoRestartDevServerWhenIdle: z.boolean().default(false),enableIssueGraphLivenessAutoRecovery: z.boolean().default(false),issueGraphLivenessAutoRecoveryLookbackHours: zdiff --git a/packages/shared/src/validators/plugin.ts b/packages/shared/src/validators/plugin.tsindex 45a1e3a845..3462d9d656 100644--- a/packages/shared/src/validators/plugin.ts+++ b/packages/shared/src/validators/plugin.ts@@ -25,6 +25,7 @@ import {ISSUE_SURFACE_VISIBILITIES,} from "../constants.js";import { routineVariableSchema } from "./routine.js";+import { externalObjectProviderKeySchema, externalObjectTypeSchema } from "./external-object.js";// ---------------------------------------------------------------------------// JSON Schema placeholder – a permissive validator for JSON Schema objects@@ -568,6 +569,55 @@ export const pluginApiRouteDeclarationSchema = z.object({export type PluginApiRouteDeclarationInput = z.infer<typeof pluginApiRouteDeclarationSchema>;+export const pluginObjectReferenceRefreshPolicySchema = z.object({+ defaultTtlSeconds: z.number().int().positive().max(86_400).optional(),+ staleAfterSeconds: z.number().int().positive().max(604_800).optional(),+}).superRefine((value, ctx) => {+ if (+ value.defaultTtlSeconds != null &&+ value.staleAfterSeconds != null &&+ value.staleAfterSeconds < value.defaultTtlSeconds+ ) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: "staleAfterSeconds must be greater than or equal to defaultTtlSeconds",+ path: ["staleAfterSeconds"],+ });+ }+});++export const pluginObjectReferenceProviderDeclarationSchema = z.object({+ providerKey: externalObjectProviderKeySchema,+ displayName: z.string().min(1).max(100),+ objectTypes: z.array(externalObjectTypeSchema).min(1),+ urlPatterns: z.array(z.string().trim().min(1).max(500)).optional(),+ refreshPolicy: pluginObjectReferenceRefreshPolicySchema.optional(),+ webhookEndpointKeys: z.array(z.string().min(1)).optional(),+}).superRefine((value, ctx) => {+ const duplicateObjectTypes = value.objectTypes.filter((type, i) => value.objectTypes.indexOf(type) !== i);+ if (duplicateObjectTypes.length > 0) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Duplicate objectTypes: ${[...new Set(duplicateObjectTypes)].join(", ")}`,+ path: ["objectTypes"],+ });+ }++ const webhookKeys = value.webhookEndpointKeys ?? [];+ const duplicateWebhookKeys = webhookKeys.filter((key, i) => webhookKeys.indexOf(key) !== i);+ if (duplicateWebhookKeys.length > 0) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Duplicate webhookEndpointKeys: ${[...new Set(duplicateWebhookKeys)].join(", ")}`,+ path: ["webhookEndpointKeys"],+ });+ }+});++export type PluginObjectReferenceProviderDeclarationInput = z.infer<+ typeof pluginObjectReferenceProviderDeclarationSchema+>;+// ---------------------------------------------------------------------------// Plugin Manifest V1 schema// ---------------------------------------------------------------------------@@ -647,6 +697,7 @@ export const pluginManifestV1Schema = z.object({routines: z.array(pluginManagedRoutineDeclarationSchema).optional(),skills: z.array(pluginManagedSkillDeclarationSchema).optional(),localFolders: z.array(pluginLocalFolderDeclarationSchema).optional(),+ objectReferences: z.array(pluginObjectReferenceProviderDeclarationSchema).optional(),launchers: z.array(pluginLauncherDeclarationSchema).optional(),ui: z.object({slots: z.array(pluginUiSlotDeclarationSchema).min(1).optional(),@@ -787,6 +838,31 @@ export const pluginManifestV1Schema = z.object({}}+ if (manifest.objectReferences && manifest.objectReferences.length > 0) {+ for (const capability of ["external.objects.detect", "external.objects.read"] as const) {+ if (!manifest.capabilities.includes(capability)) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Capability '${capability}' is required when objectReferences are declared`,+ path: ["capabilities"],+ });+ }+ }++ const declaredWebhookKeys = new Set((manifest.webhooks ?? []).map((webhook) => webhook.endpointKey));+ for (const [providerIndex, provider] of manifest.objectReferences.entries()) {+ for (const endpointKey of provider.webhookEndpointKeys ?? []) {+ if (!declaredWebhookKeys.has(endpointKey)) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `objectReferences webhookEndpointKey "${endpointKey}" must match a declared webhook endpoint`,+ path: ["objectReferences", providerIndex, "webhookEndpointKeys"],+ });+ }+ }+ }+ }+if (manifest.database) {const requiredCapabilities = ["database.namespace.migrate",@@ -950,6 +1026,18 @@ export const pluginManifestV1Schema = z.object({}}+ if (manifest.objectReferences) {+ const providerKeys = manifest.objectReferences.map((provider) => provider.providerKey);+ const duplicateProviders = providerKeys.filter((key, i) => providerKeys.indexOf(key) !== i);+ if (duplicateProviders.length > 0) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: `Duplicate object reference provider keys: ${[...new Set(duplicateProviders)].join(", ")}`,+ path: ["objectReferences"],+ });+ }+ }+// UI slot ids must be unique within the plugin (namespaced at runtime)if (manifest.ui) {if (manifest.ui.slots) {diff --git a/scripts/provision-worktree.sh b/scripts/provision-worktree.shindex a80c01f779..0fe3a2625d 100644--- a/scripts/provision-worktree.sh+++ b/scripts/provision-worktree.sh@@ -80,6 +80,84 @@ paperclipai_command_available() {return 1}+existing_worktree_config_is_usable() {+ WORKTREE_CONFIG_PATH="$worktree_config_path" \+ WORKTREE_ENV_PATH="$worktree_env_path" \+ node <<'EOF'+const fs = require("node:fs");+const os = require("node:os");+const path = require("node:path");++function expandHomePrefix(value) {+ if (!value) return value;+ if (value === "~") return os.homedir();+ if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));+ return value;+}++function parseEnvFile(contents) {+ const entries = {};+ for (const rawLine of contents.split(/\r?\n/)) {+ const line = rawLine.trim();+ if (!line || line.startsWith("#")) continue;+ const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);+ if (!match) continue;+ const [, key, rawValue] = match;+ const value = rawValue.trim();+ if (+ (value.startsWith("\"") && value.endsWith("\"")) ||+ (value.startsWith("'") && value.endsWith("'"))+ ) {+ entries[key] = value.slice(1, -1);+ continue;+ }+ entries[key] = value.replace(/\s+#.*$/, "").trim();+ }+ return entries;+}++function fail(reason) {+ console.error(reason);+ process.exit(1);+}++const configPath = path.resolve(process.env.WORKTREE_CONFIG_PATH);+const envPath = path.resolve(process.env.WORKTREE_ENV_PATH);+const config = JSON.parse(fs.readFileSync(configPath, "utf8"));+const env = parseEnvFile(fs.readFileSync(envPath, "utf8"));+const envConfigPath = expandHomePrefix(env.PAPERCLIP_CONFIG);+if (envConfigPath && path.resolve(envConfigPath) !== configPath) {+ fail(`existing worktree env points at ${envConfigPath}, not ${configPath}`);+}++const homeDir = expandHomePrefix(env.PAPERCLIP_HOME);+const instanceId = env.PAPERCLIP_INSTANCE_ID;+if (!homeDir || !instanceId) {+ fail("existing worktree env is missing PAPERCLIP_HOME or PAPERCLIP_INSTANCE_ID");+}+if (!fs.existsSync(homeDir)) {+ fail(`existing worktree home does not exist on this host: ${homeDir}`);+}++const instanceRoot = path.resolve(homeDir, "instances", instanceId);+const runtimePaths = [+ config.database?.embeddedPostgresDataDir,+ config.database?.backup?.dir,+ config.logging?.logDir,+ config.storage?.localDisk?.baseDir,+ config.secrets?.localEncrypted?.keyFilePath,+].filter((value) => typeof value === "string" && value.length > 0);++for (const rawValue of runtimePaths) {+ const resolved = path.resolve(expandHomePrefix(rawValue));+ const relative = path.relative(instanceRoot, resolved);+ if (relative.startsWith("..") || path.isAbsolute(relative)) {+ fail(`existing worktree config path is outside ${instanceRoot}: ${resolved}`);+ }+}+EOF+}+write_fallback_worktree_config() {WORKTREE_NAME="$worktree_name" \BASE_CWD="$base_cwd" \@@ -332,9 +410,12 @@ main().catch((error) => {EOF}-if [[ -e "$worktree_config_path" && -e "$worktree_env_path" ]]; then+if [[ -e "$worktree_config_path" && -e "$worktree_env_path" ]] && existing_worktree_config_is_usable; thenecho "Reusing existing isolated Paperclip worktree config at $worktree_config_path" >&2else+ if [[ -e "$worktree_config_path" || -e "$worktree_env_path" ]]; then+ echo "Existing isolated Paperclip worktree config is stale for this host; regenerating." >&2+ fiif paperclipai_command_available; thenrun_isolated_worktree_initelsediff --git a/server/src/__tests__/environment-live-ssh.test.ts b/server/src/__tests__/environment-live-ssh.test.tsindex 303d7ff7d9..cf831b04e5 100644--- a/server/src/__tests__/environment-live-ssh.test.ts+++ b/server/src/__tests__/environment-live-ssh.test.ts@@ -180,5 +180,5 @@ describeLiveSsh("live SSH environment smoke", () => {expect(result.stdout).toContain(config.remoteWorkspacePath);expect(result.stdout).toContain("git");expect(result.stdout).toContain("tar");- });+ }, 30_000);});diff --git a/server/src/__tests__/external-object-routes.test.ts b/server/src/__tests__/external-object-routes.test.tsnew file mode 100644index 0000000000..24e8064336--- /dev/null+++ b/server/src/__tests__/external-object-routes.test.ts@@ -0,0 +1,252 @@+import express from "express";+import request from "supertest";+import { beforeEach, describe, expect, it, vi } from "vitest";++const issueId = "11111111-1111-4111-8111-111111111111";+const companyId = "22222222-2222-4222-8222-222222222222";+const ownerAgentId = "33333333-3333-4333-8333-333333333333";+const peerAgentId = "44444444-4444-4444-8444-444444444444";+const ownerRunId = "55555555-5555-4555-8555-555555555555";++const mockIssueService = vi.hoisted(() => ({+ assertCheckoutOwner: vi.fn(),+ getById: vi.fn(),+}));++const mockAccessService = vi.hoisted(() => ({+ decide: vi.fn(),+ hasPermission: vi.fn(),+}));++const mockAgentService = vi.hoisted(() => ({+ list: vi.fn(),+}));++const mockExternalObjectsService = vi.hoisted(() => ({+ getIssueSummary: vi.fn(),+ getIssueSummaries: vi.fn(),+ listForIssue: vi.fn(),+ refreshIssueObjects: vi.fn(),+}));+const mockInstanceSettingsService = vi.hoisted(() => ({+ getExperimental: vi.fn(),+}));++function registerRouteMocks() {+ vi.doMock("../services/external-objects.js", () => ({+ externalObjectService: () => mockExternalObjectsService,+ }));++ vi.doMock("../services/instance-settings.js", () => ({+ instanceSettingsService: () => mockInstanceSettingsService,+ }));++ vi.doMock("../services/task-watchdog-scope.js", () => ({+ TASK_WATCHDOG_ORIGIN_KIND: "task_watchdog",+ resolveTaskWatchdogMutationScope: vi.fn(async () => ({ kind: "none" })),+ taskWatchdogScopeAllowsIssueMutation: vi.fn(async () => ({ kind: "none" })),+ }));++ vi.doMock("../services/index.js", () => ({+ accessService: () => mockAccessService,+ agentService: () => mockAgentService,+ companyService: () => ({+ getById: vi.fn(async () => null),+ }),+ companySearchService: () => ({}),+ documentAnnotationService: () => ({}),+ documentService: () => ({}),+ executionWorkspaceService: () => ({}),+ feedbackService: () => ({}),+ goalService: () => ({}),+ heartbeatService: () => ({+ wakeup: vi.fn(async () => undefined),+ reportRunActivity: vi.fn(async () => undefined),+ getRun: vi.fn(async () => null),+ getActiveRunForAgent: vi.fn(async () => null),+ cancelRun: vi.fn(async () => null),+ }),+ issueApprovalService: () => ({}),+ issueRecoveryActionService: () => ({}),+ issueReferenceService: () => ({+ listIssueReferenceSummary: async () => ({ outbound: [], inbound: [] }),+ }),+ issueService: () => mockIssueService,+ issueThreadInteractionService: () => ({}),+ logActivity: vi.fn(async () => undefined),+ projectService: () => ({}),+ routineService: () => ({}),+ workProductService: () => ({}),+ }));+}++function makeIssue(overrides: Record<string, unknown> = {}) {+ return {+ id: issueId,+ companyId,+ status: "in_progress",+ priority: "medium",+ projectId: null,+ goalId: null,+ parentId: null,+ assigneeAgentId: ownerAgentId,+ assigneeUserId: null,+ identifier: "PAP-2265",+ title: "External object routes",+ executionWorkspaceId: null,+ ...overrides,+ };+}++async function createApp(actor: Express.Request["actor"]) {+ const [{ errorHandler }, { issueRoutes }] = await Promise.all([+ vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),+ vi.importActual<typeof import("../routes/issues.js")>("../routes/issues.js"),+ ]);+ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ req.actor = actor;+ next();+ });+ app.use("/api", issueRoutes({} as any, { provider: "local_disk" } as any));+ app.use(errorHandler);+ return app;+}++function boardActor(): Express.Request["actor"] {+ return {+ type: "board",+ userId: "board-user",+ userName: null,+ userEmail: null,+ companyIds: [companyId],+ memberships: [],+ isInstanceAdmin: false,+ source: "local_implicit",+ };+}++function ownerActor(): Express.Request["actor"] {+ return {+ type: "agent",+ agentId: ownerAgentId,+ companyId,+ keyId: "key-1",+ runId: ownerRunId,+ source: "agent_key",+ };+}++function peerActor(): Express.Request["actor"] {+ return {+ type: "agent",+ agentId: peerAgentId,+ companyId,+ keyId: "key-2",+ runId: "66666666-6666-4666-8666-666666666666",+ source: "agent_key",+ };+}++describe("external object routes", () => {+ beforeEach(() => {+ vi.resetModules();+ vi.doUnmock("../routes/issues.js");+ vi.doUnmock("../services/index.js");+ vi.doUnmock("../services/external-objects.js");+ registerRouteMocks();+ vi.resetAllMocks();+ mockIssueService.getById.mockResolvedValue(makeIssue());+ mockIssueService.assertCheckoutOwner.mockResolvedValue({ adoptedFromRunId: null });+ mockAccessService.hasPermission.mockResolvedValue(false);+ mockAccessService.decide.mockImplementation(async ({ action }: { action: string }) => ({+ allowed: action === "issue:mutate",+ explanation: "Denied by test mock",+ }));+ mockAgentService.list.mockResolvedValue([+ { id: ownerAgentId, companyId, reportsTo: null, permissions: { canCreateAgents: false } },+ { id: peerAgentId, companyId, reportsTo: null, permissions: { canCreateAgents: false } },+ ]);+ mockExternalObjectsService.getIssueSummary.mockResolvedValue({ total: 1, objects: [] });+ mockExternalObjectsService.getIssueSummaries.mockResolvedValue(new Map([+ [issueId, { total: 1, objects: [] }],+ ]));+ mockExternalObjectsService.listForIssue.mockResolvedValue([]);+ mockExternalObjectsService.refreshIssueObjects.mockResolvedValue([+ { object: { id: "77777777-7777-4777-8777-777777777777" }, refreshed: false, reason: "no_resolver" },+ ]);+ mockInstanceSettingsService.getExperimental.mockResolvedValue({+ enableExternalObjects: true,+ });+ });++ it("enforces company access on read routes", async () => {+ const app = await createApp({ ...ownerActor(), companyId: "other-company" });++ const res = await request(app).get(`/api/issues/${issueId}/external-object-summary`);++ expect(res.status).toBe(403);+ expect(mockExternalObjectsService.getIssueSummary).not.toHaveBeenCalled();+ });++ it("allows board users to read issue external object summaries", async () => {+ const app = await createApp(boardActor());++ const res = await request(app).get(`/api/issues/${issueId}/external-object-summary`);++ expect(res.status).toBe(200);+ expect(res.body.total).toBe(1);+ expect(mockExternalObjectsService.getIssueSummary).toHaveBeenCalledWith(issueId);+ });++ it("allows board users to fetch company-scoped external object summaries in bulk", async () => {+ const app = await createApp(boardActor());++ const res = await request(app)+ .post(`/api/companies/${companyId}/issues/external-object-summaries`)+ .send({ issueIds: [issueId] });++ expect(res.status).toBe(200);+ expect(res.body.summaries[issueId].total).toBe(1);+ expect(mockExternalObjectsService.getIssueSummaries).toHaveBeenCalledWith(companyId, [issueId]);+ });++ it("enforces company access on bulk external object summaries", async () => {+ const app = await createApp({ ...ownerActor(), companyId: "other-company" });++ const res = await request(app)+ .post(`/api/companies/${companyId}/issues/external-object-summaries`)+ .send({ issueIds: [issueId] });++ expect(res.status).toBe(403);+ expect(mockExternalObjectsService.getIssueSummaries).not.toHaveBeenCalled();+ });++ it("requires active checkout ownership for agent manual refresh", async () => {+ const app = await createApp(peerActor());++ const res = await request(app)+ .post(`/api/issues/${issueId}/external-objects/refresh`)+ .send({});++ expect(res.status).toBe(409);+ expect(res.body.error).toBe("Issue is checked out by another agent");+ expect(mockExternalObjectsService.refreshIssueObjects).not.toHaveBeenCalled();+ });++ it("allows the checked-out agent to request manual refresh", async () => {+ const app = await createApp(ownerActor());++ const res = await request(app)+ .post(`/api/issues/${issueId}/external-objects/refresh`)+ .send({});++ expect(res.status).toBe(200);+ expect(mockIssueService.assertCheckoutOwner).toHaveBeenCalledWith(issueId, ownerAgentId, ownerRunId);+ expect(mockExternalObjectsService.refreshIssueObjects).toHaveBeenCalledWith(issueId, expect.objectContaining({+ companyId,+ actor: expect.objectContaining({ actorType: "agent", actorId: ownerAgentId }),+ }));+ });+});diff --git a/server/src/__tests__/external-objects-service.test.ts b/server/src/__tests__/external-objects-service.test.tsnew file mode 100644index 0000000000..967ea8ae42--- /dev/null+++ b/server/src/__tests__/external-objects-service.test.ts@@ -0,0 +1,705 @@+import { randomUUID } from "node:crypto";+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";+import { eq } from "drizzle-orm";+import {+ companies,+ createDb,+ activityLog,+ externalObjectMentions,+ externalObjects,+ issueComments,+ issues,+ plugins,+} from "@paperclipai/db";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.js";+import {+ createExternalObjectDetectorRegistry,+ createExternalObjectResolverRegistry,+ externalObjectService,+ type ExternalObjectResolver,+} from "../services/external-objects.js";+import { canonicalizeExternalObjectUrl } from "@paperclipai/shared/external-objects-server";+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";+import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";+import { createGitHubExternalObjectProvider } from "../services/github-external-object-provider.js";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres external object tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}++describe("external object registries", () => {+ it("lets provider detectors claim urls before the generic fallback", async () => {+ const canonical = canonicalizeExternalObjectUrl("https://github.com/acme/app/pull/42");+ if (!canonical) throw new Error("expected canonical url");+ const registry = createExternalObjectDetectorRegistry([+ {+ key: "github",+ detect: ({ urls }) =>+ urls.map((url) => ({+ canonical: url,+ detectorKey: "github",+ providerKey: "github",+ objectType: "pull_request",+ externalId: "acme/app#42",+ confidence: "exact",+ })),+ },+ ]);++ const detections = await registry.detect({+ companyId: "company-1",+ urls: [canonical],+ sourceContext: {+ companyId: "company-1",+ sourceIssueId: "issue-1",+ sourceKind: "description",+ sourceRecordId: null,+ documentKey: null,+ propertyKey: null,+ },+ });++ expect(detections).toHaveLength(1);+ expect(detections[0]).toMatchObject({+ providerKey: "github",+ objectType: "pull_request",+ externalId: "acme/app#42",+ });+ });++ it("falls back to generic url objects when no provider detector claims a url", async () => {+ const canonical = canonicalizeExternalObjectUrl("https://example.com/path?token=secret#frag");+ if (!canonical) throw new Error("expected canonical url");+ const registry = createExternalObjectDetectorRegistry([]);++ const detections = await registry.detect({+ companyId: "company-1",+ urls: [canonical],+ sourceContext: {+ companyId: "company-1",+ sourceIssueId: "issue-1",+ sourceKind: "description",+ sourceRecordId: null,+ documentKey: null,+ propertyKey: null,+ },+ });++ expect(detections[0]).toMatchObject({+ providerKey: "url",+ objectType: "link",+ externalId: canonical.canonicalIdentityHash,+ displayTitle: "https://example.com/path",+ });+ });++ it("matches resolvers by provider and optional object type", () => {+ const fallbackResolver: ExternalObjectResolver = {+ providerKey: "github",+ resolve: async () => ({+ ok: true,+ snapshot: { statusCategory: "unknown", statusTone: "neutral" },+ }),+ };+ const pullRequestResolver: ExternalObjectResolver = {+ providerKey: "github",+ objectType: "pull_request",+ resolve: async () => ({+ ok: true,+ snapshot: { statusCategory: "open", statusTone: "info" },+ }),+ };+ const registry = createExternalObjectResolverRegistry([pullRequestResolver, fallbackResolver]);++ expect(registry.find({ providerKey: "github", objectType: "pull_request" })).toBe(pullRequestResolver);+ expect(registry.find({ providerKey: "github", objectType: "issue" })).toBe(fallbackResolver);+ expect(registry.find({ providerKey: "linear", objectType: "issue" })).toBeNull();+ });+});++describe("GitHub external object provider", () => {+ function githubObject(path: string, objectType: "pull_request" | "issue") {+ const canonical = canonicalizeExternalObjectUrl(`https://github.com/acme/app/${path}`);+ if (!canonical) throw new Error("expected canonical url");+ return {+ id: randomUUID(),+ companyId: "company-1",+ providerKey: "github",+ objectType,+ externalId: `acme/app#${path}`,+ sanitizedCanonicalUrl: canonical.sanitizedCanonicalUrl,+ canonicalIdentityHash: canonical.canonicalIdentityHash,+ displayTitle: "acme/app#42",+ statusKey: null,+ statusLabel: null,+ statusCategory: "unknown",+ statusTone: "neutral",+ liveness: "unknown",+ isTerminal: false,+ data: {},+ remoteVersion: null,+ etag: null,+ } as any;+ }++ function response(body: Record<string, unknown>, init: ResponseInit = {}) {+ return new Response(JSON.stringify(body), {+ status: 200,+ headers: { "content-type": "application/json", etag: '"etag-1"', ...(init.headers ?? {}) },+ ...init,+ });+ }++ it("detects GitHub pull request and issue URLs before the generic fallback", async () => {+ const provider = createGitHubExternalObjectProvider({} as any, { tokenProvider: null });+ const pr = canonicalizeExternalObjectUrl("https://github.com/Acme/App/pull/42?token=secret#discussion");+ const issue = canonicalizeExternalObjectUrl("https://github.com/Acme/App/issues/7");+ const other = canonicalizeExternalObjectUrl("https://example.com/Acme/App/pull/42");+ if (!pr || !issue || !other) throw new Error("expected canonical urls");++ const detections = await provider.detector.detect({+ companyId: "company-1",+ urls: [pr, issue, other],+ sourceContext: {+ companyId: "company-1",+ sourceIssueId: "issue-1",+ sourceKind: "description",+ sourceRecordId: null,+ documentKey: null,+ propertyKey: null,+ },+ });++ expect(detections).toEqual([+ expect.objectContaining({+ providerKey: "github",+ objectType: "pull_request",+ externalId: "acme/app#pull/42",+ displayKey: "GitHub Pull Request",+ iconKey: "github",+ displayTitle: "Acme/App#42",+ }),+ expect.objectContaining({+ providerKey: "github",+ objectType: "issue",+ externalId: "acme/app#issues/7",+ displayKey: "GitHub Issue",+ iconKey: "github",+ displayTitle: "Acme/App#7",+ }),+ ]);+ expect(JSON.stringify(detections)).not.toContain("secret");+ });++ it.each([+ [+ "open",+ { state: "open", draft: false, merged: false, title: "Ship it", updated_at: "2026-04-24T01:02:03Z" },+ { statusKey: "open", statusLabel: "Open", statusIconKey: "git-pull-request", statusCategory: "open", statusTone: "info", isTerminal: false },+ ],+ [+ "draft",+ { state: "open", draft: true, merged: false, title: "WIP", updated_at: "2026-04-24T01:02:03Z" },+ { statusKey: "draft", statusLabel: "Draft", statusIconKey: "clock", statusCategory: "waiting", statusTone: "warning", isTerminal: false },+ ],+ [+ "closed",+ { state: "closed", draft: false, merged: false, title: "Closed PR", updated_at: "2026-04-24T01:02:03Z" },+ { statusKey: "closed", statusLabel: "Closed", statusIconKey: "x-circle", statusCategory: "closed", statusTone: "muted", isTerminal: true },+ ],+ [+ "merged",+ { state: "closed", draft: false, merged: true, title: "Merged PR", updated_at: "2026-04-24T01:02:03Z" },+ { statusKey: "merged", statusLabel: "Merged", statusIconKey: "git-merge", statusCategory: "succeeded", statusTone: "success", isTerminal: true },+ ],+ ])("resolves a %s pull request snapshot", async (_name, body, expected) => {+ const fetch = vi.fn(async () => response(body));+ const provider = createGitHubExternalObjectProvider({} as any, { fetch, tokenProvider: null });+ const resolver = provider.resolvers.find((entry) => entry.objectType === "pull_request")!;++ const result = await resolver.resolve({+ companyId: "company-1",+ object: githubObject("pull/42", "pull_request"),+ });++ expect(fetch).toHaveBeenCalledWith(+ "https://api.github.com/repos/acme/app/pulls/42",+ expect.objectContaining({+ headers: expect.not.objectContaining({ authorization: expect.any(String) }),+ }),+ );+ expect(result).toEqual({+ ok: true,+ snapshot: expect.objectContaining({+ ...expected,+ displayKey: "GitHub Pull Request",+ iconKey: "github",+ displayTitle: expect.stringContaining(String(body.title)),+ remoteVersion: "2026-04-24T01:02:03Z",+ etag: '"etag-1"',+ data: expect.objectContaining({+ provider: "github",+ owner: "acme",+ repo: "app",+ number: 42,+ }),+ }),+ });+ expect(JSON.stringify(result)).not.toContain("authorization");+ });++ it.each([+ [+ "open",+ { state: "open", title: "Issue", state_reason: null, updated_at: "2026-04-24T01:02:03Z" },+ { statusKey: "open", statusLabel: "Open", statusIconKey: "circle-dot", statusCategory: "open", statusTone: "info", isTerminal: false },+ ],+ [+ "closed",+ { state: "closed", title: "Issue", state_reason: "completed", updated_at: "2026-04-24T01:02:03Z" },+ { statusKey: "closed_completed", statusLabel: "Closed: completed", statusIconKey: "circle", statusCategory: "closed", statusTone: "muted", isTerminal: true },+ ],+ ])("resolves a %s issue snapshot", async (_name, body, expected) => {+ const fetch = vi.fn(async () => response(body));+ const provider = createGitHubExternalObjectProvider({} as any, { fetch, tokenProvider: null });+ const resolver = provider.resolvers.find((entry) => entry.objectType === "issue")!;++ const result = await resolver.resolve({+ companyId: "company-1",+ object: githubObject("issues/42", "issue"),+ });++ expect(fetch).toHaveBeenCalledWith("https://api.github.com/repos/acme/app/issues/42", expect.any(Object));+ expect(result).toEqual({+ ok: true,+ snapshot: expect.objectContaining({+ ...expected,+ displayKey: "GitHub Issue",+ iconKey: "github",+ data: expect.objectContaining({+ provider: "github",+ owner: "acme",+ repo: "app",+ number: 42,+ }),+ }),+ });+ });++ it("uses a configured token without storing it in the resolved snapshot", async () => {+ const fetch = vi.fn(async (_url: string, init?: RequestInit) => {+ expect(init?.headers).toEqual(expect.objectContaining({ authorization: "Bearer ghp_secret" }));+ return response({ state: "open", draft: false, merged: false, title: "Private PR" });+ });+ const provider = createGitHubExternalObjectProvider({} as any, {+ fetch,+ tokenProvider: async () => "ghp_secret",+ });+ const resolver = provider.resolvers.find((entry) => entry.objectType === "pull_request")!;++ const result = await resolver.resolve({+ companyId: "company-1",+ object: githubObject("pull/42", "pull_request"),+ });++ expect(result.ok).toBe(true);+ expect(JSON.stringify(result)).not.toContain("ghp_secret");+ });++ it.each([+ [+ "auth-required",+ new Response("", { status: 401 }),+ { ok: false, liveness: "auth_required", errorCode: "github_auth_required" },+ ],+ [+ "rate-limit",+ new Response("", {+ status: 403,+ headers: { "x-ratelimit-remaining": "0", "x-ratelimit-reset": String(Math.floor(Date.now() / 1000) + 120) },+ }),+ { ok: false, liveness: "unreachable", errorCode: "github_rate_limited" },+ ],+ [+ "not-found",+ new Response("", { status: 404, headers: { etag: '"missing"' } }),+ { ok: true, snapshot: expect.objectContaining({ displayKey: "GitHub Pull Request", iconKey: "github", statusKey: "not_found", statusIconKey: "archive", statusCategory: "archived", statusTone: "muted" }) },+ ],+ ])("maps %s responses to provider-safe results", async (_name, githubResponse, expected) => {+ const provider = createGitHubExternalObjectProvider({} as any, {+ fetch: async () => githubResponse,+ tokenProvider: null,+ });+ const resolver = provider.resolvers.find((entry) => entry.objectType === "pull_request")!;++ const result = await resolver.resolve({+ companyId: "company-1",+ object: githubObject("pull/42", "pull_request"),+ });++ expect(result).toEqual(expect.objectContaining(expected));+ expect(JSON.stringify(result)).not.toContain("http");+ });+});++describeEmbeddedPostgres("externalObjectService", () => {+ let db!: ReturnType<typeof createDb>;+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-external-objects-");+ db = createDb(tempDb.connectionString);+ }, 20_000);++ afterEach(async () => {+ await db.delete(activityLog);+ await db.delete(externalObjectMentions);+ await db.delete(externalObjects);+ await db.delete(issueComments);+ await db.delete(issues);+ await db.delete(plugins);+ await db.delete(companies);+ vi.restoreAllMocks();+ });++ afterAll(async () => {+ await tempDb?.cleanup();+ });++ async function createIssue(companyId = randomUUID()) {+ const issueId = randomUUID();+ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: `E${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,+ requireBoardApprovalForNewAgents: false,+ });+ await db.insert(issues).values({+ id: issueId,+ companyId,+ identifier: `PAP-${companyId.replace(/-/g, "").slice(0, 12).toUpperCase()}`,+ title: "External refs",+ description: "Track https://github.com/acme/app/pull/42?token=secret#discussion twice https://github.com/acme/app/pull/42.",+ status: "todo",+ priority: "medium",+ });+ return { companyId, issueId };+ }++ it("syncs sanitized, deduped mentions without storing secret-bearing urls", async () => {+ const { companyId, issueId } = await createIssue();+ const svc = externalObjectService(db);++ await svc.syncIssue(issueId);++ const [objectRows, mentionRows] = await Promise.all([+ db.select().from(externalObjects),+ db.select().from(externalObjectMentions),+ ]);+ expect(objectRows).toHaveLength(1);+ expect(objectRows[0]).toMatchObject({+ companyId,+ providerKey: "github",+ objectType: "pull_request",+ externalId: "acme/app#pull/42",+ sanitizedCanonicalUrl: "https://github.com/acme/app/pull/42",+ liveness: "unknown",+ statusCategory: "unknown",+ });+ expect(JSON.stringify(objectRows[0])).not.toContain("secret");+ expect(mentionRows).toHaveLength(1);+ expect(mentionRows[0]).toMatchObject({+ companyId,+ sourceIssueId: issueId,+ sourceKind: "description",+ sanitizedDisplayUrl: "https://github.com/acme/app/pull/42",+ matchedTextRedacted: "https://github.com/acme/app/pull/42",+ });+ });++ it("no-ops detection and summaries when external objects are disabled", async () => {+ const { issueId } = await createIssue();+ const svc = externalObjectService(db, { enabled: false });++ await svc.syncIssue(issueId);++ const [objectRows, mentionRows, summary] = await Promise.all([+ db.select().from(externalObjects),+ db.select().from(externalObjectMentions),+ svc.getIssueSummary(issueId),+ ]);+ expect(objectRows).toHaveLength(0);+ expect(mentionRows).toHaveLength(0);+ expect(summary).toMatchObject({+ total: 0,+ byStatusCategory: {},+ byLiveness: {},+ highestSeverity: "neutral",+ objects: [],+ });+ });++ it("preserves last-known status when resolver reports auth and unreachable failures", async () => {+ const { companyId, issueId } = await createIssue();+ const resolver: ExternalObjectResolver = {+ providerKey: "url",+ objectType: "link",+ resolve: vi+ .fn()+ .mockResolvedValueOnce({+ ok: true,+ snapshot: {+ statusCategory: "open",+ statusTone: "info",+ statusKey: "open",+ statusLabel: "Open",+ ttlSeconds: 1,+ },+ })+ .mockResolvedValueOnce({+ ok: false,+ liveness: "auth_required",+ errorCode: "auth_required",+ errorMessage: "token=secret failed for https://github.com/acme/app/pull/42?token=secret",+ retryAfterSeconds: 60,+ })+ .mockResolvedValueOnce({+ ok: false,+ liveness: "unreachable",+ errorCode: "network",+ errorMessage: "GET https://github.com/acme/app/pull/42 failed",+ retryAfterSeconds: 60,+ }),+ };+ const svc = externalObjectService(db, { resolvers: [resolver], github: false });+ await svc.syncIssue(issueId);+ const object = await db.select().from(externalObjects).then((rows) => rows[0]!);++ await svc.refreshObject(object.id, { companyId, force: true });+ await svc.refreshObject(object.id, { companyId, force: true });++ const authFailure = await db.select().from(externalObjects).then((rows) => rows[0]!);+ expect(authFailure.lastErrorMessage).toContain("token=[redacted]");+ expect(authFailure.lastErrorMessage).not.toContain("secret");++ await svc.refreshObject(object.id, { companyId, force: true });++ const updated = await db.select().from(externalObjects).then((rows) => rows[0]!);+ expect(updated.statusCategory).toBe("open");+ expect(updated.statusLabel).toBe("Open");+ expect(updated.liveness).toBe("unreachable");+ expect(updated.lastErrorMessage).toContain("[redacted-url]");+ expect(updated.lastErrorMessage).not.toContain("secret");+ });++ it("schedules newly detected objects for automatic refresh", async () => {+ const { companyId, issueId } = await createIssue();+ const resolve = vi.fn(async () => ({+ ok: true as const,+ snapshot: {+ statusCategory: "open" as const,+ statusTone: "info" as const,+ statusKey: "open",+ statusLabel: "Open",+ ttlSeconds: 300,+ },+ }));+ const resolver: ExternalObjectResolver = {+ providerKey: "url",+ objectType: "link",+ resolve,+ };+ const svc = externalObjectService(db, { resolvers: [resolver], github: false });+ await svc.syncIssue(issueId);+ const object = await db.select().from(externalObjects).then((rows) => rows[0]!);++ expect(object.nextRefreshAt).toBeInstanceOf(Date);++ const refreshed = await svc.refreshDueObjects(companyId, 50, new Date(Date.now() + 1_000));++ expect(refreshed).toHaveLength(1);+ expect(resolve).toHaveBeenCalledTimes(1);+ });++ it("removes comment mentions when a synced comment is hard-deleted", async () => {+ const { companyId, issueId } = await createIssue();+ const commentId = randomUUID();+ await db.insert(issueComments).values({+ id: commentId,+ companyId,+ issueId,+ authorType: "user",+ authorUserId: "local-board",+ body: "See https://github.com/acme/app/issues/88",+ });+ const svc = externalObjectService(db, { github: false });++ await svc.syncComment(commentId);+ expect(await db.select().from(externalObjectMentions)).toHaveLength(1);++ await db.delete(issueComments).where(eq(issueComments.id, commentId));+ await svc.syncComment(commentId);++ expect(await db.select().from(externalObjectMentions)).toHaveLength(0);+ });++ it("skips terminal objects when refreshing due objects", async () => {+ const { companyId, issueId } = await createIssue();+ const resolve = vi.fn(async () => ({+ ok: true as const,+ snapshot: {+ statusCategory: "closed" as const,+ statusTone: "muted" as const,+ statusKey: "closed",+ statusLabel: "Closed",+ isTerminal: true,+ ttlSeconds: 1,+ },+ }));+ const resolver: ExternalObjectResolver = {+ providerKey: "url",+ objectType: "link",+ resolve,+ };+ const svc = externalObjectService(db, { resolvers: [resolver], github: false });+ await svc.syncIssue(issueId);+ const object = await db.select().from(externalObjects).then((rows) => rows[0]!);++ await svc.refreshObject(object.id, { companyId, force: true });+ await db+ .update(externalObjects)+ .set({ nextRefreshAt: new Date(0) })+ .where(eq(externalObjects.id, object.id));++ const refreshed = await svc.refreshDueObjects(companyId);++ expect(refreshed).toEqual([]);+ expect(resolve).toHaveBeenCalledTimes(1);+ });++ it("keeps external object identities company-scoped for duplicate urls", async () => {+ const first = await createIssue();+ const second = await createIssue();+ const svc = externalObjectService(db);++ await svc.syncIssue(first.issueId);+ await svc.syncIssue(second.issueId);++ const objectRows = await db.select().from(externalObjects);+ expect(objectRows).toHaveLength(2);+ expect(new Set(objectRows.map((row) => row.companyId))).toEqual(new Set([first.companyId, second.companyId]));+ expect(new Set(objectRows.map((row) => row.canonicalIdentityHash)).size).toBe(1);+ });++ it("uses a mock plugin provider to detect and resolve non-GitHub objects", async () => {+ const { companyId, issueId } = await createIssue();+ await db+ .update(issues)+ .set({+ description: "Track https://mock.example/tickets/123?secret=drop",+ })+ .where(eq(issues.id, issueId));++ const manifest: PaperclipPluginManifestV1 = {+ id: "paperclip.mock-object-provider",+ apiVersion: 1,+ version: "1.0.0",+ displayName: "Mock Object Provider",+ description: "Detects mock tracker tickets",+ author: "Paperclip",+ categories: ["connector"],+ capabilities: ["external.objects.detect", "external.objects.read"],+ entrypoints: { worker: "dist/worker.js" },+ objectReferences: [+ {+ providerKey: "mocktracker",+ displayName: "Mock Tracker",+ objectTypes: ["ticket"],+ urlPatterns: ["https://mock.example/tickets/:id"],+ },+ ],+ };+ const [plugin] = await db.insert(plugins).values({+ pluginKey: manifest.id,+ packageName: "@paperclip/mock-object-provider",+ version: manifest.version,+ apiVersion: 1,+ categories: manifest.categories,+ manifestJson: manifest,+ status: "ready",+ installOrder: 1,+ }).returning();++ const workerManager = {+ call: vi.fn(async (pluginId: string, method: string, params: any) => {+ expect(pluginId).toBe(plugin!.id);+ if (method === "detectExternalObjects") {+ return {+ detections: params.urls.map((url: any) => ({+ urlIdentityHash: url.canonicalIdentityHash,+ providerKey: "mocktracker",+ objectType: "ticket",+ externalId: "MOCK-123",+ displayKey: "Mock Ticket",+ iconKey: "circle-dot",+ displayTitle: "Mock ticket 123",+ confidence: "exact",+ })),+ };+ }+ if (method === "resolveExternalObject") {+ return {+ ok: true,+ snapshot: {+ displayKey: "Mock Ticket",+ iconKey: "circle-dot",+ displayTitle: `Resolved ${params.externalId}`,+ statusKey: "ready",+ statusLabel: "Ready",+ statusIconKey: "check-circle",+ statusCategory: "succeeded",+ statusTone: "success",+ ttlSeconds: 300,+ },+ };+ }+ throw new Error(`unexpected method ${method}`);+ }),+ } as unknown as PluginWorkerManager;++ const svc = externalObjectService(db, { pluginWorkerManager: workerManager });+ await svc.syncIssue(issueId);++ const object = await db.select().from(externalObjects).then((rows) => rows[0]!);+ expect(object).toMatchObject({+ companyId,+ providerKey: "mocktracker",+ objectType: "ticket",+ externalId: "MOCK-123",+ displayKey: "Mock Ticket",+ iconKey: "circle-dot",+ pluginId: plugin!.id,+ sanitizedCanonicalUrl: "https://mock.example/tickets/123",+ });+ expect(JSON.stringify(object)).not.toContain("secret");++ const refreshed = await svc.refreshObject(object.id, { companyId, force: true });+ expect(refreshed.object).toMatchObject({+ displayKey: "Mock Ticket",+ iconKey: "circle-dot",+ displayTitle: "Resolved MOCK-123",+ statusIconKey: "check-circle",+ statusCategory: "succeeded",+ statusTone: "success",+ liveness: "fresh",+ });+ });+});diff --git a/server/src/__tests__/feedback-service.test.ts b/server/src/__tests__/feedback-service.test.tsindex 8a979d84c5..bde8659b03 100644--- a/server/src/__tests__/feedback-service.test.ts+++ b/server/src/__tests__/feedback-service.test.ts@@ -22,13 +22,25 @@ import {issues,} from "@paperclipai/db";import { feedbackService } from "../services/feedback.ts";-import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.ts";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.ts";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres feedback service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}async function closeDbClient(db: ReturnType<typeof createDb> | undefined) {await db?.$client?.end?.({ timeout: 0 });}-describe("feedbackService.saveIssueVote", () => {+describeEmbeddedPostgres("feedbackService.saveIssueVote", () => {let db!: ReturnType<typeof createDb>;let svc!: ReturnType<typeof feedbackService>;let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;diff --git a/server/src/__tests__/heartbeat-comment-wake-batching.test.ts b/server/src/__tests__/heartbeat-comment-wake-batching.test.tsindex c0edc51ce8..a883a37009 100644--- a/server/src/__tests__/heartbeat-comment-wake-batching.test.ts+++ b/server/src/__tests__/heartbeat-comment-wake-batching.test.ts@@ -15,7 +15,19 @@ import {import { runningProcesses } from "../adapters/index.js";import { heartbeatService } from "../services/heartbeat.ts";import { SUCCESSFUL_RUN_HANDOFF_REQUIRED_NOTICE_BODY } from "../services/recovery/index.ts";-import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.ts";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.ts";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres heartbeat comment wake batching tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}async function waitFor(condition: () => boolean | Promise<boolean>, timeoutMs = 10_000, intervalMs = 50) {const startedAt = Date.now();@@ -147,7 +159,7 @@ async function createControlledGatewayServer() {};}-describe("heartbeat comment wake batching", () => {+describeEmbeddedPostgres("heartbeat comment wake batching", () => {let db!: ReturnType<typeof createDb>;let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;diff --git a/server/src/__tests__/instance-settings-routes.test.ts b/server/src/__tests__/instance-settings-routes.test.tsindex bd6b63a9c4..3965dacb97 100644--- a/server/src/__tests__/instance-settings-routes.test.ts+++ b/server/src/__tests__/instance-settings-routes.test.ts@@ -100,6 +100,7 @@ describe("instance settings routes", () => {enableExperimentalFileViewer: false,enableTaskWatchdogs: false,enableCloudSync: false,+ enableExternalObjects: false,autoRestartDevServerWhenIdle: false,enableIssueGraphLivenessAutoRecovery: true,issueGraphLivenessAutoRecoveryLookbackHours: 24,@@ -142,6 +143,7 @@ describe("instance settings routes", () => {enableExperimentalFileViewer: true,enableTaskWatchdogs: true,enableCloudSync: true,+ enableExternalObjects: false,autoRestartDevServerWhenIdle: false,enableIssueGraphLivenessAutoRecovery: true,issueGraphLivenessAutoRecoveryLookbackHours: 24,@@ -194,6 +196,7 @@ describe("instance settings routes", () => {enableExperimentalFileViewer: false,enableTaskWatchdogs: false,enableCloudSync: false,+ enableExternalObjects: false,autoRestartDevServerWhenIdle: false,enableIssueGraphLivenessAutoRecovery: true,issueGraphLivenessAutoRecoveryLookbackHours: 24,@@ -271,6 +274,24 @@ describe("instance settings routes", () => {).toBe(true);});+ it("allows local board users to update external object detection", async () => {+ const app = await createApp({+ type: "board",+ userId: "local-board",+ source: "local_implicit",+ isInstanceAdmin: true,+ });++ await request(app)+ .patch("/api/instance/settings/experimental")+ .send({ enableExternalObjects: true })+ .expect(200);++ expect(mockInstanceSettingsService.updateExperimental).toHaveBeenCalledWith({+ enableExternalObjects: true,+ });+ });+it("allows local board users to update issue graph liveness auto-recovery", async () => {const app = await createApp({type: "board",diff --git a/server/src/__tests__/instance-settings-service.test.ts b/server/src/__tests__/instance-settings-service.test.tsindex 30b595e59a..4ef90da5fe 100644--- a/server/src/__tests__/instance-settings-service.test.ts+++ b/server/src/__tests__/instance-settings-service.test.ts@@ -19,6 +19,7 @@ describe("instance settings service", () => {enableIsolatedWorkspaces: true,enableStreamlinedLeftNavigation: true,enableConferenceRoomChat: false,+ enableExternalObjects: false,enableIssuePlanDecompositions: true,enableExperimentalFileViewer: true,enableTaskWatchdogs: true,diff --git a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.tsindex 436915de57..f2aabc93e4 100644--- a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts+++ b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts@@ -104,6 +104,34 @@ const mockHeartbeatService = vi.hoisted(() => ({getActiveRunForAgent: vi.fn(async () => null),cancelRun: vi.fn(async () => null),}));+const mockExternalObjectService = vi.hoisted(() => ({+ getIssueSummaries: vi.fn(async () => new Map()),+ getIssueSummary: vi.fn(async () => ({+ authRequiredCount: 0,+ byLiveness: {},+ byStatusCategory: {},+ highestSeverity: "muted",+ objects: [],+ staleCount: 0,+ total: 0,+ unreachableCount: 0,+ })),+ getProjectSummary: vi.fn(async () => ({+ authRequiredCount: 0,+ byLiveness: {},+ byStatusCategory: {},+ highestSeverity: "muted",+ objects: [],+ staleCount: 0,+ total: 0,+ unreachableCount: 0,+ })),+ listForIssue: vi.fn(async () => []),+ refreshIssueObjects: vi.fn(async () => []),+ syncCommentSafely: vi.fn(async () => undefined),+ syncDocumentSafely: vi.fn(async () => undefined),+ syncIssueSafely: vi.fn(async () => undefined),+}));function registerRouteMocks() {vi.doMock("@paperclipai/shared/telemetry", () => ({@@ -136,6 +164,10 @@ function registerRouteMocks() {workProductService: () => mockWorkProductService,}));+ vi.doMock("../services/external-objects.js", () => ({+ externalObjectService: () => mockExternalObjectService,+ }));+vi.doMock("../services/activity-log.js", () => ({logActivity: vi.fn(async () => undefined),}));@@ -329,6 +361,7 @@ describe("agent issue mutation checkout ownership", () => {vi.doUnmock("../services/activity-log.js");vi.doUnmock("../services/agents.js");vi.doUnmock("../services/documents.js");+ vi.doUnmock("../services/external-objects.js");vi.doUnmock("../services/index.js");vi.doUnmock("../services/issues.js");vi.doUnmock("../services/work-products.js");@@ -464,6 +497,14 @@ describe("agent issue mutation checkout ownership", () => {mockIssueService.findMentionedAgents.mockReset();mockDocumentService.upsertIssueDocument.mockReset();mockWorkProductService.createForIssue.mockReset();+ mockExternalObjectService.getIssueSummaries.mockClear();+ mockExternalObjectService.getIssueSummary.mockClear();+ mockExternalObjectService.getProjectSummary.mockClear();+ mockExternalObjectService.listForIssue.mockClear();+ mockExternalObjectService.refreshIssueObjects.mockClear();+ mockExternalObjectService.syncCommentSafely.mockClear();+ mockExternalObjectService.syncDocumentSafely.mockClear();+ mockExternalObjectService.syncIssueSafely.mockClear();mockWorkProductService.getById.mockReset();mockWorkProductService.remove.mockReset();mockWorkProductService.update.mockReset();diff --git a/server/src/__tests__/issue-comment-cancel-routes.test.ts b/server/src/__tests__/issue-comment-cancel-routes.test.tsindex 8c841f08d1..bd46a12ce3 100644--- a/server/src/__tests__/issue-comment-cancel-routes.test.ts+++ b/server/src/__tests__/issue-comment-cancel-routes.test.ts@@ -57,6 +57,24 @@ const mockIssueReferenceService = vi.hoisted(() => ({syncDocument: vi.fn(async () => undefined),syncIssue: vi.fn(async () => undefined),}));+const mockExternalObjectService = vi.hoisted(() => ({+ getIssueSummaries: vi.fn(async () => ({ summaries: {} })),+ getIssueSummary: vi.fn(async () => ({+ authRequiredCount: 0,+ byLiveness: {},+ byStatusCategory: {},+ highestSeverity: "muted",+ objects: [],+ staleCount: 0,+ total: 0,+ unreachableCount: 0,+ })),+ listForIssue: vi.fn(async () => []),+ refreshIssueObjects: vi.fn(async () => []),+ syncCommentSafely: vi.fn(async () => undefined),+ syncDocumentSafely: vi.fn(async () => undefined),+ syncIssueSafely: vi.fn(async () => undefined),+}));function registerModuleMocks() {vi.doMock("@paperclipai/shared/telemetry", () => ({@@ -92,6 +110,10 @@ function registerModuleMocks() {issueService: () => mockIssueService,}));+ vi.doMock("../services/external-objects.js", () => ({+ externalObjectService: () => mockExternalObjectService,+ }));+vi.doMock("../services/index.js", () => ({companyService: () => ({getById: vi.fn(async () => ({ id: "company-1", attachmentMaxBytes: 10 * 1024 * 1024 })),@@ -181,6 +203,7 @@ describe.sequential("issue comment cancel routes", () => {vi.doUnmock("../telemetry.js");vi.doUnmock("../services/access.js");vi.doUnmock("../services/activity-log.js");+ vi.doUnmock("../services/external-objects.js");vi.doUnmock("../services/feedback.js");vi.doUnmock("../services/heartbeat.js");vi.doUnmock("../services/index.js");@@ -240,6 +263,7 @@ describe.sequential("issue comment cancel routes", () => {});mockIssueReferenceService.deleteCommentSource.mockResolvedValue(undefined);mockIssueReferenceService.syncComment.mockResolvedValue(undefined);+ mockExternalObjectService.syncCommentSafely.mockResolvedValue(undefined);});it("cancels a queued comment from its author and restores the deleted body", async () => {@@ -352,6 +376,7 @@ describe.sequential("issue comment cancel routes", () => {expect.objectContaining({ afterTombstone: expect.any(Function) }),);expect(mockIssueReferenceService.syncComment).toHaveBeenCalledWith("comment-1", "tx");+ expect(mockExternalObjectService.syncCommentSafely).toHaveBeenCalledWith("comment-1", "tx");expect(mockDocumentAnnotationService.cleanupForIssueCommentDeletion).toHaveBeenCalledWith("11111111-1111-4111-8111-111111111111","comment-1",@@ -362,6 +387,7 @@ describe.sequential("issue comment cancel routes", () => {"tx",);expect(mockIssueReferenceService.deleteCommentSource).toHaveBeenCalledWith("annotation-comment-1", "tx");+ expect(mockExternalObjectService.syncCommentSafely).toHaveBeenCalledWith("annotation-comment-1", "tx");const deletedActivity = mockLogActivity.mock.calls.find((call) => call[1]?.action === "issue.comment_deleted")?.[1];expect(deletedActivity).toEqual(expect.objectContaining({action: "issue.comment_deleted",diff --git a/server/src/__tests__/issue-comment-reopen-routes.test.ts b/server/src/__tests__/issue-comment-reopen-routes.test.tsindex 3069367426..22ef7d7fa7 100644--- a/server/src/__tests__/issue-comment-reopen-routes.test.ts+++ b/server/src/__tests__/issue-comment-reopen-routes.test.ts@@ -79,6 +79,10 @@ const mockIssueRecoveryActionService = vi.hoisted(() => ({const mockIssueTreeControlService = vi.hoisted(() => ({getActivePauseHoldGate: vi.fn(async () => null),}));+const mockExternalObjectService = vi.hoisted(() => ({+ syncCommentSafely: vi.fn(async () => undefined),+ syncIssueSafely: vi.fn(async () => undefined),+}));vi.mock("@paperclipai/shared/telemetry", () => ({trackAgentTaskCompleted: vi.fn(),@@ -158,6 +162,10 @@ vi.mock("../services/index.js", () => ({workProductService: () => ({}),}));+vi.mock("../services/external-objects.js", () => ({+ externalObjectService: () => mockExternalObjectService,+}));+function createApp() {const app = express();app.use(express.json());@@ -253,6 +261,8 @@ describe.sequential("issue comment reopen routes", () => {mockRoutineService.syncRunStatusForIssue.mockReset();mockIssueRecoveryActionService.getActiveForIssue.mockReset();mockIssueTreeControlService.getActivePauseHoldGate.mockReset();+ mockExternalObjectService.syncCommentSafely.mockReset();+ mockExternalObjectService.syncIssueSafely.mockReset();mockTxInsertValues.mockReset();mockTxInsert.mockReset();mockDbSelect.mockReset();@@ -276,6 +286,8 @@ describe.sequential("issue comment reopen routes", () => {mockHeartbeatService.getRun.mockResolvedValue(null);mockHeartbeatService.getActiveRunForAgent.mockResolvedValue(null);mockHeartbeatService.cancelRun.mockResolvedValue(null);+ mockExternalObjectService.syncCommentSafely.mockResolvedValue(undefined);+ mockExternalObjectService.syncIssueSafely.mockResolvedValue(undefined);mockLogActivity.mockResolvedValue(undefined);mockFeedbackService.listIssueVotesForUser.mockResolvedValue([]);mockFeedbackService.saveIssueVote.mockResolvedValue({diff --git a/server/src/__tests__/plugin-environment-driver-seam.test.ts b/server/src/__tests__/plugin-environment-driver-seam.test.tsindex ec89adc75e..013994099c 100644--- a/server/src/__tests__/plugin-environment-driver-seam.test.ts+++ b/server/src/__tests__/plugin-environment-driver-seam.test.ts@@ -159,6 +159,203 @@ describe("plugin environment driver seam", () => {});});+const objectReferenceManifest: PaperclipPluginManifestV1 = {+ id: "test.external-object-provider",+ apiVersion: 1,+ version: "1.0.0",+ displayName: "External Object Provider",+ description: "Test external object provider plugin",+ author: "Paperclip",+ categories: ["connector"],+ capabilities: ["external.objects.detect", "external.objects.read"],+ entrypoints: { worker: "dist/worker.js" },+ objectReferences: [+ {+ providerKey: "mocktracker",+ displayName: "Mock Tracker",+ objectTypes: ["ticket"],+ urlPatterns: ["https://mock.example/tickets/:id"],+ refreshPolicy: { defaultTtlSeconds: 300, staleAfterSeconds: 1800 },+ },+ ],+};++describe("plugin external object provider seam", () => {+ it("validates provider manifest declarations and capabilities", () => {+ expect(pluginManifestV1Schema.safeParse(objectReferenceManifest).success).toBe(true);++ const missingCapability = pluginManifestV1Schema.safeParse({+ ...objectReferenceManifest,+ capabilities: ["external.objects.detect"],+ });+ expect(missingCapability.success).toBe(false);+ expect(JSON.stringify(missingCapability.error?.issues)).toContain("external.objects.read");++ const duplicateProvider = pluginManifestV1Schema.safeParse({+ ...objectReferenceManifest,+ objectReferences: [+ objectReferenceManifest.objectReferences![0],+ { ...objectReferenceManifest.objectReferences![0], displayName: "Duplicate" },+ ],+ });+ expect(duplicateProvider.success).toBe(false);+ expect(JSON.stringify(duplicateProvider.error?.issues)).toContain(+ "Duplicate object reference provider keys",+ );+ });++ it("enforces provider capability requirements", () => {+ const validator = pluginCapabilityValidator();+ expect(validator.getRequiredCapabilities("external.objects.detect")).toEqual([+ "external.objects.detect",+ ]);+ expect(validator.getRequiredCapabilities("external.objects.read")).toEqual([+ "external.objects.read",+ ]);+ expect(validator.checkOperation(objectReferenceManifest, "external.objects.read").allowed).toBe(true);++ const withoutCapability = {+ ...objectReferenceManifest,+ capabilities: ["external.objects.detect"],+ } satisfies PaperclipPluginManifestV1;++ expect(validator.checkOperation(withoutCapability, "external.objects.read")).toMatchObject({+ allowed: false,+ missing: ["external.objects.read"],+ });+ expect(validator.validateManifestCapabilities(withoutCapability)).toMatchObject({+ allowed: false,+ missing: ["external.objects.read"],+ });+ });++ it("dispatches provider detection and resolution worker hooks", async () => {+ const plugin = definePlugin({+ async setup() {},+ async onDetectExternalObjects(params) {+ return {+ detections: params.urls.map((url) => ({+ urlIdentityHash: url.canonicalIdentityHash,+ providerKey: "mocktracker",+ objectType: "ticket",+ externalId: "MOCK-123",+ displayTitle: "Mock ticket",+ confidence: "exact",+ })),+ };+ },+ async onResolveExternalObject(params) {+ return {+ ok: true,+ snapshot: {+ displayTitle: `Resolved ${params.externalId}`,+ statusKey: "ready",+ statusLabel: "Ready",+ statusCategory: "succeeded",+ statusTone: "success",+ isTerminal: true,+ ttlSeconds: 600,+ },+ };+ },+ });++ const stdin = new PassThrough();+ const stdout = new PassThrough();+ const host = startWorkerRpcHost({ plugin, stdin, stdout });+ const responses: unknown[] = [];+ stdout.on("data", (chunk) => {+ const lines = String(chunk).split("\n").filter(Boolean);+ for (const line of lines) {+ responses.push(parseMessage(line));+ }+ });++ stdin.write(serializeMessage(createRequest("initialize", {+ manifest: objectReferenceManifest,+ config: {},+ instanceInfo: { instanceId: "instance-1", hostVersion: "1.0.0" },+ apiVersion: 1,+ }, 1)));+ await waitForResponses(responses, 1);++ const initializeResponse = responses[0];+ expect(isJsonRpcSuccessResponse(initializeResponse)).toBe(true);+ if (!isJsonRpcSuccessResponse(initializeResponse)) return;+ expect(initializeResponse.result.supportedMethods).toContain("detectExternalObjects");+ expect(initializeResponse.result.supportedMethods).toContain("resolveExternalObject");++ stdin.write(serializeMessage(createRequest("detectExternalObjects", {+ companyId: "company-1",+ urls: [{+ sanitizedCanonicalUrl: "https://mock.example/tickets/123",+ sanitizedDisplayUrl: "https://mock.example/tickets/123",+ canonicalIdentityHash: "hash-123",+ canonicalIdentity: { scheme: "https", host: "mock.example", path: "/tickets/123" },+ redactedMatchedText: "https://mock.example/tickets/123",+ }],+ sourceContext: {+ companyId: "company-1",+ sourceIssueId: "issue-1",+ sourceKind: "description",+ sourceRecordId: null,+ documentKey: null,+ propertyKey: null,+ },+ }, 2)));+ await waitForResponses(responses, 2);++ const detectResponse = responses[1];+ expect(isJsonRpcSuccessResponse(detectResponse)).toBe(true);+ if (!isJsonRpcSuccessResponse(detectResponse)) return;+ expect(detectResponse.result.detections[0]).toMatchObject({+ providerKey: "mocktracker",+ objectType: "ticket",+ externalId: "MOCK-123",+ });++ stdin.write(serializeMessage(createRequest("resolveExternalObject", {+ companyId: "company-1",+ providerKey: "mocktracker",+ objectType: "ticket",+ externalId: "MOCK-123",+ object: {+ id: "object-1",+ companyId: "company-1",+ providerKey: "mocktracker",+ objectType: "ticket",+ externalId: "MOCK-123",+ sanitizedCanonicalUrl: "https://mock.example/tickets/123",+ canonicalIdentityHash: "hash-123",+ displayTitle: "Mock ticket",+ statusKey: null,+ statusLabel: null,+ statusCategory: "unknown",+ statusTone: "neutral",+ liveness: "unknown",+ isTerminal: false,+ data: {},+ remoteVersion: null,+ etag: null,+ },+ }, 3)));+ await waitForResponses(responses, 3);++ const resolveResponse = responses[2];+ expect(isJsonRpcSuccessResponse(resolveResponse)).toBe(true);+ if (!isJsonRpcSuccessResponse(resolveResponse)) return;+ expect(resolveResponse.result).toMatchObject({+ ok: true,+ snapshot: {+ statusCategory: "succeeded",+ statusTone: "success",+ },+ });++ host.stop();+ });+});+async function waitForResponses(responses: unknown[], count: number): Promise<void> {const deadline = Date.now() + 1_000;while (responses.length < count && Date.now() < deadline) {diff --git a/server/src/__tests__/workspace-runtime.test.ts b/server/src/__tests__/workspace-runtime.test.tsindex b0f9ac016a..9ba8780e93 100644--- a/server/src/__tests__/workspace-runtime.test.ts+++ b/server/src/__tests__/workspace-runtime.test.ts@@ -1536,6 +1536,97 @@ describe("realizeExecutionWorkspace", () => {}});+ it("regenerates stale worktree config that points at another host", async () => {+ const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-stale-config-"));+ const baseRoot = path.join(tempRoot, "base");+ const worktreeRoot = path.join(tempRoot, "worktree");+ const fakeBin = path.join(tempRoot, "bin");+ const fakePnpmPath = path.join(fakeBin, "pnpm");+ const scriptPath = path.join(worktreeRoot, "provision-worktree.sh");+ const paperclipDir = path.join(worktreeRoot, ".paperclip");++ try {+ await fs.mkdir(baseRoot, { recursive: true });+ await fs.mkdir(paperclipDir, { recursive: true });+ await fs.mkdir(fakeBin, { recursive: true });+ await fs.copyFile(provisionWorktreeScriptPath, scriptPath);+ await fs.chmod(scriptPath, 0o755);+ await fs.writeFile(+ path.join(paperclipDir, "config.json"),+ JSON.stringify({+ database: {+ mode: "embedded-postgres",+ embeddedPostgresDataDir: "/Users/example/.paperclip-worktrees/instances/stale/db",+ },+ logging: {+ mode: "file",+ logDir: "/Users/example/.paperclip-worktrees/instances/stale/logs",+ },+ storage: {+ provider: "local_disk",+ localDisk: {+ baseDir: "/Users/example/.paperclip-worktrees/instances/stale/data/storage",+ },+ },+ secrets: {+ provider: "local_encrypted",+ localEncrypted: {+ keyFilePath: "/Users/example/.paperclip-worktrees/instances/stale/secrets/master.key",+ },+ },+ }),+ "utf8",+ );+ await fs.writeFile(+ path.join(paperclipDir, ".env"),+ [+ "PAPERCLIP_HOME=/Users/example/.paperclip-worktrees",+ "PAPERCLIP_INSTANCE_ID=stale",+ `PAPERCLIP_CONFIG=/Users/example/paperclip/${path.basename(worktreeRoot)}/.paperclip/config.json`,+ "",+ ].join("\n"),+ "utf8",+ );+ await fs.writeFile(+ fakePnpmPath,+ [+ "#!/bin/sh",+ "if [ \"$1\" = \"paperclipai\" ] && [ \"$2\" = \"--help\" ]; then",+ " exit 0",+ "fi",+ "if [ \"$1\" = \"paperclipai\" ] && [ \"$2\" = \"worktree\" ] && [ \"$3\" = \"init\" ]; then",+ " mkdir -p \"$PWD/.paperclip\"",+ " printf '%s\\n' '{\"database\":{\"embeddedPostgresDataDir\":\"'$PWD'/.paperclip/runtime/db\"}}' > \"$PWD/.paperclip/config.json\"",+ " printf '%s\\n' \"PAPERCLIP_HOME=$PWD/.paperclip/runtime\" \"PAPERCLIP_INSTANCE_ID=healthy\" \"PAPERCLIP_CONFIG=$PWD/.paperclip/config.json\" > \"$PWD/.paperclip/.env\"",+ " exit 0",+ "fi",+ "exit 0",+ "",+ ].join("\n"),+ "utf8",+ );+ await fs.chmod(fakePnpmPath, 0o755);++ const result = await execFileAsync(scriptPath, [], {+ cwd: worktreeRoot,+ env: {+ ...process.env,+ PATH: `${fakeBin}:${process.env.PATH ?? ""}`,+ PAPERCLIP_WORKSPACE_BASE_CWD: baseRoot,+ PAPERCLIP_WORKSPACE_CWD: worktreeRoot,+ },+ });++ expect(result.stderr).toContain("Existing isolated Paperclip worktree config is stale for this host; regenerating.");+ await expect(fs.readFile(path.join(paperclipDir, ".env"), "utf8")).resolves.toContain(+ `PAPERCLIP_CONFIG=${worktreeRoot}/.paperclip/config.json`,+ );+ await expect(fs.readFile(path.join(paperclipDir, "config.json"), "utf8")).resolves.toContain(worktreeRoot);+ } finally {+ await fs.rm(tempRoot, { recursive: true, force: true });+ }+ });+it("retries worktree-local pnpm install without a frozen lockfile when the lockfile is outdated", async () => {const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-outdated-lockfile-"));const baseRoot = path.join(tempRoot, "base");diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex 21b7d01932..8e40055e9a 100644--- a/server/src/routes/issues.ts+++ b/server/src/routes/issues.ts@@ -148,11 +148,18 @@ import {resolveCoreTrustPreset,type TrustPresetResolution,} from "../services/trust-preset-resolver.js";+import { externalObjectService } from "../services/external-objects.js";const MAX_ISSUE_COMMENT_LIMIT = 500;const updateIssueRouteSchema = updateIssueSchema.extend({interrupt: z.boolean().optional(),});+const refreshExternalObjectsSchema = z.object({+ objectIds: z.array(z.string().uuid()).max(50).optional(),+}).strict();+const externalObjectSummariesSchema = z.object({+ issueIds: z.array(z.string().uuid()).max(1000),+}).strict();const promoteLowTrustOutputSchema = z.object({sourceArtifactKind: z.enum(["comment", "document", "work_product", "issue"]),@@ -1105,6 +1112,10 @@ export function issueRoutes(? heartbeat.wakeup: opts.taskWatchdogEnqueueWakeup ?? undefined,}) ?? noopTaskWatchdogService();+ const externalObjectsSvc = externalObjectService(db, {+ pluginWorkerManager: opts.pluginWorkerManager,+ enabled: async () => (await instanceSettings.getExperimental()).enableExternalObjects === true,+ });const routinesSvc = routineService(db, {pluginWorkerManager: opts.pluginWorkerManager,});@@ -3730,6 +3741,69 @@ export function issueRoutes(res.json(workProducts);});+ router.get("/issues/:id/external-objects", async (req, res) => {+ const id = req.params.id as string;+ const issue = await svc.getById(id);+ if (!issue) {+ res.status(404).json({ error: "Issue not found" });+ return;+ }+ assertCompanyAccess(req, issue.companyId);+ const objects = await externalObjectsSvc.listForIssue(issue.id);+ res.json(objects);+ });++ router.get("/issues/:id/external-object-summary", async (req, res) => {+ const id = req.params.id as string;+ const issue = await svc.getById(id);+ if (!issue) {+ res.status(404).json({ error: "Issue not found" });+ return;+ }+ assertCompanyAccess(req, issue.companyId);+ const summary = await externalObjectsSvc.getIssueSummary(issue.id);+ res.json(summary);+ });++ router.post("/companies/:companyId/issues/external-object-summaries", validate(externalObjectSummariesSchema), async (req, res) => {+ const companyId = req.params.companyId as string;+ assertCompanyAccess(req, companyId);+ const summaries = await externalObjectsSvc.getIssueSummaries(companyId, req.body.issueIds);+ res.json({ summaries: Object.fromEntries(summaries) });+ });++ router.post("/issues/:id/external-objects/refresh", validate(refreshExternalObjectsSchema), async (req, res) => {+ const id = req.params.id as string;+ const issue = await svc.getById(id);+ if (!issue) {+ res.status(404).json({ error: "Issue not found" });+ return;+ }+ assertCompanyAccess(req, issue.companyId);+ if (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;+ const actor = getActorInfo(req);+ const results = await externalObjectsSvc.refreshIssueObjects(issue.id, {+ companyId: issue.companyId,+ objectIds: req.body.objectIds,+ actor,+ });+ await logActivity(db, {+ companyId: issue.companyId,+ actorType: actor.actorType,+ actorId: actor.actorId,+ agentId: actor.agentId,+ runId: actor.runId,+ action: "external_object.refresh_requested",+ entityType: "issue",+ entityId: issue.id,+ details: {+ issueId: issue.id,+ objectIds: results.map((result) => result.object.id),+ },+ });+ res.json({ refreshed: results });+ });+router.get("/issues/:id/documents", async (req, res) => {const id = req.params.id as string;const issue = await svc.getById(id);@@ -4016,6 +4090,7 @@ export function issueRoutes(const redirectedFromLockedDocument ="redirectedFromLockedDocument" in result ? result.redirectedFromLockedDocument : null;await issueReferencesSvc.syncDocument(doc.id);+ await externalObjectsSvc.syncDocumentSafely(doc.id);const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);const remappedAnnotations = result.created@@ -4245,6 +4320,7 @@ export function issueRoutes(});await issueReferencesSvc.syncDocument(result.document.id);const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);+ await externalObjectsSvc.syncDocumentSafely(result.document.id);const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);const remappedAnnotations = await documentAnnotationsSvc.remapOpenThreadsForDocument({issueId: issue.id,@@ -4358,6 +4434,7 @@ export function issueRoutes(}await issueReferencesSvc.deleteDocumentSource(removed.id);const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);+ if (removed) await externalObjectsSvc.syncDocumentSafely(removed.id);const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);const actor = getActorInfo(req);await logActivity(db, {@@ -5025,6 +5102,7 @@ export function issueRoutes(watchdogActorRunId: actor.runId,});await issueReferencesSvc.syncIssue(issue.id);+ await externalObjectsSvc.syncIssueSafely(issue.id);const referenceSummary = await issueReferencesSvc.listIssueReferenceSummary(issue.id);const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(issueReferencesSvc.emptySummary(),@@ -5190,6 +5268,7 @@ export function issueRoutes(actorUserId: actor.actorType === "user" ? actor.actorId : null,watchdogActorRunId: actor.runId,});+ await externalObjectsSvc.syncIssueSafely(issue.id);await logActivity(db, {companyId: parent.companyId,@@ -5958,6 +6037,7 @@ export function issueRoutes(if (titleOrDescriptionChanged) {await issueReferencesSvc.syncIssue(issue.id);+ await externalObjectsSvc.syncIssueSafely(issue.id);}const updateReferenceSummaryAfter = titleOrDescriptionChanged? await issueReferencesSvc.listIssueReferenceSummary(issue.id)@@ -6263,6 +6343,7 @@ export function issueRoutes(sourceTrust: await sourceTrustForActorWrite(issue, actor),});await issueReferencesSvc.syncComment(comment.id);+ await externalObjectsSvc.syncCommentSafely(comment.id);const commentReferenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);const commentReferenceDiff = issueReferencesSvc.diffIssueReferenceSummary(commentReferenceSummaryBefore,@@ -7256,6 +7337,7 @@ export function issueRoutes({afterTombstone: async (deletedComment, tx) => {await issueReferencesSvc.syncComment(deletedComment.id, tx);+ await externalObjectsSvc.syncCommentSafely(deletedComment.id, tx);annotationCleanup = await documentAnnotationsSvc.cleanupForIssueCommentDeletion(issue.id, deletedComment.id, {actorType: actor.actorType,actorId: actor.actorId,@@ -7265,7 +7347,10 @@ export function issueRoutes(}, tx);await Promise.all(annotationCleanup.deletedCommentIds.map((annotationCommentId) =>- issueReferencesSvc.deleteCommentSource(annotationCommentId, tx)+ Promise.all([+ issueReferencesSvc.deleteCommentSource(annotationCommentId, tx),+ externalObjectsSvc.syncCommentSafely(annotationCommentId, tx),+ ])),);},@@ -7705,6 +7790,7 @@ export function issueRoutes(}await issueReferencesSvc.syncComment(comment.id);+ await externalObjectsSvc.syncCommentSafely(comment.id);const commentReferenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(currentIssue.id);const commentReferenceDiff = issueReferencesSvc.diffIssueReferenceSummary(commentReferenceSummaryBefore,diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.tsindex ccf38a30e0..82ac734ef6 100644--- a/server/src/routes/openapi.ts+++ b/server/src/routes/openapi.ts@@ -447,6 +447,14 @@ const jsonBody = (schema: z.ZodTypeAny) => ({const r = responses;+const externalObjectSummariesBodySchema = z.object({+ issueIds: z.array(z.string().uuid()).max(1000),+}).strict();++const refreshExternalObjectsBodySchema = z.object({+ objectIds: z.array(z.string().uuid()).max(50).optional(),+}).strict();+function paramsSchemaFromPath(routePath: string): z.ZodObject<z.ZodRawShape> | undefined {const names = [...routePath.matchAll(/\{([A-Za-z0-9_]+)\}/g)].map((match) => match[1]);if (names.length === 0) return undefined;@@ -3847,6 +3855,57 @@ registry.registerPath({responses: { 200: r.ok(), 401: r.unauthorized, 404: r.notFound },});+registry.registerPath({+ method: "get",+ path: "/api/issues/{id}/external-objects",+ tags: ["issues"],+ summary: "List external objects mentioned by an issue",+ request: { params: z.object({ id: z.string() }) },+ responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },+});++registry.registerPath({+ method: "get",+ path: "/api/issues/{id}/external-object-summary",+ tags: ["issues"],+ summary: "Get external object status summary for an issue",+ request: { params: z.object({ id: z.string() }) },+ responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },+});++registry.registerPath({+ method: "post",+ path: "/api/companies/{companyId}/issues/external-object-summaries",+ tags: ["issues"],+ summary: "Get external object status summaries for issues",+ request: {+ params: z.object({ companyId: z.string() }),+ body: jsonBody(externalObjectSummariesBodySchema),+ },+ responses: { 200: r.ok(), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden },+});++registry.registerPath({+ method: "post",+ path: "/api/issues/{id}/external-objects/refresh",+ tags: ["issues"],+ summary: "Refresh external objects mentioned by an issue",+ request: {+ params: z.object({ id: z.string() }),+ body: jsonBody(refreshExternalObjectsBodySchema),+ },+ responses: { 200: r.ok(), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },+});++registry.registerPath({+ method: "get",+ path: "/api/projects/{id}/external-object-summary",+ tags: ["projects"],+ summary: "Get external object status summary for a project",+ request: { params: z.object({ id: z.string() }) },+ responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },+});+// ─── Org chart images ─────────────────────────────────────────────────────────registry.registerPath({diff --git a/server/src/routes/projects.ts b/server/src/routes/projects.tsindex 6952cdd8a8..c7e123fc0d 100644--- a/server/src/routes/projects.ts+++ b/server/src/routes/projects.ts@@ -15,6 +15,8 @@ import { trackProjectCreated } from "@paperclipai/shared/telemetry";import { validate } from "../middleware/validate.js";import { accessService, projectService, logActivity, workspaceOperationService } from "../services/index.js";import { conflict, forbidden } from "../errors.js";+import { externalObjectService } from "../services/external-objects.js";+import { instanceSettingsService } from "../services/instance-settings.js";import { assertCompanyAccess, getActorInfo } from "./authz.js";import {buildWorkspaceRuntimeDesiredStatePatch,@@ -44,6 +46,10 @@ export function projectRoutes(db: Db) {const access = accessService(db);const secretsSvc = secretService(db);const workspaceOperations = workspaceOperationService(db);+ const instanceSettings = instanceSettingsService(db);+ const externalObjectsSvc = externalObjectService(db, {+ enabled: async () => (await instanceSettings.getExperimental()).enableExternalObjects === true,+ });const strictSecretsMode = process.env.PAPERCLIP_SECRETS_STRICT_MODE === "true";const environmentsSvc = environmentService(db);@@ -139,6 +145,18 @@ export function projectRoutes(db: Db) {res.json(project);});+ router.get("/projects/:id/external-object-summary", async (req, res) => {+ const id = req.params.id as string;+ const project = await svc.getById(id);+ if (!project) {+ res.status(404).json({ error: "Project not found" });+ return;+ }+ assertCompanyAccess(req, project.companyId);+ const summary = await externalObjectsSvc.getProjectSummary(project.id);+ res.json(summary);+ });+router.post("/companies/:companyId/projects", validate(createProjectSchema), async (req, res) => {const companyId = req.params.companyId as string;assertCompanyAccess(req, companyId);diff --git a/server/src/services/external-objects.ts b/server/src/services/external-objects.tsnew file mode 100644index 0000000000..4823a80fe4--- /dev/null+++ b/server/src/services/external-objects.ts@@ -0,0 +1,945 @@+import { and, asc, eq, inArray, isNull, lte, sql } from "drizzle-orm";+import type { Db } from "@paperclipai/db";+import { documents, externalObjectMentions, externalObjects, issueComments, issueDocuments, issues, plugins } from "@paperclipai/db";+import {+ formatExternalObjectMentionSourceLabel,+ type ExternalObjectCanonicalUrl,+ type ExternalObjectLivenessState,+ type ExternalObjectMentionConfidence,+ type ExternalObjectMentionSourceKind,+ type ExternalObjectStatusCategory,+ type ExternalObjectStatusTone,+ type PaperclipPluginManifestV1,+} from "@paperclipai/shared";+import { extractExternalObjectCanonicalUrls } from "@paperclipai/shared/external-objects-server";+import type { PluginExternalObjectRecordSnapshot, PluginExternalObjectResolveResult } from "@paperclipai/plugin-sdk";+import { notFound } from "../errors.js";+import { logger } from "../middleware/logger.js";+import { logActivity, type LogActivityInput } from "./activity-log.js";+import { createGitHubExternalObjectProvider, type GitHubExternalObjectProviderOptions } from "./github-external-object-provider.js";+import { publishLiveEvent } from "./live-events.js";+import type { PluginWorkerManager } from "./plugin-worker-manager.js";++export interface ExternalObjectSourceContext {+ companyId: string;+ sourceIssueId: string;+ sourceKind: ExternalObjectMentionSourceKind;+ sourceRecordId: string | null;+ documentKey: string | null;+ propertyKey: string | null;+}++export interface ExternalObjectDetection {+ canonical: ExternalObjectCanonicalUrl;+ detectorKey: string;+ providerKey: string;+ objectType: string;+ externalId: string;+ displayKey?: string | null;+ iconKey?: string | null;+ displayTitle?: string | null;+ confidence?: ExternalObjectMentionConfidence;+ pluginId?: string | null;+}++export interface ExternalObjectDetector {+ key: string;+ detect(input: {+ companyId: string;+ urls: ExternalObjectCanonicalUrl[];+ sourceContext: ExternalObjectSourceContext;+ }): Promise<ExternalObjectDetection[]> | ExternalObjectDetection[];+}++export interface ExternalObjectResolverSnapshot {+ displayKey?: string | null;+ iconKey?: string | null;+ displayTitle?: string | null;+ statusKey?: string | null;+ statusLabel?: string | null;+ statusIconKey?: string | null;+ statusCategory: ExternalObjectStatusCategory;+ statusTone: ExternalObjectStatusTone;+ isTerminal?: boolean;+ data?: Record<string, unknown>;+ remoteVersion?: string | null;+ etag?: string | null;+ ttlSeconds?: number;+}++export type ExternalObjectResolveResult =+ | { ok: true; snapshot: ExternalObjectResolverSnapshot }+ | {+ ok: false;+ liveness: Extract<ExternalObjectLivenessState, "auth_required" | "unreachable">;+ errorCode: string;+ errorMessage?: string | null;+ retryAfterSeconds?: number;+ };++export interface ExternalObjectResolver {+ providerKey: string;+ objectType?: string;+ resolve(input: {+ companyId: string;+ object: ExternalObjectRecord;+ }): Promise<ExternalObjectResolveResult>;+}++type ExternalObjectRecord = typeof externalObjects.$inferSelect;+type ExternalObjectMentionRecord = typeof externalObjectMentions.$inferSelect;++const DEFAULT_REFRESH_TTL_SECONDS = 300;+const DEFAULT_RETRY_AFTER_SECONDS = 300;++function sourceWhere(input: ExternalObjectSourceContext) {+ const conditions = [+ eq(externalObjectMentions.companyId, input.companyId),+ eq(externalObjectMentions.sourceIssueId, input.sourceIssueId),+ eq(externalObjectMentions.sourceKind, input.sourceKind),+ ];+ if (input.sourceRecordId) {+ conditions.push(eq(externalObjectMentions.sourceRecordId, input.sourceRecordId));+ } else {+ conditions.push(isNull(externalObjectMentions.sourceRecordId));+ }+ if (input.documentKey) {+ conditions.push(eq(externalObjectMentions.documentKey, input.documentKey));+ } else {+ conditions.push(isNull(externalObjectMentions.documentKey));+ }+ if (input.propertyKey) {+ conditions.push(eq(externalObjectMentions.propertyKey, input.propertyKey));+ } else {+ conditions.push(isNull(externalObjectMentions.propertyKey));+ }+ return and(...conditions);+}++function addSeconds(date: Date, seconds: number) {+ return new Date(date.getTime() + Math.max(1, seconds) * 1000);+}++function visibleLiveness(object: ExternalObjectRecord, now = new Date()): ExternalObjectLivenessState {+ if (object.liveness === "fresh" && object.nextRefreshAt && object.nextRefreshAt <= now) {+ return "stale";+ }+ return object.liveness;+}++function objectChanged(before: ExternalObjectRecord, after: ExternalObjectRecord) {+ return (+ before.statusKey !== after.statusKey ||+ before.statusLabel !== after.statusLabel ||+ before.statusIconKey !== after.statusIconKey ||+ before.statusCategory !== after.statusCategory ||+ before.statusTone !== after.statusTone ||+ before.isTerminal !== after.isTerminal+ );+}++function sanitizeErrorMessage(message: string | null | undefined) {+ if (!message) return null;+ return message+ .replace(/https?:\/\/[^\s<>()]+/gi, "[redacted-url]")+ .replace(/\b(token|key|secret|authorization|bearer)=\S+/gi, "$1=[redacted]");+}++function genericUrlDetector(): ExternalObjectDetector {+ return {+ key: "generic-url",+ detect({ urls }) {+ return urls.map((canonical) => ({+ canonical,+ detectorKey: "generic-url",+ providerKey: "url",+ objectType: "link",+ externalId: canonical.canonicalIdentityHash,+ displayTitle: canonical.sanitizedDisplayUrl,+ confidence: "possible",+ }));+ },+ };+}++export function createExternalObjectDetectorRegistry(detectors: ExternalObjectDetector[] = []) {+ const entries = [...detectors, genericUrlDetector()];++ async function detect(input: {+ companyId: string;+ urls: ExternalObjectCanonicalUrl[];+ sourceContext: ExternalObjectSourceContext;+ }) {+ const claimed = new Set<string>();+ const detections: ExternalObjectDetection[] = [];+ for (const detector of entries) {+ const remaining = input.urls.filter((url) => !claimed.has(url.canonicalIdentityHash));+ if (remaining.length === 0) break;+ try {+ const detected = await detector.detect({ ...input, urls: remaining });+ for (const detection of detected) {+ if (claimed.has(detection.canonical.canonicalIdentityHash)) continue;+ claimed.add(detection.canonical.canonicalIdentityHash);+ detections.push({ ...detection, detectorKey: detection.detectorKey || detector.key });+ }+ } catch (err) {+ logger.warn({ err, detectorKey: detector.key }, "external object detector failed");+ }+ }+ return detections;+ }++ return { detect };+}++export function createExternalObjectResolverRegistry(resolvers: ExternalObjectResolver[] = []) {+ function find(object: Pick<ExternalObjectRecord, "providerKey" | "objectType">) {+ return resolvers.find(+ (resolver) =>+ resolver.providerKey === object.providerKey &&+ (!resolver.objectType || resolver.objectType === object.objectType),+ ) ?? null;+ }+ return { find };+}++function manifestProvidesObject(+ manifest: PaperclipPluginManifestV1,+ object: Pick<ExternalObjectRecord, "providerKey" | "objectType">,+) {+ return (manifest.objectReferences ?? []).some(+ (provider) =>+ provider.providerKey === object.providerKey &&+ provider.objectTypes.includes(object.objectType),+ );+}++function objectSnapshot(object: ExternalObjectRecord): PluginExternalObjectRecordSnapshot {+ return {+ id: object.id,+ companyId: object.companyId,+ providerKey: object.providerKey,+ objectType: object.objectType,+ externalId: object.externalId,+ sanitizedCanonicalUrl: object.sanitizedCanonicalUrl,+ canonicalIdentityHash: object.canonicalIdentityHash,+ displayKey: object.displayKey,+ iconKey: object.iconKey,+ displayTitle: object.displayTitle,+ statusKey: object.statusKey,+ statusLabel: object.statusLabel,+ statusIconKey: object.statusIconKey,+ statusCategory: object.statusCategory,+ statusTone: object.statusTone,+ liveness: object.liveness,+ isTerminal: object.isTerminal,+ data: object.data as Record<string, unknown>,+ remoteVersion: object.remoteVersion,+ etag: object.etag,+ };+}++async function readyObjectReferencePlugins(db: Db) {+ return db+ .select({+ id: plugins.id,+ pluginKey: plugins.pluginKey,+ manifestJson: plugins.manifestJson,+ })+ .from(plugins)+ .where(eq(plugins.status, "ready"))+ .orderBy(asc(plugins.installOrder))+ .then((rows) =>+ rows.filter((row) => (row.manifestJson.objectReferences?.length ?? 0) > 0),+ );+}++function createPluginProviderDetector(+ db: Db,+ pluginWorkerManager: PluginWorkerManager,+): ExternalObjectDetector {+ return {+ key: "plugin-object-reference-providers",+ async detect(input) {+ const providers = await readyObjectReferencePlugins(db);+ const detections: ExternalObjectDetection[] = [];++ for (const provider of providers) {+ const manifest = provider.manifestJson;+ if (!manifest.capabilities.includes("external.objects.detect")) continue;+ try {+ const result = await pluginWorkerManager.call(provider.id, "detectExternalObjects", {+ companyId: input.companyId,+ urls: input.urls.map((url) => ({+ sanitizedCanonicalUrl: url.sanitizedCanonicalUrl,+ sanitizedDisplayUrl: url.sanitizedDisplayUrl,+ canonicalIdentityHash: url.canonicalIdentityHash,+ canonicalIdentity: url.canonicalIdentity as unknown as Record<string, unknown>,+ redactedMatchedText: url.redactedMatchedText,+ })),+ sourceContext: input.sourceContext,+ });+ const urlsByHash = new Map(input.urls.map((url) => [url.canonicalIdentityHash, url]));+ const declaredProviderKeys = new Set((manifest.objectReferences ?? []).map((entry) => entry.providerKey));++ for (const detection of result.detections ?? []) {+ const canonical = urlsByHash.get(detection.urlIdentityHash);+ if (!canonical) continue;+ if (!declaredProviderKeys.has(detection.providerKey)) continue;+ const declaration = (manifest.objectReferences ?? []).find((entry) => entry.providerKey === detection.providerKey);+ if (!declaration?.objectTypes.includes(detection.objectType)) continue;+ detections.push({+ canonical,+ detectorKey: `${provider.pluginKey}:${detection.providerKey}`,+ providerKey: detection.providerKey,+ objectType: detection.objectType,+ externalId: detection.externalId,+ displayKey: detection.displayKey,+ iconKey: detection.iconKey,+ displayTitle: detection.displayTitle,+ confidence: detection.confidence ?? "exact",+ pluginId: provider.id,+ });+ }+ } catch (err) {+ logger.warn(+ { err, pluginId: provider.id, pluginKey: provider.pluginKey },+ "plugin external object detector failed",+ );+ }+ }++ return detections;+ },+ };+}++async function resolveViaPluginProvider(+ db: Db,+ pluginWorkerManager: PluginWorkerManager | undefined,+ object: ExternalObjectRecord,+): Promise<PluginExternalObjectResolveResult | null> {+ if (!pluginWorkerManager) return null;+ const providers = await readyObjectReferencePlugins(db);+ for (const provider of providers) {+ const manifest = provider.manifestJson;+ if (!manifest.capabilities.includes("external.objects.read")) continue;+ if (!manifestProvidesObject(manifest, object)) continue;+ try {+ return await pluginWorkerManager.call(provider.id, "resolveExternalObject", {+ companyId: object.companyId,+ providerKey: object.providerKey,+ objectType: object.objectType,+ externalId: object.externalId,+ object: objectSnapshot(object),+ });+ } catch (err) {+ logger.warn(+ { err, pluginId: provider.id, pluginKey: provider.pluginKey, objectId: object.id },+ "plugin external object resolver failed",+ );+ return {+ ok: false,+ liveness: "unreachable",+ errorCode: "plugin_resolver_failed",+ errorMessage: err instanceof Error ? err.message : String(err),+ };+ }+ }+ return null;+}++export function externalObjectService(+ db: Db,+ opts: {+ detectors?: ExternalObjectDetector[];+ resolvers?: ExternalObjectResolver[];+ pluginWorkerManager?: PluginWorkerManager;+ github?: GitHubExternalObjectProviderOptions | false;+ enabled?: boolean | (() => boolean | Promise<boolean>);+ } = {},+) {+ const githubProvider = opts.github === false ? null : createGitHubExternalObjectProvider(db, opts.github);+ const pluginProviderDetector = opts.pluginWorkerManager+ ? createPluginProviderDetector(db, opts.pluginWorkerManager)+ : null;+ const detectorRegistry = createExternalObjectDetectorRegistry([+ ...(pluginProviderDetector ? [pluginProviderDetector] : []),+ ...(opts.detectors ?? []),+ ...(githubProvider ? [githubProvider.detector] : []),+ ]);+ const resolverRegistry = createExternalObjectResolverRegistry([+ ...(opts.resolvers ?? []),+ ...(githubProvider?.resolvers ?? []),+ ]);++ async function isEnabled() {+ if (typeof opts.enabled === "function") return await opts.enabled();+ return opts.enabled ?? true;+ }++ function emptySummary() {+ return summarizeObjectPayloads([]);+ }++ async function issueById(issueId: string, dbOrTx: any = db) {+ return dbOrTx+ .select({+ id: issues.id,+ companyId: issues.companyId,+ title: issues.title,+ description: issues.description,+ })+ .from(issues)+ .where(eq(issues.id, issueId))+ .then((rows: Array<{ id: string; companyId: string; title: string; description: string | null }>) => rows[0] ?? null);+ }++ async function upsertObjectFromDetection(+ companyId: string,+ detection: ExternalObjectDetection,+ dbOrTx: any,+ ): Promise<ExternalObjectRecord> {+ const now = new Date();+ const canonical = detection.canonical;+ const values = {+ companyId,+ providerKey: detection.providerKey,+ pluginId: detection.pluginId ?? null,+ objectType: detection.objectType,+ externalId: detection.externalId,+ sanitizedCanonicalUrl: canonical.sanitizedCanonicalUrl,+ canonicalIdentityHash: canonical.canonicalIdentityHash,+ displayKey: detection.displayKey ?? null,+ iconKey: detection.iconKey ?? null,+ displayTitle: detection.displayTitle ?? canonical.sanitizedDisplayUrl,+ nextRefreshAt: now,+ updatedAt: now,+ };+ const inserted = await dbOrTx+ .insert(externalObjects)+ .values(values)+ .onConflictDoUpdate({+ target: [+ externalObjects.companyId,+ externalObjects.providerKey,+ externalObjects.objectType,+ externalObjects.externalId,+ ],+ set: {+ sanitizedCanonicalUrl: values.sanitizedCanonicalUrl,+ canonicalIdentityHash: values.canonicalIdentityHash,+ displayKey: values.displayKey,+ iconKey: values.iconKey,+ displayTitle: values.displayTitle,+ nextRefreshAt: sql`coalesce(${externalObjects.nextRefreshAt}, now())`,+ updatedAt: now,+ },+ })+ .returning();+ return inserted[0]!;+ }++ async function replaceSourceMentions(+ input: ExternalObjectSourceContext & { text: string | null | undefined },+ dbOrTx: any = db,+ ) {+ const urls = extractExternalObjectCanonicalUrls(input.text ?? "");+ await dbOrTx.delete(externalObjectMentions).where(sourceWhere(input));+ if (urls.length === 0) return;++ const detections = await detectorRegistry.detect({+ companyId: input.companyId,+ urls,+ sourceContext: input,+ });+ if (detections.length === 0) return;++ const seen = new Set<string>();+ const values: Array<typeof externalObjectMentions.$inferInsert> = [];+ for (const detection of detections) {+ const canonicalHash = detection.canonical.canonicalIdentityHash;+ const sourceKey = `${detection.providerKey}:${detection.objectType}:${canonicalHash}`;+ if (seen.has(sourceKey)) continue;+ seen.add(sourceKey);+ const object = await upsertObjectFromDetection(input.companyId, detection, dbOrTx);+ values.push({+ companyId: input.companyId,+ sourceIssueId: input.sourceIssueId,+ sourceKind: input.sourceKind,+ sourceRecordId: input.sourceRecordId,+ documentKey: input.documentKey,+ propertyKey: input.propertyKey,+ matchedTextRedacted: detection.canonical.redactedMatchedText,+ sanitizedDisplayUrl: detection.canonical.sanitizedDisplayUrl,+ canonicalIdentityHash: canonicalHash,+ canonicalIdentity: detection.canonical.canonicalIdentity as unknown as Record<string, unknown>,+ objectId: object.id,+ providerKey: detection.providerKey,+ detectorKey: detection.detectorKey,+ objectType: detection.objectType,+ confidence: detection.confidence ?? "exact",+ createdByPluginId: detection.pluginId ?? null,+ });+ }+ if (values.length > 0) {+ await dbOrTx.insert(externalObjectMentions).values(values);+ }+ }++ async function syncIssue(issueId: string, dbOrTx: any = db) {+ if (!(await isEnabled())) return;+ const runSync = async (tx: any) => {+ const issue = await issueById(issueId, tx);+ if (!issue) throw notFound("Issue not found");+ await replaceSourceMentions({+ companyId: issue.companyId,+ sourceIssueId: issue.id,+ sourceKind: "title",+ sourceRecordId: null,+ documentKey: null,+ propertyKey: null,+ text: issue.title,+ }, tx);+ await replaceSourceMentions({+ companyId: issue.companyId,+ sourceIssueId: issue.id,+ sourceKind: "description",+ sourceRecordId: null,+ documentKey: null,+ propertyKey: null,+ text: issue.description,+ }, tx);+ };+ return dbOrTx === db ? db.transaction(runSync) : runSync(dbOrTx);+ }++ async function syncComment(commentId: string, dbOrTx: any = db) {+ const runSync = async (tx: any) => {+ if (!(await isEnabled())) return;+ const comment = await tx+ .select({+ id: issueComments.id,+ companyId: issueComments.companyId,+ issueId: issueComments.issueId,+ body: issueComments.body,+ })+ .from(issueComments)+ .where(eq(issueComments.id, commentId))+ .then((rows: Array<{ id: string; companyId: string; issueId: string; body: string }>) => rows[0] ?? null);+ if (!comment) {+ await tx+ .delete(externalObjectMentions)+ .where(and(eq(externalObjectMentions.sourceKind, "comment"), eq(externalObjectMentions.sourceRecordId, commentId)));+ return;+ }+ await replaceSourceMentions({+ companyId: comment.companyId,+ sourceIssueId: comment.issueId,+ sourceKind: "comment",+ sourceRecordId: comment.id,+ documentKey: null,+ propertyKey: null,+ text: comment.body,+ }, tx);+ };+ return dbOrTx === db ? db.transaction(runSync) : runSync(dbOrTx);+ }++ async function syncDocument(documentId: string, dbOrTx: any = db) {+ const runSync = async (tx: any) => {+ if (!(await isEnabled())) return;+ const document = await tx+ .select({+ documentId: documents.id,+ companyId: documents.companyId,+ issueId: issueDocuments.issueId,+ key: issueDocuments.key,+ body: documents.latestBody,+ })+ .from(issueDocuments)+ .innerJoin(documents, eq(issueDocuments.documentId, documents.id))+ .where(eq(documents.id, documentId))+ .then((rows: Array<{ documentId: string; companyId: string; issueId: string; key: string; body: string }>) => rows[0] ?? null);+ if (!document) {+ await tx+ .delete(externalObjectMentions)+ .where(and(eq(externalObjectMentions.sourceKind, "document"), eq(externalObjectMentions.sourceRecordId, documentId)));+ return;+ }+ await replaceSourceMentions({+ companyId: document.companyId,+ sourceIssueId: document.issueId,+ sourceKind: "document",+ sourceRecordId: document.documentId,+ documentKey: document.key,+ propertyKey: null,+ text: document.body,+ }, tx);+ };+ return dbOrTx === db ? db.transaction(runSync) : runSync(dbOrTx);+ }++ async function safeSync(label: string, fn: () => Promise<void>) {+ try {+ await fn();+ } catch (err) {+ logger.warn({ err }, `external object ${label} sync failed`);+ }+ }++ async function syncIssueSafely(issueId: string) {+ await safeSync("issue", () => syncIssue(issueId));+ }++ async function syncCommentSafely(commentId: string, dbOrTx: any = db) {+ await safeSync("comment", () => syncComment(commentId, dbOrTx));+ }++ async function syncDocumentSafely(documentId: string) {+ await safeSync("document", () => syncDocument(documentId));+ }++ function toObjectPayload(object: ExternalObjectRecord, now = new Date()) {+ return {+ ...object,+ liveness: visibleLiveness(object, now),+ };+ }++ async function listForIssue(issueId: string) {+ if (!(await isEnabled())) return [];+ const issue = await issueById(issueId);+ if (!issue) throw notFound("Issue not found");+ const rows = await db+ .select({+ mention: externalObjectMentions,+ object: externalObjects,+ })+ .from(externalObjectMentions)+ .leftJoin(externalObjects, eq(externalObjectMentions.objectId, externalObjects.id))+ .where(and(+ eq(externalObjectMentions.companyId, issue.companyId),+ eq(externalObjectMentions.sourceIssueId, issue.id),+ ))+ .orderBy(asc(externalObjectMentions.sourceKind), asc(externalObjectMentions.createdAt));+ const now = new Date();+ const grouped = new Map<string, {+ object: ReturnType<typeof toObjectPayload> | null;+ mentions: ExternalObjectMentionRecord[];+ mentionCount: number;+ sourceLabels: string[];+ }>();+ for (const row of rows) {+ const key = row.object?.id ?? `mention:${row.mention.id}`;+ const existing = grouped.get(key) ?? {+ object: row.object ? toObjectPayload(row.object, now) : null,+ mentions: [],+ mentionCount: 0,+ sourceLabels: [],+ };+ existing.mentions.push(row.mention);+ existing.mentionCount += 1;+ const label = formatExternalObjectMentionSourceLabel({+ sourceKind: row.mention.sourceKind,+ documentKey: row.mention.documentKey,+ propertyKey: row.mention.propertyKey,+ });+ if (!existing.sourceLabels.includes(label)) existing.sourceLabels.push(label);+ grouped.set(key, existing);+ }+ return [...grouped.values()];+ }++ function summarizeObjects(objects: Array<ReturnType<typeof toObjectPayload>>) {+ const byStatusCategory: Record<string, number> = {};+ const byLiveness: Record<string, number> = {};+ let highestSeverity: ExternalObjectStatusTone = "neutral";+ const severityRank: Record<ExternalObjectStatusTone, number> = {+ neutral: 0,+ muted: 0,+ success: 1,+ info: 2,+ warning: 3,+ danger: 4,+ };+ for (const object of objects) {+ byStatusCategory[object.statusCategory] = (byStatusCategory[object.statusCategory] ?? 0) + 1;+ byLiveness[object.liveness] = (byLiveness[object.liveness] ?? 0) + 1;+ const livenessTone = object.liveness === "auth_required" || object.liveness === "unreachable"+ ? "danger"+ : object.liveness === "stale"+ ? "warning"+ : object.statusTone;+ if (severityRank[livenessTone] > severityRank[highestSeverity]) highestSeverity = livenessTone;+ }+ return {+ total: objects.length,+ byStatusCategory,+ byLiveness,+ highestSeverity,+ staleCount: byLiveness.stale ?? 0,+ authRequiredCount: byLiveness.auth_required ?? 0,+ unreachableCount: byLiveness.unreachable ?? 0,+ };+ }++ function summarizeObjectPayloads(objects: Array<ReturnType<typeof toObjectPayload>>, objectLimit = objects.length) {+ return {+ ...summarizeObjects(objects),+ objects: objects.slice(0, objectLimit).map((object) => ({+ id: object.id,+ providerKey: object.providerKey,+ objectType: object.objectType,+ displayKey: object.displayKey,+ iconKey: object.iconKey,+ displayTitle: object.displayTitle,+ statusIconKey: object.statusIconKey,+ statusCategory: object.statusCategory,+ statusTone: object.statusTone,+ liveness: object.liveness,+ isTerminal: object.isTerminal,+ })),+ };+ }++ async function getIssueSummary(issueId: string) {+ if (!(await isEnabled())) return emptySummary();+ const groups = await listForIssue(issueId);+ const objects = groups.flatMap((group) => (group.object ? [group.object] : []));+ return summarizeObjectPayloads(objects);+ }++ async function getIssueSummaries(companyId: string, issueIds: string[]) {+ if (!(await isEnabled())) return new Map<string, ReturnType<typeof summarizeObjectPayloads>>();+ const uniqueIssueIds = [...new Set(issueIds)].filter((id) => id.length > 0);+ const summaries = new Map<string, ReturnType<typeof summarizeObjectPayloads>>();+ if (uniqueIssueIds.length === 0) return summaries;++ const rows = await db+ .select({+ issueId: externalObjectMentions.sourceIssueId,+ object: externalObjects,+ })+ .from(externalObjectMentions)+ .innerJoin(externalObjects, eq(externalObjectMentions.objectId, externalObjects.id))+ .where(and(+ eq(externalObjectMentions.companyId, companyId),+ inArray(externalObjectMentions.sourceIssueId, uniqueIssueIds),+ ));++ const now = new Date();+ const objectsByIssueId = new Map<string, Map<string, ReturnType<typeof toObjectPayload>>>();+ for (const row of rows) {+ const issueObjects = objectsByIssueId.get(row.issueId) ?? new Map<string, ReturnType<typeof toObjectPayload>>();+ issueObjects.set(row.object.id, toObjectPayload(row.object, now));+ objectsByIssueId.set(row.issueId, issueObjects);+ }++ for (const [issueId, issueObjects] of objectsByIssueId) {+ const objects = [...issueObjects.values()];+ if (objects.length > 0) summaries.set(issueId, summarizeObjectPayloads(objects));+ }+ return summaries;+ }++ async function getProjectSummary(projectId: string) {+ if (!(await isEnabled())) return emptySummary();+ const projectIssues = await db+ .select({ id: issues.id, companyId: issues.companyId })+ .from(issues)+ .where(and(eq(issues.projectId, projectId), inArray(issues.status, ["todo", "in_progress", "in_review", "blocked"])));+ if (projectIssues.length === 0) return { ...summarizeObjects([]), objects: [] };+ const companyIds = new Set(projectIssues.map((issue) => issue.companyId));+ if (companyIds.size !== 1) return { ...summarizeObjects([]), objects: [] };+ const issueIds = projectIssues.map((issue) => issue.id);+ const rows = await db+ .select({ object: externalObjects })+ .from(externalObjectMentions)+ .innerJoin(externalObjects, eq(externalObjectMentions.objectId, externalObjects.id))+ .where(and(+ eq(externalObjectMentions.companyId, projectIssues[0]!.companyId),+ inArray(externalObjectMentions.sourceIssueId, issueIds),+ ));+ const now = new Date();+ const objectsById = new Map<string, ReturnType<typeof toObjectPayload>>();+ for (const row of rows) objectsById.set(row.object.id, toObjectPayload(row.object, now));+ const objects = [...objectsById.values()];+ return summarizeObjectPayloads(objects, 25);+ }++ async function refreshObject(+ objectId: string,+ input: {+ companyId: string;+ actor?: Pick<LogActivityInput, "actorType" | "actorId" | "agentId" | "runId">;+ force?: boolean;+ now?: Date;+ },+ ) {+ const now = input.now ?? new Date();+ const object = await db+ .select()+ .from(externalObjects)+ .where(and(eq(externalObjects.id, objectId), eq(externalObjects.companyId, input.companyId)))+ .then((rows) => rows[0] ?? null);+ if (!object) throw notFound("External object not found");+ if (!input.force && object.nextRefreshAt && object.nextRefreshAt > now) {+ return { object: toObjectPayload(object, now), refreshed: false, reason: "backoff" as const };+ }++ const pluginResult = await resolveViaPluginProvider(db, opts.pluginWorkerManager, object);+ const resolver = pluginResult ? null : resolverRegistry.find(object);+ if (!pluginResult && !resolver) {+ const [updated] = await db+ .update(externalObjects)+ .set({+ liveness: visibleLiveness(object, now) === "fresh" ? "stale" : object.liveness,+ nextRefreshAt: addSeconds(now, DEFAULT_RETRY_AFTER_SECONDS),+ updatedAt: now,+ })+ .where(and(eq(externalObjects.id, object.id), eq(externalObjects.companyId, object.companyId)))+ .returning();+ return { object: toObjectPayload(updated ?? object, now), refreshed: false, reason: "no_resolver" as const };+ }++ const result = pluginResult ?? await resolver!.resolve({ companyId: object.companyId, object });+ if (!result.ok) {+ const [updated] = await db+ .update(externalObjects)+ .set({+ liveness: result.liveness,+ lastErrorAt: now,+ lastErrorCode: result.errorCode,+ lastErrorMessage: sanitizeErrorMessage(result.errorMessage),+ nextRefreshAt: addSeconds(now, result.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS),+ updatedAt: now,+ })+ .where(and(eq(externalObjects.id, object.id), eq(externalObjects.companyId, object.companyId)))+ .returning();+ publishLiveEvent({+ companyId: object.companyId,+ type: "external_object.updated",+ payload: { objectId: object.id, liveness: result.liveness },+ });+ return { object: toObjectPayload(updated ?? object, now), refreshed: true, reason: result.liveness };+ }++ const snapshot = result.snapshot;+ const patch = {+ displayKey: snapshot.displayKey ?? object.displayKey,+ iconKey: snapshot.iconKey ?? object.iconKey,+ displayTitle: snapshot.displayTitle ?? object.displayTitle,+ statusKey: snapshot.statusKey ?? object.statusKey,+ statusLabel: snapshot.statusLabel ?? object.statusLabel,+ statusIconKey: snapshot.statusIconKey ?? object.statusIconKey,+ statusCategory: snapshot.statusCategory,+ statusTone: snapshot.statusTone,+ isTerminal: snapshot.isTerminal ?? object.isTerminal,+ data: snapshot.data ?? object.data,+ remoteVersion: snapshot.remoteVersion ?? object.remoteVersion,+ etag: snapshot.etag ?? object.etag,+ liveness: "fresh" as ExternalObjectLivenessState,+ lastResolvedAt: now,+ lastErrorAt: null,+ lastErrorCode: null,+ lastErrorMessage: null,+ nextRefreshAt: addSeconds(now, snapshot.ttlSeconds ?? DEFAULT_REFRESH_TTL_SECONDS),+ updatedAt: now,+ };+ const [updated] = await db+ .update(externalObjects)+ .set({+ ...patch,+ lastChangedAt: objectChanged(object, { ...object, ...patch }) ? now : object.lastChangedAt,+ })+ .where(and(eq(externalObjects.id, object.id), eq(externalObjects.companyId, object.companyId)))+ .returning();+ const next = updated ?? object;+ if (objectChanged(object, next) && input.actor) {+ await logActivity(db, {+ companyId: object.companyId,+ actorType: input.actor.actorType,+ actorId: input.actor.actorId,+ agentId: input.actor.agentId,+ runId: input.actor.runId,+ action: "external_object.status_changed",+ entityType: "external_object",+ entityId: object.id,+ details: {+ providerKey: object.providerKey,+ objectType: object.objectType,+ statusCategory: next.statusCategory,+ statusLabel: next.statusLabel,+ _previous: {+ statusCategory: object.statusCategory,+ statusLabel: object.statusLabel,+ },+ },+ });+ }+ publishLiveEvent({+ companyId: object.companyId,+ type: "external_object.updated",+ payload: { objectId: object.id, statusCategory: next.statusCategory, liveness: next.liveness },+ });+ return { object: toObjectPayload(next, now), refreshed: true, reason: "resolved" as const };+ }++ async function refreshIssueObjects(issueId: string, input: {+ companyId: string;+ objectIds?: string[];+ actor?: Pick<LogActivityInput, "actorType" | "actorId" | "agentId" | "runId">;+ }) {+ if (!(await isEnabled())) return [];+ const groups = await listForIssue(issueId);+ const objectIds = groups+ .flatMap((group) => (group.object ? [group.object.id] : []))+ .filter((id) => !input.objectIds || input.objectIds.includes(id));+ const results = [];+ for (const objectId of objectIds) {+ results.push(await refreshObject(objectId, { companyId: input.companyId, actor: input.actor }));+ }+ return results;+ }++ async function refreshDueObjects(companyId: string, limit = 50, now = new Date()) {+ if (!(await isEnabled())) return [];+ const due = await db+ .select({ id: externalObjects.id })+ .from(externalObjects)+ .where(+ and(+ eq(externalObjects.companyId, companyId),+ eq(externalObjects.isTerminal, false),+ lte(externalObjects.nextRefreshAt, now),+ ),+ )+ .limit(limit);+ const results = [];+ for (const row of due) {+ results.push(await refreshObject(row.id, {+ companyId,+ actor: { actorType: "system", actorId: "external-object-resolver", agentId: null, runId: null },+ now,+ }));+ }+ return results;+ }++ return {+ syncIssue,+ syncComment,+ syncDocument,+ syncIssueSafely,+ syncCommentSafely,+ syncDocumentSafely,+ listForIssue,+ getIssueSummary,+ getIssueSummaries,+ getProjectSummary,+ refreshObject,+ refreshIssueObjects,+ refreshDueObjects,+ };+}diff --git a/server/src/services/github-external-object-provider.ts b/server/src/services/github-external-object-provider.tsnew file mode 100644index 0000000000..f434b24b41--- /dev/null+++ b/server/src/services/github-external-object-provider.ts@@ -0,0 +1,445 @@+import type { Db } from "@paperclipai/db";+import type { ExternalObjectCanonicalUrl } from "@paperclipai/shared";+import { ghFetch, gitHubApiBase } from "./github-fetch.js";+import { secretService } from "./secrets.js";+import type {+ ExternalObjectDetection,+ ExternalObjectDetector,+ ExternalObjectResolver,+ ExternalObjectResolverSnapshot,+ ExternalObjectResolveResult,+} from "./external-objects.js";++type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;++export interface GitHubExternalObjectProviderOptions {+ fetch?: FetchLike;+ tokenProvider?: (companyId: string) => Promise<string | null> | string | null;+ secretNames?: readonly string[];+}++interface GitHubObjectIdentity {+ host: string;+ owner: string;+ repo: string;+ number: number;+ objectType: "pull_request" | "issue";+ pathKind: "pull" | "issues";+}++const DEFAULT_GITHUB_TOKEN_SECRET_NAMES = ["GITHUB_TOKEN", "GH_TOKEN", "PAPERCLIP_GITHUB_TOKEN"] as const;+const GITHUB_OBJECT_TTL_SECONDS = 300;++function isGitHubHost(host: string) {+ const h = host.toLowerCase();+ return h === "github.com" || h === "www.github.com";+}++function asRecord(value: unknown): Record<string, unknown> | null {+ return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;+}++function asString(value: unknown) {+ return typeof value === "string" ? value : null;+}++function asBoolean(value: unknown) {+ return typeof value === "boolean" ? value : null;+}++function asNestedString(record: Record<string, unknown>, key: string, nestedKey: string) {+ const nested = asRecord(record[key]);+ return nested ? asString(nested[nestedKey]) : null;+}++function parseGitHubCanonicalUrl(canonical: ExternalObjectCanonicalUrl): GitHubObjectIdentity | null {+ if (canonical.canonicalIdentity.scheme !== "https") return null;+ const host = canonical.canonicalIdentity.host.toLowerCase();+ if (!isGitHubHost(host)) return null;++ const parts = canonical.canonicalIdentity.path.split("/").filter(Boolean);+ if (parts.length !== 4) return null;+ const [owner, repo, kind, rawNumber] = parts;+ if (!owner || !repo || !kind || !rawNumber) return null;+ if (!/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) return null;+ if (!/^[1-9][0-9]*$/.test(rawNumber)) return null;+ if (kind !== "pull" && kind !== "issues") return null;++ return {+ host: host === "www.github.com" ? "github.com" : host,+ owner,+ repo,+ number: Number(rawNumber),+ pathKind: kind,+ objectType: kind === "pull" ? "pull_request" : "issue",+ };+}++function parseGitHubObject(object: { externalId: string; sanitizedCanonicalUrl: string | null }): GitHubObjectIdentity | null {+ const match = /^([^/]+)\/([^/]+)#(pull|issues)\/([1-9][0-9]*)$/.exec(object.externalId);+ if (!match) return null;+ let host = "github.com";+ if (object.sanitizedCanonicalUrl) {+ try {+ const url = new URL(object.sanitizedCanonicalUrl);+ if (isGitHubHost(url.hostname)) host = url.hostname === "www.github.com" ? "github.com" : url.hostname;+ } catch {+ return null;+ }+ }+ return {+ host,+ owner: match[1]!,+ repo: match[2]!,+ pathKind: match[3] as "pull" | "issues",+ number: Number(match[4]),+ objectType: match[3] === "pull" ? "pull_request" : "issue",+ };+}++function externalIdFor(identity: GitHubObjectIdentity) {+ return `${identity.owner.toLowerCase()}/${identity.repo.toLowerCase()}#${identity.pathKind}/${identity.number}`;+}++function displayTitleFor(identity: GitHubObjectIdentity) {+ return `${identity.owner}/${identity.repo}#${identity.number}`;+}++function displayKeyFor(identity: Pick<GitHubObjectIdentity, "objectType">) {+ return identity.objectType === "pull_request" ? "GitHub Pull Request" : "GitHub Issue";+}++function retryAfterSeconds(response: Response) {+ const retryAfter = response.headers.get("retry-after");+ if (retryAfter && /^[0-9]+$/.test(retryAfter)) return Number(retryAfter);++ const reset = response.headers.get("x-ratelimit-reset");+ if (reset && /^[0-9]+$/.test(reset)) {+ return Math.max(1, Number(reset) - Math.floor(Date.now() / 1000));+ }++ return 300;+}++function failureFromGitHubResponse(response: Response): ExternalObjectResolveResult | null {+ if (response.status === 401) {+ return {+ ok: false,+ liveness: "auth_required",+ errorCode: "github_auth_required",+ errorMessage: "GitHub authentication is required to refresh this object.",+ retryAfterSeconds: retryAfterSeconds(response),+ };+ }++ if (response.status === 403) {+ const rateLimitRemaining = response.headers.get("x-ratelimit-remaining");+ if (rateLimitRemaining === "0") {+ return {+ ok: false,+ liveness: "unreachable",+ errorCode: "github_rate_limited",+ errorMessage: "GitHub rate limit reached while refreshing this object.",+ retryAfterSeconds: retryAfterSeconds(response),+ };+ }+ return {+ ok: false,+ liveness: "auth_required",+ errorCode: "github_forbidden",+ errorMessage: "GitHub rejected the configured credentials for this object.",+ retryAfterSeconds: retryAfterSeconds(response),+ };+ }++ if (response.status === 429 || response.status >= 500) {+ return {+ ok: false,+ liveness: "unreachable",+ errorCode: response.status === 429 ? "github_rate_limited" : "github_unreachable",+ errorMessage: `GitHub returned HTTP ${response.status} while refreshing this object.`,+ retryAfterSeconds: retryAfterSeconds(response),+ };+ }++ return null;+}++function notFoundSnapshot(identity: GitHubObjectIdentity, etag: string | null): ExternalObjectResolverSnapshot {+ return {+ displayKey: displayKeyFor(identity),+ iconKey: "github",+ displayTitle: displayTitleFor(identity),+ statusKey: "not_found",+ statusLabel: "Not found",+ statusIconKey: "archive",+ statusCategory: "archived",+ statusTone: "muted",+ isTerminal: true,+ etag,+ ttlSeconds: GITHUB_OBJECT_TTL_SECONDS,+ data: {+ provider: "github",+ owner: identity.owner,+ repo: identity.repo,+ number: identity.number,+ notFound: true,+ },+ };+}++function pullRequestSnapshot(identity: GitHubObjectIdentity, body: Record<string, unknown>, etag: string | null): ExternalObjectResolverSnapshot {+ const title = asString(body.title);+ const state = asString(body.state) ?? "unknown";+ const draft = asBoolean(body.draft) ?? false;+ const merged = (asBoolean(body.merged) ?? false) || Boolean(asString(body.merged_at));+ const authorLogin = asNestedString(body, "user", "login");+ const headRef = asNestedString(body, "head", "ref");+ const baseRef = asNestedString(body, "base", "ref");+ const reviewDecision = asString(body.review_decision);++ let statusKey = state;+ let statusLabel = state === "open" ? "Open" : state === "closed" ? "Closed" : "Unknown";+ let statusCategory: ExternalObjectResolverSnapshot["statusCategory"] = state === "open" ? "open" : "unknown";+ let statusTone: ExternalObjectResolverSnapshot["statusTone"] = state === "open" ? "info" : "neutral";+ let isTerminal = false;++ if (merged) {+ statusKey = "merged";+ statusLabel = "Merged";+ statusCategory = "succeeded";+ statusTone = "success";+ isTerminal = true;+ } else if (state === "closed") {+ statusKey = "closed";+ statusLabel = "Closed";+ statusCategory = "closed";+ statusTone = "muted";+ isTerminal = true;+ } else if (draft) {+ statusKey = "draft";+ statusLabel = "Draft";+ statusCategory = "waiting";+ statusTone = "warning";+ }++ return {+ displayKey: displayKeyFor(identity),+ iconKey: "github",+ displayTitle: title ? `${displayTitleFor(identity)}: ${title}` : displayTitleFor(identity),+ statusKey,+ statusLabel,+ statusIconKey: merged+ ? "git-merge"+ : state === "closed"+ ? "x-circle"+ : draft+ ? "clock"+ : "git-pull-request",+ statusCategory,+ statusTone,+ isTerminal,+ remoteVersion: asString(body.updated_at),+ etag,+ ttlSeconds: GITHUB_OBJECT_TTL_SECONDS,+ data: {+ provider: "github",+ owner: identity.owner,+ repo: identity.repo,+ number: identity.number,+ state,+ merged,+ draft,+ ...(authorLogin ? { authorLogin } : {}),+ ...(headRef ? { headRef } : {}),+ ...(baseRef ? { baseRef } : {}),+ ...(reviewDecision ? { reviewDecision } : {}),+ },+ };+}++function issueSnapshot(identity: GitHubObjectIdentity, body: Record<string, unknown>, etag: string | null): ExternalObjectResolverSnapshot {+ const title = asString(body.title);+ const state = asString(body.state) ?? "unknown";+ const stateReason = asString(body.state_reason);+ const authorLogin = asNestedString(body, "user", "login");+ const statusKey = state === "closed" && stateReason ? `closed_${stateReason}` : state;+ const statusLabel = state === "closed"+ ? stateReason+ ? `Closed: ${stateReason.replace(/_/g, " ")}`+ : "Closed"+ : state === "open"+ ? "Open"+ : "Unknown";++ return {+ displayKey: displayKeyFor(identity),+ iconKey: "github",+ displayTitle: title ? `${displayTitleFor(identity)}: ${title}` : displayTitleFor(identity),+ statusKey,+ statusLabel,+ statusIconKey: state === "closed" ? "circle" : "circle-dot",+ statusCategory: state === "open" ? "open" : state === "closed" ? "closed" : "unknown",+ statusTone: state === "open" ? "info" : state === "closed" ? "muted" : "neutral",+ isTerminal: state === "closed",+ remoteVersion: asString(body.updated_at),+ etag,+ ttlSeconds: GITHUB_OBJECT_TTL_SECONDS,+ data: {+ provider: "github",+ owner: identity.owner,+ repo: identity.repo,+ number: identity.number,+ state,+ ...(stateReason ? { stateReason } : {}),+ ...(authorLogin ? { authorLogin } : {}),+ },+ };+}++async function safeJson(response: Response) {+ try {+ return asRecord(await response.json());+ } catch {+ return null;+ }+}++async function defaultTokenProvider(db: Db, companyId: string, secretNames: readonly string[]) {+ const secrets = secretService(db);+ for (const secretName of secretNames) {+ const secret = await secrets.getByName(companyId, secretName);+ if (!secret) continue;+ const token = await secrets.resolveSecretValue(companyId, secret.id, "latest");+ const trimmed = token.trim();+ if (trimmed) return trimmed;+ }+ return null;+}++export function createGitHubExternalObjectProvider(+ db: Db,+ opts: GitHubExternalObjectProviderOptions = {},+): { detector: ExternalObjectDetector; resolvers: ExternalObjectResolver[] } {+ const fetchImpl = opts.fetch ?? ghFetch;+ const secretNames = opts.secretNames ?? DEFAULT_GITHUB_TOKEN_SECRET_NAMES;+ const tokenProvider = Object.prototype.hasOwnProperty.call(opts, "tokenProvider") && opts.tokenProvider !== undefined+ ? opts.tokenProvider+ : ((companyId: string) => defaultTokenProvider(db, companyId, secretNames));++ const detector: ExternalObjectDetector = {+ key: "github",+ detect({ urls }): ExternalObjectDetection[] {+ return urls.flatMap((canonical) => {+ const identity = parseGitHubCanonicalUrl(canonical);+ if (!identity) return [];+ return [{+ canonical,+ detectorKey: "github",+ providerKey: "github",+ objectType: identity.objectType,+ externalId: externalIdFor(identity),+ displayKey: displayKeyFor(identity),+ iconKey: "github",+ displayTitle: displayTitleFor(identity),+ confidence: "exact",+ }];+ });+ },+ };++ function resolver(objectType: GitHubObjectIdentity["objectType"]): ExternalObjectResolver {+ return {+ providerKey: "github",+ objectType,+ async resolve({ companyId, object }) {+ const identity = parseGitHubObject(object);+ if (!identity || identity.objectType !== objectType) {+ return {+ ok: false,+ liveness: "unreachable",+ errorCode: "github_invalid_identity",+ errorMessage: "GitHub object identity is invalid.",+ retryAfterSeconds: GITHUB_OBJECT_TTL_SECONDS,+ };+ }++ let token: string | null = null;+ try {+ token = typeof tokenProvider === "function" ? await tokenProvider(companyId) : tokenProvider;+ } catch {+ return {+ ok: false,+ liveness: "auth_required",+ errorCode: "github_token_unavailable",+ errorMessage: "Configured GitHub credentials could not be resolved.",+ retryAfterSeconds: GITHUB_OBJECT_TTL_SECONDS,+ };+ }+ token = token?.trim() || null;+ const headers: Record<string, string> = {+ accept: "application/vnd.github+json",+ "user-agent": "paperclip-external-object-resolver",+ "x-github-api-version": "2022-11-28",+ };+ if (token) headers.authorization = `Bearer ${token}`;++ const apiKind = objectType === "pull_request" ? "pulls" : "issues";+ const url = `${gitHubApiBase(identity.host)}/repos/${encodeURIComponent(identity.owner)}/${encodeURIComponent(identity.repo)}/${apiKind}/${identity.number}`;++ let response: Response;+ try {+ response = await fetchImpl(url, { headers });+ } catch {+ return {+ ok: false,+ liveness: "unreachable",+ errorCode: "github_fetch_failed",+ errorMessage: "GitHub could not be reached while refreshing this object.",+ retryAfterSeconds: GITHUB_OBJECT_TTL_SECONDS,+ };+ }++ const etag = response.headers.get("etag");+ if (response.status === 404) {+ return { ok: true, snapshot: notFoundSnapshot(identity, etag) };+ }++ const failure = failureFromGitHubResponse(response);+ if (failure) return failure;+ if (!response.ok) {+ return {+ ok: false,+ liveness: "unreachable",+ errorCode: "github_unexpected_response",+ errorMessage: `GitHub returned HTTP ${response.status} while refreshing this object.`,+ retryAfterSeconds: GITHUB_OBJECT_TTL_SECONDS,+ };+ }++ const body = await safeJson(response);+ if (!body) {+ return {+ ok: false,+ liveness: "unreachable",+ errorCode: "github_invalid_response",+ errorMessage: "GitHub returned an invalid object response.",+ retryAfterSeconds: GITHUB_OBJECT_TTL_SECONDS,+ };+ }++ return {+ ok: true,+ snapshot: objectType === "pull_request"+ ? pullRequestSnapshot(identity, body, etag)+ : issueSnapshot(identity, body, etag),+ };+ },+ };+ }++ return {+ detector,+ resolvers: [resolver("pull_request"), resolver("issue")],+ };+}diff --git a/server/src/services/index.ts b/server/src/services/index.tsindex 209e1c8d6a..e968098d72 100644--- a/server/src/services/index.ts+++ b/server/src/services/index.ts@@ -33,6 +33,15 @@ export {resolveTaskWatchdogMutationScope,taskWatchdogScopeAllowsIssueMutation,} from "./task-watchdog-scope.js";+export {+ createExternalObjectDetectorRegistry,+ createExternalObjectResolverRegistry,+ externalObjectService,+ type ExternalObjectDetector,+ type ExternalObjectResolver,+ type ExternalObjectResolveResult,+ type ExternalObjectResolverSnapshot,+} from "./external-objects.js";export { goalService } from "./goals.js";export { activityService, type ActivityFilters } from "./activity.js";export { approvalService } from "./approvals.js";diff --git a/server/src/services/instance-settings.ts b/server/src/services/instance-settings.tsindex 03bf2c02e5..88656ec14d 100644--- a/server/src/services/instance-settings.ts+++ b/server/src/services/instance-settings.ts@@ -52,6 +52,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimentaenableExperimentalFileViewer: parsed.data.enableExperimentalFileViewer ?? false,enableTaskWatchdogs: parsed.data.enableTaskWatchdogs ?? false,enableCloudSync: parsed.data.enableCloudSync ?? false,+ enableExternalObjects: parsed.data.enableExternalObjects ?? false,autoRestartDevServerWhenIdle: parsed.data.autoRestartDevServerWhenIdle ?? false,enableIssueGraphLivenessAutoRecovery: parsed.data.enableIssueGraphLivenessAutoRecovery ?? false,issueGraphLivenessAutoRecoveryLookbackHours:@@ -68,6 +69,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimentaenableIssuePlanDecompositions: false,enableExperimentalFileViewer: false,enableCloudSync: false,+ enableExternalObjects: false,autoRestartDevServerWhenIdle: false,enableIssueGraphLivenessAutoRecovery: false,issueGraphLivenessAutoRecoveryLookbackHours:diff --git a/server/src/services/plugin-capability-validator.ts b/server/src/services/plugin-capability-validator.tsindex f8b47866c3..9e01b696b5 100644--- a/server/src/services/plugin-capability-validator.ts+++ b/server/src/services/plugin-capability-validator.ts@@ -99,6 +99,10 @@ const OPERATION_CAPABILITIES: Record<string, readonly PluginCapability[]> = {"telemetry.track": ["telemetry.track"],"db.migrate": ["database.namespace.migrate"],"db.execute": ["database.namespace.write"],+ "external.objects.detect": ["external.objects.detect"],+ "external.objects.read": ["external.objects.read"],+ "external.objects.write": ["external.objects.write"],+ "external.objects.refresh": ["external.objects.refresh"],// Plugin state operations"plugin.state.get": ["plugin.state.read"],@@ -188,6 +192,7 @@ const FEATURE_CAPABILITIES: Record<string, PluginCapability> = {agents: "agents.managed",projects: "projects.managed",routines: "routines.managed",+ objectReferences: "external.objects.detect",};// ---------------------------------------------------------------------------@@ -452,6 +457,14 @@ export function pluginCapabilityValidator(): PluginCapabilityValidator {}}+ if ((manifest.objectReferences?.length ?? 0) > 0) {+ for (const requiredCap of ["external.objects.detect", "external.objects.read"] as const) {+ if (!declared.has(requiredCap) && !allMissing.includes(requiredCap)) {+ allMissing.push(requiredCap);+ }+ }+ }+// Check UI slots → required capabilitiesconst uiSlots = manifest.ui?.slots ?? [];if (uiSlots.length > 0) {diff --git a/ui/src/api/externalObjects.ts b/ui/src/api/externalObjects.tsnew file mode 100644index 0000000000..e728c82cd5--- /dev/null+++ b/ui/src/api/externalObjects.ts@@ -0,0 +1,18 @@+import type { ExternalObjectMentionGroup, ExternalObjectSummary } from "@paperclipai/shared";+import { api } from "./client";++export const externalObjectsApi = {+ listForIssue: (issueId: string) =>+ api.get<ExternalObjectMentionGroup[]>(`/issues/${issueId}/external-objects`),+ getIssueSummary: (issueId: string) =>+ api.get<ExternalObjectSummary>(`/issues/${issueId}/external-object-summary`),+ getIssueSummaries: (companyId: string, issueIds: string[]) =>+ api.post<{ summaries: Record<string, ExternalObjectSummary> }>(+ `/companies/${companyId}/issues/external-object-summaries`,+ { issueIds },+ ),+ refreshIssueObjects: (issueId: string, data?: { objectIds?: string[] }) =>+ api.post<{ refreshed: unknown[] }>(`/issues/${issueId}/external-objects/refresh`, data ?? {}),+ getProjectSummary: (projectId: string) =>+ api.get<ExternalObjectSummary>(`/projects/${projectId}/external-object-summary`),+};diff --git a/ui/src/api/index.ts b/ui/src/api/index.tsindex 7da3d5531d..1bee6e7589 100644--- a/ui/src/api/index.ts+++ b/ui/src/api/index.ts@@ -6,6 +6,7 @@ export { companiesApi } from "./companies";export { agentsApi } from "./agents";export { projectsApi } from "./projects";export { issuesApi } from "./issues";+export { externalObjectsApi } from "./externalObjects";export { routinesApi } from "./routines";export { goalsApi } from "./goals";export { approvalsApi } from "./approvals";diff --git a/ui/src/components/CommentThread.external-references.test.tsx b/ui/src/components/CommentThread.external-references.test.tsxnew file mode 100644index 0000000000..3f65b6e658--- /dev/null+++ b/ui/src/components/CommentThread.external-references.test.tsx@@ -0,0 +1,114 @@+// @vitest-environment jsdom++import { act } from "react";+import type { ReactNode } from "react";+import { createRoot } from "react-dom/client";+import { MemoryRouter } from "react-router-dom";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import type { Approval } from "@paperclipai/shared";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { ThemeProvider } from "../context/ThemeContext";+import { CommentThread } from "./CommentThread";++vi.mock("./MarkdownEditor", () => ({+ MarkdownEditor: () => null,+}));++vi.mock("./InlineEntitySelector", () => ({+ InlineEntitySelector: () => null,+}));++vi.mock("./ApprovalCard", () => ({+ ApprovalCard: ({ approval }: { approval: Approval }) => <div>{approval.type}</div>,+}));++vi.mock("@/plugins/slots", () => ({+ PluginSlotOutlet: () => null,+}));++vi.mock("../api/issues", () => ({+ issuesApi: { get: vi.fn() },+}));++// eslint-disable-next-line @typescript-eslint/no-explicit-any+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;++describe("CommentThread external object decoration (integration)", () => {+ let container: HTMLDivElement;++ beforeEach(() => {+ container = document.createElement("div");+ document.body.appendChild(container);+ });++ afterEach(() => {+ container.remove();+ });++ it("decorates a resolved URL and leaves an unknown URL unchanged when rendered through the real MarkdownBody", () => {+ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+ const root = createRoot(container);++ act(() => {+ root.render(+ <QueryClientProvider client={queryClient}>+ <ThemeProvider>+ <MemoryRouter>+ <CommentThread+ comments={[{+ id: "comment-mixed",+ companyId: "company-1",+ issueId: "issue-1",+ authorAgentId: null,+ authorUserId: "user-1",+ authorType: "user",+ presentation: null,+ metadata: null,+ body: [+ "Tracked: https://github.com/example/repo/pull/77",+ "Untracked: https://elsewhere.example.com/page",+ ].join("\n\n"),+ createdAt: new Date("2026-04-24T12:00:00.000Z"),+ updatedAt: new Date("2026-04-24T12:00:00.000Z"),+ }]}+ externalReferences={{+ "https://github.com/example/repo/pull/77": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "open",+ liveness: "fresh",+ statusLabel: "Open",+ displayTitle: "PR #77",+ },+ }}+ onAdd={async () => {}}+ />+ </MemoryRouter>+ </ThemeProvider>+ </QueryClientProvider>,+ );+ });++ const resolvedLink = container.querySelector(+ 'a[href="https://github.com/example/repo/pull/77"]',+ );+ expect(resolvedLink, "resolved URL should be wrapped by the external-link decorator").not.toBeNull();+ expect(resolvedLink?.getAttribute("data-external-link")).toBe("resolved");+ expect(resolvedLink?.getAttribute("data-external-status")).toBe("open");+ expect(resolvedLink?.classList.contains("paperclip-markdown-external-ref")).toBe(true);++ const unknownLink = container.querySelector(+ 'a[href="https://elsewhere.example.com/page"]',+ );+ expect(unknownLink, "unknown URL should still render as a plain link").not.toBeNull();+ expect(unknownLink?.getAttribute("data-external-link")).toBeNull();+ expect(unknownLink?.classList.contains("paperclip-markdown-external-ref")).toBe(false);++ act(() => {+ root.unmount();+ });+ queryClient.clear();+ });+});diff --git a/ui/src/components/CommentThread.test.tsx b/ui/src/components/CommentThread.test.tsxindex ed791baa2c..427d5f62ea 100644--- a/ui/src/components/CommentThread.test.tsx+++ b/ui/src/components/CommentThread.test.tsx@@ -9,8 +9,22 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { CommentThread } from "./CommentThread";vi.mock("./MarkdownBody", () => ({- MarkdownBody: ({ children, className }: { children: ReactNode; className?: string }) => (- <div className={className}>{children}</div>+ MarkdownBody: ({+ children,+ className,+ externalReferences,+ }: {+ children: ReactNode;+ className?: string;+ externalReferences?: Record<string, unknown>;+ }) => (+ <div+ className={className}+ data-testid="markdown-body"+ data-external-reference-keys={externalReferences ? Object.keys(externalReferences).join(",") : ""}+ >+ {children}+ </div>),}));@@ -395,4 +409,51 @@ describe("CommentThread", () => {root.unmount();});});++ it("passes externalReferences to MarkdownBody for comment bodies", () => {+ const root = createRoot(container);++ act(() => {+ root.render(+ <MemoryRouter>+ <CommentThread+ comments={[{+ id: "comment-ref",+ companyId: "company-1",+ issueId: "issue-1",+ authorAgentId: null,+ authorUserId: "user-1",+ authorType: "user",+ presentation: null,+ metadata: null,+ body: "See https://github.com/example/repo/pull/42 for context.",+ createdAt: new Date("2026-03-11T11:00:00.000Z"),+ updatedAt: new Date("2026-03-11T11:00:00.000Z"),+ }]}+ externalReferences={{+ "https://github.com/example/repo/pull/42": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "open",+ liveness: "fresh",+ statusLabel: "Open",+ displayTitle: "PR #42",+ },+ }}+ onAdd={async () => {}}+ />+ </MemoryRouter>,+ );+ });++ const commentRow = container.querySelector("#comment-comment-ref") as HTMLDivElement | null;+ expect(commentRow).not.toBeNull();+ const markdownBody = commentRow?.querySelector('[data-testid="markdown-body"]') as HTMLElement | null;+ expect(markdownBody?.getAttribute("data-external-reference-keys"))+ .toContain("https://github.com/example/repo/pull/42");++ act(() => {+ root.unmount();+ });+ });});diff --git a/ui/src/components/CommentThread.tsx b/ui/src/components/CommentThread.tsxindex cf0576abb1..9026b05106 100644--- a/ui/src/components/CommentThread.tsx+++ b/ui/src/components/CommentThread.tsx@@ -14,7 +14,7 @@ import { ArrowRight, Check, Copy, Paperclip } from "lucide-react";import { Avatar, AvatarFallback } from "@/components/ui/avatar";import { Identity } from "./Identity";import { InlineEntitySelector, type InlineEntityOption } from "./InlineEntitySelector";-import { MarkdownBody } from "./MarkdownBody";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";import { MarkdownEditor, type MarkdownEditorRef, type MentionOption } from "./MarkdownEditor";import { OutputFeedbackButtons } from "./OutputFeedbackButtons";import { ApprovalCard } from "./ApprovalCard";@@ -105,6 +105,7 @@ interface CommentThreadProps {onInterruptQueued?: (runId: string) => Promise<void>;interruptingQueuedRunId?: string | null;composerDisabledReason?: string | null;+ externalReferences?: MarkdownExternalReferenceMap;}const DRAFT_DEBOUNCE_MS = 800;@@ -324,6 +325,7 @@ function CommentCard({voting = false,highlightCommentId,queued = false,+ externalReferences,}: {comment: CommentWithRunMeta;agentMap?: Map<string, Agent>;@@ -339,6 +341,7 @@ function CommentCard({voting?: boolean;highlightCommentId?: string | null;queued?: boolean;+ externalReferences?: MarkdownExternalReferenceMap;}) {const isHighlighted = highlightCommentId === comment.id;const isPending = comment.clientStatus === "pending";@@ -412,7 +415,7 @@ function CommentCard({{isDeleted ? (<div className="text-sm italic text-muted-foreground">Comment deleted</div>) : (- <MarkdownBody className="text-sm" softBreaks>{comment.body}</MarkdownBody>+ <MarkdownBody className="text-sm" softBreaks externalReferences={externalReferences}>{comment.body}</MarkdownBody>)}{companyId && !isPending && !isDeleted ? (<div className="mt-2 space-y-2">@@ -575,6 +578,7 @@ const TimelineList = memo(function TimelineList({onVote,votingTargetId,highlightCommentId,+ externalReferences,}: {timeline: TimelineItem[];agentMap?: Map<string, Agent>;@@ -597,6 +601,7 @@ const TimelineList = memo(function TimelineList({) => Promise<void>;votingTargetId?: string | null;highlightCommentId?: string | null;+ externalReferences?: MarkdownExternalReferenceMap;}) {if (timeline.length === 0) {return <p className="text-sm text-muted-foreground">No timeline entries yet.</p>;@@ -718,6 +723,7 @@ const TimelineList = memo(function TimelineList({onVote={onVote ? (vote, options) => onVote(comment.id, vote, options) : undefined}voting={votingTargetId === comment.id}highlightCommentId={highlightCommentId}+ externalReferences={externalReferences}/>);})}@@ -756,6 +762,7 @@ export function CommentThread({onInterruptQueued,interruptingQueuedRunId = null,composerDisabledReason = null,+ externalReferences,}: CommentThreadProps) {const [body, setBody] = useState("");const [submitting, setSubmitting] = useState(false);@@ -974,6 +981,7 @@ export function CommentThread({votingTargetId={votingTargetId}highlightCommentId={highlightCommentId}feedbackTermsUrl={feedbackTermsUrl}+ externalReferences={externalReferences}/>{liveRunSlot}@@ -1006,6 +1014,7 @@ export function CommentThread({projectId={projectId}highlightCommentId={highlightCommentId}queued+ externalReferences={externalReferences}/>))}</div>diff --git a/ui/src/components/ExternalObjectPill.test.tsx b/ui/src/components/ExternalObjectPill.test.tsxnew file mode 100644index 0000000000..5899b11655--- /dev/null+++ b/ui/src/components/ExternalObjectPill.test.tsx@@ -0,0 +1,170 @@+// @vitest-environment node++import { describe, expect, it } from "vitest";+import { renderToStaticMarkup } from "react-dom/server";+import { ExternalObjectPill } from "./ExternalObjectPill";+import { ExternalObjectStatusSummary } from "./ExternalObjectStatusSummary";++describe("ExternalObjectPill", () => {+ it("renders a clickable anchor when a URL is provided", () => {+ const html = renderToStaticMarkup(+ <ExternalObjectPill+ object={{+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "succeeded",+ liveness: "fresh",+ displayTitle: "Add external refs",+ url: "https://github.com/acme/web/pull/241",+ }}+ sourceCount={4}+ sourceSummary="description, 3 comments"+ />,+ );+ expect(html).toContain('href="https://github.com/acme/web/pull/241"');+ expect(html).toContain('data-mention-kind="external-object"');+ expect(html).toContain('data-external-status="succeeded"');+ expect(html).toContain('data-external-liveness="fresh"');+ expect(html).toContain("×4");+ expect(html).toContain('aria-label="GitHub pull request — Succeeded: Add external refs"');+ });++ it("falls back to a non-interactive span when no URL is supplied", () => {+ const html = renderToStaticMarkup(+ <ExternalObjectPill+ object={{+ providerKey: null,+ objectType: null,+ statusCategory: "unknown",+ liveness: "unknown",+ url: null,+ }}+ />,+ );+ expect(html).toContain('data-mention-kind="external-object"');+ expect(html).not.toContain("<a ");+ expect(html).toContain('aria-label="External object — Not yet resolved"');+ });++ it("applies the dashed-border liveness overlay when stale or auth_required", () => {+ const stale = renderToStaticMarkup(+ <ExternalObjectPill+ object={{+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "failed",+ liveness: "stale",+ url: "https://github.com/acme/web/pull/242",+ }}+ />,+ );+ expect(stale).toContain("opacity-70");+ expect(stale).toContain("[border-style:dashed]");++ const auth = renderToStaticMarkup(+ <ExternalObjectPill+ object={{+ providerKey: "hubspot",+ objectType: "lead",+ statusCategory: "auth_required",+ liveness: "auth_required",+ url: "https://app.hubspot.com/leads/99",+ }}+ />,+ );+ expect(auth).toContain("[border-style:dashed]");+ });++ it("does not show a source count when only a single mention is present", () => {+ const html = renderToStaticMarkup(+ <ExternalObjectPill+ object={{+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "succeeded",+ liveness: "fresh",+ url: "https://github.com/acme/web/pull/241",+ }}+ sourceCount={1}+ />,+ );+ expect(html).not.toContain("×");+ });++ it("uses the object link label, provider icon, and visible status when supplied", () => {+ const html = renderToStaticMarkup(+ <ExternalObjectPill+ object={{+ providerKey: "github",+ objectType: "pull_request",+ displayKey: "Github Pull Request",+ iconKey: "github",+ statusCategory: "succeeded",+ statusIconKey: null,+ liveness: "fresh",+ statusLabel: "Merged",+ displayTitle: "acme/web#241: Add rich object presentation metadata",+ url: "https://github.com/acme/web/pull/241",+ }}+ />,+ );+ expect(html).toContain("Merged");+ expect(html).toContain("PR 241 - Merged");+ expect(html).not.toContain("acme/web#241</span>");+ expect(html).toContain("text-violet-600");+ expect(html).not.toContain("Github Pull Request");+ expect(html).toContain('aria-label="GitHub pull request — Merged: acme/web#241: Add rich object presentation metadata"');+ });+});++describe("ExternalObjectStatusSummary", () => {+ it("hides itself when there are no external objects", () => {+ const html = renderToStaticMarkup(<ExternalObjectStatusSummary summary={null} />);+ expect(html).toBe("");+ });++ it("hides itself when the highest severity is muted", () => {+ const html = renderToStaticMarkup(+ <ExternalObjectStatusSummary+ summary={{+ total: 2,+ byStatusCategory: { closed: 2 },+ byLiveness: { fresh: 2 },+ highestSeverity: "muted",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+ }}+ />,+ );+ expect(html).toBe("");+ });++ it("shows the dominant-severity icon and count", () => {+ const html = renderToStaticMarkup(+ <ExternalObjectStatusSummary+ summary={{+ total: 5,+ byStatusCategory: { failed: 3, succeeded: 2 },+ byLiveness: { fresh: 5 },+ highestSeverity: "danger",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [+ { id: "a", providerKey: "ci", objectType: "deployment", displayTitle: null, statusCategory: "failed", statusTone: "danger", liveness: "fresh", isTerminal: false },+ { id: "b", providerKey: "ci", objectType: "deployment", displayTitle: null, statusCategory: "failed", statusTone: "danger", liveness: "fresh", isTerminal: false },+ { id: "c", providerKey: "ci", objectType: "deployment", displayTitle: null, statusCategory: "failed", statusTone: "danger", liveness: "fresh", isTerminal: false },+ { id: "d", providerKey: "github", objectType: "pull_request", displayTitle: null, statusCategory: "succeeded", statusTone: "success", liveness: "fresh", isTerminal: true },+ { id: "e", providerKey: "github", objectType: "pull_request", displayTitle: null, statusCategory: "succeeded", statusTone: "success", liveness: "fresh", isTerminal: true },+ ],+ }}+ />,+ );+ expect(html).toContain('data-external-status="failed"');+ expect(html).toContain('data-external-tone="danger"');+ expect(html).toContain(">3<");+ expect(html).toContain("aria-label=\"External objects: 3 failed, 2 succeeded, 5 total\"");+ });+});diff --git a/ui/src/components/ExternalObjectPill.tsx b/ui/src/components/ExternalObjectPill.tsxnew file mode 100644index 0000000000..99617be12c--- /dev/null+++ b/ui/src/components/ExternalObjectPill.tsx@@ -0,0 +1,198 @@+import type { ReactNode } from "react";+import type {+ ExternalObjectLivenessState,+ ExternalObjectStatusCategory,+} from "@paperclipai/shared";+import { ExternalObjectStatusIcon } from "./ExternalObjectStatusIcon";+import {+ externalObjectStatusIcon,+ externalObjectStatusIconDefault,+ externalObjectLivenessOverlay,+} from "../lib/status-colors";+import {+ externalObjectCategoryLabel,+ externalObjectLivenessLabel,+ externalObjectIconForKey,+ externalObjectProviderLabel,+ externalObjectTypeLabel,+} from "../lib/external-objects";+import { cn } from "../lib/utils";++export interface ExternalObjectPillData {+ providerKey: string | null;+ objectType: string | null;+ displayKey?: string | null;+ iconKey?: string | null;+ statusCategory: ExternalObjectStatusCategory;+ liveness: ExternalObjectLivenessState;+ displayTitle?: string | null;+ statusLabel?: string | null;+ statusIconKey?: string | null;+ url?: string | null;+}++function githubObjectLabel(url: string | null | undefined): string | null {+ if (!url) return null;+ try {+ const parsed = new URL(url);+ if (parsed.hostname !== "github.com") return null;+ const [, owner, repo, kind, number] = parsed.pathname.split("/");+ if (!owner || !repo || !number) return null;+ if (kind === "pull") return `PR ${number}`;+ if (kind === "issues") return `Issue ${number}`;+ return null;+ } catch {+ return null;+ }+}++function externalObjectValueLabel(+ object: ExternalObjectPillData,+ fallback: string,+ statusLabel: string,+): string {+ const githubLabel = object.providerKey === "github" ? githubObjectLabel(object.url) : null;+ const base = githubLabel ?? object.displayTitle?.trim() ?? fallback;+ return statusLabel ? `${base} - ${statusLabel}` : base;+}++function isMergedExternalObject(object: ExternalObjectPillData, statusLabel: string): boolean {+ return object.statusIconKey === "git-merge" || statusLabel.toLowerCase() === "merged";+}++function externalObjectPillTone(object: ExternalObjectPillData, statusLabel: string): string {+ if (isMergedExternalObject(object, statusLabel)) {+ return "text-violet-600 border-violet-600 dark:text-violet-400 dark:border-violet-400";+ }+ return externalObjectStatusIcon[object.statusCategory] ?? externalObjectStatusIconDefault;+}++function externalObjectStatusIconKey(+ object: ExternalObjectPillData,+ statusLabel: string,+): string | null | undefined {+ if (isMergedExternalObject(object, statusLabel)) return object.statusIconKey ?? "git-merge";+ return object.statusIconKey;+}++interface ExternalObjectPillProps {+ object: ExternalObjectPillData;+ /** Optional external mention count (renders as `×N` superscript when > 1). */+ sourceCount?: number;+ /** Optional source-mention summary used as the pill's `title` attribute. */+ sourceSummary?: string | null;+ className?: string;+ /** Optional rendered label override. Defaults to `provider object-type`. */+ children?: ReactNode;+ /**+ * If true the pill renders without a hover treatment (used inside+ * non-interactive contexts like the property panel). Defaults to false.+ */+ inert?: boolean;+ /**+ * Hide the provider icon when the surrounding UI already names the provider.+ * The status icon still renders as the single state glyph inside the pill.+ */+ showProviderIcon?: boolean;+}++/**+ * External-object equivalent of `IssueReferencePill`. Same `paperclip-mention-chip`+ * base so external references feel native to readers (Jakob's Law).+ */+export function ExternalObjectPill({+ object,+ sourceCount,+ sourceSummary,+ className,+ children,+ inert,+ showProviderIcon = true,+}: ExternalObjectPillProps) {+ const overlay = externalObjectLivenessOverlay[object.liveness] ?? "";+ const providerLabel = externalObjectProviderLabel(object.providerKey);+ const typeLabel = externalObjectTypeLabel(object.objectType);+ const displayKey = object.displayKey?.trim() || `${providerLabel} ${typeLabel}`;+ const statusLabel = object.statusLabel ?? externalObjectCategoryLabel(object.statusCategory);+ const tone = externalObjectPillTone(object, statusLabel);+ const valueLabel = externalObjectValueLabel(object, displayKey, statusLabel);+ const statusIconKey = externalObjectStatusIconKey(object, statusLabel);+ const livenessLabel = externalObjectLivenessLabel(object.liveness);+ const ProviderIcon = externalObjectIconForKey(object.iconKey);+ const ariaLabel = `${providerLabel} ${typeLabel} — ${statusLabel}${+ object.liveness === "fresh" || object.liveness === "unknown" ? "" : ` (${livenessLabel})`+ }${object.displayTitle ? `: ${object.displayTitle}` : ""}`;++ const interactive = !inert && Boolean(object.url);+ const classNames = cn(+ "paperclip-mention-chip paperclip-mention-chip--external-object",+ "inline-flex max-w-full items-center gap-1 rounded-full border border-border px-2 py-0.5 text-xs no-underline",+ // Tone is applied as text classes only — the border style comes from the+ // overlay (dashed for stale/auth/unreachable).+ tone.split(" ").filter((c) => c.startsWith("text-")).join(" "),+ overlay,+ interactive+ && "hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring",+ className,+ );+ const titleAttr = sourceSummary+ ? `${object.displayTitle ?? displayKey} — ${sourceSummary}`+ : object.displayTitle ?? displayKey;+ const labelText = children ?? (+ <>+ <ExternalObjectStatusIcon+ category={object.statusCategory}+ liveness={object.liveness}+ statusIconKey={statusIconKey}+ sizeClassName="h-3 w-3"+ label={`${providerLabel}: ${statusLabel}`}+ />+ <span className="max-w-[16rem] truncate font-medium">{valueLabel}</span>+ </>+ );+ const countSuffix = typeof sourceCount === "number" && sourceCount > 1 ? (+ <span className="tabular-nums text-[10px] font-medium opacity-80">×{sourceCount}</span>+ ) : null;+ const innerContent = (+ <>+ {showProviderIcon && ProviderIcon ? (+ <ProviderIcon aria-hidden="true" className="h-3 w-3 shrink-0" />+ ) : null}+ <span className="inline-flex min-w-0 items-center gap-1">+ {labelText}+ </span>+ {countSuffix}+ </>+ );++ if (interactive && object.url) {+ return (+ <a+ href={object.url}+ target="_blank"+ rel="noopener noreferrer"+ data-mention-kind="external-object"+ data-external-status={object.statusCategory}+ data-external-liveness={object.liveness}+ className={classNames}+ title={titleAttr}+ aria-label={ariaLabel}+ >+ {innerContent}+ </a>+ );+ }++ return (+ <span+ data-mention-kind="external-object"+ data-external-status={object.statusCategory}+ data-external-liveness={object.liveness}+ className={classNames}+ title={titleAttr}+ aria-label={ariaLabel}+ >+ {innerContent}+ </span>+ );+}diff --git a/ui/src/components/ExternalObjectStatusIcon.tsx b/ui/src/components/ExternalObjectStatusIcon.tsxnew file mode 100644index 0000000000..a6a42de052--- /dev/null+++ b/ui/src/components/ExternalObjectStatusIcon.tsx@@ -0,0 +1,94 @@+import type {+ ExternalObjectLivenessState,+ ExternalObjectStatusCategory,+} from "@paperclipai/shared";+import { Clock } from "lucide-react";+import {+ externalObjectStatusIcon,+ externalObjectStatusIconDefault,+} from "../lib/status-colors";+import {+ externalObjectCategoryLabel,+ externalObjectIconForCategory,+ externalObjectIconForKey,+ externalObjectLivenessLabel,+} from "../lib/external-objects";+import { usePrefersReducedMotion } from "../hooks/usePrefersReducedMotion";+import { cn } from "../lib/utils";++interface ExternalObjectStatusIconProps {+ category: ExternalObjectStatusCategory;+ liveness: ExternalObjectLivenessState;+ statusIconKey?: string | null;+ /** Optional override label used in `aria-label` (e.g. provider-specific copy). */+ label?: string | null;+ className?: string;+ /** Tailwind size class — defaults to `h-3.5 w-3.5` (compact pill use). */+ sizeClassName?: string;+ /**+ * When true the icon renders inline at 12 px with the `mr-1`/`align`+ * adjustments used by `MarkdownIssueLink`. Used by the markdown decorator.+ */+ inline?: boolean;+}++/**+ * Pure presentational icon for an external object's status. Combines:+ *+ * - A category icon (lucide) from `externalObjectIconForCategory`.+ * - Tone classes (text + border) from `externalObjectStatusIcon`.+ * - An overlaid clock micro-mark when liveness is `stale`.+ * - Reduced-motion-aware spinner for the `running` category.+ *+ * Never mounts plugin React; the host is the sole renderer of identity glyphs.+ */+export function ExternalObjectStatusIcon({+ category,+ liveness,+ statusIconKey,+ label,+ className,+ sizeClassName = "h-3.5 w-3.5",+ inline = false,+}: ExternalObjectStatusIconProps) {+ const reducedMotion = usePrefersReducedMotion();+ const Icon = externalObjectIconForKey(statusIconKey) ?? externalObjectIconForCategory(category);+ const tone = statusIconKey === "git-merge"+ ? "text-violet-600 border-violet-600 dark:text-violet-400 dark:border-violet-400"+ : externalObjectStatusIcon[category] ?? externalObjectStatusIconDefault;+ const livenessSuffix = liveness === "fresh" || liveness === "unknown"+ ? ""+ : ` (${externalObjectLivenessLabel(liveness)})`;+ const ariaLabel = `${label ?? externalObjectCategoryLabel(category)}${livenessSuffix}`;++ // The clock overlay needs a positioned wrapper. Inline mode keeps the icon+ // tight to the surrounding text; pill mode expects to size by sizeClassName.+ const wrapperBase = inline+ ? "relative mr-1 inline-flex shrink-0 align-[-0.125em]"+ : "relative inline-flex shrink-0";+ const iconSize = inline ? "h-3 w-3" : sizeClassName;+ const isSpinner = category === "running";+ const animateClass = isSpinner && !reducedMotion ? "animate-spin" : "";++ return (+ <span+ role="img"+ aria-label={ariaLabel}+ className={cn(wrapperBase, className)}+ >+ <Icon+ aria-hidden="true"+ className={cn(iconSize, tone.split(" ").filter((c) => c.startsWith("text-")).join(" "), animateClass)}+ />+ {liveness === "stale" ? (+ <Clock+ aria-hidden="true"+ className={cn(+ "absolute -bottom-0.5 -right-0.5 h-2 w-2 rounded-full bg-background text-muted-foreground",+ inline ? "" : "p-px",+ )}+ />+ ) : null}+ </span>+ );+}diff --git a/ui/src/components/ExternalObjectStatusSummary.tsx b/ui/src/components/ExternalObjectStatusSummary.tsxnew file mode 100644index 0000000000..b3400fa052--- /dev/null+++ b/ui/src/components/ExternalObjectStatusSummary.tsx@@ -0,0 +1,83 @@+import type { ExternalObjectSummary } from "@paperclipai/shared";+import {+ dominantExternalObjectTone,+ externalObjectCategoryLabel,+ externalObjectDominantCount,+ externalObjectIconForCategory,+ externalObjectIconForKey,+} from "../lib/external-objects";+import { externalObjectStatusBadge, externalObjectStatusBadgeDefault } from "../lib/status-colors";+import { usePrefersReducedMotion } from "../hooks/usePrefersReducedMotion";+import { cn } from "../lib/utils";++interface ExternalObjectStatusSummaryProps {+ summary: ExternalObjectSummary | null | undefined;+ /** Compact mode trims everything down to the icon + count, no label text. */+ compact?: boolean;+ className?: string;+}++function dominantCategory(summary: ExternalObjectSummary): string {+ // Prefer the first object that matches the highestSeverity tone, since the+ // server has already ranked them server-side.+ const match = summary.objects.find((object) => object.statusTone === summary.highestSeverity);+ return match?.statusCategory ?? "unknown";+}++function dominantObject(summary: ExternalObjectSummary) {+ return summary.objects.find((object) => object.statusTone === summary.highestSeverity) ?? null;+}++function buildBreakdownTitle(summary: ExternalObjectSummary): string {+ const parts: string[] = [];+ for (const [category, count] of Object.entries(summary.byStatusCategory)) {+ if (!count) continue;+ parts.push(`${count} ${externalObjectCategoryLabel(category).toLowerCase()}`);+ }+ if (summary.staleCount > 0) parts.push(`${summary.staleCount} stale`);+ parts.push(`${summary.total} total`);+ return `External objects: ${parts.join(", ")}`;+}++/**+ * Compact rollup marker used by sidebar projects and issue list rows. Renders+ * the dominant severity icon plus a count badge. Hidden when there are zero+ * external objects or every object is in a muted tone.+ */+export function ExternalObjectStatusSummary({+ summary,+ compact,+ className,+}: ExternalObjectStatusSummaryProps) {+ const reducedMotion = usePrefersReducedMotion();+ const tone = dominantExternalObjectTone(summary);+ const total = summary?.total ?? 0;+ if (!summary || total === 0 || !tone) return null;++ const object = dominantObject(summary);+ const category = object?.statusCategory ?? dominantCategory(summary);+ const Icon = externalObjectIconForKey(object?.statusIconKey) ?? externalObjectIconForCategory(category);+ const badgeClass = externalObjectStatusBadge[category] ?? externalObjectStatusBadgeDefault;+ const dominantCount = externalObjectDominantCount(summary);+ const title = buildBreakdownTitle(summary);+ const animateClass = category === "running" && !reducedMotion ? "animate-spin" : "";++ return (+ <span+ role="img"+ aria-label={title}+ title={title}+ className={cn(+ "inline-flex items-center gap-1 rounded-full px-1.5 py-0.5 text-[10px] font-medium tabular-nums leading-none",+ badgeClass,+ compact && "px-1 py-0.5",+ className,+ )}+ data-external-status={category}+ data-external-tone={tone}+ >+ <Icon aria-hidden="true" className={cn("h-3 w-3 shrink-0", animateClass)} />+ <span>{dominantCount > 0 ? dominantCount : total}</span>+ </span>+ );+}diff --git a/ui/src/components/InlineEditor.tsx b/ui/src/components/InlineEditor.tsxindex 192e8260d8..094566243a 100644--- a/ui/src/components/InlineEditor.tsx+++ b/ui/src/components/InlineEditor.tsx@@ -1,6 +1,6 @@import { useState, useRef, useEffect, useCallback } from "react";import { cn } from "../lib/utils";-import { MarkdownBody } from "./MarkdownBody";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";import { MarkdownEditor, type MarkdownEditorRef, type MentionOption } from "./MarkdownEditor";import { useAutosaveIndicator } from "../hooks/useAutosaveIndicator";import { FoldCurtain } from "./FoldCurtain";@@ -19,6 +19,11 @@ interface InlineEditorProps {nullable?: boolean;/** When true, long display-mode markdown is clipped with a fade curtain that expands on click. */foldable?: boolean;+ /**+ * Optional host-resolved external object metadata. Forwarded to the read-mode+ * `MarkdownBody` so resolved URLs render with the inline status icon prefix.+ */+ externalReferences?: MarkdownExternalReferenceMap;}/** Shared padding so display and edit modes occupy the exact same box. */@@ -55,6 +60,7 @@ export function InlineEditor({onDropFile,mentions,foldable = false,+ externalReferences,}: InlineEditorProps) {const [editing, setEditing] = useState(false);const [multilineEditing, setMultilineEditing] = useState(false);@@ -288,12 +294,18 @@ export function InlineEditor({>{foldable ? (<FoldCurtain>- <MarkdownBody className={cn("paperclip-edit-in-place-content", className)}>+ <MarkdownBody+ className={cn("paperclip-edit-in-place-content", className)}+ externalReferences={externalReferences}+ >{previewValue}</MarkdownBody></FoldCurtain>) : (- <MarkdownBody className={cn("paperclip-edit-in-place-content", className)}>+ <MarkdownBody+ className={cn("paperclip-edit-in-place-content", className)}+ externalReferences={externalReferences}+ >{previewValue}</MarkdownBody>)}diff --git a/ui/src/components/IssueChatThread.tsx b/ui/src/components/IssueChatThread.tsxindex aa215ac4fc..48b4d92244 100644--- a/ui/src/components/IssueChatThread.tsx+++ b/ui/src/components/IssueChatThread.tsx@@ -101,7 +101,7 @@ import {DropdownMenuItem,DropdownMenuTrigger,} from "@/components/ui/dropdown-menu";-import { MarkdownBody } from "./MarkdownBody";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";import { WorkspaceFileMarkdownBody } from "./WorkspaceFileMarkdownBody";import { MarkdownEditor, type MentionOption, type MarkdownEditorRef } from "./MarkdownEditor";import { Identity } from "./Identity";@@ -217,6 +217,7 @@ interface IssueChatMessageContext {onUploadImage?: (file: File) => Promise<string>;issueStatus?: string;successfulRunHandoff?: SuccessfulRunHandoffState | null;+ externalReferences?: MarkdownExternalReferenceMap;}const IssueChatCtx = createContext<IssueChatMessageContext>({@@ -450,6 +451,7 @@ interface IssueChatThreadProps {* comment is in the loaded set before we scroll to it.*/onRefreshLatestComments?: () => Promise<unknown> | void;+ externalReferences?: MarkdownExternalReferenceMap;}type IssueChatErrorBoundaryProps = {@@ -457,6 +459,7 @@ type IssueChatErrorBoundaryProps = {messages: readonly ThreadMessage[];emptyMessage: string;variant: "full" | "embedded";+ externalReferences?: MarkdownExternalReferenceMap;children: ReactNode;};@@ -491,6 +494,7 @@ class IssueChatErrorBoundary extends Component<IssueChatErrorBoundaryProps, Issumessages={this.props.messages}emptyMessage={this.props.emptyMessage}variant={this.props.variant}+ externalReferences={this.props.externalReferences}/>);}@@ -555,10 +559,12 @@ function IssueChatFallbackThread({messages,emptyMessage,variant,+ externalReferences,}: {messages: readonly ThreadMessage[];emptyMessage: string;variant: "full" | "embedded";+ externalReferences?: MarkdownExternalReferenceMap;}) {return (<div className={cn(variant === "embedded" ? "space-y-3" : "space-y-4")}>@@ -599,7 +605,9 @@ function IssueChatFallbackThread({</div><div className="space-y-2">{lines.length > 0 ? lines.map((line, index) => (- <MarkdownBody key={`${message.id}:fallback:${index}`}>{line}</MarkdownBody>+ <MarkdownBody key={`${message.id}:fallback:${index}`} externalReferences={externalReferences}>+ {line}+ </MarkdownBody>)) : (<p className="text-sm text-muted-foreground">No message content.</p>)}@@ -705,7 +713,7 @@ function commentDateLabel(date: Date | string | undefined): string {}const IssueChatTextPart = memo(function IssueChatTextPart({ text, recessed, onAccent }: { text: string; recessed?: boolean; onAccent?: boolean }) {- const { onImageClick } = useContext(IssueChatCtx);+ const { onImageClick, externalReferences } = useContext(IssueChatCtx);if (isSuccessfulRunHandoffComment(text)) {return <SuccessfulRunHandoffCommentCallout text={text} recessed={recessed} onImageClick={onImageClick} />;}@@ -717,6 +725,7 @@ const IssueChatTextPart = memo(function IssueChatTextPart({ text, recessed, onAcstyle={recessed ? { opacity: 0.55 } : undefined}softBreaksonImageClick={onImageClick}+ externalReferences={externalReferences}>{text}</WorkspaceFileMarkdownBody>@@ -2113,6 +2122,7 @@ function ExpiredRequestConfirmationActivity({onRejectInteraction,onCancelInteraction,onUploadImage,+ externalReferences,} = useContext(IssueChatCtx);const [expanded, setExpanded] = useState(false);const hasResolvedActor = Boolean(interaction.resolvedByAgentId || interaction.resolvedByUserId);@@ -2193,6 +2203,7 @@ function ExpiredRequestConfirmationActivity({onRejectInteraction={onRejectInteraction}onCancelInteraction={onCancelInteraction}onUploadImage={onUploadImage}+ externalReferences={externalReferences}/></div>) : null}@@ -2620,6 +2631,7 @@ function IssueChatSystemMessage({ message }: { message: ThreadMessage }) {onSubmitInteractionAnswers,onCancelInteraction,onUploadImage,+ externalReferences,} = useContext(IssueChatCtx);const custom = message.metadata.custom as Record<string, unknown>;const anchorId = typeof custom.anchorId === "string" ? custom.anchorId : undefined;@@ -2677,6 +2689,7 @@ function IssueChatSystemMessage({ message }: { message: ThreadMessage }) {onSubmitInteractionAnswers={onSubmitInteractionAnswers}onCancelInteraction={onCancelInteraction}onUploadImage={onUploadImage}+ externalReferences={externalReferences}/></div></div>@@ -4094,6 +4107,7 @@ export function IssueChatThread({assigneeUserId = null,onResumeFromBacklog,resumeFromBacklogPending = false,+ externalReferences,}: IssueChatThreadProps) {const location = useLocation();const lastScrolledHashRef = useRef<string | null>(null);@@ -4618,6 +4632,7 @@ export function IssueChatThread({onUploadImage: stableOnUploadImage,issueStatus,successfulRunHandoff,+ externalReferences,}),[feedbackDataSharingPreference,@@ -4643,6 +4658,7 @@ export function IssueChatThread({stableOnUploadImage,issueStatus,successfulRunHandoff,+ externalReferences,],);@@ -4680,6 +4696,7 @@ export function IssueChatThread({messages={messages}emptyMessage={resolvedEmptyMessage}variant={variant}+ externalReferences={externalReferences}><div data-testid="thread-root"><divdiff --git a/ui/src/components/IssueContinuationHandoff.tsx b/ui/src/components/IssueContinuationHandoff.tsxindex a1830a78c1..4d4c4b6cbc 100644--- a/ui/src/components/IssueContinuationHandoff.tsx+++ b/ui/src/components/IssueContinuationHandoff.tsx@@ -3,17 +3,19 @@ import type { IssueDocument } from "@paperclipai/shared";import { ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY } from "@paperclipai/shared";import { Button } from "@/components/ui/button";import { cn, relativeTime } from "../lib/utils";-import { MarkdownBody } from "./MarkdownBody";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";import { Check, ChevronDown, ChevronRight, Copy, History } from "lucide-react";type IssueContinuationHandoffProps = {document: IssueDocument | null | undefined;focusSignal?: number;+ externalReferences?: MarkdownExternalReferenceMap;};export function IssueContinuationHandoff({document,focusSignal = 0,+ externalReferences,}: IssueContinuationHandoffProps) {const [expanded, setExpanded] = useState(false);const [copied, setCopied] = useState(false);@@ -91,7 +93,11 @@ export function IssueContinuationHandoff({</div>{expanded ? (<div className="mt-3 rounded-md border border-border bg-background/80 p-3">- <MarkdownBody className="paperclip-edit-in-place-content text-sm leading-6" softBreaks={false}>+ <MarkdownBody+ className="paperclip-edit-in-place-content text-sm leading-6"+ softBreaks={false}+ externalReferences={externalReferences}+ >{document.body}</MarkdownBody></div>diff --git a/ui/src/components/IssueDocumentsSection.test.tsx b/ui/src/components/IssueDocumentsSection.test.tsxindex 0ce5cb6627..4884beea5d 100644--- a/ui/src/components/IssueDocumentsSection.test.tsx+++ b/ui/src/components/IssueDocumentsSection.test.tsx@@ -43,8 +43,22 @@ vi.mock("@/lib/router", () => ({}));vi.mock("./MarkdownBody", () => ({- MarkdownBody: ({ children, className }: { children: string; className?: string }) => (- <div className={className}>{children}</div>+ MarkdownBody: ({+ children,+ className,+ externalReferences,+ }: {+ children: string;+ className?: string;+ externalReferences?: Record<string, unknown>;+ }) => (+ <div+ className={className}+ data-testid="markdown-body"+ data-external-reference-keys={externalReferences ? Object.keys(externalReferences).join(",") : ""}+ >+ {children}+ </div>),}));@@ -684,6 +698,61 @@ describe("IssueDocumentsSection", () => {queryClient.clear();});+ it("forwards externalReferences to the rendered document body so URL decoration applies", async () => {+ const issue = createIssue();+ const root = createRoot(container);+ const queryClient = new QueryClient({+ defaultOptions: {+ queries: { retry: false },+ mutations: { retry: false },+ },+ });++ mockIssuesApi.listDocuments.mockResolvedValue([+ createIssueDocument({+ body: "Linked work: https://github.com/example/repo/pull/99",+ }),+ ]);++ await act(async () => {+ root.render(+ <QueryClientProvider client={queryClient}>+ <IssueDocumentsSection+ issue={issue}+ canDeleteDocuments={false}+ externalReferences={{+ "https://github.com/example/repo/pull/99": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "open",+ liveness: "fresh",+ statusLabel: "Open",+ displayTitle: "PR #99",+ },+ }}+ />+ </QueryClientProvider>,+ );+ });+ await flush();+ await flush();++ const markdownBodies = Array.from(+ container.querySelectorAll('[data-testid="markdown-body"]'),+ ) as HTMLElement[];+ expect(markdownBodies.length).toBeGreaterThan(0);+ const rendered = markdownBodies.find((element) =>+ (element.textContent ?? "").includes("Linked work"),+ );+ expect(rendered?.getAttribute("data-external-reference-keys"))+ .toContain("https://github.com/example/repo/pull/99");++ await act(async () => {+ root.unmount();+ });+ queryClient.clear();+ });+it("wraps the documents header actions so mobile layouts do not overflow", async () => {const issue = createIssue();const root = createRoot(container);diff --git a/ui/src/components/IssueDocumentsSection.tsx b/ui/src/components/IssueDocumentsSection.tsxindex 4b329cfeab..ffa59eb3fc 100644--- a/ui/src/components/IssueDocumentsSection.tsx+++ b/ui/src/components/IssueDocumentsSection.tsx@@ -20,7 +20,7 @@ import { queryKeys } from "../lib/queryKeys";import { cn, relativeTime } from "../lib/utils";import { FoldCurtain } from "./FoldCurtain";import { DocumentAnnotationsCountChip, IssueDocumentAnnotations } from "./IssueDocumentAnnotations";-import { MarkdownBody } from "./MarkdownBody";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";import { MarkdownEditor, type MentionOption } from "./MarkdownEditor";import { OutputFeedbackButtons } from "./OutputFeedbackButtons";import { Button } from "@/components/ui/button";@@ -75,10 +75,16 @@ function saveFoldedDocumentKeys(issueId: string, keys: string[]) {window.localStorage.setItem(getFoldedDocumentsStorageKey(issueId), JSON.stringify(keys));}-function renderFoldableBody(body: string, className?: string) {+function renderFoldableBody(+ body: string,+ className?: string,+ externalReferences?: MarkdownExternalReferenceMap,+) {return (<FoldCurtain>- <MarkdownBody className={className} softBreaks={false}>{body}</MarkdownBody>+ <MarkdownBody className={className} softBreaks={false} externalReferences={externalReferences}>+ {body}+ </MarkdownBody></FoldCurtain>);}@@ -161,6 +167,7 @@ export function IssueDocumentsSection({defaultAnnotationPanelOpenKeys,defaultAnnotationFocusedThreadIds,forceEditDocumentKey,+ externalReferences,}: {issue: Issue;canDeleteDocuments: boolean;@@ -187,6 +194,7 @@ export function IssueDocumentsSection({defaultAnnotationFocusedThreadIds?: Readonly<Record<string, string>>;/** Force a doc into edit mode on mount (Storybook-only). */forceEditDocumentKey?: string | null;+ externalReferences?: MarkdownExternalReferenceMap;}) {const queryClient = useQueryClient();const location = useLocation();@@ -755,6 +763,7 @@ export function IssueDocumentsSection({}, [autosaveState, commitDraft, documentConflict, draft, markDocumentDirty, resetAutosaveState, sortedDocuments]);const documentBodyShellClassName = "mt-3";+ const documentBodyPaddingClassName = "";const documentBodyContentClassName = "paperclip-edit-in-place-content min-h-[220px] text-[15px] leading-7";const toggleFoldedDocument = (key: string) => {setFoldedDocumentKeys((current) =>@@ -878,7 +887,9 @@ export function IssueDocumentsSection({PLAN</span></div>- {renderFoldableBody(issue.legacyPlanDocument.body, documentBodyContentClassName)}+ <div className={documentBodyPaddingClassName}>+ {renderFoldableBody(issue.legacyPlanDocument.body, documentBodyContentClassName, externalReferences)}+ </div></div>) : null}@@ -1197,7 +1208,7 @@ export function IssueDocumentsSection({{!isPlanKey(doc.key) && activeConflict.serverDocument.title ? (<p className="mb-2 text-sm font-medium">{activeConflict.serverDocument.title}</p>) : null}- {renderFoldableBody(activeConflict.serverDocument.body, "text-[14px] leading-7")}+ {renderFoldableBody(activeConflict.serverDocument.body, "text-[14px] leading-7", externalReferences)}</div>)}</div>@@ -1235,7 +1246,7 @@ export function IssueDocumentsSection({defaultFocusedThreadId={defaultAnnotationFocusedThreadIds?.[doc.key]}>{isHistoricalPreview ? (- renderFoldableBody(displayedBody, documentBodyContentClassName)+ renderFoldableBody(displayedBody, documentBodyContentClassName, externalReferences)) : activeDraft ? (<MarkdownEditorvalue={displayedBody}@@ -1257,7 +1268,7 @@ export function IssueDocumentsSection({onSubmit={() => void commitDraft(activeDraft ?? draft, { clearAfterSave: false, trackAutosave: true })}/>) : (- renderFoldableBody(displayedBody, documentBodyContentClassName)+ renderFoldableBody(displayedBody, documentBodyContentClassName, externalReferences))}</IssueDocumentAnnotations></div>diff --git a/ui/src/components/IssueFiltersPopover.tsx b/ui/src/components/IssueFiltersPopover.tsxindex 19a844ad2c..40de541730 100644--- a/ui/src/components/IssueFiltersPopover.tsx+++ b/ui/src/components/IssueFiltersPopover.tsx@@ -9,6 +9,8 @@ import { PriorityIcon } from "./PriorityIcon";import { StatusIcon } from "./StatusIcon";import {defaultIssueFilterState,+ externalObjectFilterLabel,+ externalObjectFilterOrder,issueFilterArraysEqual,issueFilterLabel,issuePriorityOrder,@@ -17,6 +19,8 @@ import {toggleIssueFilterValue,type IssueFilterState,} from "../lib/issue-filters";+import { externalObjectIconForCategory } from "../lib/external-objects";+import { externalObjectStatusIcon } from "../lib/status-colors";import { formatAssigneeUserLabel } from "../lib/assignees";type AgentOption = {@@ -55,6 +59,7 @@ export function IssueFiltersPopover({projects,labels,currentUserId,+ enableExternalObjectFilters = true,enableRoutineVisibilityFilter = false,buttonVariant = "ghost",iconOnly = false,@@ -68,6 +73,7 @@ export function IssueFiltersPopover({projects?: ProjectOption[];labels?: LabelOption[];currentUserId?: string | null;+ enableExternalObjectFilters?: boolean;enableRoutineVisibilityFilter?: boolean;buttonVariant?: "ghost" | "outline";iconOnly?: boolean;@@ -344,6 +350,39 @@ export function IssueFiltersPopover({</div>) : null}+ {enableExternalObjectFilters ? (+ <div className="space-y-1">+ <span className="text-xs text-muted-foreground">External object status</span>+ <div className="space-y-0.5">+ {externalObjectFilterOrder.map((value) => {+ const iconCategory = value === "failed" ? "failed"+ : value === "waiting" ? "waiting"+ : value === "running" ? "running"+ : value === "auth_required" ? "auth_required"+ : value === "unreachable" ? "unreachable"+ : value === "stale" ? "unknown"+ : "closed";+ const Icon = externalObjectIconForCategory(iconCategory);+ const tone = externalObjectStatusIcon[iconCategory] ?? "";+ const textTone = tone.split(" ").filter((c) => c.startsWith("text-")).join(" ");+ return (+ <label+ key={value}+ className="flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1 hover:bg-accent/50"+ >+ <Checkbox+ checked={state.externalObjectStatuses.includes(value)}+ onCheckedChange={() => onChange({ externalObjectStatuses: toggleIssueFilterValue(state.externalObjectStatuses, value) })}+ />+ <Icon className={`h-3.5 w-3.5 shrink-0 ${textTone}`} aria-hidden="true" />+ <span className="text-sm">{externalObjectFilterLabel(value)}</span>+ </label>+ );+ })}+ </div>+ </div>+ ) : null}+<div className="space-y-1"><span className="text-xs text-muted-foreground">Visibility</span><label className="flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1 hover:bg-accent/50">diff --git a/ui/src/components/IssueProperties.test.tsx b/ui/src/components/IssueProperties.test.tsxindex 4545c41a51..d11059a7a2 100644--- a/ui/src/components/IssueProperties.test.tsx+++ b/ui/src/components/IssueProperties.test.tsx@@ -1797,4 +1797,81 @@ describe("IssueProperties", () => {act(() => root.unmount());});++ it("renders each external object as its own properties row using display metadata", async () => {+ const root = renderProperties(container, {+ issue: createIssue(),+ childIssues: [],+ onUpdate: vi.fn(),+ inline: true,+ externalObjects: [+ {+ mentionCount: 1,+ sourceLabels: ["Description"],+ pill: {+ providerKey: "github",+ objectType: "pull_request",+ displayKey: null,+ iconKey: "github",+ statusCategory: "succeeded",+ statusIconKey: null,+ statusLabel: "Merged",+ liveness: "fresh",+ displayTitle: "acme/web#241: Add rich object presentation metadata",+ url: "https://github.com/acme/web/pull/241",+ },+ group: {+ object: null,+ mentions: [],+ mentionCount: 1,+ sourceLabels: ["Description"],+ },+ },+ {+ mentionCount: 1,+ sourceLabels: ["Comment"],+ pill: {+ providerKey: "github",+ objectType: "issue",+ displayKey: "Github Issue",+ iconKey: "github",+ statusCategory: "open",+ statusIconKey: "circle-dot",+ statusLabel: "Open",+ liveness: "fresh",+ displayTitle: "acme/web#12: Follow-up",+ url: "https://github.com/acme/web/issues/12",+ },+ group: {+ object: null,+ mentions: [],+ mentionCount: 1,+ sourceLabels: ["Comment"],+ },+ },+ ],+ });+ await flush();++ expect(container.textContent).toContain("Github Pull Request");+ expect(container.textContent).toContain("Github Issue");+ expect(container.textContent).toContain("PR 241 - Merged");+ expect(container.textContent).toContain("Merged");+ expect(container.textContent).toContain("Open");+ expect(container.textContent).not.toContain("External objects");+ const label = Array.from(container.querySelectorAll("span"))+ .find((span) => span.textContent === "Github Pull Request");+ expect(label?.querySelector("svg")).toBeTruthy();+ const pullRequestLink = Array.from(container.querySelectorAll("a"))+ .find((anchor) => anchor.getAttribute("href") === "https://github.com/acme/web/pull/241");+ expect(pullRequestLink?.textContent).toContain("PR 241 - Merged");+ expect(pullRequestLink?.textContent).not.toContain("acme/web#241");+ expect(pullRequestLink?.textContent).not.toContain("Github Pull Request");+ expect(pullRequestLink?.querySelectorAll("svg")).toHaveLength(1);+ expect(pullRequestLink?.className).not.toContain("paperclip-mention-chip");+ expect(pullRequestLink?.className).not.toContain("rounded-full");+ expect(pullRequestLink?.className).not.toContain("border");++ act(() => root.unmount());+ });});diff --git a/ui/src/components/IssueProperties.tsx b/ui/src/components/IssueProperties.tsxindex dadb31e7e8..b39ac0884f 100644--- a/ui/src/components/IssueProperties.tsx+++ b/ui/src/components/IssueProperties.tsx@@ -35,6 +35,19 @@ import { PriorityIcon } from "./PriorityIcon";import { Identity } from "./Identity";import { IssueReferencePill } from "./IssueReferencePill";import { formatDate, formatDateTime, cn, projectUrl } from "../lib/utils";+import { ExternalObjectStatusIcon } from "./ExternalObjectStatusIcon";+import type { IssueExternalObjectGroup } from "../hooks/useIssueExternalObjects";+import {+ externalObjectCategoryLabel,+ externalObjectIconForKey,+ externalObjectProviderLabel,+ externalObjectToneSeverity,+ externalObjectTypeLabel,+} from "../lib/external-objects";+import {+ externalObjectStatusIcon,+ externalObjectStatusIconDefault,+} from "../lib/status-colors";import { timeAgo } from "../lib/timeAgo";import { Button } from "@/components/ui/button";import { ToggleSwitch } from "@/components/ui/toggle-switch";@@ -153,20 +166,173 @@ interface IssuePropertiesProps {/** Whether an agent run is currently in flight on this issue, so the assignee* picker can warn that reassigning will interrupt it. */hasActiveRun?: boolean;+ externalObjects?: IssueExternalObjectGroup[];+ externalObjectsLoading?: boolean;+ externalObjectsError?: boolean;+ onRetryExternalObjects?: () => void;}const ISSUE_BLOCKER_SEARCH_LIMIT = 50;const ISSUE_PROPERTY_RELATION_PREVIEW_COUNT = 5;-function PropertyRow({ label, children }: { label: string; children: React.ReactNode }) {+function PropertyRow({+ label,+ children,+ labelClassName,+}: {+ label: React.ReactNode;+ children: React.ReactNode;+ labelClassName?: string;+}) {return (<div className="flex items-start gap-3 py-1.5">- <span className="text-xs text-muted-foreground shrink-0 w-20 mt-0.5">{label}</span>+ <span className={cn("text-xs text-muted-foreground shrink-0 w-20 mt-0.5", labelClassName)}>{label}</span><div className="flex items-center gap-1.5 min-w-0 flex-1 flex-wrap">{children}</div></div>);}+function sortExternalObjectGroups(groups: IssueExternalObjectGroup[]) {+ return [...groups].sort((a, b) => {+ const aTone = externalObjectToneSeverity(a.group.object?.statusTone);+ const bTone = externalObjectToneSeverity(b.group.object?.statusTone);+ return bTone - aTone;+ });+}++function externalObjectRowDisplayKey(group: IssueExternalObjectGroup): string {+ const { pill } = group;+ const displayKey = pill.displayKey?.trim();+ if (displayKey) return displayKey;+ if (pill.providerKey === "github") {+ if (pill.objectType === "pull_request") return "Github Pull Request";+ if (pill.objectType === "issue") return "Github Issue";+ }+ return `${externalObjectProviderLabel(pill.providerKey)} ${externalObjectTypeLabel(pill.objectType)}`;+}++function externalObjectRowLabel(group: IssueExternalObjectGroup): React.ReactNode {+ const { pill } = group;+ const displayKey = externalObjectRowDisplayKey(group);+ const Icon = externalObjectIconForKey(pill.iconKey);+ return (+ <span className="inline-flex min-w-0 items-start gap-1">+ {Icon ? <Icon aria-hidden="true" className="h-3 w-3 shrink-0 mt-0.5" /> : null}+ <span className="whitespace-normal break-words leading-tight">{displayKey}</span>+ </span>+ );+}++function githubObjectPropertyValue(url: string | null | undefined): string | null {+ if (!url) return null;+ try {+ const parsed = new URL(url);+ if (parsed.hostname !== "github.com") return null;+ const [, owner, repo, kind, number] = parsed.pathname.split("/");+ if (!owner || !repo || !number) return null;+ if (kind === "pull") return `PR ${number}`;+ if (kind === "issues") return `Issue ${number}`;+ return null;+ } catch {+ return null;+ }+}++function externalObjectPropertyStatusLabel(group: IssueExternalObjectGroup): string {+ return group.pill.statusLabel ?? externalObjectCategoryLabel(group.pill.statusCategory);+}++function externalObjectPropertyValue(group: IssueExternalObjectGroup): string {+ const { pill } = group;+ const statusLabel = externalObjectPropertyStatusLabel(group);+ const githubLabel = pill.providerKey === "github" ? githubObjectPropertyValue(pill.url) : null;+ const base = githubLabel ?? pill.displayTitle?.trim() ?? externalObjectRowDisplayKey(group);+ return statusLabel ? `${base} - ${statusLabel}` : base;+}++function isMergedExternalObject(group: IssueExternalObjectGroup): boolean {+ const statusLabel = externalObjectPropertyStatusLabel(group);+ return group.pill.statusIconKey === "git-merge" || statusLabel.toLowerCase() === "merged";+}++function externalObjectPropertyTone(group: IssueExternalObjectGroup): string {+ if (isMergedExternalObject(group)) {+ return "text-violet-600 dark:text-violet-400";+ }+ const tone = externalObjectStatusIcon[group.pill.statusCategory] ?? externalObjectStatusIconDefault;+ return tone.split(" ").filter((c) => c.startsWith("text-")).join(" ");+}++function externalObjectPropertyStatusIconKey(group: IssueExternalObjectGroup): string | null | undefined {+ if (isMergedExternalObject(group)) return group.pill.statusIconKey ?? "git-merge";+ return group.pill.statusIconKey;+}++function externalObjectPropertyTitle(group: IssueExternalObjectGroup): string {+ const { pill, sourceLabels } = group;+ const base = pill.displayTitle ?? externalObjectPropertyValue(group);+ return sourceLabels.length > 0 ? `${base} - ${sourceLabels.join(", ")}` : base;+}++function ExternalObjectPropertyValue({ group }: { group: IssueExternalObjectGroup }) {+ const { pill, mentionCount } = group;+ const statusLabel = externalObjectPropertyStatusLabel(group);+ const providerLabel = externalObjectProviderLabel(pill.providerKey);+ const typeLabel = externalObjectTypeLabel(pill.objectType);+ const value = externalObjectPropertyValue(group);+ const content = (+ <>+ <ExternalObjectStatusIcon+ category={pill.statusCategory}+ liveness={pill.liveness}+ statusIconKey={externalObjectPropertyStatusIconKey(group)}+ sizeClassName="h-3 w-3"+ label={`${providerLabel}: ${statusLabel}`}+ />+ <span className="min-w-0 truncate">{value}</span>+ {mentionCount > 1 ? (+ <span className="tabular-nums text-[10px] font-medium opacity-80">x{mentionCount}</span>+ ) : null}+ </>+ );+ const className = cn(+ "inline-flex min-w-0 max-w-full items-center gap-1 text-xs font-medium no-underline",+ externalObjectPropertyTone(group),+ pill.url ? "hover:underline focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring" : "",+ );++ if (pill.url) {+ return (+ <a+ href={pill.url}+ target="_blank"+ rel="noopener noreferrer"+ data-mention-kind="external-object"+ data-external-status={pill.statusCategory}+ data-external-liveness={pill.liveness}+ className={className}+ title={externalObjectPropertyTitle(group)}+ aria-label={`${providerLabel} ${typeLabel} - ${statusLabel}: ${pill.displayTitle ?? value}`}+ >+ {content}+ </a>+ );+ }++ return (+ <span+ data-mention-kind="external-object"+ data-external-status={pill.statusCategory}+ data-external-liveness={pill.liveness}+ className={className}+ title={externalObjectPropertyTitle(group)}+ aria-label={`${providerLabel} ${typeLabel} - ${statusLabel}: ${pill.displayTitle ?? value}`}+ >+ {content}+ </span>+ );+}+const ISSUE_THINKING_EFFORT_OPTIONS = {claude_local: [{ value: "", label: "Default" },@@ -414,6 +580,10 @@ export function IssueProperties({onUpdate,inline,hasActiveRun = false,+ externalObjects,+ externalObjectsLoading,+ externalObjectsError,+ onRetryExternalObjects,}: IssuePropertiesProps) {const { selectedCompanyId } = useCompany();const queryClient = useQueryClient();@@ -2168,6 +2338,46 @@ export function IssueProperties({{projectContent}</PropertyPicker>+ {externalObjectsError ? (+ <PropertyRow label="External objects">+ <span className="text-xs text-muted-foreground">+ Couldn't load external objects.+ {onRetryExternalObjects ? (+ <>+ {" "}+ <button+ type="button"+ className="text-primary underline-offset-2 hover:underline"+ onClick={onRetryExternalObjects}+ >+ Retry+ </button>+ </>+ ) : null}+ </span>+ </PropertyRow>+ ) : externalObjectsLoading ? (+ <PropertyRow label="External objects">+ <span className="h-4 w-24 animate-pulse rounded bg-muted/40" />+ </PropertyRow>+ ) : externalObjects && externalObjects.length > 0 ? (+ <>+ {sortExternalObjectGroups(externalObjects)+ .map((externalObject) => {+ const { pill, group } = externalObject;+ return (+ <PropertyRow+ key={group.object?.id ?? `${pill.providerKey}:${pill.objectType}:${pill.url ?? "anon"}`}+ label={externalObjectRowLabel(externalObject)}+ labelClassName="w-20 max-w-20 whitespace-normal leading-tight"+ >+ <ExternalObjectPropertyValue group={externalObject} />+ </PropertyRow>+ );+ })}+ </>+ ) : null}+<PropertyPickerinline={inline}label="Parent"diff --git a/ui/src/components/IssueRelatedWorkPanel.tsx b/ui/src/components/IssueRelatedWorkPanel.tsxindex b3072807f4..9d5fad9df7 100644--- a/ui/src/components/IssueRelatedWorkPanel.tsx+++ b/ui/src/components/IssueRelatedWorkPanel.tsx@@ -1,5 +1,8 @@import type { IssueRelatedWorkItem, IssueRelatedWorkSummary } from "@paperclipai/shared";import { IssueReferencePill } from "./IssueReferencePill";+import { ExternalObjectPill } from "./ExternalObjectPill";+import type { IssueExternalObjectGroup } from "../hooks/useIssueExternalObjects";+import { externalObjectToneSeverity } from "../lib/external-objects";type GroupedSource = {label: string;@@ -83,10 +86,103 @@ function Section({);}+function ExternalObjectsSection({+ groups,+ isLoading,+ isError,+ onRetry,+}: {+ groups: IssueExternalObjectGroup[];+ isLoading: boolean;+ isError: boolean;+ onRetry?: () => void;+}) {+ // Severity-first sort with most-recently-changed as the secondary sort.+ const sorted = [...groups].sort((a, b) => {+ const aTone = externalObjectToneSeverity(a.pill.statusCategory ? a.group.object?.statusTone ?? null : null);+ const bTone = externalObjectToneSeverity(b.pill.statusCategory ? b.group.object?.statusTone ?? null : null);+ if (aTone !== bTone) return bTone - aTone;+ const aChanged = a.group.object?.lastChangedAt ?? a.group.object?.lastResolvedAt ?? "";+ const bChanged = b.group.object?.lastChangedAt ?? b.group.object?.lastResolvedAt ?? "";+ return aChanged < bChanged ? 1 : aChanged > bChanged ? -1 : 0;+ });++ return (+ <section className="space-y-3 rounded-lg border border-border p-3">+ <div className="space-y-1">+ <h3 className="text-sm font-semibold">External objects</h3>+ <p className="text-xs text-muted-foreground">+ Remote work referenced from this issue — pull requests, deployments, tickets in other systems, and more.+ </p>+ </div>++ {isError ? (+ <p className="text-xs text-muted-foreground">+ Couldn't load external objects.{" "}+ {onRetry ? (+ <button+ type="button"+ onClick={onRetry}+ className="text-primary underline-offset-2 hover:underline"+ >+ Retry+ </button>+ ) : null}+ </p>+ ) : isLoading ? (+ <p className="text-xs text-muted-foreground">Loading external objects…</p>+ ) : sorted.length === 0 ? (+ <p className="text-xs text-muted-foreground">+ This issue does not reference any external objects yet.+ </p>+ ) : (+ <ul className="-mx-1 flex flex-col">+ {sorted.map(({ pill, mentionCount, sourceLabels, group }) => {+ const object = group.object;+ return (+ <li+ key={object?.id ?? `${pill.providerKey}:${pill.objectType}:${pill.url ?? "anon"}`}+ className="flex flex-wrap items-center gap-x-2 gap-y-1.5 rounded-md px-1 py-1.5 hover:bg-accent/40"+ >+ <ExternalObjectPill object={pill} sourceCount={mentionCount} sourceSummary={sourceLabels.join(", ")} />+ {pill.displayTitle ? (+ <span className="min-w-0 flex-1 truncate text-sm text-muted-foreground">+ {pill.displayTitle}+ </span>+ ) : null}+ <div className="flex flex-wrap items-center gap-1.5">+ {sourceLabels.map((label) => (+ <span+ key={`${object?.id ?? pill.url ?? label}:${label}`}+ className="inline-flex items-center gap-1 rounded-full border border-border bg-muted/40 px-2 py-0.5 text-xs text-muted-foreground"+ >+ <span>{label}</span>+ </span>+ ))}+ </div>+ </li>+ );+ })}+ </ul>+ )}+ </section>+ );+}+export function IssueRelatedWorkPanel({relatedWork,+ externalObjectsEnabled = true,+ externalObjects,+ externalObjectsLoading,+ externalObjectsError,+ onRetryExternalObjects,}: {relatedWork?: IssueRelatedWorkSummary | null;+ externalObjectsEnabled?: boolean;+ externalObjects?: IssueExternalObjectGroup[];+ externalObjectsLoading?: boolean;+ externalObjectsError?: boolean;+ onRetryExternalObjects?: () => void;}) {const outbound = relatedWork?.outbound ?? [];const inbound = relatedWork?.inbound ?? [];@@ -99,6 +195,14 @@ export function IssueRelatedWorkPanel({items={outbound}emptyLabel="This task does not reference any other tasks yet."/>+ {externalObjectsEnabled ? (+ <ExternalObjectsSection+ groups={externalObjects ?? []}+ isLoading={Boolean(externalObjectsLoading)}+ isError={Boolean(externalObjectsError)}+ onRetry={onRetryExternalObjects}+ />+ ) : null}<Sectiontitle="Referenced by"description="Other tasks that currently point at this task."diff --git a/ui/src/components/IssueRow.tsx b/ui/src/components/IssueRow.tsxindex e474770a1b..3a3aaf4b4d 100644--- a/ui/src/components/IssueRow.tsx+++ b/ui/src/components/IssueRow.tsx@@ -1,5 +1,5 @@import type { ReactNode } from "react";-import type { Issue, IssueRecoveryAction } from "@paperclipai/shared";+import type { ExternalObjectSummary, Issue, IssueRecoveryAction } from "@paperclipai/shared";import { Link } from "@/lib/router";import { Eye, Flag, X } from "lucide-react";import {@@ -16,6 +16,7 @@ import {import { StatusIcon } from "./StatusIcon";import { productivityReviewTriggerLabel } from "./ProductivityReviewBadge";import { hasAssignedBacklogBlocker } from "../lib/issue-blockers";+import { ExternalObjectStatusSummary } from "./ExternalObjectStatusSummary";type UnreadState = "hidden" | "visible" | "fading";@@ -28,6 +29,11 @@ interface IssueRowProps {desktopLeadingSpacer?: boolean;mobileMeta?: ReactNode;desktopTrailing?: ReactNode;+ /**+ * Optional pre-fetched external-object summary. Renders a compact severity+ * marker before the rest of `desktopTrailing` on desktop only.+ */+ externalObjectSummary?: ExternalObjectSummary | null;trailingMeta?: ReactNode;titleSuffix?: ReactNode;titleClassName?: string;@@ -51,6 +57,7 @@ export function IssueRow({desktopLeadingSpacer = false,mobileMeta,desktopTrailing,+ externalObjectSummary,trailingMeta,titleSuffix,titleClassName,@@ -162,8 +169,11 @@ export function IssueRow({) : null}</span></span>- {(desktopTrailing || trailingMeta) ? (+ {(desktopTrailing || trailingMeta || externalObjectSummary) ? (<span className="ml-auto hidden shrink-0 items-center gap-2 sm:order-3 sm:flex sm:gap-3">+ {externalObjectSummary ? (+ <ExternalObjectStatusSummary summary={externalObjectSummary} compact />+ ) : null}{desktopTrailing}{trailingMeta ? (<span className="text-xs text-muted-foreground">{trailingMeta}</span>diff --git a/ui/src/components/IssueThreadInteractionCard.tsx b/ui/src/components/IssueThreadInteractionCard.tsxindex 49e4e4a561..508caf133d 100644--- a/ui/src/components/IssueThreadInteractionCard.tsx+++ b/ui/src/components/IssueThreadInteractionCard.tsx@@ -21,7 +21,7 @@ import {type SuggestedTaskTreeNode,} from "../lib/issue-thread-interactions";import { cn, formatDateTime, formatShortDate } from "../lib/utils";-import { MarkdownBody } from "./MarkdownBody";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";import { Button } from "./ui/button";import { Checkbox } from "./ui/checkbox";import { PriorityIcon } from "./PriorityIcon";@@ -58,6 +58,7 @@ interface IssueThreadInteractionCardProps {interaction: AskUserQuestionsInteraction,) => Promise<void> | void;onUploadImage?: (file: File) => Promise<string>;+ externalReferences?: MarkdownExternalReferenceMap;}function resolveActorLabel(args: {@@ -706,6 +707,7 @@ function AskUserQuestionsCard({interaction,onSubmitInteractionAnswers,onCancelInteraction,+ externalReferences,}: {interaction: AskUserQuestionsInteraction;onSubmitInteractionAnswers?: (@@ -715,6 +717,7 @@ function AskUserQuestionsCard({onCancelInteraction?: (interaction: AskUserQuestionsInteraction,) => Promise<void> | void;+ externalReferences?: MarkdownExternalReferenceMap;}) {const [draftAnswers, setDraftAnswers] = useState<Record<string, string[]>>(() =>Object.fromEntries(@@ -1013,7 +1016,7 @@ function AskUserQuestionsCard({<div className="mb-2 text-[11px] font-semibold uppercase tracking-[0.16em] text-emerald-700">Submitted summary</div>- <MarkdownBody>{interaction.result.summaryMarkdown}</MarkdownBody>+ <MarkdownBody externalReferences={externalReferences}>{interaction.result.summaryMarkdown}</MarkdownBody></div>) : null}</div>@@ -1173,6 +1176,7 @@ function RequestConfirmationCard({onAcceptInteraction,onRejectInteraction,onUploadImage,+ externalReferences,}: {interaction: RequestConfirmationInteraction;isPlan?: boolean;@@ -1184,6 +1188,7 @@ function RequestConfirmationCard({reason?: string,) => Promise<void> | void;onUploadImage?: (file: File) => Promise<string>;+ externalReferences?: MarkdownExternalReferenceMap;}) {const [rejecting, setRejecting] = useState(false);const [working, setWorking] = useState<"accept" | "reject" | null>(null);@@ -1283,7 +1288,7 @@ function RequestConfirmationCard({</div>{interaction.payload.detailsMarkdown ? (<div className="border-t border-border/60 pt-3 text-sm">- <MarkdownBody>{interaction.payload.detailsMarkdown}</MarkdownBody>+ <MarkdownBody externalReferences={externalReferences}>{interaction.payload.detailsMarkdown}</MarkdownBody></div>) : null}<RequestConfirmationTargetChip@@ -1575,6 +1580,7 @@ function RequestCheckboxConfirmationCard({interaction,onAcceptInteraction,onRejectInteraction,+ externalReferences,}: {interaction: RequestCheckboxConfirmationInteraction;onAcceptInteraction?: (@@ -1586,6 +1592,7 @@ function RequestCheckboxConfirmationCard({interaction: RequestCheckboxConfirmationInteraction,reason?: string,) => Promise<void> | void;+ externalReferences?: MarkdownExternalReferenceMap;}) {const options = interaction.payload.options;const optionIds = useMemo(() => options.map((option) => option.id), [options]);@@ -1721,7 +1728,7 @@ function RequestCheckboxConfirmationCard({<div className="text-sm leading-6 text-foreground">{interaction.payload.prompt}</div>{interaction.payload.detailsMarkdown ? (<div className="border-t border-border/60 pt-3 text-sm">- <MarkdownBody>{interaction.payload.detailsMarkdown}</MarkdownBody>+ <MarkdownBody externalReferences={externalReferences}>{interaction.payload.detailsMarkdown}</MarkdownBody></div>) : null}<RequestConfirmationTargetChip@@ -1881,6 +1888,7 @@ export function IssueThreadInteractionCard({onSubmitInteractionAnswers,onCancelInteraction,onUploadImage,+ externalReferences,}: IssueThreadInteractionCardProps) {const isPlan = isPlanConfirmation(interaction);const planStyles = isPlan ? planStatusClasses(interaction.status) : null;@@ -1973,12 +1981,14 @@ export function IssueThreadInteractionCard({interaction={interaction}onSubmitInteractionAnswers={onSubmitInteractionAnswers}onCancelInteraction={onCancelInteraction}+ externalReferences={externalReferences}/>) : interaction.kind === "request_checkbox_confirmation" ? (<RequestCheckboxConfirmationCardinteraction={interaction}onAcceptInteraction={onAcceptInteraction}onRejectInteraction={onRejectInteraction}+ externalReferences={externalReferences}/>) : (<RequestConfirmationCard@@ -1987,6 +1997,7 @@ export function IssueThreadInteractionCard({onAcceptInteraction={onAcceptInteraction}onRejectInteraction={onRejectInteraction}onUploadImage={onUploadImage}+ externalReferences={externalReferences}/>)}</div>diff --git a/ui/src/components/IssuesList.test.tsx b/ui/src/components/IssuesList.test.tsxindex cb07cdfc24..b62d8a6dda 100644--- a/ui/src/components/IssuesList.test.tsx+++ b/ui/src/components/IssuesList.test.tsx@@ -42,6 +42,10 @@ const mockInstanceSettingsApi = vi.hoisted(() => ({getExperimental: vi.fn(),}));+const mockExternalObjectsApi = vi.hoisted(() => ({+ getIssueSummaries: vi.fn(),+}));+vi.mock("../context/CompanyContext", () => ({useCompany: () => companyState,}));@@ -87,6 +91,10 @@ vi.mock("../api/instanceSettings", () => ({instanceSettingsApi: mockInstanceSettingsApi,}));+vi.mock("../api/externalObjects", () => ({+ externalObjectsApi: mockExternalObjectsApi,+}));+vi.mock("./IssueRow", () => ({IssueRow: ({issue,@@ -97,6 +105,7 @@ vi.mock("./IssueRow", () => ({checklistCurrentStep,checklistDependencyChips,checklistRowId,+ externalObjectSummary,}: {issue: Issue;desktopMetaLeading?: ReactNode;@@ -106,6 +115,7 @@ vi.mock("./IssueRow", () => ({checklistCurrentStep?: boolean;checklistDependencyChips?: ReactNode;checklistRowId?: string;+ externalObjectSummary?: { total: number } | null;}) => (<divdata-testid="issue-row"@@ -115,6 +125,9 @@ vi.mock("./IssueRow", () => ({data-title-class={titleClassName ?? undefined}><span>{issue.title}</span>+ {externalObjectSummary ? (+ <span data-testid="external-object-summary">{externalObjectSummary.total}</span>+ ) : null}{desktopMetaLeading}{desktopTrailing}{checklistDependencyChips}@@ -286,6 +299,7 @@ describe("IssuesList", () => {mockExecutionWorkspacesApi.list.mockReset();mockExecutionWorkspacesApi.listSummaries.mockReset();mockInstanceSettingsApi.getExperimental.mockReset();+ mockExternalObjectsApi.getIssueSummaries.mockReset();mockIssuesApi.list.mockResolvedValue([]);mockIssuesApi.listLabels.mockResolvedValue([]);mockAuthApi.getSession.mockResolvedValue({ user: null, session: null });@@ -293,8 +307,12 @@ describe("IssuesList", () => {mockAccessApi.listUserDirectory.mockResolvedValue({ users: [] });mockExecutionWorkspacesApi.list.mockResolvedValue([]);mockExecutionWorkspacesApi.listSummaries.mockResolvedValue([]);- mockInstanceSettingsApi.getExperimental.mockResolvedValue({ enableIsolatedWorkspaces: false });+ mockInstanceSettingsApi.getExperimental.mockResolvedValue({+ enableIsolatedWorkspaces: false,+ enableExternalObjects: false,+ });setDocumentScrollMetrics({ innerHeight: 600, scrollY: 0, scrollHeight: 2400 });+ mockExternalObjectsApi.getIssueSummaries.mockResolvedValue({ summaries: {} });localStorage.clear();});@@ -303,6 +321,130 @@ describe("IssuesList", () => {container.remove();});+ it("forwards external-object summaries into issue rows", async () => {+ mockInstanceSettingsApi.getExperimental.mockResolvedValue({+ enableIsolatedWorkspaces: false,+ enableExternalObjects: true,+ });+ mockExternalObjectsApi.getIssueSummaries.mockResolvedValue({+ summaries: {+ "issue-1": {+ total: 2,+ byStatusCategory: { failed: 1, succeeded: 1 },+ byLiveness: { fresh: 2 },+ highestSeverity: "danger",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+ },+ },+ });++ const { root } = renderWithQueryClient(+ <IssuesList+ issues={[createIssue()]}+ agents={[]}+ projects={[]}+ viewStateKey="paperclip:test-issues"+ onUpdateIssue={() => undefined}+ />,+ container,+ );++ await waitForAssertion(() => {+ expect(mockExternalObjectsApi.getIssueSummaries).toHaveBeenCalledWith("company-1", ["issue-1"]);+ expect(container.querySelector("[data-testid='external-object-summary']")?.textContent).toBe("2");+ });++ act(() => {+ root.unmount();+ });+ });++ it("does not load external-object summaries when the experimental flag is disabled", async () => {+ const { root } = renderWithQueryClient(+ <IssuesList+ issues={[createIssue()]}+ agents={[]}+ projects={[]}+ viewStateKey="paperclip:test-issues"+ onUpdateIssue={() => undefined}+ />,+ container,+ );++ await waitForAssertion(() => {+ expect(mockInstanceSettingsApi.getExperimental).toHaveBeenCalled();+ expect(container.querySelector("[data-testid='issue-row']")).not.toBeNull();+ });+ expect(mockExternalObjectsApi.getIssueSummaries).not.toHaveBeenCalled();++ act(() => {+ root.unmount();+ });+ });++ it("filters issue rows by external-object status summaries", async () => {+ mockInstanceSettingsApi.getExperimental.mockResolvedValue({+ enableIsolatedWorkspaces: false,+ enableExternalObjects: true,+ });+ const failedIssue = createIssue({ id: "issue-failed", identifier: "PAP-10", title: "Failed external object" });+ const freshIssue = createIssue({ id: "issue-fresh", identifier: "PAP-11", title: "Fresh external object" });+ const noObjectIssue = createIssue({ id: "issue-none", identifier: "PAP-12", title: "No external object" });+ localStorage.setItem("paperclip:test-issues:company-1", JSON.stringify({ externalObjectStatuses: ["failed"] }));+ mockExternalObjectsApi.getIssueSummaries.mockResolvedValue({+ summaries: {+ "issue-failed": {+ total: 1,+ byStatusCategory: { failed: 1 },+ byLiveness: { fresh: 1 },+ highestSeverity: "danger",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+ },+ "issue-fresh": {+ total: 1,+ byStatusCategory: { succeeded: 1 },+ byLiveness: { fresh: 1 },+ highestSeverity: "success",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+ },+ },+ });++ const { root } = renderWithQueryClient(+ <IssuesList+ issues={[failedIssue, freshIssue, noObjectIssue]}+ agents={[]}+ projects={[]}+ viewStateKey="paperclip:test-issues"+ onUpdateIssue={() => undefined}+ />,+ container,+ );++ await waitForAssertion(() => {+ expect(mockExternalObjectsApi.getIssueSummaries).toHaveBeenCalledWith(+ "company-1",+ ["issue-failed", "issue-fresh", "issue-none"],+ );+ expect(container.textContent).toContain("Failed external object");+ expect(container.textContent).not.toContain("Fresh external object");+ expect(container.textContent).not.toContain("No external object");+ });++ act(() => {+ root.unmount();+ });+ });+it("renders server search results instead of filtering the full issue list locally", async () => {const localIssue = createIssue({ id: "issue-local", identifier: "PAP-1", title: "Local issue" });const serverIssue = createIssue({ id: "issue-server", identifier: "PAP-2", title: "Server result" });diff --git a/ui/src/components/IssuesList.tsx b/ui/src/components/IssuesList.tsxindex 833845afaf..81d4af908e 100644--- a/ui/src/components/IssuesList.tsx+++ b/ui/src/components/IssuesList.tsx@@ -9,6 +9,7 @@ import { issuesApi } from "../api/issues";import { authApi } from "../api/auth";import { instanceSettingsApi } from "../api/instanceSettings";import { queryKeys } from "../lib/queryKeys";+import { useIssueExternalObjectSummaries } from "../hooks/useIssueExternalObjects";import {shouldBlurPageSearchOnEnter,shouldBlurPageSearchOnEscape,@@ -642,7 +643,9 @@ export function IssuesList({retry: false,});const currentUserId = session?.user?.id ?? session?.session?.userId ?? null;+ const experimentalSettingsLoaded = experimentalSettings !== undefined;const isolatedWorkspacesEnabled = experimentalSettings?.enableIsolatedWorkspaces === true;+ const externalObjectsEnabled = experimentalSettings?.enableExternalObjects === true;// Scope the storage key per company so folding/view state is independent across companies.const scopedKey = selectedCompanyId ? `${viewStateKey}:${selectedCompanyId}` : viewStateKey;@@ -692,6 +695,11 @@ export function IssuesList({});}, [scopedKey]);+ useEffect(() => {+ if (!experimentalSettingsLoaded || externalObjectsEnabled || viewState.externalObjectStatuses.length === 0) return;+ updateView({ externalObjectStatuses: [] });+ }, [experimentalSettingsLoaded, externalObjectsEnabled, updateView, viewState.externalObjectStatuses.length]);+// Prune stale IDs from collapsedParents whenever the issue list changes.// Deleted or reassigned issues leave orphan IDs in localStorage; this keeps// the stored array bounded to only current parent IDs.@@ -967,32 +975,58 @@ export function IssuesList({[boardIssueQueries, searchWithinLoadedIssues, viewState.viewMode],);- const filtered = useMemo(() => {+ const sourceIssues = useMemo(() => {const useRemoteSearch = normalizedIssueSearch.length > 0 && !searchWithinLoadedIssues;- const sourceIssues = boardIssues ?? (useRemoteSearch ? searchedIssues : issues);- const searchScopedIssues = normalizedIssueSearch.length > 0 && searchWithinLoadedIssues+ return boardIssues ?? (useRemoteSearch ? searchedIssues : issues);+ }, [boardIssues, issues, normalizedIssueSearch, searchedIssues, searchWithinLoadedIssues]);++ const searchScopedIssues = useMemo(+ () => normalizedIssueSearch.length > 0 && searchWithinLoadedIssues? sourceIssues.filter((issue) => issueMatchesLocalSearch(issue, normalizedIssueSearch))- : sourceIssues;+ : sourceIssues,+ [normalizedIssueSearch, searchWithinLoadedIssues, sourceIssues],+ );+ const hasExternalObjectStatusFilters = viewState.externalObjectStatuses.length > 0;+ const issueIdsForExternalObjectSummaries = useMemo(+ () => (viewState.viewMode === "list" || hasExternalObjectStatusFilters+ ? searchScopedIssues.map((issue) => issue.id)+ : []),+ [hasExternalObjectStatusFilters, searchScopedIssues, viewState.viewMode],+ );+ const {+ summaries: externalObjectSummaryByIssueId,+ isLoading: externalObjectSummariesLoading,+ isReady: externalObjectSummariesReady,+ } = useIssueExternalObjectSummaries(+ selectedCompanyId,+ issueIdsForExternalObjectSummaries,+ );+ const issueFilterContext = useMemo(() => ({+ ...issueFilterWorkspaceContext,+ externalObjectSummaryByIssueId,+ externalObjectSummariesReady: externalObjectSummariesReady && !externalObjectSummariesLoading,+ }), [externalObjectSummariesLoading, externalObjectSummariesReady, externalObjectSummaryByIssueId, issueFilterWorkspaceContext]);+ const externalObjectFilterLoading = hasExternalObjectStatusFilters+ && externalObjectSummariesLoading+ && !externalObjectSummariesReady;++ const filtered = useMemo(() => {const filteredByControls = applyIssueFilters(searchScopedIssues,viewState,currentUserId,enableRoutineVisibilityFilter,liveIssueIds,- issueFilterWorkspaceContext,+ issueFilterContext,);return sortIssues(filteredByControls, viewState);}, [- boardIssues,- issues,- searchedIssues,- searchWithinLoadedIssues,+ searchScopedIssues,viewState,- normalizedIssueSearch,currentUserId,enableRoutineVisibilityFilter,liveIssueIds,- issueFilterWorkspaceContext,+ issueFilterContext,]);const progressSummary = useMemo(@@ -1479,6 +1513,7 @@ export function IssuesList({projects={projects?.map((project) => ({ id: project.id, name: project.name }))}labels={labels?.map((label) => ({ id: label.id, name: label.name, color: label.color }))}currentUserId={currentUserId}+ enableExternalObjectFilters={externalObjectsEnabled}enableRoutineVisibilityFilter={enableRoutineVisibilityFilter}iconOnlyworkspaces={isolatedWorkspacesEnabled ? workspaceOptions : undefined}@@ -1565,7 +1600,7 @@ export function IssuesList({</div></div>- {isLoading && <PageSkeleton variant="issues-list" />}+ {(isLoading || externalObjectFilterLoading) && <PageSkeleton variant="issues-list" />}{error && <p className="text-sm text-destructive">{error.message}</p>}{!searchWithinLoadedIssues && normalizedIssueSearch.length > 0 && searchedIssues.length === ISSUE_SEARCH_RESULT_LIMIT && (<p className="text-xs text-muted-foreground">@@ -1577,7 +1612,7 @@ export function IssuesList({Some board columns are showing up to {ISSUE_BOARD_COLUMN_RESULT_LIMIT} tasks. Refine filters or search to reveal the rest.</p>)}- {!isLoading && filtered.length === 0 && viewState.viewMode === "list" && (+ {!isLoading && !externalObjectFilterLoading && filtered.length === 0 && viewState.viewMode === "list" && (<EmptyStateicon={CircleDot}message="No tasks match the current filters or search."@@ -1749,6 +1784,7 @@ export function IssuesList({checklistDependencyChips={checklistDependencyChips}checklistRowId={checklistRowId}titleClassName={doneRowTitleClass}+ externalObjectSummary={externalObjectSummaryByIssueId.get(issue.id) ?? null}titleSuffix={(<>{hasChildren && !isExpanded ? (diff --git a/ui/src/components/MarkdownBody.tsx b/ui/src/components/MarkdownBody.tsxindex 60052cc094..87814f7d8c 100644--- a/ui/src/components/MarkdownBody.tsx+++ b/ui/src/components/MarkdownBody.tsx@@ -1,4 +1,4 @@-import { isValidElement, useCallback, useEffect, useId, useRef, useState, type ReactNode } from "react";+import { isValidElement, useCallback, useEffect, useId, useMemo, useRef, useState, type ReactNode } from "react";import { useQuery } from "@tanstack/react-query";import { Check, Copy, ExternalLink, Github, WrapText } from "lucide-react";import Markdown, { defaultUrlTransform, type Components, type Options } from "react-markdown";@@ -15,6 +15,36 @@ import { parseWorkspaceFileHref, remarkWorkspaceFileRefs, WORKSPACE_FILE_HREF_PRimport { remarkSoftBreaks } from "../lib/remark-soft-breaks";import { StatusIcon } from "./StatusIcon";import { WorkspaceFileLink } from "./WorkspaceFileLink";+import { ExternalObjectStatusIcon } from "./ExternalObjectStatusIcon";+import {+ externalObjectCategoryLabel,+ externalObjectLivenessLabel,+ externalObjectProviderLabel,+} from "../lib/external-objects";+import { normalizeExternalObjectHref } from "../lib/external-object-href";+import type {+ ExternalObjectLivenessState,+ ExternalObjectStatusCategory,+} from "@paperclipai/shared";++/**+ * Host-resolved external-object metadata for inline markdown decoration.+ * The renderer only consumes the host normalized fields here — plugin React+ * is never mounted inline (Phase 1B security review).+ */+export interface MarkdownExternalReference {+ providerKey: string | null;+ objectType: string | null;+ displayKey?: string | null;+ iconKey?: string | null;+ statusCategory: ExternalObjectStatusCategory;+ liveness: ExternalObjectLivenessState;+ statusLabel?: string | null;+ statusIconKey?: string | null;+ displayTitle?: string | null;+}++export type MarkdownExternalReferenceMap = Record<string, MarkdownExternalReference>;interface MarkdownBodyProps {children: string;@@ -28,6 +58,12 @@ interface MarkdownBodyProps {wikiLinkRoot?: string;/** Optional href resolver for wikilinks. Return null to leave a token as plain text. */resolveWikiLinkHref?: (target: string, label: string) => string | null | undefined;+ /**+ * Optional map of `normalizeExternalObjectHref(href)` → host-resolved metadata.+ * Hrefs in the markdown that resolve to one of these keys get the inline+ * status icon prefix used by §2 of the UX spec.+ */+ externalReferences?: MarkdownExternalReferenceMap;/** Optional resolver for relative image paths (e.g. within export packages) */resolveImageSrc?: (src: string) => string | null;/** Called when a user clicks an inline image */@@ -72,6 +108,51 @@ function MarkdownIssueLink({);}+function MarkdownExternalLink({+ href,+ reference,+ children,+}: {+ href: string;+ reference: MarkdownExternalReference;+ children: ReactNode;+}) {+ const provider = externalObjectProviderLabel(reference.providerKey);+ const displayKey = reference.displayKey?.trim() || provider;+ const statusLabel = reference.statusLabel ?? externalObjectCategoryLabel(reference.statusCategory);+ const livenessLabel = externalObjectLivenessLabel(reference.liveness);+ const livenessSuffix = reference.liveness === "fresh" || reference.liveness === "unknown"+ ? ""+ : ` (${livenessLabel})`;+ const titleParts = [+ reference.displayTitle ?? `${displayKey} ${statusLabel}`,+ `${displayKey} — ${statusLabel}${livenessSuffix}`,+ ];+ const title = titleParts.filter(Boolean).join(" · ");+ return (+ <a+ href={href}+ target="_blank"+ rel="noopener noreferrer"+ data-external-link="resolved"+ data-external-status={reference.statusCategory}+ data-external-liveness={reference.liveness}+ title={title}+ aria-label={`${displayKey} ${statusLabel}${livenessSuffix}: ${reference.displayTitle ?? href}`}+ className="paperclip-markdown-external-ref"+ >+ <ExternalObjectStatusIcon+ category={reference.statusCategory}+ liveness={reference.liveness}+ statusIconKey={reference.statusIconKey}+ label={`${displayKey}: ${statusLabel}`}+ inline+ />+ {children}+ </a>+ );+}+function loadMermaid() {if (!mermaidLoaderPromise) {mermaidLoaderPromise = import("mermaid").then((module) => module.default);@@ -572,6 +653,7 @@ export function MarkdownBody({enableWikiLinks = false,wikiLinkRoot,resolveWikiLinkHref,+ externalReferences,resolveImageSrc,onImageClick,linkWorkspaceFileRefs = false,@@ -584,6 +666,15 @@ export function MarkdownBody({const knownPrefixes = company?.companies.length? company.companies.map((c) => c.issuePrefix): undefined;+ const externalReferenceLookup = useMemo<MarkdownExternalReferenceMap | null>(() => {+ if (!externalReferences) return null;+ const lookup: MarkdownExternalReferenceMap = {};+ for (const [key, value] of Object.entries(externalReferences)) {+ const normalized = normalizeExternalObjectHref(key) ?? key;+ lookup[normalized] = value;+ }+ return lookup;+ }, [externalReferences]);const remarkPlugins: NonNullable<Options["remarkPlugins"]> = [remarkGfm];if (enableWikiLinks) {remarkPlugins.push(createRemarkWikiLinks({ wikiLinkRoot, resolveWikiLinkHref }));@@ -706,6 +797,17 @@ export function MarkdownBody({</a>);}+ const externalReference = href && externalReferenceLookup+ ? externalReferenceLookup[normalizeExternalObjectHref(href) ?? ""] ?? null+ : null;+ if (externalReference && href) {+ return (+ <MarkdownExternalLink href={href} reference={externalReference}>+ {linkChildren}+ </MarkdownExternalLink>+ );+ }+const isGitHubLink = isGitHubUrl(href);const isExternal = isExternalHttpUrl(href);const leadingIcon = isGitHubLink ? (diff --git a/ui/src/components/MarkdownExternalLink.test.tsx b/ui/src/components/MarkdownExternalLink.test.tsxnew file mode 100644index 0000000000..173b1c46c3--- /dev/null+++ b/ui/src/components/MarkdownExternalLink.test.tsx@@ -0,0 +1,94 @@+// @vitest-environment node++import type { ReactNode } from "react";+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";+import { describe, expect, it, vi } from "vitest";+import { renderToStaticMarkup } from "react-dom/server";+import { ThemeProvider } from "../context/ThemeContext";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "./MarkdownBody";++vi.mock("@/lib/router", () => ({+ Link: ({+ children,+ to,+ ...props+ }: { children: ReactNode; to: string } & React.ComponentProps<"a">) => (+ <a href={to} {...props}>{children}</a>+ ),+}));++vi.mock("../api/issues", () => ({+ issuesApi: { get: vi.fn() },+}));++function render(children: string, externalReferences?: MarkdownExternalReferenceMap) {+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });+ return renderToStaticMarkup(+ <QueryClientProvider client={queryClient}>+ <ThemeProvider>+ <MarkdownBody externalReferences={externalReferences}>{children}</MarkdownBody>+ </ThemeProvider>+ </QueryClientProvider>,+ );+}++describe("MarkdownBody external object decoration", () => {+ const successReference: MarkdownExternalReferenceMap = {+ "https://github.com/acme/web/pull/241": {+ providerKey: "github",+ objectType: "pull_request",+ displayKey: "Github Pull Request",+ iconKey: "github",+ statusCategory: "succeeded",+ statusIconKey: "git-merge",+ liveness: "fresh",+ statusLabel: "Merged",+ displayTitle: "Add external refs",+ },+ };++ it("decorates a known URL with the external status icon and metadata attributes", () => {+ const html = render("Take a look: https://github.com/acme/web/pull/241", successReference);+ expect(html).toContain('class="paperclip-markdown-external-ref"');+ expect(html).toContain('data-external-link="resolved"');+ expect(html).toContain('data-external-status="succeeded"');+ expect(html).toContain('data-external-liveness="fresh"');+ expect(html).toContain('aria-label="Github Pull Request Merged: Add external refs"');+ expect(html).toContain("github.com/acme/web/pull/241");+ });++ it("matches a URL even when the user pasted it with different host case or trailing punctuation", () => {+ const html = render("see HTTPS://Github.com/acme/web/pull/241#frag.", successReference);+ expect(html).toContain('data-external-status="succeeded"');+ });++ it("renders an unresolved URL as a plain external link with no status affordance", () => {+ const html = render("https://random.example.com/path");+ expect(html).not.toContain("paperclip-markdown-external-ref");+ expect(html).toContain('href="https://random.example.com/path"');+ });++ it("never decorates a URL that lives inside a fenced or inline code block", () => {+ const html = render(+ "```\nhttps://github.com/acme/web/pull/241\n```\n\nInline: `https://github.com/acme/web/pull/241`",+ successReference,+ );+ // The fenced/inline literal should still be present as text but the+ // decorated anchor should not appear since no `<a>` is created in code.+ expect(html).not.toContain('class="paperclip-markdown-external-ref"');+ });++ it("shows liveness suffix in the aria-label when the object is stale or auth_required", () => {+ const html = render("Auth-blocked: https://app.hubspot.com/leads/99", {+ "https://app.hubspot.com/leads/99": {+ providerKey: "hubspot",+ objectType: "lead",+ statusCategory: "auth_required",+ liveness: "auth_required",+ statusLabel: "Reconnect",+ displayTitle: "Acme deal",+ },+ });+ expect(html).toContain('aria-label="HubSpot Reconnect (Requires auth): Acme deal"');+ });+});diff --git a/ui/src/components/SidebarProjects.tsx b/ui/src/components/SidebarProjects.tsxindex 968e05d8d8..8351a13d23 100644--- a/ui/src/components/SidebarProjects.tsx+++ b/ui/src/components/SidebarProjects.tsx@@ -22,7 +22,9 @@ import { queryKeys } from "../lib/queryKeys";import { cn, projectRouteRef, SIDEBAR_RAIL_HIDDEN_LABEL } from "../lib/utils";import { useProjectOrder } from "../hooks/useProjectOrder";import { resourceMembershipState, useResourceMembershipMutation, useResourceMemberships } from "../hooks/useResourceMemberships";+import { useProjectExternalObjectSummary } from "../hooks/useIssueExternalObjects";import { BudgetSidebarMarker } from "./BudgetSidebarMarker";+import { ExternalObjectStatusSummary } from "./ExternalObjectStatusSummary";import { ProjectTile } from "./ProjectTile";import { SidebarSection, type SidebarSectionRadioChoice } from "./SidebarSection";import { Button } from "@/components/ui/button";@@ -122,6 +124,7 @@ function ProjectItem({isDragging = false,}: ProjectItemProps) {const routeRef = projectRouteRef(project);+ const { summary: externalObjectsSummary } = useProjectExternalObjectSummary(project.id);const link = (<NavLink@@ -143,6 +146,7 @@ function ProjectItem({><ProjectTile color={project.color ?? null} icon={project.icon ?? null} size="xs" /><span className={rail ? SIDEBAR_RAIL_HIDDEN_LABEL : "flex-1 truncate"}>{project.name}</span>+ {!rail ? <ExternalObjectStatusSummary summary={externalObjectsSummary} compact /> : null}{!rail && project.pauseReason === "budget" ? <BudgetSidebarMarker title="Project paused by budget" /> : null}</NavLink>);diff --git a/ui/src/components/transcript/RunTranscriptView.tsx b/ui/src/components/transcript/RunTranscriptView.tsxindex a9130f8cde..52e9f6bfc8 100644--- a/ui/src/components/transcript/RunTranscriptView.tsx+++ b/ui/src/components/transcript/RunTranscriptView.tsx@@ -1,6 +1,6 @@import { useEffect, useMemo, useRef, useState } from "react";import type { TranscriptEntry } from "../../adapters";-import { MarkdownBody } from "../MarkdownBody";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "../MarkdownBody";import { cn, formatTokens } from "../../lib/utils";import {Check,@@ -31,6 +31,7 @@ interface RunTranscriptViewProps {emptyMessage?: string;className?: string;thinkingClassName?: string;+ externalReferences?: MarkdownExternalReferenceMap;}type TranscriptBlock =@@ -636,9 +637,11 @@ export function normalizeTranscript(entries: TranscriptEntry[], streaming: boolefunction TranscriptMessageBlock({block,density,+ externalReferences,}: {block: Extract<TranscriptBlock, { type: "message" }>;density: TranscriptDensity;+ externalReferences?: MarkdownExternalReferenceMap;}) {const isAssistant = block.role === "assistant";const compact = density === "compact";@@ -656,6 +659,7 @@ function TranscriptMessageBlock({"[&>*:first-child]:mt-0 [&>*:last-child]:mb-0",compact ? "text-xs leading-5 text-foreground/85" : "text-sm",)}+ externalReferences={externalReferences}>{block.text}</MarkdownBody>@@ -676,10 +680,12 @@ function TranscriptThinkingBlock({block,density,className,+ externalReferences,}: {block: Extract<TranscriptBlock, { type: "thinking" }>;density: TranscriptDensity;className?: string;+ externalReferences?: MarkdownExternalReferenceMap;}) {return (<MarkdownBody@@ -688,6 +694,7 @@ function TranscriptThinkingBlock({density === "compact" ? "text-[11px] leading-5" : "text-sm leading-6",className,)}+ externalReferences={externalReferences}>{block.text}</MarkdownBody>@@ -1090,9 +1097,11 @@ function TranscriptActivityRow({function TranscriptEventRow({block,density,+ externalReferences,}: {block: Extract<TranscriptBlock, { type: "event" }>;density: TranscriptDensity;+ externalReferences?: MarkdownExternalReferenceMap;}) {const compact = density === "compact";const toneClasses =@@ -1121,6 +1130,7 @@ function TranscriptEventRow({"[&>*:first-child]:mt-0 [&>*:last-child]:mb-0 text-sky-700 dark:text-sky-300",compact ? "text-[11px] leading-5" : "text-xs leading-5",)}+ externalReferences={externalReferences}>{block.text}</MarkdownBody>@@ -1473,6 +1483,7 @@ export function RunTranscriptView({emptyMessage = "No transcript yet.",className,thinkingClassName,+ externalReferences,}: RunTranscriptViewProps) {const blocks = useMemo(() => (mode === "raw" ? [] : normalizeTranscript(entries, streaming)),@@ -1504,9 +1515,20 @@ export function RunTranscriptView({key={`${block.type}-${block.ts}-${index}`}className={cn(index === visibleBlocks.length - 1 && streaming && "animate-in fade-in slide-in-from-bottom-1 duration-300")}>- {block.type === "message" && <TranscriptMessageBlock block={block} density={density} />}+ {block.type === "message" && (+ <TranscriptMessageBlock+ block={block}+ density={density}+ externalReferences={externalReferences}+ />+ )}{block.type === "thinking" && (- <TranscriptThinkingBlock block={block} density={density} className={thinkingClassName} />+ <TranscriptThinkingBlock+ block={block}+ density={density}+ className={thinkingClassName}+ externalReferences={externalReferences}+ />)}{block.type === "tool" && <TranscriptToolCard block={block} density={density} />}{block.type === "command_group" && <TranscriptCommandGroup block={block} density={density} />}@@ -1518,7 +1540,13 @@ export function RunTranscriptView({<TranscriptStdoutRow block={block} density={density} collapseByDefault={collapseStdout} />)}{block.type === "activity" && <TranscriptActivityRow block={block} density={density} />}- {block.type === "event" && <TranscriptEventRow block={block} density={density} />}+ {block.type === "event" && (+ <TranscriptEventRow+ block={block}+ density={density}+ externalReferences={externalReferences}+ />+ )}</div>))}</div>diff --git a/ui/src/hooks/useIssueExternalObjects.ts b/ui/src/hooks/useIssueExternalObjects.tsnew file mode 100644index 0000000000..8f8052afb0--- /dev/null+++ b/ui/src/hooks/useIssueExternalObjects.ts@@ -0,0 +1,250 @@+import { useCallback, useMemo } from "react";+import { useQuery } from "@tanstack/react-query";+import type {+ ExternalObjectMention,+ ExternalObjectMentionGroup,+ ExternalObjectSummary,+} from "@paperclipai/shared";+import { externalObjectsApi } from "../api/externalObjects";+import { queryKeys } from "../lib/queryKeys";+import { normalizeExternalObjectHref } from "../lib/external-object-href";+import type { MarkdownExternalReferenceMap } from "../components/MarkdownBody";+import type { ExternalObjectPillData } from "../components/ExternalObjectPill";+import { instanceSettingsApi } from "../api/instanceSettings";++export const EXTERNAL_OBJECT_SUMMARY_BATCH_SIZE = 500;++export async function fetchIssueExternalObjectSummariesInBatches(+ companyId: string,+ issueIds: readonly string[],+) {+ const summaries: Record<string, ExternalObjectSummary> = {};+ for (let index = 0; index < issueIds.length; index += EXTERNAL_OBJECT_SUMMARY_BATCH_SIZE) {+ const batch = issueIds.slice(index, index + EXTERNAL_OBJECT_SUMMARY_BATCH_SIZE);+ const response = await externalObjectsApi.getIssueSummaries(companyId, batch);+ Object.assign(summaries, response.summaries);+ }+ return { summaries };+}++/**+ * Browser-side mention-source label. Keep in sync with the shared formatter+ * without coupling this hook to the server-only URL canonicalization helpers.+ */+function formatMentionSourceLabel(mention: ExternalObjectMention): string {+ switch (mention.sourceKind) {+ case "title":+ return "Title";+ case "description":+ return "Description";+ case "comment":+ return "Comment";+ case "document":+ return mention.documentKey ? `Document: ${mention.documentKey}` : "Document";+ case "property":+ return mention.propertyKey ? `Property: ${mention.propertyKey}` : "Property";+ case "plugin":+ return "Plugin";+ default:+ return "Source";+ }+}++export interface IssueExternalObjectGroup {+ pill: ExternalObjectPillData;+ mentionCount: number;+ sourceLabels: string[];+ group: ExternalObjectMentionGroup;+}++export interface IssueExternalObjectsResult {+ isEnabled: boolean;+ groups: IssueExternalObjectGroup[];+ /** Lookup map for `MarkdownBody`'s `externalReferences` prop. */+ markdownReferences: MarkdownExternalReferenceMap;+ isLoading: boolean;+ isError: boolean;+ refetch: () => void;+}++function useExternalObjectsFeature() {+ const query = useQuery({+ queryKey: queryKeys.instance.experimentalSettings,+ queryFn: () => instanceSettingsApi.getExperimental(),+ retry: false,+ });+ return {+ isEnabled: query.data?.enableExternalObjects === true,+ isLoaded: query.data !== undefined || query.isError,+ };+}++/**+ * Loads `external_objects` for an issue and produces both the per-group rows+ * (used by the property panel and related-work section) and the markdown URL+ * lookup map (used by inline decoration). Single source of truth so every+ * surface reads from the same query result.+ */+export function useIssueExternalObjects(issueId: string | null | undefined): IssueExternalObjectsResult {+ const externalObjectsFeature = useExternalObjectsFeature();+ const enabled = externalObjectsFeature.isEnabled && Boolean(issueId);+ const query = useQuery({+ queryKey: queryKeys.externalObjects.byIssue(issueId ?? "__none__"),+ queryFn: () => externalObjectsApi.listForIssue(issueId!),+ enabled,+ staleTime: 60_000,+ });++ const groups = useMemo<IssueExternalObjectGroup[]>(() => {+ const data = query.data ?? [];+ return data+ .filter((entry): entry is ExternalObjectMentionGroup => Boolean(entry.object))+ .map((entry) => {+ const object = entry.object!;+ const sourceLabels = entry.sourceLabels && entry.sourceLabels.length > 0+ ? entry.sourceLabels+ : Array.from(new Set(entry.mentions.map(formatMentionSourceLabel)));+ return {+ group: entry,+ mentionCount: entry.mentionCount ?? entry.mentions.length,+ sourceLabels,+ pill: {+ providerKey: object.providerKey,+ objectType: object.objectType,+ displayKey: object.displayKey,+ iconKey: object.iconKey,+ statusCategory: object.statusCategory,+ liveness: object.liveness,+ displayTitle: object.displayTitle,+ statusLabel: object.statusLabel,+ statusIconKey: object.statusIconKey,+ url: object.sanitizedCanonicalUrl,+ },+ };+ });+ }, [query.data]);++ const markdownReferences = useMemo<MarkdownExternalReferenceMap>(() => {+ const result: MarkdownExternalReferenceMap = {};+ for (const { group } of groups) {+ const object = group.object;+ if (!object) continue;+ // Index by the object's canonical URL.+ const canonical = normalizeExternalObjectHref(object.sanitizedCanonicalUrl ?? null);+ if (canonical) {+ result[canonical] = {+ providerKey: object.providerKey,+ objectType: object.objectType,+ displayKey: object.displayKey,+ iconKey: object.iconKey,+ statusCategory: object.statusCategory,+ liveness: object.liveness,+ statusLabel: object.statusLabel,+ statusIconKey: object.statusIconKey,+ displayTitle: object.displayTitle,+ };+ }+ // Also index by every mention's sanitized display URL so user-pasted+ // hrefs that differ only in case/punctuation still resolve.+ for (const mention of group.mentions) {+ const normalizedMention = normalizeExternalObjectHref(+ mention.sanitizedDisplayUrl ?? null,+ );+ if (normalizedMention && !result[normalizedMention]) {+ result[normalizedMention] = {+ providerKey: object.providerKey,+ objectType: object.objectType,+ displayKey: object.displayKey,+ iconKey: object.iconKey,+ statusCategory: object.statusCategory,+ liveness: object.liveness,+ statusLabel: object.statusLabel,+ statusIconKey: object.statusIconKey,+ displayTitle: object.displayTitle,+ };+ }+ }+ }+ return result;+ }, [groups]);++ const refetch = useCallback(() => {+ void query.refetch();+ }, [query.refetch]);++ return {+ isEnabled: externalObjectsFeature.isEnabled,+ groups,+ markdownReferences,+ isLoading: enabled && query.isLoading,+ isError: query.isError,+ refetch,+ };+}++export function useIssueExternalObjectSummary(issueId: string | null | undefined): {+ summary: ExternalObjectSummary | null;+ isLoading: boolean;+} {+ const externalObjectsFeature = useExternalObjectsFeature();+ const enabled = externalObjectsFeature.isEnabled && Boolean(issueId);+ const query = useQuery({+ queryKey: queryKeys.externalObjects.issueSummary(issueId ?? "__none__"),+ queryFn: () => externalObjectsApi.getIssueSummary(issueId!),+ enabled,+ staleTime: 60_000,+ });+ return {+ summary: query.data ?? null,+ isLoading: enabled && query.isLoading,+ };+}++export function useIssueExternalObjectSummaries(+ companyId: string | null | undefined,+ issueIds: readonly string[],+): {+ summaries: Map<string, ExternalObjectSummary>;+ isLoading: boolean;+ isReady: boolean;+} {+ const externalObjectsFeature = useExternalObjectsFeature();+ const normalizedIssueIds = useMemo(+ () => [...new Set(issueIds.filter((issueId) => issueId.length > 0))].sort(),+ [issueIds],+ );+ const enabled = externalObjectsFeature.isEnabled && Boolean(companyId) && normalizedIssueIds.length > 0;+ const query = useQuery({+ queryKey: queryKeys.externalObjects.issueSummaries(companyId ?? "__none__", normalizedIssueIds),+ queryFn: () => fetchIssueExternalObjectSummariesInBatches(companyId!, normalizedIssueIds),+ enabled,+ staleTime: 60_000,+ });+ const summaries = useMemo(+ () => new Map(Object.entries(query.data?.summaries ?? {})),+ [query.data?.summaries],+ );+ return {+ summaries,+ isLoading: enabled && query.isLoading,+ isReady: externalObjectsFeature.isLoaded && (!enabled || query.isSuccess),+ };+}++export function useProjectExternalObjectSummary(projectId: string | null | undefined): {+ summary: ExternalObjectSummary | null;+ isLoading: boolean;+} {+ const externalObjectsFeature = useExternalObjectsFeature();+ const enabled = externalObjectsFeature.isEnabled && Boolean(projectId);+ const query = useQuery({+ queryKey: queryKeys.externalObjects.projectSummary(projectId ?? "__none__"),+ queryFn: () => externalObjectsApi.getProjectSummary(projectId!),+ enabled,+ staleTime: 60_000,+ });+ return {+ summary: query.data ?? null,+ isLoading: enabled && query.isLoading,+ };+}diff --git a/ui/src/hooks/usePrefersReducedMotion.ts b/ui/src/hooks/usePrefersReducedMotion.tsnew file mode 100644index 0000000000..88bdd6a611--- /dev/null+++ b/ui/src/hooks/usePrefersReducedMotion.ts@@ -0,0 +1,23 @@+import { useEffect, useState } from "react";++const QUERY = "(prefers-reduced-motion: reduce)";++function getInitialValue(): boolean {+ if (typeof window === "undefined" || !window.matchMedia) return false;+ return window.matchMedia(QUERY).matches;+}++export function usePrefersReducedMotion(): boolean {+ const [reduced, setReduced] = useState<boolean>(getInitialValue);++ useEffect(() => {+ if (typeof window === "undefined" || !window.matchMedia) return;+ const media = window.matchMedia(QUERY);+ const handler = (event: MediaQueryListEvent) => setReduced(event.matches);+ setReduced(media.matches);+ media.addEventListener("change", handler);+ return () => media.removeEventListener("change", handler);+ }, []);++ return reduced;+}diff --git a/ui/src/index.css b/ui/src/index.cssindex 6c5e2b7c58..f3da45a2ce 100644--- a/ui/src/index.css+++ b/ui/src/index.css@@ -1097,6 +1097,13 @@ a.paperclip-mention-chip[data-mention-kind="agent"]::before {white-space: nowrap;}+/* External object URL decorations follow the same pattern: the host renders+ the icon prefix, the link text is left untouched (Postel's Law). */+.paperclip-markdown-external-ref {+ display: inline;+ white-space: nowrap;+}+.dark .paperclip-markdown a {color: color-mix(in oklab, var(--foreground) 80%, #58a6ff 20%);}@@ -1206,6 +1213,25 @@ span.paperclip-project-mention-chip {white-space: nowrap;}+/* Touch target floor: WCAG 2.5.5 expects ≥24px on coarse pointers. The base+ chip is 22px; bump it on touch viewports without disturbing inline metrics. */+@media (pointer: coarse) {+ a.paperclip-mention-chip,+ a.paperclip-project-mention-chip,+ span.paperclip-mention-chip,+ span.paperclip-project-mention-chip {+ min-height: 24px;+ }+}++/* External object pills: variant marker the host renders for known-resolved+ external URLs. Inline status icon is rendered by ExternalObjectStatusIcon. */+a.paperclip-mention-chip[data-mention-kind="external-object"],+span.paperclip-mention-chip[data-mention-kind="external-object"] {+ /* Inherit base chip styling; status colour comes from inline classes so the+ host can vary tone per category without defining a CSS variant per state. */+}+/* When the identifier inside a chip is backtick-wrapped in markdown, strip theinline-code monospace/gray styling so the pill label reads cleanly. */.paperclip-markdown a.paperclip-mention-chip code,diff --git a/ui/src/lib/external-object-href.ts b/ui/src/lib/external-object-href.tsnew file mode 100644index 0000000000..eeb2d3b660--- /dev/null+++ b/ui/src/lib/external-object-href.ts@@ -0,0 +1,32 @@+/**+ * Browser-safe URL key for matching markdown hrefs against the+ * `external_objects.sanitizedCanonicalUrl` returned by the host API.+ *+ * The shared/server canonicalizer is the source of truth for the canonical+ * URL string, but it imports from `node:crypto` (it also produces an identity+ * hash) and therefore cannot run in the browser. We replicate just the URL+ * normalization here:+ *+ * - protocol must be http or https+ * - reject userinfo (`username:password@`)+ * - lowercase host+ * - drop query string + fragment+ * - default empty pathname to `/`+ */+export function normalizeExternalObjectHref(value: string | null | undefined): string | null {+ if (!value) return null;++ let url: URL;+ try {+ url = new URL(value.trim());+ } catch {+ return null;+ }++ if (url.protocol !== "http:" && url.protocol !== "https:") return null;+ if (url.username || url.password) return null;++ const scheme = url.protocol === "https:" ? "https" : "http";+ const path = url.pathname || "/";+ return `${scheme}://${url.host.toLowerCase()}${path}`;+}diff --git a/ui/src/lib/external-objects.test.ts b/ui/src/lib/external-objects.test.tsnew file mode 100644index 0000000000..70ae3560c4--- /dev/null+++ b/ui/src/lib/external-objects.test.ts@@ -0,0 +1,190 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import type { ExternalObjectSummary } from "@paperclipai/shared";+import { externalObjectsApi } from "../api/externalObjects";+import {+ EXTERNAL_OBJECT_SUMMARY_BATCH_SIZE,+ fetchIssueExternalObjectSummariesInBatches,+} from "../hooks/useIssueExternalObjects";+import {+ dominantExternalObjectTone,+ externalObjectCategoryLabel,+ externalObjectDominantCount,+ externalObjectFallbackTone,+ externalObjectIconForCategory,+ externalObjectIconForKey,+ externalObjectLivenessLabel,+ externalObjectProviderLabel,+ externalObjectToneSeverity,+ externalObjectTypeLabel,+ sortExternalObjectsBySeverity,+} from "./external-objects";+import { normalizeExternalObjectHref } from "./external-object-href";++vi.mock("../api/externalObjects", () => ({+ externalObjectsApi: {+ getIssueSummaries: vi.fn(),+ },+}));++const emptySummary: ExternalObjectSummary = {+ total: 0,+ byStatusCategory: {},+ byLiveness: {},+ highestSeverity: "neutral",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+};++describe("normalizeExternalObjectHref", () => {+ it("lowercases the host (case preserving the path) and drops query/fragment", () => {+ expect(+ normalizeExternalObjectHref("HTTPS://Github.com/Acme/Web/pull/241?token=abc#frag"),+ ).toBe("https://github.com/Acme/Web/pull/241");+ });++ it("rejects non-http(s) and userinfo-bearing URLs", () => {+ expect(normalizeExternalObjectHref("javascript:alert(1)")).toBeNull();+ expect(normalizeExternalObjectHref("ftp://example.com/file")).toBeNull();+ expect(normalizeExternalObjectHref("https://user:[email protected]/")).toBeNull();+ expect(normalizeExternalObjectHref(null)).toBeNull();+ expect(normalizeExternalObjectHref(undefined)).toBeNull();+ expect(normalizeExternalObjectHref("not a url")).toBeNull();+ });++ it("defaults pathless URLs to /", () => {+ expect(normalizeExternalObjectHref("https://example.com")).toBe("https://example.com/");+ });+});++describe("fetchIssueExternalObjectSummariesInBatches", () => {+ afterEach(() => {+ vi.mocked(externalObjectsApi.getIssueSummaries).mockReset();+ });++ it("chunks bulk summary requests below the server validation cap and merges results", async () => {+ const issueIds = Array.from(+ { length: EXTERNAL_OBJECT_SUMMARY_BATCH_SIZE * 2 + 3 },+ (_entry, index) => `issue-${index}`,+ );+ vi.mocked(externalObjectsApi.getIssueSummaries).mockImplementation(async (_companyId, ids) => ({+ summaries: Object.fromEntries(ids.map((id) => [id, { ...emptySummary, total: id.endsWith("-0") ? 1 : 0 }])),+ }));++ const result = await fetchIssueExternalObjectSummariesInBatches("company-1", issueIds);++ expect(externalObjectsApi.getIssueSummaries).toHaveBeenCalledTimes(3);+ expect(vi.mocked(externalObjectsApi.getIssueSummaries).mock.calls.map((call) => call[1].length)).toEqual([+ EXTERNAL_OBJECT_SUMMARY_BATCH_SIZE,+ EXTERNAL_OBJECT_SUMMARY_BATCH_SIZE,+ 3,+ ]);+ expect(Object.keys(result.summaries)).toHaveLength(issueIds.length);+ expect(result.summaries["issue-0"]?.total).toBe(1);+ });+});++describe("external-objects helpers", () => {+ it("labels categories with copy from the UX spec", () => {+ expect(externalObjectCategoryLabel("auth_required")).toBe("Authorization required");+ expect(externalObjectCategoryLabel("succeeded")).toBe("Succeeded");+ expect(externalObjectCategoryLabel("unknown")).toBe("Not yet resolved");+ });++ it("labels liveness states with non-tech copy", () => {+ expect(externalObjectLivenessLabel("stale")).toBe("Stale");+ expect(externalObjectLivenessLabel("auth_required")).toBe("Requires auth");+ expect(externalObjectLivenessLabel("fresh")).toBe("Fresh");+ });++ it("falls back to a humanised label for unknown providers and types", () => {+ expect(externalObjectProviderLabel("github")).toBe("GitHub");+ expect(externalObjectProviderLabel("hubspot_marketing")).toBe("Hubspot Marketing");+ expect(externalObjectProviderLabel(null)).toBe("External");+ expect(externalObjectTypeLabel("workflow_run")).toBe("workflow run");+ expect(externalObjectTypeLabel(null)).toBe("object");+ });++ it("orders tones from danger down to muted", () => {+ expect(externalObjectToneSeverity("danger")).toBeGreaterThan(externalObjectToneSeverity("warning"));+ expect(externalObjectToneSeverity("warning")).toBeGreaterThan(externalObjectToneSeverity("info"));+ expect(externalObjectToneSeverity("info")).toBeGreaterThan(externalObjectToneSeverity("success"));+ expect(externalObjectToneSeverity("success")).toBeGreaterThan(externalObjectToneSeverity("muted"));+ expect(externalObjectToneSeverity(null)).toBe(0);+ expect(externalObjectToneSeverity("nonsense")).toBe(0);+ });++ it("maps every spec category to a fallback tone", () => {+ expect(externalObjectFallbackTone("failed")).toBe("danger");+ expect(externalObjectFallbackTone("waiting")).toBe("warning");+ expect(externalObjectFallbackTone("running")).toBe("info");+ expect(externalObjectFallbackTone("succeeded")).toBe("success");+ expect(externalObjectFallbackTone("auth_required")).toBe("warning");+ expect(externalObjectFallbackTone("unreachable")).toBe("danger");+ });++ it("returns the spec lucide icon names for every category", () => {+ expect(externalObjectIconForCategory("succeeded").displayName ?? "").toMatch(/CheckCircle2|Check/);+ expect(externalObjectIconForCategory("failed").displayName ?? "").toMatch(/XCircle|X/);+ expect(externalObjectIconForCategory("auth_required").displayName ?? "").toMatch(/KeyRound|Key/);+ expect(externalObjectIconForCategory("unreachable").displayName ?? "").toMatch(/CloudOff|Cloud/);+ expect(externalObjectIconForCategory("running").displayName ?? "").toMatch(/Loader2|Loader/);+ });++ it("maps provider-controlled icon keys through host-owned icons", () => {+ expect(externalObjectIconForKey("github")?.displayName ?? "").toMatch(/Github/i);+ expect(externalObjectIconForKey("git-pull-request")?.displayName ?? "").toMatch(/GitPullRequest/i);+ expect(externalObjectIconForKey("unknown-provider-icon")).toBeNull();+ });++ it("sorts items by severity first, preserving insertion order within a tone", () => {+ const items = [+ { id: "a", statusTone: "info", providerKey: "github", objectType: "pull_request", displayTitle: null, statusCategory: "running", liveness: "fresh", isTerminal: false },+ { id: "b", statusTone: "danger", providerKey: "ci", objectType: "deployment", displayTitle: null, statusCategory: "failed", liveness: "fresh", isTerminal: false },+ { id: "c", statusTone: "warning", providerKey: "hubspot", objectType: "lead", displayTitle: null, statusCategory: "waiting", liveness: "fresh", isTerminal: false },+ { id: "d", statusTone: "danger", providerKey: "github", objectType: "issue", displayTitle: null, statusCategory: "blocked", liveness: "fresh", isTerminal: false },+ ] as const;+ const sorted = sortExternalObjectsBySeverity(items as never);+ expect(sorted.map((item) => item.id)).toEqual(["b", "d", "c", "a"]);+ });++ it("hides the rollup when every item is in a muted tone", () => {+ const summary = {+ total: 2,+ byStatusCategory: { closed: 2 },+ byLiveness: { fresh: 2 },+ highestSeverity: "muted" as const,+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [+ { id: "a", providerKey: "x", objectType: "y", displayTitle: null, statusCategory: "closed" as const, statusTone: "muted" as const, liveness: "fresh" as const, isTerminal: true },+ { id: "b", providerKey: "x", objectType: "y", displayTitle: null, statusCategory: "closed" as const, statusTone: "muted" as const, liveness: "fresh" as const, isTerminal: true },+ ],+ };+ expect(dominantExternalObjectTone(summary)).toBeNull();+ expect(externalObjectDominantCount(summary)).toBe(0);+ });++ it("counts only the dominant-severity items in the rollup", () => {+ const summary = {+ total: 5,+ byStatusCategory: { failed: 3, succeeded: 2 },+ byLiveness: { fresh: 5 },+ highestSeverity: "danger" as const,+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [+ { id: "a", providerKey: "ci", objectType: "deployment", displayTitle: null, statusCategory: "failed" as const, statusTone: "danger" as const, liveness: "fresh" as const, isTerminal: false },+ { id: "b", providerKey: "ci", objectType: "deployment", displayTitle: null, statusCategory: "failed" as const, statusTone: "danger" as const, liveness: "fresh" as const, isTerminal: false },+ { id: "c", providerKey: "ci", objectType: "deployment", displayTitle: null, statusCategory: "failed" as const, statusTone: "danger" as const, liveness: "fresh" as const, isTerminal: false },+ { id: "d", providerKey: "github", objectType: "pull_request", displayTitle: null, statusCategory: "succeeded" as const, statusTone: "success" as const, liveness: "fresh" as const, isTerminal: true },+ { id: "e", providerKey: "github", objectType: "pull_request", displayTitle: null, statusCategory: "succeeded" as const, statusTone: "success" as const, liveness: "fresh" as const, isTerminal: true },+ ],+ };+ expect(dominantExternalObjectTone(summary)).toBe("danger");+ expect(externalObjectDominantCount(summary)).toBe(3);+ });+});diff --git a/ui/src/lib/external-objects.ts b/ui/src/lib/external-objects.tsnew file mode 100644index 0000000000..76ca0c91c0--- /dev/null+++ b/ui/src/lib/external-objects.ts@@ -0,0 +1,236 @@+import {+ AlertCircle,+ AlertOctagon,+ Archive,+ CheckCircle2,+ Circle,+ CircleDashed,+ CircleDot,+ Clock,+ CloudOff,+ GitMerge,+ Github,+ GitPullRequest,+ KeyRound,+ Loader2,+ XCircle,+ type LucideIcon,+} from "lucide-react";+import type {+ ExternalObjectLivenessState,+ ExternalObjectStatusCategory,+ ExternalObjectStatusTone,+ ExternalObjectSummary,+ ExternalObjectSummaryItem,+} from "@paperclipai/shared";++/**+ * Lucide icon for each status category. The mapping is host-owned per the+ * Phase 1B security review — providers never inject inline React.+ */+export const externalObjectCategoryIcon: Record<string, LucideIcon> = {+ unknown: CircleDashed,+ open: CircleDot,+ waiting: Clock,+ running: Loader2,+ succeeded: CheckCircle2,+ failed: XCircle,+ blocked: AlertOctagon,+ closed: Circle,+ archived: Archive,+ auth_required: KeyRound,+ unreachable: CloudOff,+};++export const externalObjectCategoryIconDefault: LucideIcon = CircleDashed;++export function externalObjectIconForCategory(category: string): LucideIcon {+ return externalObjectCategoryIcon[category] ?? externalObjectCategoryIconDefault;+}++const EXTERNAL_OBJECT_ICON_KEYS: Record<string, LucideIcon> = {+ archive: Archive,+ check: CheckCircle2,+ "check-circle": CheckCircle2,+ circle: Circle,+ "circle-dot": CircleDot,+ clock: Clock,+ github: Github,+ "git-merge": GitMerge,+ "git-pull-request": GitPullRequest,+ key: KeyRound,+ loader: Loader2,+ "x-circle": XCircle,+};++export function externalObjectIconForKey(iconKey: string | null | undefined): LucideIcon | null {+ if (!iconKey) return null;+ return EXTERNAL_OBJECT_ICON_KEYS[iconKey] ?? null;+}++export function externalObjectIconForLiveness(liveness: string): LucideIcon | null {+ if (liveness === "auth_required") return KeyRound;+ if (liveness === "unreachable") return CloudOff;+ return null;+}++const CATEGORY_LABELS: Record<string, string> = {+ unknown: "Not yet resolved",+ open: "Open",+ waiting: "Waiting",+ running: "Running",+ succeeded: "Succeeded",+ failed: "Failed",+ blocked: "Blocked",+ closed: "Closed",+ archived: "Archived",+ auth_required: "Authorization required",+ unreachable: "Unreachable",+};++export function externalObjectCategoryLabel(category: string): string {+ return CATEGORY_LABELS[category] ?? category.replace(/_/g, " ");+}++const LIVENESS_LABELS: Record<string, string> = {+ unknown: "Not yet refreshed",+ fresh: "Fresh",+ stale: "Stale",+ auth_required: "Requires auth",+ unreachable: "Unreachable",+};++export function externalObjectLivenessLabel(liveness: string): string {+ return LIVENESS_LABELS[liveness] ?? liveness.replace(/_/g, " ");+}++/**+ * Higher number = more attention-worthy. The rollups in §5 sort by tone first.+ * Mirrors `externalObjectStatusToneSeverity` in `status-colors.ts`.+ */+const TONE_SEVERITY: Record<string, number> = {+ muted: 0,+ neutral: 1,+ success: 2,+ info: 3,+ warning: 4,+ danger: 5,+};++export function externalObjectToneSeverity(tone: string | null | undefined): number {+ if (!tone) return 0;+ return TONE_SEVERITY[tone] ?? 0;+}++const CATEGORY_TONE_FALLBACK: Record<string, ExternalObjectStatusTone> = {+ unknown: "muted",+ open: "info",+ waiting: "warning",+ running: "info",+ succeeded: "success",+ failed: "danger",+ blocked: "danger",+ closed: "muted",+ archived: "muted",+ auth_required: "warning",+ unreachable: "danger",+};++export function externalObjectFallbackTone(+ category: ExternalObjectStatusCategory,+): ExternalObjectStatusTone {+ return CATEGORY_TONE_FALLBACK[category] ?? "neutral";+}++const PROVIDER_LABELS: Record<string, string> = {+ github: "GitHub",+ github_pull_request: "GitHub",+ github_issue: "GitHub",+ hubspot: "HubSpot",+ linear: "Linear",+ jira: "Jira",+ notion: "Notion",+ asana: "Asana",+};++export function externalObjectProviderLabel(providerKey: string | null | undefined): string {+ if (!providerKey) return "External";+ const lookup = PROVIDER_LABELS[providerKey];+ if (lookup) return lookup;+ return providerKey+ .split(/[._-]/)+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))+ .join(" ");+}++const OBJECT_TYPE_LABELS: Record<string, string> = {+ pull_request: "pull request",+ issue: "issue",+ deployment: "deployment",+ workflow_run: "workflow run",+ ticket: "ticket",+ lead: "lead",+};++export function externalObjectTypeLabel(objectType: string | null | undefined): string {+ if (!objectType) return "object";+ return OBJECT_TYPE_LABELS[objectType] ?? objectType.replace(/_/g, " ");+}++/**+ * Sort summary items by severity-first ordering: danger → warning → info →+ * success → muted/neutral. Within a tone, items keep their incoming order so+ * server-side ordering (e.g. most recent change first) is preserved.+ */+export function sortExternalObjectsBySeverity<T extends ExternalObjectSummaryItem>(+ items: readonly T[],+): T[] {+ return [...items]+ .map((item, index) => ({ item, index }))+ .sort((a, b) => {+ const aTone = externalObjectToneSeverity(a.item.statusTone);+ const bTone = externalObjectToneSeverity(b.item.statusTone);+ if (aTone !== bTone) return bTone - aTone;+ return a.index - b.index;+ })+ .map(({ item }) => item);+}++/**+ * Compute the dominant tone in a summary — used by sidebar / list rollups.+ * Falls back to `null` when no objects are present or every tone is `muted`.+ */+export function dominantExternalObjectTone(+ summary: Pick<ExternalObjectSummary, "highestSeverity" | "objects"> | null | undefined,+): ExternalObjectStatusTone | null {+ if (!summary) return null;+ const tone = summary.highestSeverity;+ if (!tone) return null;+ if (externalObjectToneSeverity(tone) <= TONE_SEVERITY.muted) return null;+ return tone;+}++/**+ * For the sidebar / list rollup we want the count of objects matching the+ * dominant severity (e.g. "3 failed PRs"), not the global total. Returns 0+ * whenever the dominant tone is muted so callers can render based on the+ * count without double-checking the rollup-hide rule.+ */+export function externalObjectDominantCount(+ summary: Pick<ExternalObjectSummary, "highestSeverity" | "objects"> | null | undefined,+): number {+ if (!summary) return 0;+ const tone = dominantExternalObjectTone(summary);+ if (!tone) return 0;+ return summary.objects.filter((object) => object.statusTone === tone).length;+}++/**+ * Reduced motion support — match `prefers-reduced-motion: reduce` so the+ * spinning Loader2 stays static when requested. Hooks consume this via React+ * to react to runtime changes; non-hook callers can use the helper directly.+ */+export function prefersReducedMotion(): boolean {+ if (typeof window === "undefined" || !window.matchMedia) return false;+ return window.matchMedia("(prefers-reduced-motion: reduce)").matches;+}diff --git a/ui/src/lib/inbox.test.ts b/ui/src/lib/inbox.test.tsindex d18bc7c89e..e17c8418f6 100644--- a/ui/src/lib/inbox.test.ts+++ b/ui/src/lib/inbox.test.ts@@ -5,6 +5,7 @@ import type {Approval,DashboardSummary,ExecutionWorkspace,+ ExternalObjectSummary,HeartbeatRun,Issue,JoinRequest,@@ -909,6 +910,7 @@ describe("inbox helpers", () => {projects: [],workspaces: [],liveOnly: false,+ externalObjectStatuses: [],hideRoutineExecutions: true,},}).map((issue) => issue.id),@@ -929,6 +931,7 @@ describe("inbox helpers", () => {projects: [],workspaces: [],liveOnly: false,+ externalObjectStatuses: [],hideRoutineExecutions: true,},}),@@ -949,12 +952,65 @@ describe("inbox helpers", () => {projects: [],workspaces: [],liveOnly: false,+ externalObjectStatuses: [],hideRoutineExecutions: true,},}),).toEqual([]);});+ it("applies external-object filters to remote inbox search supplements", () => {+ const failedMatch = makeIssue("failed-match", false);+ const freshMatch = makeIssue("fresh-match", false);+ const summaries = new Map<string, ExternalObjectSummary>([+ ["failed-match", {+ total: 1,+ byStatusCategory: { failed: 1 },+ byLiveness: { fresh: 1 },+ highestSeverity: "danger",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+ }],+ ["fresh-match", {+ total: 1,+ byStatusCategory: { succeeded: 1 },+ byLiveness: { fresh: 1 },+ highestSeverity: "success",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+ }],+ ]);++ expect(+ getInboxSearchSupplementIssues({+ query: "github",+ filteredWorkItems: [],+ archivedSearchIssues: [],+ remoteIssues: [failedMatch, freshMatch],+ issueFilters: {+ statuses: [],+ priorities: [],+ assignees: [],+ creators: [],+ labels: [],+ projects: [],+ workspaces: [],+ liveOnly: false,+ externalObjectStatuses: ["failed"],+ hideRoutineExecutions: true,+ },+ issueFilterContext: {+ externalObjectSummaryByIssueId: summaries,+ externalObjectSummariesReady: true,+ },+ }).map((issue) => issue.id),+ ).toEqual(["failed-match"]);+ });+it("keeps inbox search matches ahead of archived and other result sections", () => {const inboxIssue = makeIssue("inbox", false);inboxIssue.lastActivityAt = new Date("2026-03-11T04:00:00.000Z");@@ -1021,6 +1077,7 @@ describe("inbox helpers", () => {projects: ["project-1"],workspaces: ["workspace-1"],liveOnly: true,+ externalObjectStatuses: [],hideRoutineExecutions: false,},});@@ -1036,6 +1093,7 @@ describe("inbox helpers", () => {projects: [],workspaces: [],liveOnly: false,+ externalObjectStatuses: [],hideRoutineExecutions: true,},});@@ -1052,6 +1110,7 @@ describe("inbox helpers", () => {projects: ["project-1"],workspaces: ["workspace-1"],liveOnly: true,+ externalObjectStatuses: [],hideRoutineExecutions: false,},});@@ -1067,6 +1126,7 @@ describe("inbox helpers", () => {projects: [],workspaces: [],liveOnly: false,+ externalObjectStatuses: [],hideRoutineExecutions: true,},});@@ -1101,6 +1161,7 @@ describe("inbox helpers", () => {projects: ["project-1"],workspaces: ["workspace-1"],liveOnly: false,+ externalObjectStatuses: [],hideRoutineExecutions: false,},});diff --git a/ui/src/lib/inbox.ts b/ui/src/lib/inbox.tsindex 780aeb3bcf..48885d8085 100644--- a/ui/src/lib/inbox.ts+++ b/ui/src/lib/inbox.ts@@ -11,6 +11,7 @@ import {defaultIssueFilterState,normalizeIssueFilterState,type IssueFilterState,+ type IssueFilterWorkspaceContext,} from "./issue-filters";import { formatAssigneeUserLabel } from "./assignees";@@ -462,6 +463,7 @@ export function getInboxSearchSupplementIssues({currentUserId,enableRoutineVisibilityFilter = false,liveIssueIds,+ issueFilterContext = {},}: {query: string;filteredWorkItems: InboxWorkItem[];@@ -471,6 +473,7 @@ export function getInboxSearchSupplementIssues({currentUserId?: string | null;enableRoutineVisibilityFilter?: boolean;liveIssueIds?: ReadonlySet<string>;+ issueFilterContext?: IssueFilterWorkspaceContext;}): Issue[] {const normalizedQuery = query.trim();if (!normalizedQuery) return [];@@ -480,7 +483,14 @@ export function getInboxSearchSupplementIssues({.map((item) => item.issue.id),...archivedSearchIssues.map((issue) => issue.id),]);- return applyIssueFilters(remoteIssues, issueFilters, currentUserId, enableRoutineVisibilityFilter, liveIssueIds)+ return applyIssueFilters(+ remoteIssues,+ issueFilters,+ currentUserId,+ enableRoutineVisibilityFilter,+ liveIssueIds,+ issueFilterContext,+ ).filter((issue) => !visibleIssueIds.has(issue.id));}diff --git a/ui/src/lib/issue-filters.test.ts b/ui/src/lib/issue-filters.test.tsindex bb0afde7ac..4e210b19bf 100644--- a/ui/src/lib/issue-filters.test.ts+++ b/ui/src/lib/issue-filters.test.ts@@ -1,7 +1,7 @@// @vitest-environment nodeimport { describe, expect, it } from "vitest";-import type { Issue } from "@paperclipai/shared";+import type { ExternalObjectSummary, Issue } from "@paperclipai/shared";import {applyIssueFilters,countActiveIssueFilters,@@ -51,6 +51,20 @@ function makeIssue(overrides: Partial<Issue> = {}): Issue {};}+function makeExternalObjectSummary(overrides: Partial<ExternalObjectSummary> = {}): ExternalObjectSummary {+ return {+ total: 1,+ byStatusCategory: {},+ byLiveness: { fresh: 1 },+ highestSeverity: "neutral",+ staleCount: 0,+ authRequiredCount: 0,+ unreachableCount: 0,+ objects: [],+ ...overrides,+ };+}+describe("issue filters", () => {it("filters issues by creator across agents and users", () => {const issues = [@@ -169,4 +183,62 @@ describe("issue filters", () => {new Set(["workspace-default"]),)).toBe(true);});++ it.each([+ ["failed", ["failed-issue", "blocked-issue"]],+ ["auth_required", ["auth-issue"]],+ ["stale", ["stale-issue"]],+ ["none", ["none-issue"]],+ ])("filters issues by external-object status token %s", (externalObjectStatus, expectedIssueIds) => {+ const issues = [+ makeIssue({ id: "failed-issue" }),+ makeIssue({ id: "blocked-issue" }),+ makeIssue({ id: "auth-issue" }),+ makeIssue({ id: "stale-issue" }),+ makeIssue({ id: "none-issue" }),+ makeIssue({ id: "fresh-issue" }),+ ];+ const summaries = new Map<string, ExternalObjectSummary>([+ ["failed-issue", makeExternalObjectSummary({ byStatusCategory: { failed: 1 }, highestSeverity: "danger" })],+ ["blocked-issue", makeExternalObjectSummary({ byStatusCategory: { blocked: 1 }, highestSeverity: "danger" })],+ ["auth-issue", makeExternalObjectSummary({+ byLiveness: { auth_required: 1 },+ highestSeverity: "danger",+ authRequiredCount: 1,+ })],+ ["stale-issue", makeExternalObjectSummary({+ byLiveness: { stale: 1 },+ highestSeverity: "warning",+ staleCount: 1,+ })],+ ["fresh-issue", makeExternalObjectSummary({ byStatusCategory: { succeeded: 1 }, highestSeverity: "success" })],+ ]);++ const filtered = applyIssueFilters(+ issues,+ { ...defaultIssueFilterState, externalObjectStatuses: [externalObjectStatus] },+ null,+ false,+ undefined,+ {+ externalObjectSummaryByIssueId: summaries,+ externalObjectSummariesReady: true,+ },+ );++ expect(filtered.map((issue) => issue.id)).toEqual(expectedIssueIds);+ });++ it("does not apply external-object filters before summaries are ready", () => {+ const filtered = applyIssueFilters(+ [makeIssue({ id: "issue-1" })],+ { ...defaultIssueFilterState, externalObjectStatuses: ["none"] },+ null,+ false,+ undefined,+ { externalObjectSummaryByIssueId: new Map(), externalObjectSummariesReady: false },+ );++ expect(filtered).toEqual([]);+ });});diff --git a/ui/src/lib/issue-filters.ts b/ui/src/lib/issue-filters.tsindex 63ce019378..a0576a5305 100644--- a/ui/src/lib/issue-filters.ts+++ b/ui/src/lib/issue-filters.ts@@ -1,4 +1,4 @@-import type { Issue } from "@paperclipai/shared";+import type { ExternalObjectSummary, Issue } from "@paperclipai/shared";export type IssueFilterWorkspaceLookup = {mode?: string | null;@@ -8,6 +8,8 @@ export type IssueFilterWorkspaceLookup = {export type IssueFilterWorkspaceContext = {executionWorkspaceById?: ReadonlyMap<string, IssueFilterWorkspaceLookup>;defaultProjectWorkspaceIdByProjectId?: ReadonlyMap<string, string>;+ externalObjectSummaryByIssueId?: ReadonlyMap<string, ExternalObjectSummary>;+ externalObjectSummariesReady?: boolean;};export type IssueFilterState = {@@ -19,6 +21,21 @@ export type IssueFilterState = {projects: string[];workspaces: string[];liveOnly?: boolean;+ /**+ * External object status filter. Values are special tokens that map to+ * properties of the issue's external-object summary (rather than to a+ * single category) so the filter UI can describe intent rather than every+ * possible permutation.+ *+ * - `failed` — any external object with `statusCategory in (failed, blocked)`+ * - `waiting` — any external object with `statusCategory in (waiting)`+ * - `running` — any external object with `statusCategory in (running)`+ * - `auth_required` — any external object with `liveness == auth_required`+ * - `unreachable` — any external object with `liveness == unreachable`+ * - `stale` — any external object with `liveness == stale`+ * - `none` — issues with zero external objects+ */+ externalObjectStatuses: string[];hideRoutineExecutions: boolean;};@@ -31,9 +48,34 @@ export const defaultIssueFilterState: IssueFilterState = {projects: [],workspaces: [],liveOnly: false,+ externalObjectStatuses: [],hideRoutineExecutions: false,};+export const externalObjectFilterOrder = [+ "failed",+ "waiting",+ "running",+ "auth_required",+ "unreachable",+ "stale",+ "none",+];++const EXTERNAL_OBJECT_FILTER_LABELS: Record<string, string> = {+ failed: "Any failed",+ waiting: "Any waiting",+ running: "Any running",+ auth_required: "Auth required",+ unreachable: "Unreachable",+ stale: "Stale",+ none: "No external objects",+};++export function externalObjectFilterLabel(value: string): string {+ return EXTERNAL_OBJECT_FILTER_LABELS[value] ?? issueFilterLabel(value);+}+export const issueStatusOrder = ["in_progress", "todo", "backlog", "in_review", "blocked", "done", "cancelled"];export const issuePriorityOrder = ["critical", "high", "medium", "low"];@@ -72,6 +114,7 @@ export function normalizeIssueFilterState(value: unknown): IssueFilterState {projects: normalizeIssueFilterValueArray(candidate.projects),workspaces: normalizeIssueFilterValueArray(candidate.workspaces),liveOnly: candidate.liveOnly === true,+ externalObjectStatuses: normalizeIssueFilterValueArray(candidate.externalObjectStatuses),hideRoutineExecutions: candidate.hideRoutineExecutions === true,};}@@ -118,6 +161,39 @@ export function shouldIncludeIssueFilterWorkspaceOption(&& defaultProjectWorkspaceIds.has(workspace.projectWorkspaceId));}+function summaryRecordCount(record: Record<string, number> | undefined, key: string): number {+ return record?.[key] ?? 0;+}++function issueMatchesExternalObjectStatusFilter(+ summary: ExternalObjectSummary | null | undefined,+ value: string,+): boolean {+ const total = summary?.total ?? 0;+ switch (value) {+ case "failed":+ return summaryRecordCount(summary?.byStatusCategory, "failed") > 0+ || summaryRecordCount(summary?.byStatusCategory, "blocked") > 0;+ case "waiting":+ return summaryRecordCount(summary?.byStatusCategory, "waiting") > 0;+ case "running":+ return summaryRecordCount(summary?.byStatusCategory, "running") > 0;+ case "auth_required":+ return (summary?.authRequiredCount ?? 0) > 0+ || summaryRecordCount(summary?.byLiveness, "auth_required") > 0;+ case "unreachable":+ return (summary?.unreachableCount ?? 0) > 0+ || summaryRecordCount(summary?.byLiveness, "unreachable") > 0;+ case "stale":+ return (summary?.staleCount ?? 0) > 0+ || summaryRecordCount(summary?.byLiveness, "stale") > 0;+ case "none":+ return total === 0;+ default:+ return false;+ }+}+export function applyIssueFilters(issues: Issue[],state: IssueFilterState,@@ -166,6 +242,16 @@ export function applyIssueFilters(return workspaceId != null && state.workspaces.includes(workspaceId);});}+ if (state.externalObjectStatuses.length > 0) {+ const summaries = workspaceContext.externalObjectSummaryByIssueId;+ if (!summaries || workspaceContext.externalObjectSummariesReady !== true) return [];+ result = result.filter((issue) => {+ const summary = summaries.get(issue.id) ?? null;+ return state.externalObjectStatuses.some((status) =>+ issueMatchesExternalObjectStatusFilter(summary, status),+ );+ });+ }return result;}@@ -182,6 +268,7 @@ export function countActiveIssueFilters(if (state.projects.length > 0) count += 1;if (state.workspaces.length > 0) count += 1;if (state.liveOnly) count += 1;+ if (state.externalObjectStatuses.length > 0) count += 1;if (enableRoutineVisibilityFilter && state.hideRoutineExecutions) count += 1;return count;}diff --git a/ui/src/lib/queryKeys.ts b/ui/src/lib/queryKeys.tsindex d5429df38a..8583974684 100644--- a/ui/src/lib/queryKeys.ts+++ b/ui/src/lib/queryKeys.ts@@ -139,6 +139,13 @@ export const queryKeys = {list: (companyId: string) => ["projects", companyId] as const,detail: (id: string) => ["projects", "detail", id] as const,},+ externalObjects: {+ byIssue: (issueId: string) => ["external-objects", "by-issue", issueId] as const,+ issueSummary: (issueId: string) => ["external-objects", "issue-summary", issueId] as const,+ issueSummaries: (companyId: string, issueIds: readonly string[]) =>+ ["external-objects", "issue-summaries", companyId, issueIds] as const,+ projectSummary: (projectId: string) => ["external-objects", "project-summary", projectId] as const,+ },goals: {list: (companyId: string) => ["goals", companyId] as const,detail: (id: string) => ["goals", "detail", id] as const,diff --git a/ui/src/lib/status-colors.ts b/ui/src/lib/status-colors.tsindex bcedcedca7..267ade6830 100644--- a/ui/src/lib/status-colors.ts+++ b/ui/src/lib/status-colors.ts@@ -217,3 +217,86 @@ export const priorityColor: Record<string, string> = {};export const priorityColorDefault = "text-yellow-600 dark:text-yellow-400";++// ---------------------------------------------------------------------------+// External object status — colors & severity ranking+// ---------------------------------------------------------------------------+//+// Categories come from `EXTERNAL_OBJECT_STATUS_CATEGORIES` in @paperclipai/shared.+// The map keys here intentionally mirror the union — keep them in sync.+//+// Tone reuse rationale (see UX spec §1):+// unknown → backlog hue (muted, dashed circle)+// open → todo / blue+// waiting → amber (distinct from internal in_progress yellow)+// running → cyan, animated when motion is allowed+// succeeded → done / green+// failed → red+// blocked → red+// closed → muted neutral+// archived → muted neutral+// auth_required → amber + dashed+// unreachable → red + dashed++export const externalObjectStatusIcon: Record<string, string> = {+ unknown: "text-muted-foreground border-muted-foreground",+ open: "text-blue-600 border-blue-600 dark:text-blue-400 dark:border-blue-400",+ waiting: "text-amber-600 border-amber-600 dark:text-amber-400 dark:border-amber-400",+ running: "text-cyan-600 border-cyan-600 dark:text-cyan-400 dark:border-cyan-400",+ succeeded: "text-green-600 border-green-600 dark:text-green-400 dark:border-green-400",+ failed: "text-red-600 border-red-600 dark:text-red-400 dark:border-red-400",+ blocked: "text-red-600 border-red-600 dark:text-red-400 dark:border-red-400",+ closed: "text-neutral-500 border-neutral-500",+ archived: "text-neutral-500 border-neutral-500",+ auth_required: "text-amber-600 border-amber-600 dark:text-amber-400 dark:border-amber-400",+ unreachable: "text-red-600 border-red-600 dark:text-red-400 dark:border-red-400",+};++export const externalObjectStatusIconDefault = "text-muted-foreground border-muted-foreground";++export const externalObjectStatusBadge: Record<string, string> = {+ unknown: "bg-muted text-muted-foreground",+ open: "bg-blue-100 text-blue-700 dark:bg-blue-900/50 dark:text-blue-300",+ waiting: "bg-amber-100 text-amber-700 dark:bg-amber-900/50 dark:text-amber-300",+ running: "bg-cyan-100 text-cyan-700 dark:bg-cyan-900/50 dark:text-cyan-300",+ succeeded: "bg-green-100 text-green-700 dark:bg-green-900/50 dark:text-green-300",+ failed: "bg-red-100 text-red-700 dark:bg-red-900/50 dark:text-red-300",+ blocked: "bg-red-100 text-red-700 dark:bg-red-900/50 dark:text-red-300",+ closed: "bg-muted text-muted-foreground",+ archived: "bg-muted text-muted-foreground",+ auth_required: "bg-amber-100 text-amber-700 dark:bg-amber-900/50 dark:text-amber-300",+ unreachable: "bg-red-100 text-red-700 dark:bg-red-900/50 dark:text-red-300",+};++export const externalObjectStatusBadgeDefault = "bg-muted text-muted-foreground";++/**+ * Liveness overlay applied on top of the base status tone. We deliberately+ * encode it as utility classes (not a tone change) so callers can append the+ * overlay to any pill, icon, or marker without redefining colors.+ *+ * The dashed border + reduced opacity guarantees a non-color differentiator+ * for stale / auth_required / unreachable per WCAG 1.4.1.+ */+export const externalObjectLivenessOverlay: Record<string, string> = {+ unknown: "",+ fresh: "",+ stale: "opacity-70 [border-style:dashed]",+ auth_required: "[border-style:dashed]",+ unreachable: "[border-style:dashed]",+};++/**+ * Severity ranking used by sidebar/list rollups. Higher number = more+ * attention-worthy. Anything ≤ `muted` should be hidden when summarising.+ */+export const externalObjectStatusToneSeverity: Record<string, number> = {+ muted: 0,+ neutral: 1,+ success: 2,+ info: 3,+ warning: 4,+ danger: 5,+};++export const externalObjectStatusToneSeverityDefault = 0;diff --git a/ui/src/pages/Inbox.tsx b/ui/src/pages/Inbox.tsxindex b63218dc60..5a29c986d4 100644--- a/ui/src/pages/Inbox.tsx+++ b/ui/src/pages/Inbox.tsx@@ -25,6 +25,7 @@ import { useGeneralSettings } from "../context/GeneralSettingsContext";import { useSidebar } from "../context/SidebarContext";import { queryKeys } from "../lib/queryKeys";import { useDialogActions } from "../context/DialogContext";+import { useIssueExternalObjectSummaries } from "../hooks/useIssueExternalObjects";import {applyIssueFilters,countActiveIssueFilters,@@ -732,6 +733,7 @@ export function Inbox() {enabled: !!selectedCompanyId,});const isolatedWorkspacesEnabled = experimentalSettings?.enableIsolatedWorkspaces === true;+ const externalObjectsEnabled = experimentalSettings?.enableExternalObjects === true;const { data: executionWorkspaces = [] } = useQuery({queryKey: selectedCompanyId? queryKeys.executionWorkspaces.summaryList(selectedCompanyId)@@ -863,13 +865,49 @@ export function Inbox() {const mineIssues = useMemo(() => getRecentTouchedIssues(mineIssuesRaw), [mineIssuesRaw]);const touchedIssues = useMemo(() => getRecentTouchedIssues(touchedIssuesRaw), [touchedIssuesRaw]);+ const shouldUseIssueSearchSupplement =+ !!selectedCompanyId+ && normalizedSearchQuery.length > 0;+ const { data: remoteIssueSearchResults = [] } = useQuery({+ queryKey: [+ ...queryKeys.issues.search(selectedCompanyId!, normalizedSearchQuery, undefined, 25),+ "inbox-supplement",+ ],+ queryFn: () =>+ issuesApi.list(selectedCompanyId!, {+ q: normalizedSearchQuery,+ limit: 25,+ includeRoutineExecutions: true,+ }),+ enabled: shouldUseIssueSearchSupplement,+ placeholderData: (previousData) => previousData,+ });+ const inboxIssueIdsForExternalObjectSummaries = useMemo(() => {+ const issueIds = new Set<string>();+ for (const issue of mineIssues) issueIds.add(issue.id);+ for (const issue of touchedIssues) issueIds.add(issue.id);+ for (const issue of remoteIssueSearchResults) issueIds.add(issue.id);+ return [...issueIds];+ }, [mineIssues, remoteIssueSearchResults, touchedIssues]);+ const {+ summaries: externalObjectSummaryByIssueId,+ isLoading: externalObjectSummariesLoading,+ isReady: externalObjectSummariesReady,+ } = useIssueExternalObjectSummaries(+ selectedCompanyId,+ inboxIssueIdsForExternalObjectSummaries,+ );+ const issueFilterContext = useMemo(() => ({+ externalObjectSummaryByIssueId,+ externalObjectSummariesReady: externalObjectSummariesReady && !externalObjectSummariesLoading,+ }), [externalObjectSummariesLoading, externalObjectSummariesReady, externalObjectSummaryByIssueId]);const visibleMineIssues = useMemo(- () => applyIssueFilters(mineIssues, issueFilters, currentUserId, true, liveIssueIds),- [mineIssues, issueFilters, currentUserId, liveIssueIds],+ () => applyIssueFilters(mineIssues, issueFilters, currentUserId, true, liveIssueIds, issueFilterContext),+ [mineIssues, issueFilters, currentUserId, liveIssueIds, issueFilterContext],);const visibleTouchedIssues = useMemo(- () => applyIssueFilters(touchedIssues, issueFilters, currentUserId, true, liveIssueIds),- [touchedIssues, issueFilters, currentUserId, liveIssueIds],+ () => applyIssueFilters(touchedIssues, issueFilters, currentUserId, true, liveIssueIds, issueFilterContext),+ [touchedIssues, issueFilters, currentUserId, liveIssueIds, issueFilterContext],);const unreadTouchedIssues = useMemo(() => visibleTouchedIssues.filter((issue) => issue.isUnreadForMe),@@ -1160,23 +1198,6 @@ export function Inbox() {visibleTouchedIssues,],);- const shouldUseIssueSearchSupplement =- !!selectedCompanyId- && normalizedSearchQuery.length > 0;- const { data: remoteIssueSearchResults = [] } = useQuery({- queryKey: [- ...queryKeys.issues.search(selectedCompanyId!, normalizedSearchQuery, undefined, 25),- "inbox-supplement",- ],- queryFn: () =>- issuesApi.list(selectedCompanyId!, {- q: normalizedSearchQuery,- limit: 25,- includeRoutineExecutions: true,- }),- enabled: shouldUseIssueSearchSupplement,- placeholderData: (previousData) => previousData,- });const issueSearchSupplementResults = useMemo(() =>getInboxSearchSupplementIssues({@@ -1188,11 +1209,13 @@ export function Inbox() {currentUserId,enableRoutineVisibilityFilter: true,liveIssueIds,+ issueFilterContext,}),[archivedSearchIssues,currentUserId,filteredWorkItems,+ issueFilterContext,issueFilters,liveIssueIds,normalizedSearchQuery,@@ -1367,6 +1390,15 @@ export function Inbox() {issueFilters: { ...previous.issueFilters, ...patch },}));}, [updateFilterPreferences]);+ useEffect(() => {+ if (!experimentalSettingsLoaded || externalObjectsEnabled || issueFilters.externalObjectStatuses.length === 0) return;+ updateIssueFilters({ externalObjectStatuses: [] });+ }, [+ experimentalSettingsLoaded,+ externalObjectsEnabled,+ issueFilters.externalObjectStatuses.length,+ updateIssueFilters,+ ]);const updateAllCategoryFilter = useCallback((value: InboxCategoryFilter) => {updateFilterPreferences((previous) => ({ ...previous, allCategoryFilter: value }));}, [updateFilterPreferences]);@@ -2027,6 +2059,7 @@ export function Inbox() {projects={projects?.map((project) => ({ id: project.id, name: project.name }))}labels={labels?.map((label) => ({ id: label.id, name: label.name, color: label.color }))}currentUserId={currentUserId}+ enableExternalObjectFilters={externalObjectsEnabled}enableRoutineVisibilityFilterbuttonVariant="outline"iconOnly@@ -2124,6 +2157,7 @@ export function Inbox() {projects={projects?.map((project) => ({ id: project.id, name: project.name }))}labels={labels?.map((label) => ({ id: label.id, name: label.name, color: label.color }))}currentUserId={currentUserId}+ enableExternalObjectFilters={externalObjectsEnabled}enableRoutineVisibilityFilterbuttonVariant="outline"iconOnly@@ -2334,6 +2368,7 @@ export function Inbox() {key={`issue:${issue.id}`}issue={issue}issueLinkState={issueLinkState}+ externalObjectSummary={externalObjectSummaryByIssueId.get(issue.id) ?? null}selected={selected}className={isArchivingdiff --git a/ui/src/pages/InstanceExperimentalSettings.test.tsx b/ui/src/pages/InstanceExperimentalSettings.test.tsxindex 6a8d8dd5ff..9a8d837226 100644--- a/ui/src/pages/InstanceExperimentalSettings.test.tsx+++ b/ui/src/pages/InstanceExperimentalSettings.test.tsx@@ -53,6 +53,7 @@ function defaultExperimentalSettings(): InstanceExperimentalSettingsPayload {enableConferenceRoomChat: false,enableIssuePlanDecompositions: false,enableExperimentalFileViewer: false,+ enableExternalObjects: false,enableTaskWatchdogs: false,enableCloudSync: false,autoRestartDevServerWhenIdle: false,diff --git a/ui/src/pages/InstanceExperimentalSettings.tsx b/ui/src/pages/InstanceExperimentalSettings.tsxindex e16ab3501a..9c769817f2 100644--- a/ui/src/pages/InstanceExperimentalSettings.tsx+++ b/ui/src/pages/InstanceExperimentalSettings.tsx@@ -243,6 +243,7 @@ export function InstanceExperimentalSettings() {experimentalQuery.data?.enableExperimentalFileViewer === true;const enableTaskWatchdogs = experimentalQuery.data?.enableTaskWatchdogs === true;const enableCloudSync = experimentalQuery.data?.enableCloudSync === true;+ const enableExternalObjects = experimentalQuery.data?.enableExternalObjects === true;const autoRestartDevServerWhenIdle = experimentalQuery.data?.autoRestartDevServerWhenIdle === true;const enableIssueGraphLivenessAutoRecovery =experimentalQuery.data?.enableIssueGraphLivenessAutoRecovery === true;@@ -355,6 +356,24 @@ export function InstanceExperimentalSettings() {</div></section>+ <section className="rounded-xl border border-border bg-card p-5">+ <div className="flex items-start justify-between gap-4">+ <div className="space-y-1.5">+ <h2 className="text-sm font-semibold">Enable External Objects</h2>+ <p className="max-w-2xl text-sm text-muted-foreground">+ Detect external URLs in issues and show resolved status for pull requests, tickets, and other referenced+ work objects.+ </p>+ </div>+ <ToggleSwitch+ checked={enableExternalObjects}+ onCheckedChange={() => toggleMutation.mutate({ enableExternalObjects: !enableExternalObjects })}+ disabled={toggleMutation.isPending}+ aria-label="Toggle external objects experimental setting"+ />+ </div>+ </section>+<section className="rounded-xl border border-border bg-card p-5"><div className="flex items-start justify-between gap-4"><div className="space-y-1.5">diff --git a/ui/src/pages/IssueDetail.test.tsx b/ui/src/pages/IssueDetail.test.tsxindex 961fba00c0..43c894c9a8 100644--- a/ui/src/pages/IssueDetail.test.tsx+++ b/ui/src/pages/IssueDetail.test.tsx@@ -957,6 +957,7 @@ describe("IssueDetail", () => {mockInstanceSettingsApi.getExperimental.mockResolvedValue({enableIssuePlanDecompositions: false,enableExperimentalFileViewer: false,+ enableExternalObjects: false,});mockIssuesApi.listAcceptedPlanDecompositions.mockResolvedValue([]);conferenceRoomChatFlag.enabled = true;diff --git a/ui/src/pages/IssueDetail.tsx b/ui/src/pages/IssueDetail.tsxindex 342313bc0f..8ada911036 100644--- a/ui/src/pages/IssueDetail.tsx+++ b/ui/src/pages/IssueDetail.tsx@@ -79,6 +79,7 @@ import { IssueOutputSection } from "../components/issue-output/IssueOutputSectioimport { isImageAttachment } from "../lib/issue-attachments";import { getPromotedOutputAttachmentIds } from "../lib/issue-output";import { IssueSiblingNavigation } from "../components/IssueSiblingNavigation";+import type { MarkdownExternalReferenceMap } from "../components/MarkdownBody";import { IssuesList } from "../components/IssuesList";import { AgentIcon } from "../components/AgentIconPicker";import { IssueReferenceActivitySummary } from "../components/IssueReferenceActivitySummary";@@ -88,6 +89,7 @@ import { IssueScheduledRetryCard } from "../components/IssueScheduledRetryCard";import { IssueProperties } from "../components/IssueProperties";import { PauseAffectsSummaryView } from "../components/interrupt-handoff/InterruptHandoffViews";import { computePauseAffectsSummary } from "../lib/interrupt-handoff";+import { useIssueExternalObjects } from "../hooks/useIssueExternalObjects";import { IssueRunLedger } from "../components/IssueRunLedger";import { IssueWorkspaceCard } from "../components/IssueWorkspaceCard";import type { MentionOption } from "../components/MarkdownEditor";@@ -743,6 +745,7 @@ type IssueDetailChatTabProps = {assigneeUserId: string | null;onResumeFromBacklog?: () => Promise<void> | void;resumeFromBacklogPending?: boolean;+ externalReferences?: MarkdownExternalReferenceMap;};const IssueDetailChatTab = memo(function IssueDetailChatTab({@@ -804,6 +807,7 @@ const IssueDetailChatTab = memo(function IssueDetailChatTab({assigneeUserId,onResumeFromBacklog,resumeFromBacklogPending,+ externalReferences,}: IssueDetailChatTabProps) {// Conference Room Chat experimental flag (PAP-136/PAP-139): ON renders the// NUX thread (bubbles, metadata rows, composer chrome); OFF renders the@@ -1028,6 +1032,7 @@ const IssueDetailChatTab = memo(function IssueDetailChatTab({onResumeFromBacklog={onResumeFromBacklog}resumeFromBacklogPending={resumeFromBacklogPending}footer={footer}+ externalReferences={externalReferences}/></div>);@@ -1048,6 +1053,7 @@ type IssueDetailActivityTabProps = {onCheckMonitorNow: () => void;checkingMonitorNow: boolean;handoffFocusSignal?: number;+ externalReferences?: MarkdownExternalReferenceMap;};function IssueDetailActivityTab({@@ -1065,6 +1071,7 @@ function IssueDetailActivityTab({onCheckMonitorNow,checkingMonitorNow,handoffFocusSignal = 0,+ externalReferences,}: IssueDetailActivityTabProps) {const { data: activity, isLoading: activityLoading } = useQuery({queryKey: queryKeys.issues.activity(issueId),@@ -1266,6 +1273,11 @@ function IssueDetailActivityTab({}}/></div>+ <IssueContinuationHandoff+ document={continuationHandoff}+ focusSignal={handoffFocusSignal}+ externalReferences={externalReferences}+ />{linkedApprovals && linkedApprovals.length > 0 && (<div className="mb-3 space-y-3">{linkedApprovals.map((approval) => (@@ -1286,7 +1298,6 @@ function IssueDetailActivityTab({))}</div>)}- <IssueContinuationHandoff document={continuationHandoff} focusSignal={handoffFocusSignal} /><IssueScheduledRetryCard issueId={issue.id} scheduledRetry={issue.scheduledRetry ?? null} /><IssueMonitorActivityCardissue={issue}@@ -1355,6 +1366,7 @@ export function IssueDetail() {enabled: !!issueId,});const resolvedCompanyId = issue?.companyId ?? selectedCompanyId;+ const externalObjectsState = useIssueExternalObjects(issue?.id ?? null);const commentComposerDisabledReason = useMemo(() => {if (!issue?.currentExecutionWorkspace || !isClosedIsolatedExecutionWorkspace(issue.currentExecutionWorkspace)) {return null;@@ -2859,6 +2871,10 @@ export function IssueDetail() {onAddSubIssue={openNewSubIssue}onUpdate={handleIssuePropertiesUpdate}hasActiveRun={resolvedHasActiveRun}+ externalObjects={externalObjectsState.isEnabled ? externalObjectsState.groups : undefined}+ externalObjectsLoading={externalObjectsState.isEnabled ? externalObjectsState.isLoading : undefined}+ externalObjectsError={externalObjectsState.isEnabled ? externalObjectsState.isError : undefined}+ onRetryExternalObjects={externalObjectsState.isEnabled ? externalObjectsState.refetch : undefined}/>);return () => closePanel();@@ -2871,6 +2887,11 @@ export function IssueDetail() {panelChildIssues,panelIssue,resolvedHasActiveRun,+ externalObjectsState.isEnabled,+ externalObjectsState.groups,+ externalObjectsState.isLoading,+ externalObjectsState.isError,+ externalObjectsState.refetch,]);const goToInboxShortcutArmedRef = useRef(false);@@ -3947,6 +3968,7 @@ export function IssueDetail() {multilinefoldablementions={mentionOptions}+ externalReferences={externalObjectsState.isEnabled ? externalObjectsState.markdownReferences : undefined}imageUploadHandler={async (file) => {const attachment = await uploadAttachment.mutateAsync(file);return attachment.contentPath;@@ -4049,6 +4071,7 @@ export function IssueDetail() {feedbackDataSharingPreference={feedbackDataSharingPreference}feedbackTermsUrl={FEEDBACK_TERMS_URL}mentions={mentionOptions}+ externalReferences={externalObjectsState.isEnabled ? externalObjectsState.markdownReferences : undefined}imageUploadHandler={async (file) => {const attachment = await uploadAttachment.mutateAsync(file);return attachment.contentPath;@@ -4240,6 +4263,7 @@ export function IssueDetail() {resumeFromBacklogPending={updateIssue.isPending && updateIssue.variables?.status === "todo"}+ externalReferences={externalObjectsState.isEnabled ? externalObjectsState.markdownReferences : undefined}/>) : null}</TabsContent>@@ -4263,12 +4287,20 @@ export function IssueDetail() {}}onCheckMonitorNow={() => checkIssueMonitorNow.mutate()}checkingMonitorNow={checkIssueMonitorNow.isPending}+ externalReferences={externalObjectsState.isEnabled ? externalObjectsState.markdownReferences : undefined}/>) : null}</TabsContent><TabsContent value="related-work">- <IssueRelatedWorkPanel relatedWork={issue.relatedWork} />+ <IssueRelatedWorkPanel+ relatedWork={issue.relatedWork}+ externalObjectsEnabled={externalObjectsState.isEnabled}+ externalObjects={externalObjectsState.isEnabled ? externalObjectsState.groups : undefined}+ externalObjectsLoading={externalObjectsState.isEnabled ? externalObjectsState.isLoading : undefined}+ externalObjectsError={externalObjectsState.isEnabled ? externalObjectsState.isError : undefined}+ onRetryExternalObjects={externalObjectsState.isEnabled ? externalObjectsState.refetch : undefined}+ /></TabsContent>{activePluginTab && (@@ -4456,6 +4488,10 @@ export function IssueDetail() {onUpdate={(data) => updateIssue.mutate(data)}inlinehasActiveRun={resolvedHasActiveRun}+ externalObjects={externalObjectsState.isEnabled ? externalObjectsState.groups : undefined}+ externalObjectsLoading={externalObjectsState.isEnabled ? externalObjectsState.isLoading : undefined}+ externalObjectsError={externalObjectsState.isEnabled ? externalObjectsState.isError : undefined}+ onRetryExternalObjects={externalObjectsState.isEnabled ? externalObjectsState.refetch : undefined}/></div></ScrollArea>diff --git a/ui/storybook/.storybook/main.ts b/ui/storybook/.storybook/main.tsindex e7e2dadaf0..592ab9d9e9 100644--- a/ui/storybook/.storybook/main.ts+++ b/ui/storybook/.storybook/main.ts@@ -24,6 +24,11 @@ const config: StorybookConfig = {alias: {"@": path.resolve(storybookConfigDir, "../../src"),lexical: path.resolve(storybookConfigDir, "../../node_modules/lexical/Lexical.mjs"),+ // Vite's bundled `node:crypto` polyfill omits `createHash`, which+ // `@paperclipai/shared/external-objects.ts` imports server-side. Use+ // a no-op browser shim so the import resolves; the canonicalizer+ // only runs server-side.+ "node:crypto": path.resolve(storybookConfigDir, "node-crypto-browser-shim.ts"),},},}),diff --git a/ui/storybook/.storybook/node-crypto-browser-shim.ts b/ui/storybook/.storybook/node-crypto-browser-shim.tsnew file mode 100644index 0000000000..7a6cb01d73--- /dev/null+++ b/ui/storybook/.storybook/node-crypto-browser-shim.ts@@ -0,0 +1,31 @@+/**+ * Browser-safe shim for the slice of `node:crypto` that+ * `@paperclipai/shared/external-objects.ts` imports.+ *+ * The shared canonicalizer runs server-side and never executes in the browser,+ * but the static `import { createHash } from "node:crypto"` is still pulled+ * into Storybook's module graph. Vite's built-in `node:crypto` polyfill does+ * not export `createHash`, so the build fails before our code runs. This shim+ * provides a no-op implementation so the bundler can resolve the import; if a+ * code path ever reaches it in the browser we throw loudly so we notice.+ */++class BrowserHash {+ update(_value: string): this {+ throw new Error(+ "createHash from node:crypto is not available in the browser bundle",+ );+ }++ digest(_encoding: string): string {+ throw new Error(+ "createHash from node:crypto is not available in the browser bundle",+ );+ }+}++export function createHash(_algorithm: string): BrowserHash {+ return new BrowserHash();+}++export default { createHash };diff --git a/ui/storybook/stories/chat-comments.stories.tsx b/ui/storybook/stories/chat-comments.stories.tsxindex 041293f9b1..7ed50e53ef 100644--- a/ui/storybook/stories/chat-comments.stories.tsx+++ b/ui/storybook/stories/chat-comments.stories.tsx@@ -4,6 +4,7 @@ import type { TranscriptEntry } from "@/adapters";import type { LiveRunForIssue } from "@/api/heartbeats";import { CommentThread } from "@/components/CommentThread";import { IssueChatThread } from "@/components/IssueChatThread";+import type { MarkdownExternalReferenceMap } from "@/components/MarkdownBody";import { RunChatSurface } from "@/components/RunChatSurface";import type { InlineEntityOption } from "@/components/InlineEntitySelector";import type { MentionOption } from "@/components/MarkdownEditor";@@ -376,14 +377,14 @@ const liveRunTranscript: TranscriptEntry[] = [const issueChatComments: IssueChatComment[] = [createComment({id: "comment-issue-board",- body: "Please turn the comment thread into a reviewable chat surface. I need to see operator messages, agent output, system events, and live run progress together.",+ body: "Please turn the comment thread into a reviewable chat surface. I need to see operator messages, agent output, system events, and live run progress together.\n\nFollow-up tracked in https://github.com/acme/web/pull/241 (merged) and https://github.com/acme/web/pull/243 (review pending).",createdAt: new Date("2026-04-20T13:44:00.000Z"),}),createComment({id: "comment-issue-agent",authorAgentId: codexAgent.id,authorUserId: null,- body: "I kept the existing component contracts and added fixtures with realistic Paperclip work: checkout, comments, linked runs, and review feedback.",+ body: "I kept the existing component contracts and added fixtures with realistic Paperclip work: checkout, comments, linked runs, and review feedback.\n\nFlaky CI lives in https://github.com/acme/web/pull/242 — re-running. Plain control link: https://random.example.com/path stays undecorated.",createdAt: new Date("2026-04-20T13:50:00.000Z"),runId: "run-issue-chat-01",runAgentId: codexAgent.id,@@ -592,10 +593,12 @@ function ThreadProps({comments,queuedComments = [],timelineEvents = [],+ externalReferences,}: {comments: StoryComment[];queuedComments?: StoryComment[];timelineEvents?: IssueTimelineEvent[];+ externalReferences?: MarkdownExternalReferenceMap;}) {return (<CommentThread@@ -615,10 +618,77 @@ function ThreadProps({suggestedAssigneeValue={`agent:${codexAgent.id}`}mentions={mentionOptions}onInterruptQueued={async () => {}}+ externalReferences={externalReferences}/>);}+const externalReferenceComments: StoryComment[] = [+ createComment({+ id: "comment-external-board",+ body: [+ "Tracking work that just landed:",+ "",+ "- Merged PR: https://github.com/acme/web/pull/241",+ "- Awaiting review: https://github.com/acme/web/pull/243",+ "- Auth-blocked: https://app.hubspot.com/leads/99",+ "- Plain control link (no decoration): https://random.example.com/path",+ ].join("\n"),+ createdAt: new Date("2026-04-20T14:02:00.000Z"),+ }),+ createComment({+ id: "comment-external-agent",+ authorAgentId: codexAgent.id,+ authorUserId: null,+ body: [+ "Confirmed handoff updated.",+ "Failed CI on https://github.com/acme/web/pull/242 needs a rerun.",+ "",+ "```",+ "Code-fenced URLs stay plain: https://github.com/acme/web/pull/241",+ "```",+ ].join("\n"),+ createdAt: new Date("2026-04-20T14:05:00.000Z"),+ runId: "run-external-01",+ runAgentId: codexAgent.id,+ }),+];++const externalReferences: MarkdownExternalReferenceMap = {+ "https://github.com/acme/web/pull/241": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "succeeded",+ liveness: "fresh",+ statusLabel: "Merged",+ displayTitle: "Add external refs",+ },+ "https://github.com/acme/web/pull/242": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "failed",+ liveness: "stale",+ statusLabel: "CI failed",+ displayTitle: "Flaky tests",+ },+ "https://github.com/acme/web/pull/243": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "waiting",+ liveness: "fresh",+ statusLabel: "Awaiting review",+ displayTitle: "Add liveness overlay",+ },+ "https://app.hubspot.com/leads/99": {+ providerKey: "hubspot",+ objectType: "lead",+ statusCategory: "auth_required",+ liveness: "auth_required",+ statusLabel: "Reconnect",+ displayTitle: "Acme deal",+ },+};+function CommentThreadMatrix() {return (<Section eyebrow="CommentThread" title="Timeline comments across empty, single, long, markdown, and queued states">@@ -635,6 +705,15 @@ function CommentThreadMatrix() {<ScenarioCard title="Markdown, code, mentions, and links" description="Markdown rendering with code fences, @mentions, links, and a queued reply."><ThreadProps comments={markdownComments} queuedComments={[queuedComment]} /></ScenarioCard>+ <ScenarioCard+ title="External object decoration"+ description="Resolved URLs render with the §2 status chip; an unknown URL stays plain. Code-fenced URLs are not decorated."+ >+ <ThreadProps+ comments={externalReferenceComments}+ externalReferences={externalReferences}+ />+ </ScenarioCard></div></Section>);@@ -709,6 +788,7 @@ function IssueChatMatrix() {includeSucceededRunsWithoutOutputonInterruptQueued={async () => {}}onCancelQueued={() => undefined}+ externalReferences={externalReferences}/></div><div className="space-y-5">diff --git a/ui/storybook/stories/external-objects.stories.tsx b/ui/storybook/stories/external-objects.stories.tsxnew file mode 100644index 0000000000..d70e211c3e--- /dev/null+++ b/ui/storybook/stories/external-objects.stories.tsx@@ -0,0 +1,720 @@+import { useEffect, useRef, useState } from "react";+import type { Meta, StoryObj } from "@storybook/react-vite";+import {+ EXTERNAL_OBJECT_LIVENESS_STATES,+ EXTERNAL_OBJECT_STATUS_CATEGORIES,+ type ExternalObject,+ type ExternalObjectLivenessState,+ type ExternalObjectMention,+ type ExternalObjectStatusCategory,+ type ExternalObjectSummary,+} from "@paperclipai/shared";+import { ExternalObjectPill } from "@/components/ExternalObjectPill";+import { ExternalObjectStatusIcon } from "@/components/ExternalObjectStatusIcon";+import { ExternalObjectStatusSummary } from "@/components/ExternalObjectStatusSummary";+import { IssueFiltersPopover } from "@/components/IssueFiltersPopover";+import { IssueProperties } from "@/components/IssueProperties";+import { IssueRelatedWorkPanel } from "@/components/IssueRelatedWorkPanel";+import { IssueRow } from "@/components/IssueRow";+import { MarkdownBody, type MarkdownExternalReferenceMap } from "@/components/MarkdownBody";+import {+ countActiveIssueFilters,+ defaultIssueFilterState,+ type IssueFilterState,+} from "@/lib/issue-filters";+import {+ externalObjectCategoryLabel,+ externalObjectFallbackTone,+ externalObjectLivenessLabel,+ externalObjectProviderLabel,+ externalObjectTypeLabel,+} from "@/lib/external-objects";+import type { IssueExternalObjectGroup } from "@/hooks/useIssueExternalObjects";+import {+ storybookAgents,+ storybookExecutionWorkspaces,+ storybookIssueLabels,+ storybookIssues,+ storybookProjects,+} from "../fixtures/paperclipData";++function makeObject(args: {+ id: string;+ providerKey: string;+ objectType: string;+ statusCategory: ExternalObjectStatusCategory;+ liveness: ExternalObjectLivenessState;+ displayTitle?: string;+ url: string;+ statusLabel?: string;+}): ExternalObject {+ return {+ id: args.id,+ companyId: "company-1",+ providerKey: args.providerKey,+ pluginId: null,+ objectType: args.objectType,+ externalId: args.id,+ sanitizedCanonicalUrl: args.url,+ canonicalIdentityHash: args.id,+ displayTitle: args.displayTitle ?? null,+ statusKey: args.statusCategory,+ statusLabel: args.statusLabel ?? externalObjectCategoryLabel(args.statusCategory),+ statusCategory: args.statusCategory,+ statusTone: externalObjectFallbackTone(args.statusCategory),+ liveness: args.liveness,+ isTerminal: ["succeeded", "failed", "closed", "archived"].includes(args.statusCategory),+ data: {},+ remoteVersion: null,+ etag: null,+ lastResolvedAt: "2026-04-24T22:45:00.000Z",+ lastChangedAt: "2026-04-24T22:45:00.000Z",+ lastErrorAt: args.liveness === "unreachable" ? "2026-04-24T22:50:00.000Z" : null,+ nextRefreshAt: null,+ lastErrorCode: null,+ lastErrorMessage: null,+ createdAt: "2026-04-24T20:00:00.000Z",+ updatedAt: "2026-04-24T22:45:00.000Z",+ };+}++function makeMention(args: {+ id: string;+ objectId: string;+ sourceKind: ExternalObjectMention["sourceKind"];+ documentKey?: string | null;+}): ExternalObjectMention {+ return {+ id: args.id,+ companyId: "company-1",+ sourceIssueId: "issue-1",+ sourceKind: args.sourceKind,+ sourceRecordId: null,+ documentKey: args.documentKey ?? null,+ propertyKey: null,+ matchedTextRedacted: null,+ sanitizedDisplayUrl: "https://example.com/object",+ canonicalIdentityHash: args.objectId,+ canonicalIdentity: null,+ objectId: args.objectId,+ providerKey: null,+ detectorKey: null,+ objectType: null,+ confidence: "exact",+ createdByPluginId: null,+ createdAt: "2026-04-24T20:00:00.000Z",+ updatedAt: "2026-04-24T22:45:00.000Z",+ };+}++function makeGroup(args: {+ object: ExternalObject;+ mentionCount?: number;+ sourceLabels?: string[];+}): IssueExternalObjectGroup {+ return {+ group: {+ object: args.object,+ mentions: [makeMention({ id: `${args.object.id}-m`, objectId: args.object.id, sourceKind: "description" })],+ mentionCount: args.mentionCount ?? 1,+ sourceLabels: args.sourceLabels ?? ["description"],+ },+ pill: {+ providerKey: args.object.providerKey,+ objectType: args.object.objectType,+ statusCategory: args.object.statusCategory,+ liveness: args.object.liveness,+ displayTitle: args.object.displayTitle,+ statusLabel: args.object.statusLabel,+ url: args.object.sanitizedCanonicalUrl,+ },+ mentionCount: args.mentionCount ?? 1,+ sourceLabels: args.sourceLabels ?? ["description"],+ };+}++function StateMatrix() {+ return (+ <div className="paperclip-story space-y-8">+ <header className="space-y-2">+ <h1 className="text-2xl font-semibold">External object status matrix</h1>+ <p className="text-sm text-muted-foreground">+ Every status category × liveness combination from the UX spec §6, used as the canonical+ presentational reference for inline markdown, pills, properties, and rollups.+ </p>+ </header>+ <table className="w-full table-auto border-collapse text-sm">+ <thead>+ <tr className="border-b border-border text-left text-xs uppercase tracking-wide text-muted-foreground">+ <th className="px-3 py-2">Category</th>+ {EXTERNAL_OBJECT_LIVENESS_STATES.map((liveness) => (+ <th key={liveness} className="px-3 py-2">{externalObjectLivenessLabel(liveness)}</th>+ ))}+ </tr>+ </thead>+ <tbody>+ {EXTERNAL_OBJECT_STATUS_CATEGORIES.map((category) => (+ <tr key={category} className="border-b border-border">+ <td className="px-3 py-3 font-mono text-xs text-muted-foreground">{category}</td>+ {EXTERNAL_OBJECT_LIVENESS_STATES.map((liveness) => (+ <td key={liveness} className="px-3 py-3">+ <ExternalObjectStatusIcon+ category={category}+ liveness={liveness}+ sizeClassName="h-5 w-5"+ />+ </td>+ ))}+ </tr>+ ))}+ </tbody>+ </table>++ <section className="space-y-3">+ <h2 className="text-lg font-medium">Pills (host-rendered identity, no plugin React)</h2>+ <div className="flex flex-wrap items-center gap-2">+ <ExternalObjectPill+ object={{+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "succeeded",+ liveness: "fresh",+ displayTitle: "Add external refs",+ url: "https://github.com/acme/web/pull/241",+ }}+ sourceCount={4}+ sourceSummary="description, 3 comments"+ />+ <ExternalObjectPill+ object={{+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "failed",+ liveness: "stale",+ displayTitle: "Bad CI run",+ url: "https://github.com/acme/web/pull/242",+ }}+ sourceCount={2}+ />+ <ExternalObjectPill+ object={{+ providerKey: "hubspot",+ objectType: "lead",+ statusCategory: "auth_required",+ liveness: "auth_required",+ displayTitle: "Acme deal",+ url: "https://app.hubspot.com/leads/99",+ }}+ />+ <ExternalObjectPill+ object={{+ providerKey: "linear",+ objectType: "issue",+ statusCategory: "running",+ liveness: "fresh",+ displayTitle: "Spike: queues",+ url: "https://linear.app/acme/issue/INF-44",+ }}+ />+ <ExternalObjectPill+ object={{+ providerKey: "ci",+ objectType: "deployment",+ statusCategory: "unreachable",+ liveness: "unreachable",+ displayTitle: "deploy prod-0412",+ url: "https://ci.example.com/runs/88421",+ }}+ />+ </div>+ </section>+ </div>+ );+}++function inlineMarkdownStory() {+ const references: MarkdownExternalReferenceMap = {+ "https://github.com/acme/web/pull/241": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "succeeded",+ liveness: "fresh",+ statusLabel: "Merged",+ displayTitle: "Add external refs",+ },+ "https://github.com/acme/web/pull/242": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "failed",+ liveness: "stale",+ statusLabel: "CI failed",+ displayTitle: "Flaky tests",+ },+ "https://github.com/acme/web/pull/243": {+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "waiting",+ liveness: "fresh",+ statusLabel: "Awaiting review",+ displayTitle: "Add liveness overlay",+ },+ "https://app.hubspot.com/leads/99": {+ providerKey: "hubspot",+ objectType: "lead",+ statusCategory: "auth_required",+ liveness: "auth_required",+ statusLabel: "Reconnect",+ displayTitle: "Acme deal",+ },+ "https://ci.example.com/runs/88421": {+ providerKey: "ci",+ objectType: "deployment",+ statusCategory: "unreachable",+ liveness: "unreachable",+ statusLabel: "Unreachable",+ displayTitle: "Prod-0412",+ },+ };+ const markdown = `Status of recent integrations:\n\n- Merged PR: https://github.com/acme/web/pull/241\n- Stale failed CI: https://github.com/acme/web/pull/242\n- Awaiting review: https://github.com/acme/web/pull/243\n- Auth required: https://app.hubspot.com/leads/99\n- Unreachable deploy: https://ci.example.com/runs/88421\n- Unrelated control link: https://random.example.com/path\n\n\`\`\`\n# Code blocks must be left alone — https://github.com/acme/web/pull/241\n\`\`\`\n\nInline code stays plain too: \`https://github.com/acme/web/pull/241\`.`;+ return (+ <div className="paperclip-story space-y-4 text-sm">+ <h2 className="text-lg font-medium">Inline markdown decoration</h2>+ <MarkdownBody externalReferences={references}>{markdown}</MarkdownBody>+ </div>+ );+}++function relatedWorkStory() {+ const externalObjects = [+ makeGroup({+ object: makeObject({+ id: "obj-1",+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "failed",+ liveness: "fresh",+ displayTitle: "Add external refs",+ url: "https://github.com/acme/web/pull/241",+ }),+ mentionCount: 4,+ sourceLabels: ["description", "comments", "plan document"],+ }),+ makeGroup({+ object: makeObject({+ id: "obj-2",+ providerKey: "hubspot",+ objectType: "lead",+ statusCategory: "auth_required",+ liveness: "auth_required",+ displayTitle: "Acme deal",+ url: "https://app.hubspot.com/leads/99",+ }),+ mentionCount: 1,+ sourceLabels: ["External links property"],+ }),+ makeGroup({+ object: makeObject({+ id: "obj-3",+ providerKey: "ci",+ objectType: "deployment",+ statusCategory: "running",+ liveness: "fresh",+ displayTitle: "deploy prod-0412",+ url: "https://ci.example.com/runs/88421",+ }),+ mentionCount: 2,+ sourceLabels: ["comments"],+ }),+ makeGroup({+ object: makeObject({+ id: "obj-4",+ providerKey: "github",+ objectType: "issue",+ statusCategory: "succeeded",+ liveness: "stale",+ displayTitle: "Closed parent issue",+ url: "https://github.com/acme/web/issues/15",+ }),+ mentionCount: 1,+ sourceLabels: ["comments"],+ }),+ ];++ return (+ <IssueRelatedWorkPanel+ relatedWork={{+ outbound: [],+ inbound: [],+ }}+ externalObjects={externalObjects}+ />+ );+}++function projectsRollupStory() {+ function summary(args: {+ failed?: number;+ waiting?: number;+ running?: number;+ succeeded?: number;+ auth?: number;+ stale?: number;+ }): ExternalObjectSummary {+ const objects: ExternalObjectSummary["objects"] = [];+ function pushMany(category: ExternalObjectStatusCategory, count: number) {+ for (let i = 0; i < count; i += 1) {+ objects.push({+ id: `obj-${category}-${i}`,+ providerKey: "github",+ objectType: "pull_request",+ displayTitle: null,+ statusCategory: category,+ statusTone: externalObjectFallbackTone(category),+ liveness: args.stale && i % 2 === 0 ? "stale" : "fresh",+ isTerminal: false,+ });+ }+ }+ pushMany("failed", args.failed ?? 0);+ pushMany("waiting", args.waiting ?? 0);+ pushMany("running", args.running ?? 0);+ pushMany("succeeded", args.succeeded ?? 0);+ pushMany("auth_required", args.auth ?? 0);+ const tones = objects.map((o) => o.statusTone);+ const dominant: ExternalObjectSummary["highestSeverity"] =+ tones.includes("danger") ? "danger"+ : tones.includes("warning") ? "warning"+ : tones.includes("info") ? "info"+ : tones.includes("success") ? "success"+ : "muted";+ const byStatusCategory: Record<string, number> = {};+ for (const obj of objects) {+ byStatusCategory[obj.statusCategory] = (byStatusCategory[obj.statusCategory] ?? 0) + 1;+ }+ return {+ total: objects.length,+ byStatusCategory,+ byLiveness: { fresh: objects.length, stale: 0, auth_required: 0, unreachable: 0, unknown: 0 },+ highestSeverity: dominant,+ staleCount: args.stale ?? 0,+ authRequiredCount: args.auth ?? 0,+ unreachableCount: 0,+ objects,+ };+ }++ const projects = [+ { name: "Paperclip App", color: "#6366f1", summary: summary({ failed: 3, running: 12 }) },+ { name: "Marketing site", color: "#22c55e", summary: summary({ waiting: 2 }) },+ { name: "Experimental", color: "#a855f7", summary: summary({ succeeded: 6 }) },+ { name: "Auth provider", color: "#f97316", summary: summary({ auth: 1 }) },+ ];+ return (+ <div className="paperclip-story w-72 rounded border border-border bg-background p-2">+ <div className="mb-2 text-xs uppercase tracking-wide text-muted-foreground">Projects (sidebar)</div>+ <ul className="flex flex-col">+ {projects.map((project) => (+ <li+ key={project.name}+ className="flex items-center gap-2.5 px-3 py-1.5 text-[13px] font-medium hover:bg-accent/50"+ >+ <span className="h-3.5 w-3.5 shrink-0 rounded-sm" style={{ backgroundColor: project.color }} />+ <span className="flex-1 truncate">{project.name}</span>+ <ExternalObjectStatusSummary summary={project.summary} compact />+ </li>+ ))}+ </ul>+ </div>+ );+}++function StateMatrixStory() {+ return (+ <div className="paperclip-story space-y-12 p-6">+ <StateMatrix />+ {inlineMarkdownStory()}+ {relatedWorkStory()}+ {projectsRollupStory()}+ </div>+ );+}++function makeIntegrationGroups(): IssueExternalObjectGroup[] {+ return [+ makeGroup({+ object: makeObject({+ id: "obj-int-failed",+ providerKey: "github",+ objectType: "pull_request",+ statusCategory: "failed",+ liveness: "fresh",+ displayTitle: "CI broken on main",+ url: "https://github.com/acme/web/pull/241",+ statusLabel: "CI failed",+ }),+ mentionCount: 4,+ sourceLabels: ["Description", "3 comments"],+ }),+ makeGroup({+ object: makeObject({+ id: "obj-int-auth",+ providerKey: "hubspot",+ objectType: "lead",+ statusCategory: "auth_required",+ liveness: "auth_required",+ displayTitle: "Acme deal — needs reconnect",+ url: "https://app.hubspot.com/leads/99",+ statusLabel: "Reconnect",+ }),+ mentionCount: 1,+ sourceLabels: ["External links property"],+ }),+ makeGroup({+ object: makeObject({+ id: "obj-int-running",+ providerKey: "ci",+ objectType: "deployment",+ statusCategory: "running",+ liveness: "fresh",+ displayTitle: "deploy prod-0412",+ url: "https://ci.example.com/runs/88421",+ statusLabel: "Running",+ }),+ mentionCount: 2,+ sourceLabels: ["2 comments"],+ }),+ ];+}++function makeIntegrationSummary(): ExternalObjectSummary {+ const objects = makeIntegrationGroups()+ .map((entry) => entry.group.object)+ .filter((object): object is ExternalObject => Boolean(object))+ .map((object) => ({+ id: object.id,+ providerKey: object.providerKey,+ objectType: object.objectType,+ displayTitle: object.displayTitle,+ statusCategory: object.statusCategory,+ statusTone: object.statusTone,+ liveness: object.liveness,+ isTerminal: object.isTerminal,+ }));+ const tones = objects.map((o) => o.statusTone);+ const dominant: ExternalObjectSummary["highestSeverity"] =+ tones.includes("danger") ? "danger"+ : tones.includes("warning") ? "warning"+ : tones.includes("info") ? "info"+ : tones.includes("success") ? "success"+ : "muted";+ const byStatusCategory: Record<string, number> = {};+ for (const o of objects) {+ byStatusCategory[o.statusCategory] = (byStatusCategory[o.statusCategory] ?? 0) + 1;+ }+ return {+ total: objects.length,+ byStatusCategory,+ byLiveness: { fresh: objects.length - 1, stale: 0, auth_required: 1, unreachable: 0, unknown: 0 },+ highestSeverity: dominant,+ staleCount: 0,+ authRequiredCount: 1,+ unreachableCount: 0,+ objects,+ };+}++function PropertiesPanelDesktop() {+ const issue = storybookIssues[0]!;+ return (+ <div className="paperclip-story w-[420px] rounded-lg border border-border bg-background/70 p-4">+ <div className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">+ Issue properties — desktop @ 1440×900+ </div>+ <IssueProperties+ issue={issue}+ childIssues={[]}+ externalObjects={makeIntegrationGroups()}+ onAddSubIssue={() => undefined}+ onUpdate={() => undefined}+ />+ </div>+ );+}++function PropertiesPanelMobile() {+ const issue = storybookIssues[0]!;+ return (+ <div className="paperclip-story mx-auto w-[358px] rounded-lg border border-border bg-background/70 p-3">+ <div className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">+ Issue properties — mobile sheet @ 390×844+ </div>+ <IssueProperties+ issue={issue}+ childIssues={[]}+ externalObjects={makeIntegrationGroups()}+ onAddSubIssue={() => undefined}+ onUpdate={() => undefined}+ inline+ />+ </div>+ );+}++function RelatedWorkEmptyDesktop() {+ return (+ <div className="paperclip-story space-y-3 p-6">+ <div className="text-xs uppercase tracking-wide text-muted-foreground">+ Related work — empty external objects (zero refs, empty copy visible)+ </div>+ <IssueRelatedWorkPanel+ relatedWork={{ outbound: [], inbound: [] }}+ externalObjects={[]}+ />+ </div>+ );+}++function SidebarMobileDrawer() {+ const summary = makeIntegrationSummary();+ return (+ <div className="paperclip-story mx-auto w-[320px] rounded border border-border bg-background p-2">+ <div className="mb-2 text-xs uppercase tracking-wide text-muted-foreground">Projects (mobile drawer)</div>+ <ul className="flex flex-col">+ {[+ { name: "Paperclip App", color: "#6366f1", summary },+ { name: "Marketing site", color: "#22c55e", summary: { ...summary, highestSeverity: "warning", byStatusCategory: { waiting: 2 }, total: 2, objects: [] } },+ { name: "Experimental", color: "#a855f7", summary: { ...summary, highestSeverity: "muted", byStatusCategory: {}, total: 0, objects: [] } },+ ].map((project) => (+ <li+ key={project.name}+ className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium hover:bg-accent/50"+ >+ <span className="h-3.5 w-3.5 shrink-0 rounded-sm" style={{ backgroundColor: project.color }} />+ <span className="flex-1 truncate">{project.name}</span>+ <ExternalObjectStatusSummary summary={project.summary as ExternalObjectSummary} compact />+ </li>+ ))}+ </ul>+ </div>+ );+}++function IssueListWithBadge() {+ const summary = makeIntegrationSummary();+ return (+ <div className="paperclip-story p-6">+ <div className="mb-3 text-xs uppercase tracking-wide text-muted-foreground">+ Issue list — desktop @ 1440×900 (badge + control row)+ </div>+ <div className="overflow-hidden rounded-xl border border-border bg-background/70">+ {storybookIssues.slice(0, 2).map((issue, index) => (+ <IssueRow+ key={issue.id}+ issue={issue}+ externalObjectSummary={index === 0 ? summary : null}+ desktopTrailing={+ <span className="text-xs text-muted-foreground">{issue.priority}</span>+ }+ />+ ))}+ </div>+ </div>+ );+}++function FilterPopoverWithExternalChecked() {+ const [state, setState] = useState<IssueFilterState>({+ ...defaultIssueFilterState,+ externalObjectStatuses: ["failed", "auth_required"],+ });+ const triggerRef = useRef<HTMLDivElement | null>(null);++ useEffect(() => {+ const timer = window.setTimeout(() => {+ triggerRef.current?.querySelector("button")?.click();+ }, 150);+ return () => window.clearTimeout(timer);+ }, []);++ return (+ <div className="paperclip-story flex min-h-[640px] items-start justify-end p-6">+ <div ref={triggerRef}>+ <IssueFiltersPopover+ state={state}+ onChange={(patch) => setState((current) => ({ ...current, ...patch }))}+ activeFilterCount={countActiveIssueFilters(state, true)}+ agents={storybookAgents.map((agent) => ({ id: agent.id, name: agent.name }))}+ projects={storybookProjects.map((project) => ({ id: project.id, name: project.name }))}+ labels={storybookIssueLabels.map((label) => ({ id: label.id, name: label.name, color: label.color }))}+ currentUserId="user-board"+ enableRoutineVisibilityFilter+ buttonVariant="outline"+ workspaces={storybookExecutionWorkspaces.map((workspace) => ({ id: workspace.id, name: workspace.name }))}+ creators={[+ { id: "user:user-board", label: "Riley Board", kind: "user", searchText: "board user human" },+ ]}+ />+ </div>+ </div>+ );+}++function IntegrationSurfacesStory() {+ return (+ <div className="paperclip-story space-y-10 p-6">+ <PropertiesPanelDesktop />+ <PropertiesPanelMobile />+ <RelatedWorkEmptyDesktop />+ <SidebarMobileDrawer />+ <IssueListWithBadge />+ <FilterPopoverWithExternalChecked />+ </div>+ );+}++const meta = {+ title: "Foundations/External Objects",+ component: StateMatrixStory,+ parameters: {+ docs: {+ description: {+ component:+ "External-object surface gallery: the §6 state matrix, the inline markdown decoration, the related-work section, and the project-rollup sidebar marker. Mirrors the Phase 6 acceptance set from the UX spec.",+ },+ },+ },+} satisfies Meta<typeof StateMatrixStory>;++export default meta;++type Story = StoryObj<typeof meta>;++export const FullSurface: Story = {};++export const PropertiesRowDesktop: StoryObj = {+ render: () => <PropertiesPanelDesktop />,+};++export const PropertiesRowMobileSheet: StoryObj = {+ render: () => <PropertiesPanelMobile />,+};++export const RelatedWorkEmpty: StoryObj = {+ render: () => <RelatedWorkEmptyDesktop />,+};++export const SidebarMobile: StoryObj = {+ render: () => <SidebarMobileDrawer />,+};++export const IssueListRow: StoryObj = {+ render: () => <IssueListWithBadge />,+};++export const FilterPopoverOpen: StoryObj = {+ render: () => <FilterPopoverWithExternalChecked />,+};++export const IntegrationSurfaces: StoryObj = {+ render: () => <IntegrationSurfacesStory />,+};