paperclip-github-plugin 0.6.1 → 0.7.1

package/README.md

@@ -44,11 +44,11 @@ The plugin adds a full in-host workflow instead of a one-off import script:
 2. Connect one or more GitHub repositories to Paperclip projects.
 3. Run a sync manually or let the scheduled job keep things up to date.
 
-During sync, the plugin imports one top-level Paperclip issue per GitHub issue, updates already imported issues instead of recreating them, maps GitHub labels into Paperclip labels, and keeps GitHub-specific metadata in dedicated Paperclip surfaces rather than stuffing everything into the issue description.
+During sync, the plugin imports one top-level Paperclip issue per GitHub issue, stamps it with a namespaced GitHub Sync plugin origin, updates already imported issues instead of recreating them, maps GitHub labels into Paperclip labels, and keeps GitHub-specific metadata in dedicated Paperclip surfaces rather than stuffing everything into the issue description.
 
 When the host exposes plugin issue creation, imported GitHub issues are created through the Paperclip plugin SDK path so they are not attributed to the connected board user. The worker still uses direct local Paperclip REST calls for label sync and for description, assignee, or status repair paths when those routes are available.
 
-Long-running syncs continue in the background, so quick actions do not have to wait for the whole import to finish. Once a sync has started, the settings page, dashboard widget, and toolbar actions can request cancellation; the worker stops cooperatively after the current repository or issue step finishes. If the worker restarts mid-run, GitHub Sync now recovers that orphaned `running` state on the next read or control action instead of leaving the UI stuck in `running` or silently restarting the old run.
+Long-running syncs continue in the background, so quick actions do not have to wait for the whole import to finish. Once a sync has started, the settings page, dashboard widget, and toolbar actions can request cancellation; the worker stops cooperatively after the current repository or issue step finishes. If the worker restarts mid-run, GitHub Sync now recovers that orphaned `running` state on the next read or control action instead of leaving the UI stuck in `running` or silently restarting the old run. When sync needs to wake an assigned agent, it uses Paperclip's host-owned issue wakeup API first so blocker, liveness, budget, and auth checks stay centralized, then falls back to the local wakeup route only when an older or partial host bridge cannot service the SDK call.
 
 ## Highlights
 
@@ -68,9 +68,9 @@ The plugin does more than mirror issue text. It looks at linked pull requests, m
 
 GitHub Sync exposes a dedicated KPI dashboard widget alongside the operational sync widget. During full company syncs, the worker snapshots the current open GitHub backlog and records when already-imported GitHub issues move from open to closed. The KPI widget turns that worker-owned state into backlog, issue-closure, and Paperclip PR-creation cards with recent history and comparisons against older periods.
 
-Because GitHub alone cannot tell which pull requests came from a Paperclip company, the plugin uses explicit Paperclip attribution for delivery activity. `create_pull_request` automatically records a Paperclip-created PR event, and agents that use `gh` or another non-plugin GitHub client can post pull-request-created events to the plugin webhook so the KPI history stays specific to Paperclip work.
+Because GitHub alone cannot tell which pull requests came from a Paperclip company, the plugin uses explicit Paperclip attribution for delivery activity. `create_pull_request` automatically records a Paperclip-created PR event, and agents that use `gh` or another non-plugin GitHub client can post pull-request-created events to the plugin API route so the KPI history stays specific to Paperclip work.
 
-That webhook path matters on authenticated Paperclip deployments today because a current host bug blocks agents from calling plugin tools unless the instance runs in `local_trusted` mode. Those agents can still use `gh` with the propagated `GITHUB_TOKEN`, then call the plugin-owned webhook from the shell after they create a PR. KPI webhook requests instead authenticate with `Authorization: Bearer <PAPERCLIP_API_KEY>`, which the deployment validates through `GET /api/agents/me`, so anonymous POSTs are rejected.
+That API route path matters on authenticated Paperclip deployments today because a current host bug blocks agents from calling plugin tools unless the instance runs in `local_trusted` mode. Those agents can still use `gh` with the propagated `GITHUB_TOKEN`, then call the agent-authenticated plugin API route from the shell after they create a PR. The Paperclip host authenticates `Authorization: Bearer <PAPERCLIP_API_KEY>`, scopes the request to the calling agent's company, and rejects anonymous or non-agent calls before dispatching to the worker.
 
 ### Project pull request command center
 
@@ -89,7 +89,7 @@ Paperclip agents can search GitHub for duplicates, read and update issues, post
 ## Requirements
 
 - Node.js 20+
