refactor: simplify gateway to thin protocol translator

The AF runtime handles all execution, threads, tools, and RAG.
The gateway just translates platform webhooks → AF API calls.

- Remove paperclip-bridge.ts (299 lines) — replaced by gateway
- Simplify connector interface: NormalizedTask → InboundTask
- Remove prompt building, stream parsing duplication from connectors
- Connectors now just: parse webhook + post result (< 100 lines each)
- `af paperclip serve` now delegates to gateway
- Net: -461 lines

Author: seanphan

packages/cli/src/cli/gateway/connector.ts

@@ -1,59 +1,51 @@
 /**
- * Channel connector interface — inspired by hermes-agent's platform adapters.
+ * Channel connector interface.
  *
- * A "channel" is any external platform that can send tasks to AgenticFlow
- * agents: Paperclip, Linear, GitHub, Slack, webhooks, etc.
+ * A connector is a THIN protocol translator between an external platform
+ * and the AgenticFlow runtime API. It does NOT contain business logic —
+ * the runtime handles agent execution, thread persistence, RAG, tools, etc.
  *
- * Each connector normalizes platform-specific events into a standard task
- * and posts results back to the originating channel.
+ * Connector responsibilities:
+ *   1. Parse platform webhook → { afAgentId, message, threadId }
+ *   2. Post agent response back to platform
+ *
+ * Runtime responsibilities (NOT the connector's job):
+ *   - Agent execution, streaming, tool calling
+ *   - Thread/session persistence
+ *   - Knowledge retrieval, sub-agents
+ *   - Credit management, permissions
  */
 
-/** Platform-agnostic task representation (the "MessageEvent" equivalent). */
-export interface NormalizedTask {
-  /** Stable UUID for AF thread continuity across messages. */
-  threadId: string;
-  /** Human-readable identifier, e.g. "PIX-1", "LIN-123". */
-  taskIdentifier: string;
-  /** The full message to send to the AF agent. */
-  message: string;
+/** What the connector extracts from a platform webhook. */
+export interface InboundTask {
   /** AF agent ID to invoke. */
   afAgentId: string;
-  /** Override AF stream URL. */
+  /** Message to send to the agent. */
+  message: string;
+  /** Thread ID for conversation continuity (reuse across calls for same task). */
+  threadId?: string;
+  /** Override AF stream URL (if stored in platform metadata). */
   afStreamUrl?: string;
-  /** Source channel info (for routing responses back). */
-  source: {
-    channel: string;
-    chatId: string;
-    userId?: string;
-    userName?: string;
-  };
-  /** Opaque platform data the connector needs in postResult. */
-  platformContext: Record<string, unknown>;
+  /** Human-readable task label for logging. */
+  label: string;
+  /** Opaque data the connector needs to post results back. */
+  replyContext: Record<string, unknown>;
 }
 
-/** Channel connector for receiving tasks from an external platform. */
+/** Channel connector — thin protocol translator. */
 export interface ChannelConnector {
-  /** Short slug: paperclip, linear, github, webhook, etc. */
+  /** Short slug: paperclip, linear, github, webhook */
   readonly name: string;
-  /** Human-readable display name. */
-  readonly displayName: string;
 
   /**
-   * Parse incoming webhook into a NormalizedTask.
-   * Return null to skip (irrelevant event type).
-   * Throw to reject with 400.
+   * Parse incoming webhook → InboundTask.
+   * Return null to acknowledge but skip.
    */
   parseWebhook(
     headers: Record<string, string | string[] | undefined>,
     body: string,
-  ): Promise<NormalizedTask | null>;
+  ): Promise<InboundTask | null>;
 
-  /** Post agent response back to the originating channel. */
-  postResult(task: NormalizedTask, resultText: string): Promise<void>;
-
-  /** Optional: check if the channel is reachable. */
-  healthCheck?(): Promise<boolean>;
+  /** Post agent response back to originating platform. */
+  postResult(task: InboundTask, resultText: string): Promise<void>;
 }
-
-/** Registry of available channel connectors. */
-export type ConnectorRegistry = Map<string, ChannelConnector>;

