non-linear-docs/05-AGENT-INTEGRATION.md

# Non-Linear: AI Agent Integration

## Overview

Non-Linear treats AI agents as first-class actors — not assistants bolted onto a human interface, but independent participants with their own accounts, roles, permissions, and graph navigation capabilities.

## Two Agent Modes

### Agent as User

The agent operates independently within the project graph. It has its own account, picks up tasks, reports status, and navigates the decomposition tree autonomously.

**Primary use case:** One-person team where an AI agent acts as a focused collaborator.

**How the graph helps:** The decomposition tree gives the agent *rails*:

- "What's the highest-priority unblocked leaf node in Backend?" → graph traversal query
- "What's the status of the Auth component?" → read subtree, aggregate child statuses
- "What should I work on next?" → find unblocked, assigned, in-progress leaves

### Agent as Assistant

The agent helps human users by analyzing the graph and suggesting actions.

**Primary use case:** Teams where AI augments human decision-making.

**Examples:**
- "Break this component into tasks" → agent suggests child nodes, human approves
- "What's blocking the Auth epic?" → agent traverses subtree and lateral links
- "Summarize progress on Dashboard this week" → agent reads subtree statuses and recent comments
- "Suggest priority order for these tasks" → agent considers dependencies and blockers

## Agent API (v0.1)

Governed by the same policy engine as human users. Agents authenticate with API tokens tied to their actor account.

### Graph Traversal

```
GET /api/v1/nodes/{id}                    # Read single node
GET /api/v1/nodes/{id}/children           # Direct children
GET /api/v1/nodes/{id}/subtree            # Full subtree (depth-limited)
GET /api/v1/nodes/{id}/parent             # Parent node
GET /api/v1/nodes/{id}/links              # Outbound lateral links
GET /api/v1/nodes/{id}/backlinks          # Inbound lateral links
GET /api/v1/nodes/{id}/path              # Path from root to this node
GET /api/v1/nodes/{id}/history            # Change history timeline
GET /api/v1/projects/{id}/root            # Project root node
GET /api/v1/projects/{id}/inbox           # Triage inbox (rootless nodes)
```

### Queries

```
GET /api/v1/projects/{id}/nodes?status=in_progress&assignee=agent-123
GET /api/v1/projects/{id}/nodes?label=bug&status=backlog
GET /api/v1/projects/{id}/nodes?unblocked=true&status=todo
GET /api/v1/projects/{id}/nodes?cycle=current
```

### Write Actions (v0.1)

```
POST   /api/v1/nodes/{id}/comments        # Add comment
PATCH  /api/v1/nodes/{id}/status          # Change status
PATCH  /api/v1/nodes/{id}/parent          # Triage: assign parent to inbox item
```

### Deferred Actions (v0.2+)

```
POST   /api/v1/nodes/{id}/children        # Create child node
POST   /api/v1/nodes/{id}/links           # Create lateral link
DELETE /api/v1/nodes/{id}/links/{link_id} # Remove lateral link
PATCH  /api/v1/nodes/{id}                 # Edit node details
```

### Authentication

- Agents authenticate via API tokens (bearer tokens)
- Each token is tied to an actor (agent account)
- The actor has roles/policies assigned via the policy engine
- Token scoping: a token can optionally be restricted to a subset of the agent's permissions

### Pagination

All list endpoints use **cursor-based pagination**. Responses include a cursor for the next page and a flag indicating whether more results exist.

**Response envelope:**

```json
{
  "items": [ ... ],
  "next_cursor": "eyJpZCI6IjEyMyIsInRzIjoiMjAyNS0wMS0wMVQwMDowMDowMFoifQ==",
  "has_more": true
}
```

**Query parameters:**

| Parameter | Default | Max | Description |
|-----------|---------|-----|-------------|
| `limit` | 50 | 200 | Items per page |
| `cursor` | null | — | Opaque cursor from previous response |
| `max_depth` | 3 | 10 | Subtree query depth limit (subtree endpoint only) |

- **Subtree queries** (`GET /nodes/{id}/subtree`) accept `max_depth` to cap traversal depth. The graph visualization uses this to load progressively — fetch immediate children on expand, not the entire tree at once.
- **Children queries** (`GET /nodes/{id}/children`) are paginated but not depth-limited (they return a single level).
- **Search/filter queries** (`GET /projects/{id}/nodes?...`) are always paginated.
- Cursor encoding is opaque to the client. Internally it encodes the sort key (e.g., `created_at` + `id`) for stable pagination under concurrent writes.