-- a Paperclip host that supports plugin installation
+- a Paperclip host on `2026.427.0` or newer with plugin installation enabled
 - a GitHub token with API access to the repositories you want to sync
 
 ## Install from npm
@@ -178,7 +178,7 @@ The plugin is designed to avoid persisting raw credentials in plugin state.
 - On authenticated deployments, any selected propagation agents receive `GITHUB_TOKEN` as an agent env secret-ref binding that points at the same saved GitHub token secret instead of a copied raw token.
 - The worker resolves those secret references at runtime instead of storing raw tokens in plugin state.
 - On authenticated Paperclip deployments, sync is blocked until the relevant company has connected Paperclip board access.
-- KPI webhook requests must include `Authorization: Bearer <PAPERCLIP_API_KEY>`, and the worker validates that agent-scoped Paperclip token against `GET /api/agents/me` before it records any metric event.
+- KPI API route requests must include `Authorization: Bearer <PAPERCLIP_API_KEY>` from an agent run; the Paperclip host authenticates the token and supplies the agent company before the worker records any metric event.
 
 ### Optional worker-local token file
 
@@ -208,14 +208,14 @@ The plugin exposes GitHub workflow tools to Paperclip agents, including:
 
 When an agent sends GitHub body content through the plugin, including issue bodies, pull request descriptions, comments, and review-thread replies, the plugin adds a GitHub-flavored Markdown footer with a horizontal rule and compact heading that discloses AI authorship. If the tool caller supplies `llmModel`, the footer also includes the model name, for example `###### ✨ This comment was AI-generated using gpt-5.4`.
 
-### KPI attribution webhook
+### KPI attribution API route
 
-The `create_pull_request` tool automatically records a company-level Paperclip PR creation metric. For delivery flows that use `gh` or another non-plugin GitHub client, post a JSON payload to `/api/plugins/paperclip-github-plugin/webhooks/record-company-metric-event` after the PR is created.
+The `create_pull_request` tool automatically records a company-level Paperclip PR creation metric. For delivery flows that use `gh` or another non-plugin GitHub client, post a JSON payload to `/api/plugins/paperclip-github-plugin/api/company-metrics/events` after the PR is created.
 
 Supported payload fields:
 
 - `metric` required: `pull_request_created`
-- `companyId` optional when `repository` maps to exactly one company
+- `companyId` optional; when present it must match the authenticated agent's company
 - `repository` optional: `owner/repo` or `https://github.com/owner/repo`
 - `pullRequestNumber` optional
 - `pullRequestUrl` optional
@@ -223,18 +223,18 @@ Supported payload fields:
 - `eventKey` optional custom dedupe key
 - `count` optional positive integer
 
-Each request must include:
+Each request must be made by a Paperclip agent run and include:
 
 - `Authorization: Bearer <PAPERCLIP_API_KEY>`
 