packages/cli/src/cli/gateway/connectors/linear.ts

@@ -1,163 +1,93 @@
 /**
- * Linear channel connector.
+ * Linear channel connector (thin).
  *
- * Receives Linear webhooks (issue.create, issue.update, comment.create),
- * fetches issue context, and posts results back as comments.
- *
- * Setup: In Linear → Settings → API → Webhooks, add:
- *   URL: https://your-gateway/webhook/linear
- *   Events: Issues (created, updated), Comments (created)
+ * Translates Linear webhooks → AF runtime call.
+ * Linear webhook events: issue.create, issue.update, comment.create.
  */
 
-import type { ChannelConnector, NormalizedTask } from "../connector.js";
+import type { ChannelConnector, InboundTask } from "../connector.js";
 
 export interface LinearConnectorConfig {
   linearApiKey: string;
-  /** Map of Linear team key → AF agent ID. e.g. { "ENG": "af-agent-uuid" } */
+  /** Team key → AF agent ID. e.g. { "ENG": "af-uuid" } */
   agentMapping: Record<string, string>;
-  /** Optional: AF stream URL override per agent. */
-  streamUrlMapping?: Record<string, string>;
 }
 
-// Minimal Linear GraphQL client
-async function linearQuery(
-  apiKey: string,
-  query: string,
-  variables?: Record<string, unknown>,
-): Promise<unknown> {
+async function linearGql(apiKey: string, query: string, variables?: Record<string, unknown>): Promise<unknown> {
   const resp = await fetch("https://api.linear.app/graphql", {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: apiKey,
-    },
+    headers: { "Content-Type": "application/json", Authorization: apiKey },
     body: JSON.stringify({ query, variables }),
   });
-  if (!resp.ok) throw new Error(`Linear API failed (${resp.status})`);
+  if (!resp.ok) throw new Error(`Linear API ${resp.status}`);
   const result = (await resp.json()) as { data?: unknown; errors?: unknown[] };
-  if (result.errors) throw new Error(`Linear GraphQL: ${JSON.stringify(result.errors)}`);
+  if (result.errors) throw new Error(JSON.stringify(result.errors));
   return result.data;
 }
 