### Response Format

All responses include effective permissions on the returned resource:

```json
{
  "node": {
    "id": "uuid-123",
    "short_id": "NL-42",
    "title": "Login component",
    "status": "in_progress",
    "labels": ["frontend", "p1"],
    "parent_id": "uuid-456",
    "children_count": 3,
    "backlinks": {
      "blocked_by_count": 1,
      "relates_to_count": 2
    },
    "links": [
      {
        "type": "blocked_by",
        "target_id": "uuid-789",
        "target_accessible": true,
        "target_title": "SSO integration"
      },
      {
        "type": "relates_to",
        "target_id": "uuid-000",
        "target_accessible": false,
        "target_title": null
      }
    ]
  },
  "permissions": {
    "can_edit": false,
    "can_change_status": true,
    "can_comment": true,
    "can_create_child": false
  }
}
```

## Agent Design Patterns

### Focused Worker Agent

```
Loop:
  1. Query subtree for unblocked, assigned, todo items
  2. Pick highest priority
  3. Change status to in_progress
  4. Do work (external to tracker)
  5. Post comment with results
  6. Change status to done or in_review
```

### Triage Agent

```
Loop:
  1. Query inbox for unplaced nodes
  2. For each, analyze title/description and match to existing subtrees
  3. Assign parent (place in tree)
  4. Post comment with rationale
```

### Decomposition Agent (v0.2+)

```
Triggered when: a node has label "needs-decomposition"
  1. Read node context (parent, siblings, description)
  2. Propose child nodes via comment or plan-then-apply
  3. Human reviews and approves
  4. Agent creates children
```

## Webhooks (v0.1)

Webhooks follow a **GitLab-style hooks model** — per-project registration with event filtering, signed payloads, and automatic retry.

### Registration

Webhooks are registered per project via the API or settings UI:

```
POST /api/v1/projects/{id}/webhooks
```

```json
{
  "url": "https://agent.example.com/hooks/nonlinear",
  "secret": "whsec_...",
  "events": ["node.status_changed", "node.comment_added"],
  "active": true
}
```

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | HTTPS endpoint to receive POST requests |
| `secret` | string | Shared secret for HMAC-SHA256 signature |
| `events` | string[] | Event types to subscribe to (empty = all) |
| `active` | bool | Enable/disable without deleting |

### Event Catalog

| Event | Trigger |
|-------|---------|
| `node.created` | New node (component or issue) created |
| `node.status_changed` | Issue status transition |
| `node.comment_added` | Comment posted on a node |
| `node.link_created` | Lateral link created |
| `node.link_removed` | Lateral link removed |
| `node.reparented` | Node moved to a different parent |
| `node.cycle_added` | Issue added to a cycle |
| `node.deleted` | Node (and subtree) deleted |
| `repo.commit_associated` | Commit auto-associated with a component |

### Payload Format

All webhook payloads share a common envelope:

```json
{
  "event": "node.status_changed",
  "timestamp": "2025-06-15T14:30:00Z",
  "project_id": "uuid-project",
  "actor": {
    "id": "uuid-actor",
    "type": "user",
    "name": "alice"
  },
  "data": {
    "node_id": "uuid-123",
    "short_id": "NL-42",
    "previous_status": "in_progress",
    "new_status": "in_review"
  }
}
```

The `data` field varies by event type. Each event includes the affected node's `node_id` and `short_id` at minimum.

### Signature Verification

Every webhook request includes an `X-NonLinear-Signature` header containing an HMAC-SHA256 hex digest of the raw request body, computed with the webhook's shared secret:

```
X-NonLinear-Signature: sha256=a1b2c3d4e5f6...
```

Receivers should verify the signature before processing to confirm authenticity.

### Delivery & Retry

- Webhooks are delivered asynchronously via the Taskiq worker.
- **Timeout:** 10 seconds per delivery attempt.
- **Retry:** 3 attempts with exponential backoff (10s, 60s, 300s).
- **Failure handling:** After 3 failed attempts, the event is logged and dropped. After 50 consecutive failures across any events, the webhook is automatically deactivated and the project owner is notified.
- **Ordering:** Best-effort chronological. Not guaranteed under high concurrency.

## MCP Compatibility (v0.2+)

Expose the Non-Linear API as an MCP server so AI agents built on LLM frameworks can connect natively.