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>

cli/src/commands/client/connections.ts

@@ -0,0 +1,74 @@
+import { Command } from "commander";
+import {
+  CONNECTION_INTENT_AGENT_GUIDANCE,
+  connectionRequestInputSchema,
+  connectionsSearchInputSchema,
+} from "@paperclipai/shared";
+
+interface RuntimeConnectionOptions {
+  json?: boolean;
+}
+
+async function callRuntimeConnectionTool(
+  endpointEnv: "PAPERCLIP_RUNTIME_TOOLS_CONNECTIONS_SEARCH_URL" | "PAPERCLIP_RUNTIME_TOOLS_CONNECTION_REQUEST_URL",
+  body: unknown,
+) {
+  const endpoint = process.env[endpointEnv]?.trim();
+  const token = process.env.PAPERCLIP_RUNTIME_TOOLS_TOKEN?.trim();
+  if (!endpoint || !token) {
+    throw new Error("This command requires the runtime connection environment from an active heartbeat run");
+  }
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  const parsed = text ? JSON.parse(text) as unknown : null;
+  if (!response.ok) {
+    const message = parsed && typeof parsed === "object" && "error" in parsed
+      ? String((parsed as { error: unknown }).error)
+      : `Runtime connection request failed with ${response.status}`;
+    throw new Error(message);
+  }
+  return parsed;
+}
+
+function writeResult(value: unknown, options: RuntimeConnectionOptions) {
+  process.stdout.write(`${JSON.stringify(value, null, options.json ? 2 : 0)}\n`);
+}
+
+export function registerConnectionIntentCommands(program: Command) {
+  const connections = program
+    .command("connections")
+    .description("Search or request connections from an active heartbeat run")
+    .addHelpText("after", `\n${CONNECTION_INTENT_AGENT_GUIDANCE}\n`);
+
+  connections
+    .command("search")
+    .argument("[query]", "Service name or capability")
+    .option("--json", "Print formatted JSON")
+    .action(async (query: string | undefined, options: RuntimeConnectionOptions) => {
+      const input = connectionsSearchInputSchema.parse({ query: query ?? "" });
+      writeResult(await callRuntimeConnectionTool(
+        "PAPERCLIP_RUNTIME_TOOLS_CONNECTIONS_SEARCH_URL",
+        input,
+      ), options);
+    });
+
+  connections
+    .command("request")
+    .argument("<service>", "Connectable service slug")
+    .option("--json", "Print formatted JSON")
+    .action(async (service: string, options: RuntimeConnectionOptions) => {
+      const input = connectionRequestInputSchema.parse({ service });
+      writeResult(await callRuntimeConnectionTool(
+        "PAPERCLIP_RUNTIME_TOOLS_CONNECTION_REQUEST_URL",
+        input,
+      ), options);
+    });
+}

cli/src/index.ts

@@ -48,6 +48,7 @@ import { installCommand } from "./commands/install.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { updateCommand } from "./commands/update.js";
 import { registerServiceCommands } from "./commands/service.js";
+import { registerConnectionIntentCommands } from "./commands/client/connections.js";
 
 const program = new Command();
 const DATA_DIR_OPTION_HELP =
@@ -209,6 +210,7 @@ heartbeat
 
 registerContextCommands(program);
 registerConnectCommand(program);
+registerConnectionIntentCommands(program);
 registerCompanyCommands(program);
 registerIssueCommands(program);
 registerAgentCommands(program);