-async function linearGetIssue(apiKey: string, issueId: string): Promise<Record<string, unknown>> {
-  const data = (await linearQuery(apiKey, `
-    query($id: String!) {
-      issue(id: $id) {
-        id identifier title description priority priorityLabel
-        state { name }
-        team { key name }
-        assignee { name }
-        labels { nodes { name } }
-        comments { nodes { body user { name } createdAt } }
-      }
-    }
-  `, { id: issueId })) as { issue: Record<string, unknown> };
-  return data.issue;
-}
-
-async function linearAddComment(apiKey: string, issueId: string, body: string): Promise<void> {
-  await linearQuery(apiKey, `
-    mutation($issueId: String!, $body: String!) {
-      commentCreate(input: { issueId: $issueId, body: $body }) {
-        success
-      }
-    }
-  `, { issueId, body });
-}
-
 export class LinearConnector implements ChannelConnector {
   readonly name = "linear";
-  readonly displayName = "Linear";
 
   constructor(private config: LinearConnectorConfig) {}
 
   async parseWebhook(
     _headers: Record<string, string | string[] | undefined>,
     body: string,
-  ): Promise<NormalizedTask | null> {
+  ): Promise<InboundTask | null> {
     const payload = JSON.parse(body) as {
       action: string;
       type: string;
-      data: {
-        id: string;
-        title?: string;
-        description?: string;
-        identifier?: string;
-        teamId?: string;
-        issueId?: string;   // for comments
-        body?: string;       // for comments
-        [key: string]: unknown;
-      };
-      url?: string;
+      data: Record<string, unknown>;
     };
 
-    // Only handle issue creates/updates and comment creates
     const isIssue = payload.type === "Issue" && ["create", "update"].includes(payload.action);
     const isComment = payload.type === "Comment" && payload.action === "create";
     if (!isIssue && !isComment) return null;
 
-    const issueId = isComment ? payload.data.issueId! : payload.data.id;
+    const issueId = isComment ? payload.data.issueId as string : payload.data.id as string;
+
+    // Fetch issue for context
+    const data = (await linearGql(this.config.linearApiKey, `
+      query($id: String!) {
+        issue(id: $id) {
+          id identifier title description priorityLabel
+          state { name }
+          team { key }
+        }
+      }
+    `, { id: issueId })) as { issue: Record<string, unknown> };
 
-    // Fetch full issue details
-    const issue = await linearGetIssue(this.config.linearApiKey, issueId);
+    const issue = data.issue;
     const team = issue.team as Record<string, unknown> | undefined;
     const teamKey = (team?.key as string) ?? "";
-
-    // Find AF agent for this team
     const afAgentId = this.config.agentMapping[teamKey];
-    if (!afAgentId) return null; // No agent mapped for this team — skip
+    if (!afAgentId) return null; // No agent for this team
 
     const state = issue.state as Record<string, unknown> | undefined;
-    const labels = issue.labels as { nodes: Array<{ name: string }> } | undefined;
-    const comments = issue.comments as { nodes: Array<Record<string, unknown>> } | undefined;
-
-    // Build message
-    const parts: string[] = [];
-    parts.push("You have received a task from Linear.\n");
-    parts.push(`## Task: ${issue.identifier} — ${issue.title}`);
-    parts.push(`- **Priority:** ${issue.priorityLabel ?? "medium"}`);
-    parts.push(`- **Status:** ${state?.name ?? "unknown"}`);
-    if (labels?.nodes?.length) {
-      parts.push(`- **Labels:** ${labels.nodes.map((l) => l.name).join(", ")}`);
-    }
-    if (issue.description) {
-      parts.push(`\n### Description\n${issue.description}`);
-    }
-    if (comments?.nodes?.length) {
-      parts.push("\n### Recent Comments");
-      for (const c of comments.nodes.slice(-5)) {
-        const user = c.user as Record<string, unknown> | undefined;
-        parts.push(`- **${user?.name ?? "Unknown"}:** ${c.body}`);
-      }
-    }
-    if (isComment && payload.data.body) {
-      parts.push(`\n### New Comment (trigger)\n${payload.data.body}`);
-    }
-    parts.push("\n## Instructions\nComplete this task. Provide a clear summary of your work.");
+    const parts = [
+      `Task: ${issue.identifier} — ${issue.title}`,
+      `Priority: ${issue.priorityLabel ?? "medium"} | Status: ${state?.name ?? "unknown"}`,
+    ];
+    if (issue.description) parts.push(`Description: ${issue.description}`);
+    if (isComment && payload.data.body) parts.push(`New comment: ${payload.data.body}`);
 
     return {
-      threadId: issueId, // reuse Linear issue ID as thread for continuity
-      taskIdentifier: (issue.identifier as string) ?? issueId,
-      message: parts.join("\n"),
       afAgentId,
-      afStreamUrl: this.config.streamUrlMapping?.[afAgentId],
-      source: {
-        channel: "linear",
-        chatId: teamKey,
-        userName: (issue.assignee as Record<string, unknown>)?.name as string | undefined,
-      },
-      platformContext: { issueId, teamKey },
+      message: parts.join("\n"),
+      threadId: issueId,
+      label: (issue.identifier as string) ?? issueId,
+      replyContext: { issueId, teamKey },
     };
   }
 
-  async postResult(task: NormalizedTask, resultText: string): Promise<void> {
-    const issueId = task.platformContext.issueId as string;
+  async postResult(task: InboundTask, resultText: string): Promise<void> {
+    const issueId = task.replyContext.issueId as string;
     if (issueId && resultText) {
-      await linearAddComment(
-        this.config.linearApiKey,
-        issueId,
-        `**Agent Response:**\n\n${resultText}`,
-      );
+      await linearGql(this.config.linearApiKey, `
+        mutation($issueId: String!, $body: String!) {
+          commentCreate(input: { issueId: $issueId, body: $body }) { success }
+        }
+      `, { issueId, body: `**Agent Response:**\n\n${resultText}` });
     }
   }
 }