@pixelml/agenticflow-cli 1.1.0 → 1.2.0

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/company-blueprints.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pre-built company blueprints for Paperclip deployment.
+ *
+ * Each blueprint defines a team of AgenticFlow agents that can be
+ * deployed to Paperclip as a ready-made company. Agents are sourced
+ * from the AF marketplace templates or the user's existing agents.
+ */
+export interface AgentSlot {
+    /** Paperclip role */
+    role: string;
+    /** What this slot does */
+    title: string;
+    /** Human description */
+    description: string;
+    /** Suggested AF agent name to search for (from marketplace) */
+    suggestedTemplate?: string;
+    /** Allow user to skip this slot */
+    optional?: boolean;
+}
+export interface CompanyBlueprint {
+    /** Short slug */
+    id: string;
+    /** Display name */
+    name: string;
+    /** What this company does */
+    description: string;
+    /** Company goal */
+    goal: string;
+    /** Starter tasks */
+    starterTasks: Array<{
+        title: string;
+        description: string;
+        assigneeRole: string;
+        priority: string;
+    }>;
+    /** Agent slots to fill */
+    agents: AgentSlot[];
+}
+export declare const BLUEPRINTS: Record<string, CompanyBlueprint>;
+export declare function listBlueprints(): CompanyBlueprint[];
+export declare function getBlueprint(id: string): CompanyBlueprint | null;
+//# sourceMappingURL=company-blueprints.d.ts.map

package/dist/cli/company-blueprints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"company-blueprints.d.ts","sourceRoot":"","sources":["../../src/cli/company-blueprints.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,SAAS;IACxB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,YAAY,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpG,0BAA0B;IAC1B,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAiFvD,CAAC;AAEF,wBAAgB,cAAc,IAAI,gBAAgB,EAAE,CAEnD;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAEhE"}

package/dist/cli/company-blueprints.js

