feat(connections): add self-serve intent runtime (#12345)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents need a governed way to request app connections during issue
work.
> - The catalog now describes the available providers and setup methods.
> - A request must become a durable, company-scoped intent before an
operator acts on it.
> - This pull request adds that intent runtime across server, agent,
CLI, and shared contracts.
> - The benefit is a safe bridge from agent need to operator-approved
setup.

## Linked Issues or Issue Description

Refs #11965

This is stack 7 of 11. It depends on stack 6 and replaces another
reviewable part of #11965.

## What Changed

- Add connection intent types, validation, service logic, and routes.
- Add agent runtime tools and CLI support for connection requests.
- Add issue-thread interaction support for connection intents.
- Add runtime, route, adapter, and contract tests.
- Hold the final resolved-continuation row lock through asynchronous
adapter preparation until an actual process spawn, so parking or
reassignment cannot cross that boundary.
- Report Hermes Gateway's first remote run request through the shared
dispatch hook so the resolved-intent lock is released at the true
dispatch boundary.
- Revalidate the addressed user's live non-viewer membership and
connection-management authority for every intent mutation, including
OAuth completion.

## Verification

- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/tool-access-service.test.ts`
- Result: 176 tests passed.
- `pnpm build`
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/heartbeat-stale-queue-invalidation.test.ts` (32 passed;
includes non-process dispatch lock-release coverage)
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/connection-intents-service.test.ts -t
"addressed-user mutation"` (1 passed)
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/tool-access-service.test.ts -t "binds OAuth
callback completion to the initiating board session"` (1 passed)
- `pnpm --filter @paperclipai/hermes-paperclip-adapter test --
src/gateway/server/execute.test.ts` (23 passed; includes dispatch-hook
ordering and exactly-once coverage)
- `pnpm --filter @paperclipai/hermes-paperclip-adapter typecheck`

## Risks

- A malformed intent could create an unusable operator request.
- Validators and company checks reject invalid or cross-company
requests.
- The final continuation gate holds the issue row lock through adapter
preparation until process or remote dispatch; later operator changes use
the normal active-run interruption path.
- The change does not add a database migration.

> I checked `ROADMAP.md`. This stack continues the existing app
connection work from #11965 and does not duplicate another planned item.

## Model Used

OpenAI Codex, GPT-5. The runtime model ID and context window were not
exposed. The model used reasoning, tool use, and code execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have linked the public source pull request with `Refs #`
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

packages/shared/src/validators/connection-intent.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import {
+  connectionIntentPayloadSchema,
+  connectionIntentResultSchema,
+  connectionRequestInputSchema,
+  connectionsSearchInputSchema,
+  createIssueThreadInteractionSchema,
+} from "../index.js";
+
+const agentId = "11111111-1111-4111-8111-111111111111";
+
+describe("connection intent contracts", () => {
+  it("accepts the versioned server-authored payload and safe phases", () => {
+    expect(connectionIntentPayloadSchema.parse({
+      version: 1,
+      serviceSlug: "notion",
+      serviceName: "Notion",
+      serviceLogoUrl: "https://example.test/notion.svg",
+      requestingAgentId: agentId,
+      requestingAgentName: "Researcher",
+      phase: "requested",
+    })).toMatchObject({ serviceSlug: "notion", phase: "requested" });
+  });
+
+  it("rejects credentials, authorization URLs, and unknown phases in thread payloads", () => {
+    const base = {
+      version: 1,
+      serviceSlug: "notion",
+      serviceName: "Notion",
+      requestingAgentId: agentId,
+      requestingAgentName: "Researcher",
+      phase: "requested",
+    };
+    expect(connectionIntentPayloadSchema.safeParse({ ...base, credential: "secret" }).success).toBe(false);
+    expect(connectionIntentPayloadSchema.safeParse({ ...base, authorizationUrl: "https://oauth.test" }).success).toBe(false);
+    expect(connectionIntentPayloadSchema.safeParse({ ...base, phase: "connected" }).success).toBe(false);
+  });
+
+  it("validates terminal outcomes independently from payload state", () => {
+    expect(connectionIntentResultSchema.parse({
+      version: 1,
+      outcome: "connected",
+      connectionId: "22222222-2222-4222-8222-222222222222",
+    }).outcome).toBe("connected");
+    expect(connectionIntentResultSchema.parse({ version: 1, outcome: "declined" }).outcome).toBe("declined");
+  });
+
+  it("keeps generic interaction creation closed to the server-owned kind", () => {
+    expect(createIssueThreadInteractionSchema.safeParse({
+      kind: "connection_intent",
+      payload: {
+        version: 1,
+        serviceSlug: "notion",
+        serviceName: "Notion",
+        requestingAgentId: agentId,
+        requestingAgentName: "Researcher",
+        phase: "requested",
+      },
+    }).success).toBe(false);
+  });
+
+  it("normalizes canonical search and request tool inputs", () => {
+    expect(connectionsSearchInputSchema.parse({ query: "  notion  " })).toEqual({ query: "notion" });
+    expect(connectionRequestInputSchema.parse({ service: " notion " })).toEqual({ service: "notion" });
+  });
+});

packages/shared/src/validators/connection-intent.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+export const connectionsSearchInputSchema = z.object({
+  query: z.string().trim().max(200).default(""),
+}).strict();
+
+export const connectionRequestInputSchema = z.object({
+  service: z.string().trim().min(1).max(120),
+}).strict();
+
+export const completeConnectionIntentSchema = z.object({
+  connectionId: z.string().guid(),
+}).strict();
+
+export const declineConnectionIntentSchema = z.object({
+  reason: z.string().trim().max(4000).optional(),
+}).strict();
+
+export type ConnectionsSearchInput = z.infer<typeof connectionsSearchInputSchema>;
+export type ConnectionRequestInput = z.infer<typeof connectionRequestInputSchema>;
+export type CompleteConnectionIntent = z.infer<typeof completeConnectionIntentSchema>;
+export type DeclineConnectionIntent = z.infer<typeof declineConnectionIntentSchema>;

packages/shared/src/validators/index.ts

@@ -1,3 +1,14 @@
+export {
+  connectionsSearchInputSchema,
+  connectionRequestInputSchema,
+  completeConnectionIntentSchema,
+  declineConnectionIntentSchema,
+  type ConnectionsSearchInput,
+  type ConnectionRequestInput,
+  type CompleteConnectionIntent,
+  type DeclineConnectionIntent,
+} from "./connection-intent.js";
+
 export {
   nativeFinalizationResultSchema,
   nativeFinalizationResultV1Schema,
@@ -440,6 +451,9 @@ export {
   issueThreadInteractionResolverPolicyProvenanceSchema,
   issueThreadInteractionEffectiveResolverPolicySourceSchema,
   issueThreadInteractionContinuationPolicySchema,
+  connectionIntentPhaseSchema,
+  connectionIntentPayloadSchema,
+  connectionIntentResultSchema,
   suggestedTaskDraftSchema,
   suggestTasksPayloadSchema,
   suggestTasksResultCreatedTaskSchema,
@@ -884,6 +898,8 @@ export {
   type GenericMcpOAuthClient,
   reconnectToolAppSchema,
   finishToolAppSchema,
+  finalizeOAuthAccessSchema,
+  startToolOAuthSchema,
   updateToolApplicationSchema,
   createToolConnectionSchema,
   createToolMcpGatewaySchema,
@@ -917,6 +933,8 @@ export {
   type ReconnectToolApp,
   type CreateToolApplication,
   type FinishToolApp,
+  type FinalizeOAuthAccess,
+  type StartToolOAuth,
   type UpdateToolApplication,
   type CreateToolConnection,
   type CreateToolMcpGateway,

packages/shared/src/validators/issue.ts

@@ -756,6 +756,50 @@ export const issueThreadInteractionContinuationPolicySchema = z.enum(
   ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES,
 );
 
+export const connectionIntentPhaseSchema = z.enum(["requested", "authorizing", "needs_retry"]);
+const connectionIntentBrandAssetSchema = z.string().max(2048).refine((value) => {
+  if (/^\/brands\/apps\/[a-z0-9][a-z0-9._-]*\.(?:svg|png)$/i.test(value)) return true;
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}, "Connection intent brand assets must be HTTPS URLs or local app brand paths");
+
+export const connectionIntentPayloadSchema = z.object({
+  version: z.literal(1),
+  serviceSlug: z.string().trim().min(1).max(120),
+  serviceName: z.string().trim().min(1).max(160),
+  serviceLogoUrl: connectionIntentBrandAssetSchema.nullable().optional(),
+  serviceDarkLogoUrl: connectionIntentBrandAssetSchema.nullable().optional(),
+  requestingAgentId: z.string().guid(),
+  requestingAgentName: z.string().trim().min(1).max(160),
+  phase: connectionIntentPhaseSchema,
+}).strict();
+
+export const connectionIntentResultSchema = z.object({
+  version: z.literal(1),
+  outcome: z.enum(["connected", "declined", "superseded", "expired"]),
+  connectionId: z.string().guid().nullable().optional(),
+  reason: z.string().trim().max(4000).nullable().optional(),
+  supersededByInteractionId: z.string().guid().nullable().optional(),
+}).strict().superRefine((value, ctx) => {
+  if (value.outcome === "connected" && !value.connectionId) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["connectionId"],
+      message: "Connected intents require a connection id",
+    });
+  }
+  if (value.outcome === "superseded" && !value.supersededByInteractionId) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["supersededByInteractionId"],
+      message: "Superseded intents require the replacement interaction id",
+    });
+  }
+});
+
 export const issueDocumentKeySchema = z
   .string()
   .trim()

