run.started

A harness has begun a unit of work, optionally with the plan it intends to follow.

Direction: Harness → Chips
Sent by: a harness
Requires a run: yes
Schema: run.started.json

Fields

Every event also carries the envelope.

Field	Required	Type	Description
v	yes	1	Protocol major version.
type	yes	"run.started"
id	yes	string	The event’s own id. Stable across a retry of the same event.
ts	yes	string	When it happened, by Chips’ clock. Stamped on the way in; a value the sender writes is replaced.
workspace_id	yes	string	A workspace identifier: ws_ followed by a ULID.
space_id	no	string	The space, when the event belongs to one.
run_id	no	string	The run, when the event belongs to one.
seq	no	number	Assigned by the server on append, monotonic per workspace. Absent on the way in.
idempotency_key	no	string	Required on every client-originated write. Sending the same key twice is a no-op.
actor	yes	object	The participant an event is attributed to.
actor.kind	yes	"person" | "harness" | "agent" | "system"	Whether a person, a harness, one of a harness’s agents or Chips itself acted.
actor.id	yes	string	The participant id, or system for Chips.
actor.harness_id	no	string	For an agent: the harness it speaks through, whose budget and runs are the agent’s (ADR 0087). Filled in by Chips.
goal	yes	string	What the run is for, in the person’s words where possible.
plan	no	object[]	The steps the harness expects to take. The run panel draws one hollow dot each.
plan[].step_id	yes	string	Stable for the life of the run, so updates land on the right row.
plan[].title	yes	string	What this step will do.
session_ref	no	string	The visit this run belongs to, so two terminals in one space are told apart.
goal_from	no	"harness" | "chips"	Where the goal came from. harness: a person asked for it at the harness’s own surface — a terminal, a chat the harness already had — so Chips shows it as their message, because otherwise the room holds only the answers. chips: it arrived as a message here and is already on screen. Either way the room’s header and the run panel leave the goal out, because the room shows it. Omit when the goal was not a person’s words at all; the header and the run panel then say it.

Example

{
  "v": 1,
  "type": "run.started",
  "id": "evt_01K4ZQPX000000000000000064",
  "ts": "2026-09-02T14:22:00.004Z",
  "workspace_id": "ws_01K4ZQPX000000000000000001",
  "space_id": "spc_01K4ZQPX000000000000000002",
  "actor": {
    "kind": "harness",
    "id": "hrn_01K4ZQPX000000000000000004"
  },
  "run_id": "run_01K4ZQPX000000000000000005",
  "goal": "Get PO #4471 confirmed with Northwind and update the tracker.",
  "plan": [
    {
      "step_id": "read-po",
      "title": "Read PO #4471"
    },
    {
      "step_id": "check-crm",
      "title": "Check the Northwind record in the CRM"
    },
    {
      "step_id": "email-dana",
      "title": "Email Dana to confirm"
    },
    {
      "step_id": "update-tracker",
      "title": "Update the tracker"
    }
  ],
  "session_ref": "scout://sessions/2026-09-02/po-4471"
}