@@ -0,0 +1,96 @@
+/**
+ * Pre-built company blueprints for Paperclip deployment.
+ *
+ * Each blueprint defines a team of AgenticFlow agents that can be
+ * deployed to Paperclip as a ready-made company. Agents are sourced
+ * from the AF marketplace templates or the user's existing agents.
+ */
+export const BLUEPRINTS = {
+    "dev-shop": {
+        id: "dev-shop",
+        name: "Software Dev Shop",
+        description: "A lean engineering team that builds and ships software products.",
+        goal: "Build and ship high-quality software products",
+        agents: [
+            { role: "ceo", title: "CEO / Tech Lead", description: "Strategic direction, delegation, project oversight" },
+            { role: "engineer", title: "Senior Engineer", description: "Core development, architecture, code implementation" },
+            { role: "designer", title: "UX Designer", description: "UI/UX design, user research, visual design", optional: true },
+            { role: "qa", title: "QA Engineer", description: "Testing, bug finding, quality assurance", optional: true },
+        ],
+        starterTasks: [
+            { title: "Define product roadmap", description: "Create a 3-month product roadmap with milestones and deliverables.", assigneeRole: "ceo", priority: "high" },
+            { title: "Set up project architecture", description: "Design the technical architecture and set up the development environment.", assigneeRole: "engineer", priority: "high" },
+        ],
+    },
+    "marketing-agency": {
+        id: "marketing-agency",
+        name: "Marketing Agency",
+        description: "A full-service marketing team for content, social media, SEO, and campaigns.",
+        goal: "Drive brand awareness and customer acquisition through multi-channel marketing",
+        agents: [
+            { role: "ceo", title: "Agency Director", description: "Strategy, client relations, campaign oversight" },
+            { role: "cmo", title: "Content Strategist", description: "Content planning, blog posts, newsletters", suggestedTemplate: "Content Writer" },
+            { role: "designer", title: "Visual Designer", description: "Graphics, social media visuals, brand assets", suggestedTemplate: "Visual designer" },
+            { role: "researcher", title: "Market Researcher", description: "Competitive analysis, trend research", suggestedTemplate: "Ari, the Market Researcher", optional: true },
+        ],
+        starterTasks: [
+            { title: "Develop content calendar", description: "Create a 4-week content calendar covering blog posts, social media, and email newsletters.", assigneeRole: "cmo", priority: "high" },
+            { title: "Create brand guidelines", description: "Define color palette, typography, logo usage, and visual style for all marketing materials.", assigneeRole: "designer", priority: "high" },
+            { title: "Competitive landscape report", description: "Research top 5 competitors and summarize their positioning, pricing, and marketing strategies.", assigneeRole: "researcher", priority: "medium" },
+        ],
+    },
+    "sales-team": {
+        id: "sales-team",
+        name: "Sales Team",
+        description: "A sales operation with outreach, research, and customer management.",
+        goal: "Generate qualified leads and close deals",
+        agents: [
+            { role: "ceo", title: "Sales Director", description: "Pipeline management, strategy, team coordination" },
+            { role: "researcher", title: "Sales Researcher", description: "Lead research, company profiling, ICP matching", suggestedTemplate: "Olivia, the Sales Strategist" },
+            { role: "general", title: "SDR / Outreach", description: "Email outreach, follow-ups, scheduling", suggestedTemplate: "Rachel, the Support Agent" },
+        ],
+        starterTasks: [
+            { title: "Define ICP and target list", description: "Create ideal customer profile and build a list of 50 target companies.", assigneeRole: "researcher", priority: "high" },
+            { title: "Write outreach sequences", description: "Draft 3-step email sequences for cold outreach, follow-up, and re-engagement.", assigneeRole: "general", priority: "high" },
+        ],
+    },
+    "content-studio": {
+        id: "content-studio",
+        name: "Content Studio",
+        description: "A creative content production team for video, social, and written content.",
+        goal: "Produce high-quality content across video, social media, and written formats",
+        agents: [
+            { role: "ceo", title: "Creative Director", description: "Content strategy, quality control, brand voice" },
+            { role: "cmo", title: "Social Media Manager", description: "Social media scheduling, engagement, analytics", suggestedTemplate: "Mason, the Social Media Manager" },
+            { role: "engineer", title: "Content Writer", description: "Blog posts, articles, scripts, copy", suggestedTemplate: "Content Writer" },
+            { role: "designer", title: "Visual Creator", description: "Graphics, thumbnails, social visuals", suggestedTemplate: "Visual designer", optional: true },
+        ],
+        starterTasks: [
+            { title: "Create content pillars", description: "Define 3-5 content themes/pillars that align with the brand and audience.", assigneeRole: "ceo", priority: "high" },
+            { title: "Write 5 blog posts", description: "Draft 5 blog posts of 800-1200 words each on the defined content pillars.", assigneeRole: "engineer", priority: "high" },
+            { title: "Design social media templates", description: "Create reusable templates for Instagram, Twitter, and LinkedIn posts.", assigneeRole: "designer", priority: "medium" },
+        ],
+    },
+    "support-center": {
+        id: "support-center",
+        name: "Customer Support Center",
+        description: "A customer support team with triage, resolution, and escalation.",
+        goal: "Provide fast, helpful customer support and maintain high satisfaction",
+        agents: [
+            { role: "ceo", title: "Support Manager", description: "Escalation handling, SLA monitoring, team coordination" },
+            { role: "general", title: "Support Agent", description: "Ticket triage, first response, common issue resolution", suggestedTemplate: "Rachel, the Support Agent" },
+            { role: "researcher", title: "Knowledge Base Manager", description: "FAQ maintenance, documentation, self-service content", optional: true },
+        ],
+        starterTasks: [
+            { title: "Set up support playbook", description: "Create a support playbook with common issues, resolution steps, and escalation criteria.", assigneeRole: "ceo", priority: "high" },
+            { title: "Draft FAQ document", description: "Write an FAQ with the top 20 most common customer questions and answers.", assigneeRole: "researcher", priority: "medium" },
+        ],
+    },
+};
+export function listBlueprints() {
+    return Object.values(BLUEPRINTS);
+}
+export function getBlueprint(id) {
+    return BLUEPRINTS[id] ?? null;
+}
+//# sourceMappingURL=company-blueprints.js.map

package/dist/cli/company-blueprints.js.map

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

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

@@ -1,51 +1,45 @@
 /**
- * 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>;
-    /** 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>;
+    parseWebhook(headers: Record<string, string | string[] | undefined>, body: string): Promise<InboundTask | null>;
+    /** 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>;
 //# sourceMappingURL=connector.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/cli/gateway/connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE/B,wDAAwD;IACxD,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE"}

package/dist/cli/gateway/connector.js

@@ -1,11 +1,19 @@
 /**
- * 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
  */
 export {};
 //# sourceMappingURL=connector.js.map

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

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

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

@@ -1,27 +1,20 @@
 /**
- * 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>;
 }
 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>;
+    parseWebhook(_headers: Record<string, string | string[] | undefined>, body: string): Promise<InboundTask | null>;
+    postResult(task: InboundTask, resultText: string): Promise<void>;
 }
 //# sourceMappingURL=linear.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"linear.d.ts","sourceRoot":"","sources":["../../../../src/cli/gateway/connectors/linear.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAcD,qBAAa,eAAgB,YAAW,gBAAgB;IAG1C,OAAO,CAAC,MAAM;IAF1B,QAAQ,CAAC,IAAI,YAAY;gBAEL,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,WAAW,GAAG,IAAI,CAAC;IA+CxB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAUvE"}