packages/shared/src/validators/tool-access.test.ts

@@ -72,6 +72,17 @@ describe("tool access validators", () => {
     }).success).toBe(false);
   });
 
+  it("accepts only UUID connection request links during app setup", () => {
+    expect(connectToolAppSchema.safeParse({
+      galleryKey: "posthog",
+      interactionId: "11111111-1111-4111-8111-111111111111",
+    }).success).toBe(true);
+    expect(connectToolAppSchema.safeParse({
+      galleryKey: "posthog",
+      interactionId: "not-an-interaction",
+    }).success).toBe(false);
+  });
+
   // PAP-17087: the guided generic flow and paste-config both reach the connect
   // endpoint, so unsafe header names/values are rejected once at this boundary.
   it("accepts generic advanced-authentication input for a pasted URL", () => {
@@ -91,6 +102,11 @@ describe("tool access validators", () => {
       oauthClient: { clientId: "client-abc", clientSecret: "shhh" },
     });
     expect(manualClient.success).toBe(true);
+
+    expect(connectToolAppSchema.safeParse({
+      galleryKey: "asana",
+      oauthClient: { clientId: "customer-client", clientSecret: "customer-secret" },
+    }).success).toBe(true);
   });
 
   it("rejects header credentials Paperclip refuses to send", () => {
@@ -123,7 +139,7 @@ describe("tool access validators", () => {
     }
   });
 
-  it("keeps generic advanced authentication off the curated gallery path", () => {
+  it("keeps generic auth-mode selection off curated apps while allowing owned OAuth clients", () => {
     expect(connectToolAppSchema.safeParse({
       galleryKey: "posthog",
       authMode: "bearer",
@@ -131,7 +147,7 @@ describe("tool access validators", () => {
     expect(connectToolAppSchema.safeParse({
       galleryKey: "posthog",
       oauthClient: { clientId: "client-abc" },
-    }).success).toBe(false);
+    }).success).toBe(true);
   });
 
   it("accepts secret references for connection credentials", () => {

packages/shared/src/validators/tool-access.ts

@@ -364,6 +364,8 @@ export const connectToolAppSchema = z.object({
   credentialValues: z.record(z.string().trim().min(1).max(200), z.string().min(1)).optional(),
   configValues: z.record(z.string().trim().min(1).max(200), z.unknown()).optional(),
   applicationId: z.string().guid().optional(),
+  /** Pending connection request this setup should resolve after authorization. */
+  interactionId: z.string().uuid().optional(),
   authMode: genericMcpAuthModeSchema.optional(),
   oauthClient: genericMcpOAuthClientSchema.optional(),
   /**
@@ -383,13 +385,6 @@ export const connectToolAppSchema = z.object({
       message: "Authentication mode selection applies to a pasted URL, not a gallery app",
     });
   }
-  if (value.oauthClient && value.galleryKey) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.custom,
-      path: ["oauthClient"],
-      message: "Preregistered OAuth client credentials apply to a pasted URL, not a gallery app",
-    });
-  }
 }).refine(
   (value) => Boolean(value.galleryKey) !== Boolean(value.link),
   { message: "Provide exactly one of galleryKey or link" },
@@ -415,6 +410,24 @@ export const finishToolAppSchema = z.object({
 
 export type FinishToolApp = z.infer<typeof finishToolAppSchema>;
 
+/**
+ * Legacy promotion boundary retained for connection-intent flows. Interactive
+ * app setup chooses identity before OAuth and writes the token directly to that
+ * credential scope.
+ */
+export const finalizeOAuthAccessSchema = z.object({
+  grantKind: connectionGrantKindSchema,
+}).strict();
+
+export type FinalizeOAuthAccess = z.infer<typeof finalizeOAuthAccessSchema>;
+
+export const startToolOAuthSchema = z.object({
+  asCurrentUser: z.boolean().optional(),
+  interactionId: z.string().uuid().optional(),
+}).strict().default({});
+
+export type StartToolOAuth = z.infer<typeof startToolOAuthSchema>;
+
 export const upsertToolCatalogEntrySchema = z.object({
   applicationId: z.string().guid(),
   connectionId: z.string().guid(),