HARBOR_RESPONSE_PIPELINES.md

Goal

Reduce agent token usage by letting Harbor return smaller action responses and, on Business nodes, persist filtered response artifacts for later readback.

Two layers

1. Compact execute replies

Available on all plans.

Use these request fields on action execute routes:

• responseMode: "full" | "compact" | "ok"
• compact alias rm: "f" | "c" | "o"

Examples:

{
  "i": {
    "body": {
      "title": "Test Email",
      "body": "Hello from Harbor"
    }
  },
  "w": "s",
  "rm": "c"
}

Compact reply:

{
  "ok": true,
  "s": "approved",
  "x": "exec_123",
  "o": {
    "draftId": "dr_123"
  }
}

Use rm: "o" when the agent only needs status and ids back.

2. Saved response pipelines

Business-only in v1.

Response pipelines:

• target one local actionRef
• project named fields from the full output using dot-separated JSON paths
• always store the filtered artifact locally
• may optionally keep a raw operator-only copy
• reply to the agent in either compact or ok mode

Request field:

• responsePipelineId
• compact alias rp

Pipeline request example:

{
  "i": {
    "query": {
      "limit": 100
    }
  },
  "rp": "heartbeat-summary"
}

Good first patterns

Heartbeat summary

Use when a remote API returns a large health payload but the agent only needs the current state.

Suggested selector fields:

• status -> data.heartbeat.status
• updatedAt -> data.heartbeat.updatedAt
• nodeCount -> data.cluster.nodeCount

Reply mode:

• compact

Queue acknowledge only

Use when Harbor or the downstream system already stores the result and the agent only needs to know the request succeeded.

Suggested selector fields:

• jobId -> data.job.id
• queuedAt -> data.job.queuedAt

Reply mode:

• ok

Store raw copy:

• usually false

Top-N projection

Use when the remote output returns a large array and the agent only needs the first few items.

Suggested selector fields:

• items -> data.items
• arrayLimit -> 5

Reply mode:

• compact

Artifact access

Business nodes expose:

• GET /v1/response-artifacts
• GET /v1/response-artifacts/:artifactId

Agent tokens need:

• responses.read

Important:

• agent routes never return the stored raw copy
• raw copies are operator-visible only in NodeUI execution detail

Current v1 limits

• no wildcard path selectors
• no transforms, expressions, scripts, or regex
• no cross-node pipeline routing
• no retention UI yet
• rm and rp cannot be used together on one request