Protocol

Pydantic models for the harness↔agent message protocol.

Task (harness → agent) and Decision (agent → harness) message contracts, plus supporting types.

CLASS	DESCRIPTION
`ActionItem`	A single action to be executed by the harness after a decision.
`DecisionMessage`	Decision returned from an agent to the harness.
`DecisionType`	Valid agent decision values.
`LLMBackendRef`	Reference to the LLM backend the agent should use.
`TaskContext`	Context injected by the harness into each task.
`TaskMessage`	Task sent from the harness to an agent container.

Classes¶

ActionItem `pydantic-model` ¶

Bases: BaseModel

A single action to be executed by the harness after a decision.

Extra fields are allowed to support future action types without schema changes.

PARAMETER	DESCRIPTION
`type`	Action type identifier (e.g. `add_label`, `comment`). TYPE: `str`

Show JSON schema:

{
  "additionalProperties": true,
  "description": "A single action to be executed by the harness after a decision.\n\nExtra fields are allowed to support future action types without schema changes.",
  "properties": {
    "type": {
      "title": "Type",
      "type": "string"
    }
  },
  "required": [
    "type"
  ],
  "title": "ActionItem",
  "type": "object"
}

Config:

default: {'extra': 'allow'}

Fields:

type (str)

Attributes¶

type `pydantic-field` ¶

type: str

Action type identifier (e.g. add_label, comment).

DecisionMessage `pydantic-model` ¶

Bases: BaseModel

Decision returned from an agent to the harness.

PARAMETER	DESCRIPTION
`task_id`	Must match the `task_id` from the corresponding :class:`TaskMessage`. TYPE: `str`
`decision`	The agent's decision on how to handle the task. TYPE: `DecisionType`
`rationale`	Human-readable explanation of the decision. TYPE: `str`
`actions`	Ordered list of actions for the harness to execute. TYPE: `list[ActionItem]` DEFAULT: `[]`

Show JSON schema:

{
  "$defs": {
    "ActionItem": {
      "additionalProperties": true,
      "description": "A single action to be executed by the harness after a decision.\n\nExtra fields are allowed to support future action types without schema changes.",
      "properties": {
        "type": {
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "type"
      ],
      "title": "ActionItem",
      "type": "object"
    },
    "DecisionType": {
      "description": "Valid agent decision values.",
      "enum": [
        "label_and_respond",
        "close",
        "escalate",
        "skip"
      ],
      "title": "DecisionType",
      "type": "string"
    }
  },
  "description": "Decision returned from an agent to the harness.",
  "properties": {
    "task_id": {
      "title": "Task Id",
      "type": "string"
    },
    "decision": {
      "$ref": "#/$defs/DecisionType"
    },
    "rationale": {
      "title": "Rationale",
      "type": "string"
    },
    "actions": {
      "default": [],
      "items": {
        "$ref": "#/$defs/ActionItem"
      },
      "title": "Actions",
      "type": "array"
    }
  },
  "required": [
    "task_id",
    "decision",
    "rationale"
  ],
  "title": "DecisionMessage",
  "type": "object"
}

Fields:

Attributes¶

actions `pydantic-field` ¶

actions: list[ActionItem] = []

Ordered list of actions for the harness to execute.

decision `pydantic-field` ¶

decision: DecisionType

The agent's decision on how to handle the task.

rationale `pydantic-field` ¶

rationale: str

Human-readable explanation of the decision.

task_id `pydantic-field` ¶

task_id: str

Must match the task_id from the corresponding :class:TaskMessage.

DecisionType ¶

Bases: str, Enum

Valid agent decision values.

LLMBackendRef `pydantic-model` ¶

Bases: BaseModel

Reference to the LLM backend the agent should use.

PARAMETER	DESCRIPTION
`provider`	LLM provider identifier (e.g. `anthropic`, `ollama`). TYPE: `str`
`model`	Model name / identifier (e.g. `claude-sonnet-4-6`). TYPE: `str`

Show JSON schema:

{
  "description": "Reference to the LLM backend the agent should use.",
  "properties": {
    "provider": {
      "title": "Provider",
      "type": "string"
    },
    "model": {
      "title": "Model",
      "type": "string"
    }
  },
  "required": [
    "provider",
    "model"
  ],
  "title": "LLMBackendRef",
  "type": "object"
}

Fields:

provider (str)
model (str)

Attributes¶

model `pydantic-field` ¶

model: str

Model name / identifier (e.g. claude-sonnet-4-6).

provider `pydantic-field` ¶

provider: str

LLM provider identifier (e.g. anthropic, ollama).

TaskContext `pydantic-model` ¶

Bases: BaseModel

Context injected by the harness into each task.

PARAMETER	DESCRIPTION
`llm_backend`	LLM backend the agent should use for this task. TYPE: `LLMBackendRef`
`memory_summary`	LLM-generated summary of prior actions on this issue/repo, if any. TYPE: `str \| None` DEFAULT: `None`

Show JSON schema:

{
  "$defs": {
    "LLMBackendRef": {
      "description": "Reference to the LLM backend the agent should use.",
      "properties": {
        "provider": {
          "title": "Provider",
          "type": "string"
        },
        "model": {
          "title": "Model",
          "type": "string"
        }
      },
      "required": [
        "provider",
        "model"
      ],
      "title": "LLMBackendRef",
      "type": "object"
    }
  },
  "description": "Context injected by the harness into each task.",
  "properties": {
    "llm_backend": {
      "$ref": "#/$defs/LLMBackendRef"
    },
    "memory_summary": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Memory Summary"
    }
  },
  "required": [
    "llm_backend"
  ],
  "title": "TaskContext",
  "type": "object"
}

