@pixelml/agenticflow-cli 1.0.7 → 1.1.1

package/README.md

@@ -1,232 +1,150 @@
 # @pixelml/agenticflow-cli
 
-Command-line interface for the [AgenticFlow](https://agenticflow.ai) platform.
-Manage agents, workflows, connections and more — directly from your terminal.
+Command-line interface for the [AgenticFlow](https://agenticflow.ai) platform — build agents, deploy them to external platforms, and receive tasks from any webhook source.
 
 Built on [`@pixelml/agenticflow-sdk`](https://www.npmjs.com/package/@pixelml/agenticflow-sdk).
 
-## Installation
+## Install
 
 ```bash
 npm install -g @pixelml/agenticflow-cli
 ```
 
-Or run directly via `npx`:
+Available as both `agenticflow` and `af` (short alias). Requires Node.js 18+.
 
-```bash
-npx @pixelml/agenticflow-cli --help
-```
-
-## Authentication
-
-### Interactive login
+## Quick Start
 
 ```bash
-agenticflow login
+af login                    # Authenticate
+af doctor --json            # Verify setup
+af agent list --fields id,name,model --json   # List agents
+af agent stream --agent-id <id> --body '{"messages":[{"content":"Hello!"}]}'
 ```
 
-Prompts for API key, workspace ID and project ID, then saves them to
-`~/.agenticflow/auth.json`.
+> **AI agents**: Run `af context --json` for a machine-readable bootstrap guide.
 
-### Environment variables
+## Authentication
 
 ```bash
-export AGENTICFLOW_API_KEY="sk-..."
-export AGENTICFLOW_WORKSPACE_ID="ws-..."
-export AGENTICFLOW_PROJECT_ID="proj-..."
+af login                                 # Interactive (saves to ~/.agenticflow/auth.json)
+export AGENTICFLOW_API_KEY=<key>         # Environment variable
+af --api-key <key> agent list            # CLI flag
+af auth import-env --file .env           # Import from .env
+af whoami --json                         # Verify
 ```
 
-### Import from `.env` file
-
-```bash
-agenticflow auth import-env --file .env
-```
+## Core Commands
 
-### CLI flags
+### Agents
 
 ```bash
-agenticflow --api-key sk-... --workspace-id ws-... agent list
+af agent list --fields id,name,model --json
+af agent get --agent-id <id> --json
+af agent create --body @agent.json --dry-run    # Validate first
+af agent create --body @agent.json
+af agent stream --agent-id <id> --body @stream.json
+af agent update --agent-id <id> --body @update.json
+af agent delete --agent-id <id>
 ```
 
-**Resolution order:** CLI flag → environment variable → `~/.agenticflow/auth.json`
-
-### Verify
+### Workflows
 
 ```bash
-agenticflow whoami
+af workflow list --fields id,name,status --json
+af workflow create --body @wf.json --dry-run
+af workflow create --body @wf.json
+af workflow run --workflow-id <id> --input @input.json
+af workflow run-status --workflow-run-id <run_id> --json
+af workflow validate --body @wf.json --local-only
 ```
 
-```
-Profile:      default
-API Key:      present
-Workspace ID: ws-abc123
-Project ID:   proj-xyz789
-Config:       ~/.agenticflow/auth.json
-```
+### Webhook Gateway
 
-### Logout
+Receive tasks from any platform and route them to AgenticFlow agents:
 
 ```bash
-agenticflow logout                   # remove all credentials
-agenticflow logout --profile staging # remove a single profile
+af gateway serve --channels paperclip,linear,webhook --verbose
+af gateway channels    # List available channels
 ```
 
-## Commands
-
-### Cold start
-
+**Generic webhook** — any system can send tasks:
 ```bash
-# Machine-discoverable first-touch path
-agenticflow discover --json
-agenticflow playbook first-touch
-
-# Prime local template cache for workflow/agent/workforce examples
-agenticflow templates sync --json
-agenticflow templates index --json
+curl -X POST http://localhost:4100/webhook/webhook \
+  -H "Content-Type: application/json" \
+  -d '{"agent_id":"<id>","message":"Summarize Q4 report"}'
 ```
 
-### agent
-
+**Paperclip** — AI company orchestration:
 ```bash
-agenticflow agent list [--project-id <id>] [--search <q>] [--limit <n>] [--offset <n>]
-agenticflow agent get --agent-id <id>
-agenticflow agent create --body <json|@file>
-agenticflow agent update --agent-id <id> --body <json|@file>
-agenticflow agent delete --agent-id <id>
-agenticflow agent stream --agent-id <id> --body <json|@file>
-agenticflow agent reference-impact --agent-id <id>
+af gateway serve --channels paperclip
 ```
 
-### workflow
-
+**Linear** — engineering project management:
 ```bash
-agenticflow workflow list [--workspace-id <id>] [--project-id <id>] [--search <q>] [--limit <n>]
-agenticflow workflow get --workflow-id <id>
-agenticflow workflow create --body <json|@file> [--workspace-id <id>]
-agenticflow workflow update --workflow-id <id> --body <json|@file> [--workspace-id <id>]
-agenticflow workflow delete --workflow-id <id> [--workspace-id <id>]
-agenticflow workflow run --workflow-id <id> [--input <json|@file>]
-agenticflow workflow run-status --workflow-run-id <id>
-agenticflow workflow list-runs --workflow-id <id> [--sort-order asc|desc]
-agenticflow workflow run-history --workflow-id <id>
-agenticflow workflow validate --body <json|@file> [--local-only]
-agenticflow workflow reference-impact --workflow-id <id>
-agenticflow workflow like-status --workflow-id <id>
+af gateway serve --channels linear
 ```
 
-### connections
-
-```bash
-agenticflow connections list [--workspace-id <id>] [--project-id <id>]
-agenticflow connections create --body <json|@file> [--workspace-id <id>]
-agenticflow connections update --connection-id <id> --body <json|@file> [--workspace-id <id>]
-agenticflow connections delete --connection-id <id> [--workspace-id <id>]
-```
+### Paperclip Integration
 
-### node-types
+Deploy agents to [Paperclip](https://github.com/paperclipai/paperclip) companies:
 
 ```bash
-agenticflow node-types list
-agenticflow node-types get --name <name>
-agenticflow node-types search --query <q>
-agenticflow node-types dynamic-options --name <name> --field-name <field> [--connection <name>]
+af paperclip company create --name "My Company" --budget 100000
+af paperclip deploy --agent-id <id> --role engineer
+af paperclip goal create --title "Build the product" --level company
+af paperclip issue create --title "Design landing page" --assignee <agent-id>
+af paperclip connect                    # Wire agents to gateway
+af paperclip agent wakeup --id <id>     # Trigger execution
+af paperclip dashboard                  # Monitor
 ```
 
-### uploads
+### AI-Agent Discovery
 
 ```bash
-agenticflow uploads create --body <json|@file>
-agenticflow uploads status --session-id <id>
+af context --json       # Bootstrap guide with invariants and schemas
+af schema agent         # Payload schema with examples
+af schema --json        # List all resource schemas
+af discover --json      # Full capability index
+af playbook quickstart  # Step-by-step guide
 ```
 
-### Generic API call
-
-For any endpoint not covered by resource commands:
+### Node Types & Connections
 
 ```bash
-# By operation ID
-agenticflow call --operation-id get_by_id_v1_agents__agent_id__get -P agent_id=abc123
-
-# By method + path
-agenticflow call --method GET --path /v1/agents/
-
-# With parameters and body
-agenticflow call --operation-id update_v1_agents__agent_id__put \
-  -P agent_id=abc123 \
-  --body '{"name": "Updated"}'
-
-# Query parameters
-agenticflow call --method GET --path /v1/agents/ -Q limit=10
-
-# Dry run (shows request without executing)
-agenticflow call --operation-id get_all_v1_agents__get --dry-run
+af node-types search --query "llm" --json
+af node-types get --name <name> --json
+af connections list --limit 200 --json
 ```
 
-### Utilities
+### Playbooks
 
 ```bash
-# Preflight diagnostics
-agenticflow doctor
-
-# Machine-readable capability discovery
-agenticflow discover --json
-
-# OpenAPI operation discovery
-agenticflow ops list [--public-only] [--tag <tag>] [--json]
-agenticflow ops show <operation-id>
-
-# Operation catalog
-agenticflow catalog export [--public-only]
-agenticflow catalog rank --task "send a message" [--top <n>]
-
-# Policy guardrails
-agenticflow policy show
-agenticflow policy init [--spend-ceiling <amount>]
-
-# Built-in playbooks
-agenticflow playbook [topic] [--list]
-# First-touch onboarding for cold agents
-agenticflow playbook first-touch
-agenticflow playbook --list --json
-
-# Template bootstrap cache for cold agents
-agenticflow templates sync [--dir .agenticflow/templates] [--limit 100] [--strict] [--json]
-agenticflow templates index [--dir .agenticflow/templates] [--json]
-
-# Duplicate resources from templates (web-like flow)
-agenticflow templates duplicate workflow --template-id <workflow_template_id> --json
-agenticflow templates duplicate agent --template-id <agent_template_id> --json
-# Build payloads only (no create)
-agenticflow templates duplicate workflow --template-id <id> --dry-run --json
-# Resolve template IDs from local cache first (cold/sandbox-friendly)
-agenticflow templates duplicate workflow --template-id <id> --cache-dir .agenticflow/templates --json
-agenticflow templates duplicate agent --template-file .agenticflow/templates/agent/<file>.json --cache-dir .agenticflow/templates --dry-run --json
+af playbook quickstart           # Zero to working agent in 5 min
+af playbook gateway-setup        # Webhook gateway setup
+af playbook deploy-to-paperclip  # Paperclip company setup
+af playbook agent-channels       # Connect Linear, webhooks, etc.
+af playbook agent-build          # Agent configuration
+af playbook workflow-build       # Workflow design
+af playbook template-bootstrap   # Start from templates
 ```
 
 ## Global Options
 
-| Flag | Description |
-|---|---|
-| `--api-key <key>` | API key for authentication |
-| `--workspace-id <id>` | Default workspace ID |
-| `--project-id <id>` | Default project ID |
-| `--spec-file <path>` | Path to OpenAPI spec JSON |
-| `--no-color` | Disable ANSI color output |
-| `--json` | Force JSON output |
-| `--version` | Show version |
-| `--help` | Show help |
-
-## Output
-
-Use `--json` for machine-readable output. In JSON mode, errors use a structured envelope and exit non-zero.
-
-Create/update/run/stream commands perform local payload validation first. This returns `local_schema_validation_failed` immediately for malformed inputs, before any API request is sent.
-
-`templates duplicate` can resolve workflow templates from a local `templates sync` cache via `--cache-dir` before attempting API fetches. This improves cold-start behavior in restricted environments.
-
-```bash
-agenticflow agent list | jq '.[] | .name'
-```
+| Flag | Purpose |
+|------|---------|
+| `--json` | Machine-readable JSON output |
+| `--fields <fields>` | Filter output fields (saves context window) |
+| `--dry-run` | Validate without executing |
+| `--api-key <key>` | Override API key |
+| `--workspace-id <id>` | Override workspace |
+| `--project-id <id>` | Override project |
+
+## Links
+
+- [AgenticFlow Platform](https://agenticflow.ai)
+- [Documentation](https://docs.agenticflow.ai)
+- [SDK Package](https://www.npmjs.com/package/@pixelml/agenticflow-sdk)
+- [GitHub](https://github.com/PixelML/agenticflow-cli)
 
 ## License
 

package/dist/cli/gateway/connector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Channel connector interface — inspired by hermes-agent's platform adapters.
+ *
+ * A "channel" is any external platform that can send tasks to AgenticFlow
+ * agents: Paperclip, Linear, GitHub, Slack, webhooks, etc.
+ *
+ * Each connector normalizes platform-specific events into a standard task
+ * and posts results back to the originating channel.
+ */
+/** 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;
+    /** AF agent ID to invoke. */
+    afAgentId: string;
+    /** Override AF stream URL. */
+    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>;
+}
+/** Channel connector for receiving tasks from an external platform. */
+export interface ChannelConnector {
+    /** Short slug: paperclip, linear, github, webhook, etc. */
+    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.
+     */
+    parseWebhook(headers: Record<string, string | string[] | undefined>, body: string): Promise<NormalizedTask | 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>;
+}
+/** Registry of available channel connectors. */
+export type ConnectorRegistry = Map<string, ChannelConnector>;
+//# sourceMappingURL=connector.d.ts.map

package/dist/cli/gateway/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/cli/gateway/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAElC,2DAA2D;IAC3D,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE,mDAAmD;IACnD,WAAW,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC;AAED,gDAAgD;AAChD,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/cli/gateway/connector.js

@@ -0,0 +1,11 @@
+/**
+ * Channel connector interface — inspired by hermes-agent's platform adapters.
+ *
+ * A "channel" is any external platform that can send tasks to AgenticFlow
+ * agents: Paperclip, Linear, GitHub, Slack, webhooks, etc.
+ *
+ * Each connector normalizes platform-specific events into a standard task
+ * and posts results back to the originating channel.
+ */
+export {};
+//# sourceMappingURL=connector.js.map

package/dist/cli/gateway/connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../../src/cli/gateway/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/cli/gateway/connectors/index.d.ts

@@ -0,0 +1,4 @@
+export { PaperclipConnector, type PaperclipConnectorConfig } from "./paperclip.js";
+export { LinearConnector, type LinearConnectorConfig } from "./linear.js";
+export { WebhookConnector } from "./webhook.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/gateway/connectors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/gateway/connectors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/cli/gateway/connectors/index.js

@@ -0,0 +1,4 @@
+export { PaperclipConnector } from "./paperclip.js";
+export { LinearConnector } from "./linear.js";
+export { WebhookConnector } from "./webhook.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/gateway/connectors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cli/gateway/connectors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAiC,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,eAAe,EAA8B,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/cli/gateway/connectors/linear.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Linear channel connector.
+ *
+ * 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)
+ */
+import type { ChannelConnector, NormalizedTask } from "../connector.js";
+export interface LinearConnectorConfig {
+    linearApiKey: string;
+    /** Map of Linear team key → AF agent ID. e.g. { "ENG": "af-agent-uuid" } */
+    agentMapping: Record<string, string>;
+    /** Optional: AF stream URL override per agent. */
+    streamUrlMapping?: Record<string, string>;
+}
+export declare class LinearConnector implements ChannelConnector {
+    private config;
+    readonly name = "linear";
+    readonly displayName = "Linear";
+    constructor(config: LinearConnectorConfig);
+    parseWebhook(_headers: Record<string, string | string[] | undefined>, body: string): Promise<NormalizedTask | null>;
+    postResult(task: NormalizedTask, resultText: string): Promise<void>;
+}
+//# sourceMappingURL=linear.d.ts.map

package/dist/cli/gateway/connectors/linear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear.d.ts","sourceRoot":"","sources":["../../../../src/cli/gateway/connectors/linear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAgDD,qBAAa,eAAgB,YAAW,gBAAgB;IAI1C,OAAO,CAAC,MAAM;IAH1B,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,WAAW,YAAY;gBAEZ,MAAM,EAAE,qBAAqB;IAE3C,YAAY,CAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACvD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA4E3B,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAU1E"}

package/dist/cli/gateway/connectors/linear.js

@@ -0,0 +1,122 @@
+/**
+ * Linear channel connector.
+ *
+ * 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)
+ */
+// Minimal Linear GraphQL client
+async function linearQuery(apiKey, query, variables) {
+    const resp = await fetch("https://api.linear.app/graphql", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: apiKey,
+        },
+        body: JSON.stringify({ query, variables }),
+    });
+    if (!resp.ok)
+        throw new Error(`Linear API failed (${resp.status})`);
+    const result = (await resp.json());
+    if (result.errors)
+        throw new Error(`Linear GraphQL: ${JSON.stringify(result.errors)}`);
+    return result.data;
+}
+async function linearGetIssue(apiKey, issueId) {
+    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 }));
+    return data.issue;
+}
+async function linearAddComment(apiKey, issueId, body) {
+    await linearQuery(apiKey, `
+    mutation($issueId: String!, $body: String!) {
+      commentCreate(input: { issueId: $issueId, body: $body }) {
+        success
+      }
+    }
+  `, { issueId, body });
+}
+export class LinearConnector {
+    config;
+    name = "linear";
+    displayName = "Linear";
+    constructor(config) {
+        this.config = config;
+    }
+    async parseWebhook(_headers, body) {
+        const payload = JSON.parse(body);
+        // 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;
+        // Fetch full issue details
+        const issue = await linearGetIssue(this.config.linearApiKey, issueId);
+        const team = issue.team;
+        const teamKey = team?.key ?? "";
+        // Find AF agent for this team
+        const afAgentId = this.config.agentMapping[teamKey];
+        if (!afAgentId)
+            return null; // No agent mapped for this team — skip
+        const state = issue.state;
+        const labels = issue.labels;
+        const comments = issue.comments;
+        // Build message
+        const parts = [];
+        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;
+                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.");
+        return {
+            threadId: issueId, // reuse Linear issue ID as thread for continuity
+            taskIdentifier: issue.identifier ?? issueId,
+            message: parts.join("\n"),
+            afAgentId,
+            afStreamUrl: this.config.streamUrlMapping?.[afAgentId],
+            source: {
+                channel: "linear",
+                chatId: teamKey,
+                userName: issue.assignee?.name,
+            },
+            platformContext: { issueId, teamKey },
+        };
+    }
+    async postResult(task, resultText) {
+        const issueId = task.platformContext.issueId;
+        if (issueId && resultText) {
+            await linearAddComment(this.config.linearApiKey, issueId, `**Agent Response:**\n\n${resultText}`);
+        }
+    }
+}
+//# sourceMappingURL=linear.js.map

package/dist/cli/gateway/connectors/linear.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear.js","sourceRoot":"","sources":["../../../../src/cli/gateway/connectors/linear.ts"],"names":[],"mappings":"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"}

package/dist/cli/gateway/connectors/paperclip.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Paperclip channel connector.
+ *
+ * Receives heartbeat POSTs from Paperclip, fetches issue context,
+ * builds agent message, and posts results back as comments.
+ */
+import type { ChannelConnector, NormalizedTask } from "../connector.js";
+export interface PaperclipConnectorConfig {
+    paperclipUrl: string;
+}
+export declare class PaperclipConnector implements ChannelConnector {
+    private config;
+    readonly name = "paperclip";
+    readonly displayName = "Paperclip";
+    private pc;
+    constructor(config: PaperclipConnectorConfig);
+    healthCheck(): Promise<boolean>;
+    parseWebhook(_headers: Record<string, string | string[] | undefined>, body: string): Promise<NormalizedTask | null>;
+    postResult(task: NormalizedTask, resultText: string): Promise<void>;
+    private buildMessage;
+}
+//# sourceMappingURL=paperclip.d.ts.map

package/dist/cli/gateway/connectors/paperclip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paperclip.d.ts","sourceRoot":"","sources":["../../../../src/cli/gateway/connectors/paperclip.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,kBAAmB,YAAW,gBAAgB;IAK7C,OAAO,CAAC,MAAM;IAJ1B,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,WAAW,eAAe;IACnC,OAAO,CAAC,EAAE,CAAoB;gBAEV,MAAM,EAAE,wBAAwB;IAI9C,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B,YAAY,CAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACvD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAmD3B,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAS3D,YAAY;CAiD3B"}