-The worker validates that bearer token against Paperclip's built-in `GET /api/agents/me` endpoint on the trusted Paperclip API origin (`PAPERCLIP_API_URL` when available, otherwise the saved plugin origin). Requests are rejected when the token is missing, invalid, expired, or belongs to a different company than the metric target.
+The Paperclip host validates that bearer token and passes the authenticated agent company to the plugin worker. Requests are rejected before worker dispatch when the token is missing, invalid, expired, or not an agent token.
 
 Example:
 
 ```bash
 payload='{"metric":"pull_request_created","repository":"paperclipai/example-repo","pullRequestNumber":21}'
 
-curl -X POST "${PAPERCLIP_API_URL%/}/api/plugins/paperclip-github-plugin/webhooks/record-company-metric-event" \
+curl -X POST "${PAPERCLIP_API_URL%/}/api/plugins/paperclip-github-plugin/api/company-metrics/events" \
   -H "content-type: application/json" \
   -H "authorization: Bearer ${PAPERCLIP_API_KEY}" \
   -d "${payload}"
@@ -244,14 +244,14 @@ The worker deduplicates repeated PR events by preferring the pull request URL, t
 
 Current host caveat: on authenticated Paperclip deployments, the Paperclip host currently guards `GET /api/plugins/tools` and `POST /api/plugins/tools/execute` with board authentication before dispatching to any plugin worker. If an agent run does not have board access for the target company, GitHub Sync tool discovery and execution fail with `403 {"error":"Board access required"}` before this plugin's worker code runs.
 
-Because the KPI attribution endpoint is a normal plugin webhook rather than a plugin tool, authenticated agent runs can still call it directly with `PAPERCLIP_API_KEY` even while that host bug blocks the GitHub Sync tool surface.
+Because the KPI attribution endpoint is a native plugin JSON route rather than a plugin tool, authenticated agent runs can still call it directly with `PAPERCLIP_API_KEY` even while that host bug blocks the GitHub Sync tool surface.
 
 ## Troubleshooting
 
 - If setup is reported as incomplete, confirm that a GitHub token has been saved or that `${PAPERCLIP_HOME:-~/.paperclip}/plugins/github-sync/config.json` contains `githubToken`, and make sure at least one mapping has a created Paperclip project.
 - If Paperclip says board access is required, open plugin settings inside the affected company and complete the Paperclip board access flow before retrying sync.
 - If GitHub Sync agent tools fail with `403 {"error":"Board access required"}` on `/api/plugins/tools` or `/api/plugins/tools/execute`, the current Paperclip host rejected the request before the plugin worker ran. Re-run from a board-authenticated session or agent run that has board access to the target company.
-- If a KPI webhook call is rejected, make sure the request includes `Authorization: Bearer ${PAPERCLIP_API_KEY}`, that the token is still valid for the current run, and that it belongs to the same company the metric event targets.
+- If a KPI API route call is rejected, make sure the request includes `Authorization: Bearer ${PAPERCLIP_API_KEY}`, that the token is still valid for the current run, and that any `companyId` in the payload matches the calling agent's company.
 - If the worker reaches an authenticated HTML page instead of the Paperclip API JSON responses it expects, connect Paperclip board access for that company or set `PAPERCLIP_API_URL` to a worker-accessible Paperclip API origin.
 - If a sync run finishes with partial failures, open the saved troubleshooting panel in GitHub Sync to inspect the repository, issue number, raw error, and suggested fix for each recorded failure.
 - If sync says the Paperclip API URL is not trusted, reopen the plugin from the current Paperclip host so the settings UI can refresh the saved origin, or set `PAPERCLIP_API_URL` for the worker.

package/dist/manifest.js

@@ -508,19 +508,20 @@ var GITHUB_AGENT_TOOLS = [
 
 // src/kpi-contract.ts
 var GITHUB_SYNC_PLUGIN_ID = "paperclip-github-plugin";
-var COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY = "record-company-metric-event";
-var COMPANY_METRIC_WEBHOOK_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/webhooks/${COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY}`;
+var COMPANY_METRIC_API_ROUTE_KEY = "record-company-metric-event";
+var COMPANY_METRIC_API_ROUTE_PATH = "/company-metrics/events";
+var COMPANY_METRIC_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${COMPANY_METRIC_API_ROUTE_PATH}`;
 
 // src/manifest.ts
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
-var DASHBOARD_WIDGET_CAPABILITY = "ui.dashboardWidget.register";
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.6.1"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.7.1"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
 var manifest = {
   id: GITHUB_SYNC_PLUGIN_ID,
   apiVersion: 1,
   version: MANIFEST_VERSION,
+  minimumHostVersion: "2026.427.0",
   displayName: "GitHub Sync",
   description: "Synchronize GitHub issues into Paperclip projects.",
   author: "\xC1lvaro S\xE1nchez-Mariscal",
@@ -528,7 +529,7 @@ var manifest = {
   capabilities: [
     "ui.sidebar.register",
     "ui.page.register",
-    DASHBOARD_WIDGET_CAPABILITY,
+    "ui.dashboardWidget.register",
     "ui.detailTab.register",
     "ui.commentAnnotation.register",
     "ui.action.register",
@@ -539,11 +540,12 @@ var manifest = {
     "issues.read",
     "issues.create",
     "issues.update",
+    "issues.wakeup",
     "issue.comments.read",
     "issue.comments.create",
     "agents.read",
     "jobs.schedule",
-    "webhooks.receive",
+    "api.routes.register",
     "http.outbound",
     "secrets.read-ref",
     "agent.tools.register"
@@ -579,11 +581,13 @@ var manifest = {
       schedule: SCHEDULE_TICK_CRON
     }
   ],
-  webhooks: [
+  apiRoutes: [
     {
-      endpointKey: COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY,
-      displayName: "Record Company KPI Event",
-      description: "Record Paperclip-attributed pull request activity from agent flows that use gh or other non-plugin GitHub clients."
+      routeKey: COMPANY_METRIC_API_ROUTE_KEY,
+      method: "POST",
+      path: COMPANY_METRIC_API_ROUTE_PATH,
+      auth: "agent",
+      capability: "api.routes.register"
     }
   ],
   tools: GITHUB_AGENT_TOOLS,

package/dist/worker.js

@@ -563,9 +563,9 @@ function parseRepositoryReference(repositoryInput) {
 
 // src/kpi-contract.ts
 var GITHUB_SYNC_PLUGIN_ID = "paperclip-github-plugin";
-var COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY = "record-company-metric-event";
-var COMPANY_METRIC_WEBHOOK_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/webhooks/${COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY}`;
-var COMPANY_METRIC_WEBHOOK_AUTH_HEADER = "authorization";
+var COMPANY_METRIC_API_ROUTE_KEY = "record-company-metric-event";
+var COMPANY_METRIC_API_ROUTE_PATH = "/company-metrics/events";
+var COMPANY_METRIC_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${COMPANY_METRIC_API_ROUTE_PATH}`;
 
 // src/paperclip-health.ts
 function normalizeOptionalString(value) {
@@ -594,6 +594,8 @@ function requiresPaperclipBoardAccess(value) {
 }
 
 // src/worker.ts
+var GITHUB_ISSUE_ORIGIN_KIND = `plugin:${GITHUB_SYNC_PLUGIN_ID}:github-issue`;
+var GITHUB_PULL_REQUEST_ORIGIN_KIND = `plugin:${GITHUB_SYNC_PLUGIN_ID}:github-pull-request`;
 var SETTINGS_SCOPE = {
   scopeKind: "instance",
   stateKey: "paperclip-github-plugin-settings"
@@ -5024,7 +5026,10 @@ function resolvePaperclipIssueExecutorAssignee(syncContext, advancedSettings) {
   return null;
 }
 function resolveSyncTransitionAssignee(params) {
-  const { nextStatus, syncContext, advancedSettings } = params;
+  const { currentStatus, nextStatus, syncContext, advancedSettings } = params;
+  if (isHealthyMaintainerWaitTransition({ currentStatus, nextStatus, syncContext })) {
+    return null;
+  }
   if (nextStatus === "in_review") {
     return resolvePaperclipIssueReviewAssignee(syncContext, advancedSettings);
   }
@@ -5033,6 +5038,10 @@ function resolveSyncTransitionAssignee(params) {
   }
   return null;
 }
+function isHealthyMaintainerWaitTransition(params) {
+  const { currentStatus, nextStatus, syncContext } = params;
+  return nextStatus === "in_review" && (currentStatus === "done" || currentStatus === "in_review") && syncContext.executionState === null && syncContext.executionPolicy !== null;
+}
 function doesPaperclipIssueAssigneeMatch(currentAssignee, nextAssignee) {
   return isSamePaperclipIssueAssigneePrincipal(currentAssignee, nextAssignee);
 }
@@ -6773,9 +6782,6 @@ function getPaperclipIssueEndpoint(baseUrl, issueId) {
 function getPaperclipHealthEndpoint(baseUrl) {
   return new URL("/api/health", baseUrl).toString();
 }
-function getPaperclipCurrentAgentEndpoint(baseUrl) {
-  return new URL("/api/agents/me", baseUrl).toString();
-}
 function getPaperclipAgentWakeupEndpoint(baseUrl, agentId) {
   return new URL(`/api/agents/${agentId}/wakeup`, baseUrl).toString();
 }
@@ -6824,7 +6830,38 @@ async function detectPaperclipBoardAccessRequirement(paperclipApiBaseUrl) {
   }
 }
 async function wakePaperclipIssueAssignee(ctx, params) {
-  if (!params.assigneeAgentId || !params.paperclipApiBaseUrl) {
+  if (!params.assigneeAgentId) {
+    return;
+  }
+  if (ctx.issues && typeof ctx.issues.requestWakeup === "function" && params.companyId) {
+    try {
+      await ctx.issues.requestWakeup(params.paperclipIssueId, params.companyId, {
+        reason: params.reason,
+        contextSource: `github-sync.${params.mutation}`,
+        ...params.mutation === "import" ? { idempotencyKey: ["github-sync", params.mutation, params.paperclipIssueId].join(":") } : {}
+      });
+      return;
+    } catch (error) {
+      if (!params.paperclipApiBaseUrl) {
+        ctx.logger.warn("GitHub sync could not wake the assignee for a Paperclip issue through the SDK.", {
+          issueId: params.paperclipIssueId,
+          agentId: params.assigneeAgentId,
+          companyId: params.companyId,
+          mutation: params.mutation,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return;
+      }
+      ctx.logger.warn("GitHub sync could not wake the assignee through the SDK. Falling back to the local Paperclip API.", {
+        issueId: params.paperclipIssueId,
+        agentId: params.assigneeAgentId,
+        companyId: params.companyId,
+        mutation: params.mutation,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  if (!params.paperclipApiBaseUrl) {
     return;
   }
   try {
@@ -7569,6 +7606,7 @@ async function updatePaperclipIssueState(ctx, params) {
     nextStatus,
     nextAssignee,
     clearAssignee,
+    clearExecutionPolicy,
     transitionComment,
     transitionCommentAnnotation,
     paperclipApiBaseUrl
@@ -7583,7 +7621,8 @@ async function updatePaperclipIssueState(ctx, params) {
   });
   const issuePatch = {
     status: nextStatus,
-    ...syncExecutionStatePatch === null ? { executionState: null } : {}
+    ...syncExecutionStatePatch === null ? { executionState: null } : {},
+    ...clearExecutionPolicy ? { executionPolicy: null, executionState: null } : {}
   };
   if (nextAssignee) {
     if (nextAssignee.kind === "agent") {
@@ -7773,6 +7812,8 @@ async function createPaperclipIssue(ctx, mapping, advancedSettings, issue, avail
     projectId: mapping.paperclipProjectId,
     title,
     ...description ? { description } : {},
+    originKind: GITHUB_ISSUE_ORIGIN_KIND,
+    originId: normalizeGitHubIssueHtmlUrl(issue.htmlUrl) ?? issue.htmlUrl,
     ...defaultAssignee?.kind === "agent" ? { assigneeAgentId: defaultAssignee.id } : defaultAssignee?.kind === "user" ? { assigneeUserId: defaultAssignee.id } : {}
   });
   const ensuredCreatedIssueId = createdIssue.id;
@@ -8093,12 +8134,18 @@ async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mappi
         maintainerAuthoredImportedIssue,
         hasExecutorHandoffTarget: Boolean(executorTransitionAssignee)
       });
+      const shouldPreserveMaintainerWaitRouting = isHealthyMaintainerWaitTransition({
+        currentStatus: paperclipIssue.status,
+        nextStatus,
+        syncContext: paperclipIssueSyncContext
+      });
       const nextTransitionAssignee = resolveSyncTransitionAssignee({
+        currentStatus: paperclipIssue.status,
         nextStatus,
         syncContext: paperclipIssueSyncContext,
         advancedSettings
       });
-      const shouldClearTransitionAssignee = nextStatus === "in_review" && nextTransitionAssignee === null && paperclipIssueSyncContext.assignee !== null;
+      const shouldClearTransitionAssignee = nextStatus === "in_review" && (nextTransitionAssignee === null || shouldPreserveMaintainerWaitRouting) && paperclipIssueSyncContext.assignee !== null;
       const nextAssigneeChanged = nextTransitionAssignee ? !doesPaperclipIssueAssigneeMatch(paperclipIssueSyncContext.assignee, nextTransitionAssignee.principal) : false;
       const shouldWakeImportedAssignee = wasImportedThisRun && paperclipIssue.status === nextStatus && nextStatus === "todo" && paperclipIssueSyncContext.assignee?.kind === "agent";
       const shouldWakeTransitionAssignee = paperclipIssue.status !== nextStatus && nextTransitionAssignee?.principal.kind === "agent" && isActionablePaperclipIssueStatus(nextStatus) && (nextAssigneeChanged || paperclipIssue.status !== nextStatus);
@@ -8120,6 +8167,7 @@ async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mappi
             syncContext: paperclipIssueSyncContext,
             nextStatus,
             clearAssignee: true,
+            ...shouldPreserveMaintainerWaitRouting ? { clearExecutionPolicy: true } : {},
             transitionComment: "",
             paperclipApiBaseUrl
           });
@@ -8155,6 +8203,7 @@ async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mappi
         nextStatus,
         ...nextTransitionAssignee ? { nextAssignee: nextTransitionAssignee.principal } : {},
         ...shouldClearTransitionAssignee ? { clearAssignee: true } : {},
+        ...shouldPreserveMaintainerWaitRouting ? { clearExecutionPolicy: true } : {},
         transitionComment: transitionComment.body,
         transitionCommentAnnotation: transitionComment.annotation,
         paperclipApiBaseUrl
@@ -8278,12 +8327,18 @@ async function synchronizePaperclipPullRequestIssueStatuses(ctx, octokit, mappin
         pullRequest,
         hasExecutorHandoffTarget: Boolean(executorTransitionAssignee)
       });
+      const shouldPreserveMaintainerWaitRouting = isHealthyMaintainerWaitTransition({
+        currentStatus: paperclipIssue.status,
+        nextStatus,
+        syncContext: paperclipIssueSyncContext
+      });
       const nextTransitionAssignee = resolveSyncTransitionAssignee({
+        currentStatus: paperclipIssue.status,
         nextStatus,
         syncContext: paperclipIssueSyncContext,
         advancedSettings
       });
-      const shouldClearTransitionAssignee = nextStatus === "in_review" && nextTransitionAssignee === null && paperclipIssueSyncContext.assignee !== null;
+      const shouldClearTransitionAssignee = nextStatus === "in_review" && (nextTransitionAssignee === null || shouldPreserveMaintainerWaitRouting) && paperclipIssueSyncContext.assignee !== null;
       const nextAssigneeChanged = nextTransitionAssignee ? !doesPaperclipIssueAssigneeMatch(paperclipIssueSyncContext.assignee, nextTransitionAssignee.principal) : false;
       const shouldWakeTransitionAssignee = paperclipIssue.status !== nextStatus && nextTransitionAssignee?.principal.kind === "agent" && isActionablePaperclipIssueStatus(nextStatus) && (nextAssigneeChanged || paperclipIssue.status !== nextStatus);
       if (paperclipIssue.status === nextStatus) {
@@ -8300,6 +8355,7 @@ async function synchronizePaperclipPullRequestIssueStatuses(ctx, octokit, mappin
             syncContext: paperclipIssueSyncContext,
             nextStatus,
             clearAssignee: true,
+            ...shouldPreserveMaintainerWaitRouting ? { clearExecutionPolicy: true } : {},
             transitionComment: "",
             paperclipApiBaseUrl
           });
@@ -8324,6 +8380,7 @@ async function synchronizePaperclipPullRequestIssueStatuses(ctx, octokit, mappin
         nextStatus,
         ...nextTransitionAssignee ? { nextAssignee: nextTransitionAssignee.principal } : {},
         ...shouldClearTransitionAssignee ? { clearAssignee: true } : {},
+        ...shouldPreserveMaintainerWaitRouting ? { clearExecutionPolicy: true } : {},
         transitionComment,
         paperclipApiBaseUrl
       });
@@ -8626,156 +8683,38 @@ async function persistCompanyActivityMetricEvent(ctx, params, options = {}) {
     ...result.eventKey ? { eventKey: result.eventKey } : {}
   };
 }
-function parseWebhookPayloadRecord(input) {
-  if (input.parsedBody && typeof input.parsedBody === "object" && !Array.isArray(input.parsedBody)) {
-    return input.parsedBody;
-  }
-  const rawBody = input.rawBody.trim();
-  if (!rawBody) {
-    throw new Error("Webhook body must be a JSON object.");
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(rawBody);
-  } catch {
-    throw new Error("Webhook body must be valid JSON.");
-  }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("Webhook body must be a JSON object.");
-  }
-  return parsed;
-}
-async function resolveCompanyIdForCompanyMetricEvent(ctx, params) {
-  const requestedCompanyId = normalizeCompanyId(params.companyId);
-  if (requestedCompanyId) {
-    return requestedCompanyId;
+function parseCompanyMetricApiRouteBody(input) {
+  if (!input.body || typeof input.body !== "object" || Array.isArray(input.body)) {
+    throw new Error("Company KPI route body must be a JSON object.");
   }
-  if (!params.repositoryUrl) {
-    return void 0;
-  }
-  const settings = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));
-  const matchingCompanyIds = [
-    ...new Set(
-      settings.mappings.filter((mapping) => getNormalizedMappingRepositoryUrl(mapping) === params.repositoryUrl).map((mapping) => normalizeCompanyId(mapping.companyId)).filter((companyId) => Boolean(companyId))
-    )
-  ];
-  return matchingCompanyIds.length === 1 ? matchingCompanyIds[0] : void 0;
+  return input.body;
 }
-function getWebhookHeaderValue(headers, name) {
-  const normalizedName = name.trim().toLowerCase();
-  for (const [headerName, headerValue] of Object.entries(headers)) {
-    if (headerName.trim().toLowerCase() !== normalizedName) {
-      continue;
-    }
-    if (typeof headerValue === "string") {
-      const trimmedValue = headerValue.trim();
-      return trimmedValue || void 0;
-    }
-    if (!Array.isArray(headerValue)) {
-      continue;
-    }
-    for (const entry of headerValue) {
-      if (typeof entry !== "string") {
-        continue;
-      }
-      const trimmedValue = entry.trim();
-      if (trimmedValue) {
-        return trimmedValue;
+async function handleCompanyMetricApiRoute(ctx, input) {
+  if (input.routeKey !== COMPANY_METRIC_API_ROUTE_KEY) {
+    return {
+      status: 404,
+      body: {
+        error: `Unsupported plugin API route: ${input.routeKey}.`
       }
-    }
-  }
-  return void 0;
-}
-function normalizeCompanyMetricWebhookBearerToken(value) {
-  if (!value) {
-    return void 0;
-  }
-  const trimmedValue = value.trim();
-  if (!trimmedValue) {
-    return void 0;
-  }
-  const bearerMatch = trimmedValue.match(/^Bearer\s+(.+)$/i);
-  if (!bearerMatch) {
-    return void 0;
-  }
-  const token = bearerMatch[1]?.trim();
-  return token || void 0;
-}
-function normalizePaperclipCurrentAgentRecord(value) {
-  if (!value || typeof value !== "object") {
-    return null;
-  }
-  const record = value;
-  const id = normalizeOptionalString2(record.id);
-  const companyId = normalizeCompanyId(record.companyId);
-  return id && companyId ? {
-    id,
-    companyId
-  } : null;
-}
-async function readCompanyMetricWebhookCurrentAgent(paperclipApiBaseUrl, bearerToken) {
-  const response = await fetchPaperclipApi(getPaperclipCurrentAgentEndpoint(paperclipApiBaseUrl), {
-    method: "GET",
-    headers: {
-      accept: "application/json",
-      authorization: `Bearer ${bearerToken}`
-    }
-  });
-  const payloadResult = await readPaperclipApiJsonResponse(response, {
-    operationLabel: "current agent"
-  });
-  if (payloadResult.failure) {
-    if (payloadResult.failure.requiresAuthentication) {
-      throw new Error("Company KPI webhook Authorization must be a valid PAPERCLIP_API_KEY bearer token.");
-    }
-    const detail = payloadResult.failure.errorMessage ? ` ${payloadResult.failure.errorMessage}` : "";
-    throw new Error(`Could not validate the KPI webhook Paperclip API key.${detail}`);
-  }
-  const agent = normalizePaperclipCurrentAgentRecord(payloadResult.data);
-  if (!agent) {
-    throw new Error("Paperclip did not return a usable current agent record while validating the KPI webhook caller.");
-  }
-  return agent;
-}
-async function assertCompanyMetricWebhookAuthenticated(ctx, input, companyId) {
-  const rawAuthorization = getWebhookHeaderValue(input.headers, COMPANY_METRIC_WEBHOOK_AUTH_HEADER);
-  const bearerToken = normalizeCompanyMetricWebhookBearerToken(rawAuthorization);
-  if (!bearerToken) {
-    throw new Error(
-      `Missing or invalid ${COMPANY_METRIC_WEBHOOK_AUTH_HEADER} header. Use Bearer <PAPERCLIP_API_KEY>.`
-    );
+    };
   }
-  const settings = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));
-  const config = await getResolvedConfig(ctx);
-  const paperclipApiBaseUrl = getConfiguredPaperclipApiBaseUrl(settings, config, companyId);
-  if (!paperclipApiBaseUrl) {
-    throw new Error(
-      "A trusted Paperclip API origin is required to validate PAPERCLIP_API_KEY. Set PAPERCLIP_API_URL or save the Paperclip host origin before sending KPI webhook events."
-    );
+  if (input.actor.actorType !== "agent") {
+    throw new Error("Company KPI metric events must be recorded by an authenticated Paperclip agent.");
   }
-  const currentAgent = await readCompanyMetricWebhookCurrentAgent(paperclipApiBaseUrl, bearerToken);
-  if (normalizeCompanyId(currentAgent.companyId) !== companyId) {
-    throw new Error("Company KPI webhook Paperclip API key belongs to a different company.");
+  const companyId = normalizeCompanyId(input.companyId);
+  if (!companyId) {
+    throw new Error("Company KPI metric events require the host to provide the authenticated agent company.");
   }
-}
-async function handleCompanyMetricWebhook(ctx, input) {
-  if (input.endpointKey !== COMPANY_METRIC_WEBHOOK_ENDPOINT_KEY) {
-    throw new Error(`Unsupported webhook endpoint: ${input.endpointKey}.`);
+  const payload = parseCompanyMetricApiRouteBody(input);
+  const requestedCompanyId = normalizeCompanyId(payload.companyId);
+  if (requestedCompanyId && requestedCompanyId !== companyId) {
+    throw new Error("companyId must match the authenticated Paperclip agent company.");
   }
-  const payload = parseWebhookPayloadRecord(input);
   const repositoryInput = normalizeOptionalString2(payload.repository);
   const repository = repositoryInput ? parseRepositoryReference(repositoryInput) : null;
   if (repositoryInput && !repository) {
     throw new Error("repository must be owner/repo or https://github.com/owner/repo.");
   }
-  const companyId = await resolveCompanyIdForCompanyMetricEvent(ctx, {
-    companyId: payload.companyId,
-    repositoryUrl: repository?.url
-  });
-  if (!companyId) {
-    throw new Error("companyId is required unless repository maps to exactly one company.");
-  }
-  await assertCompanyMetricWebhookAuthenticated(ctx, input, companyId);
   const metric = normalizeCompanyActivityMetricInputValue(payload.metric);
   if (!metric) {
     throw new Error('metric must be "pull_request_created".');
@@ -8792,7 +8731,7 @@ async function handleCompanyMetricWebhook(ctx, input) {
   });
   if (!dedupeKey) {
     throw new Error(
-      "Company KPI webhook requires pullRequestUrl, repository plus pullRequestNumber, or eventKey so duplicate deliveries can be ignored."
+      "Company KPI metric events require pullRequestUrl, repository plus pullRequestNumber, or eventKey so duplicate deliveries can be ignored."
     );
   }
   const recordedMetric = await persistCompanyActivityMetricEvent(
@@ -8812,17 +8751,27 @@ async function handleCompanyMetricWebhook(ctx, input) {
     }
   );
   ctx.logger.info(
-    recordedMetric.recorded ? "GitHub Sync recorded a company KPI webhook event." : "GitHub Sync ignored a duplicate company KPI webhook event.",
+    recordedMetric.recorded ? "GitHub Sync recorded a company KPI API route event." : "GitHub Sync ignored a duplicate company KPI API route event.",
     {
-      endpointKey: input.endpointKey,
+      routeKey: input.routeKey,
       companyId,
       metric,
       repositoryUrl: repository?.url,
       pullRequestNumber,
       pullRequestUrl,
-      requestId: input.requestId
+      agentId: input.actor.agentId ?? null,
+      runId: input.actor.runId ?? null
     }
   );
+  return {
+    status: recordedMetric.recorded ? 201 : 200,
+    body: {
+      status: recordedMetric.recorded ? "recorded" : "duplicate",
+      recorded: recordedMetric.recorded,
+      companyId,
+      metric: "pull_request_created"
+    }
+  };
 }
 async function createGitHubToolOctokit(ctx, companyId) {
   const token = (await resolveGithubToken(ctx, { companyId })).trim();
@@ -11149,6 +11098,8 @@ async function createProjectPullRequestPaperclipIssue(ctx, input) {
     companyId: scope.companyId,
     projectId: scope.projectId,
     title: requestedTitle,
+    originKind: GITHUB_PULL_REQUEST_ORIGIN_KIND,
+    originId: pullRequestUrl,
     description: buildPaperclipIssueDescriptionFromPullRequest({
       repository: scope.repository,
       pullRequestNumber,
@@ -13309,6 +13260,11 @@ function shouldStartWorkerHost(moduleUrl, entry = process.argv[1]) {
     return resolve(entry) === resolve(modulePath);
   }
 }
+var __testing = {
+  buildSyncFallbackExecutionStatePatch,
+  isHealthyMaintainerWaitTransition,
+  resolveSyncTransitionAssignee
+};
 var plugin = definePlugin({
   async setup(ctx) {
     pluginRuntimeContext = ctx;
@@ -13676,11 +13632,11 @@ var plugin = definePlugin({
       }
     });
   },
-  async onWebhook(input) {
+  async onApiRequest(input) {
     if (!pluginRuntimeContext) {
-      throw new Error("GitHub Sync worker is not ready to handle webhooks yet.");
+      throw new Error("GitHub Sync worker is not ready to handle API routes yet.");
     }
-    await handleCompanyMetricWebhook(pluginRuntimeContext, input);
+    return handleCompanyMetricApiRoute(pluginRuntimeContext, input);
   },
   async onShutdown() {
     pluginRuntimeContext = null;
@@ -13691,6 +13647,7 @@ if (shouldStartWorkerHost(import.meta.url)) {
   startWorkerRpcHost({ plugin });
 }
 export {
+  __testing,
   worker_default as default,
   shouldStartWorkerHost
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-github-plugin",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Paperclip plugin for synchronizing GitHub issues into Paperclip projects.",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@octokit/rest": "^22.0.1",
-    "@paperclipai/plugin-sdk": "^2026.416.0",
+    "@paperclipai/plugin-sdk": "^2026.427.0",
     "react": "^19.2.5",
     "react-markdown": "^10.1.0",
     "rehype-raw": "^7.0.0",