Fields:

llm_backend (LLMBackendRef)
memory_summary (str | None)

Attributes¶

llm_backend `pydantic-field` ¶

llm_backend: LLMBackendRef

LLM backend the agent should use for this task.

memory_summary `pydantic-field` ¶

memory_summary: str | None = None

LLM-generated summary of prior actions on this issue/repo, if any.

TaskMessage `pydantic-model` ¶

Bases: BaseModel

Task sent from the harness to an agent container.

The harness generates a task_id automatically if not supplied.

PARAMETER	DESCRIPTION
`task_id`	Unique identifier for this task (UUID4). TYPE: `str` DEFAULT: `'e21b84be-4528-4258-9cc8-6789d9ee749d'`
`type`	Task type (e.g. `issue.triage`). TYPE: `str`
`repo`	Repository in `owner/repo` format. TYPE: `str`
`payload`	Raw GitHub event payload. TYPE: `dict[str, Any]`
`context`	Harness-injected context (memory summary, LLM backend). TYPE: `TaskContext`

Show JSON schema:

{
  "$defs": {
    "LLMBackendRef": {
      "description": "Reference to the LLM backend the agent should use.",
      "properties": {
        "provider": {
          "title": "Provider",
          "type": "string"
        },
        "model": {
          "title": "Model",
          "type": "string"
        }
      },
      "required": [
        "provider",
        "model"
      ],
      "title": "LLMBackendRef",
      "type": "object"
    },
    "TaskContext": {
      "description": "Context injected by the harness into each task.",
      "properties": {
        "llm_backend": {
          "$ref": "#/$defs/LLMBackendRef"
        },
        "memory_summary": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Memory Summary"
        }
      },
      "required": [
        "llm_backend"
      ],
      "title": "TaskContext",
      "type": "object"
    }
  },
  "description": "Task sent from the harness to an agent container.\n\nThe harness generates a ``task_id`` automatically if not supplied.",
  "properties": {
    "task_id": {
      "title": "Task Id",
      "type": "string"
    },
    "type": {
      "title": "Type",
      "type": "string"
    },
    "repo": {
      "title": "Repo",
      "type": "string"
    },
    "payload": {
      "additionalProperties": true,
      "title": "Payload",
      "type": "object"
    },
    "context": {
      "$ref": "#/$defs/TaskContext"
    }
  },
  "required": [
    "type",
    "repo",
    "payload",
    "context"
  ],
  "title": "TaskMessage",
  "type": "object"
}

Fields:

task_id (str)
type (str)
repo (str)
payload (dict[str, Any])
context (TaskContext)

Attributes¶

context `pydantic-field` ¶

context: TaskContext

Harness-injected context (memory summary, LLM backend).

payload `pydantic-field` ¶

payload: dict[str, Any]

Raw GitHub event payload.

repo `pydantic-field` ¶

repo: str

Repository in owner/repo format.

task_id `pydantic-field` ¶

task_id: str

Unique identifier for this task (UUID4).

type `pydantic-field` ¶

type: str

Task type (e.g. issue.triage).

Protocol

Classes¶

ActionItem pydantic-model ¶

Attributes¶

type pydantic-field ¶

DecisionMessage pydantic-model ¶

Attributes¶

actions pydantic-field ¶

decision pydantic-field ¶

rationale pydantic-field ¶

task_id pydantic-field ¶

DecisionType ¶

LLMBackendRef pydantic-model ¶

Attributes¶

model pydantic-field ¶

provider pydantic-field ¶

TaskContext pydantic-model ¶

Attributes¶

llm_backend pydantic-field ¶

memory_summary pydantic-field ¶

TaskMessage pydantic-model ¶

Attributes¶

context pydantic-field ¶

payload pydantic-field ¶

repo pydantic-field ¶

task_id pydantic-field ¶

type pydantic-field ¶

ActionItem `pydantic-model` ¶

type `pydantic-field` ¶

DecisionMessage `pydantic-model` ¶

actions `pydantic-field` ¶

decision `pydantic-field` ¶

rationale `pydantic-field` ¶

task_id `pydantic-field` ¶

LLMBackendRef `pydantic-model` ¶

model `pydantic-field` ¶

provider `pydantic-field` ¶

TaskContext `pydantic-model` ¶

llm_backend `pydantic-field` ¶

memory_summary `pydantic-field` ¶

TaskMessage `pydantic-model` ¶

context `pydantic-field` ¶

payload `pydantic-field` ¶

repo `pydantic-field` ¶

task_id `pydantic-field` ¶

type `pydantic-field` ¶