<!-- Generated by scripts/ax-docs.mts from the JSDoc in registry/ouro/ax/. Do not edit; run `pnpm run docs`. -->

# ax-work-event

An attributed work event: who acted and for whom, on what, why, with which receipt, when. An agent interface emits them for its actions, handoffs, waits and returns, so the person sees what their agents did and a value stream can be measured from it.

```sh
npx shadcn@latest add ourostack/ouro-ui/ax-work-event#v1.3.10
```

It installs `lib/ouro/ax/work-event.ts`, with `ax-effects`, `ax-outcome`. Its tests are `ax-work-event-tests`. Every item runs on Node 22.18 or later as it is copied: the files import each other as `./<file>.ts`. The [Ouro AX guide](ax.md) shows how they fit together.

## Exports

### `actorOf`

The actor string read as who acts; anything else is null.

```ts
function actorOf(actor: string): WorkActor | null
```

### `checkWorkEvent`

Whether a value is a work event; when not, the first problem and its fix, so a tool that emits events can repair them from the message alone.

```ts
function checkWorkEvent(v: unknown): { ok: true; event: WorkEvent; } | { ok: false; problem: string; fix: string; }
```

### `foldWork`

Work events folded per target, in the order each target first appears.

```ts
function foldWork(events: readonly WorkEvent[]): WorkFold[]
```

### `WORK_EVENT_VERSION`

An attributed work event: who acted and for whom, on what, why, with which receipt, when. An agent interface emits them for its actions, handoffs, waits and returns, so the person sees what their agents did and a value stream can be measured from it.

```ts
const WORK_EVENT_VERSION: "work-event/1"
```

### `WORK_KINDS`

The moments where an agent and a person meet over a piece of work: an agent acted, handed the work to the person, waited (on a person or on anything else), asked for the person's attention, had it sent back, or it was finished.

```ts
const WORK_KINDS: readonly ["action", "handoff", "wait", "attention", "return", "done"]
```

### `WorkActor`

An actor string read as who acts: a named agent, an unnamed agent, or the person.

```ts
type WorkActor = { kind: "agent"; name: string | null } | { kind: "person" };
```

### `WorkEvent`

One work event. `actor` is `agent:<name>`, `agent` or `person`; `onBehalfOf` names the person an agent acts for (null when the person acts). `why` is the stated reason. `receipt` is the action's receipt id; `correlation` ties the events of one piece of work together. `detail` carries a wait's `phase` (`start` or `end`), a return's `cause` or a done's `evidence`.

```ts
interface WorkEvent {
  ax: typeof WORK_EVENT_VERSION;
  id: string;
  at: string;
  kind: WorkKind;
  actor: string;
  onBehalfOf: string | null;
  target: AxRef | null;
  why: string | null;
  effect: Effect;
  receipt: string | null;
  correlation: string | null;
  verb?: string;
  detail?: Record<string, unknown>;
}
```

### `workEventOf`

The work event an outcome makes: an action, attributed to the actor, with the outcome's target, effect, why and receipt. A planned or refused outcome changed nothing, so it makes none.

```ts
function workEventOf(o: Outcome, who: { id: string; actor: string; onBehalfOf: string | null; correlation?: string | null | undefined; at?: string | undefined; }): WorkEvent | null
```

### `WorkFold`

One target's work, counted from its own events: actions, handoffs, returns, attention asked, waits and how long the finished ones lasted. A figure nothing measured is null, never 0.

```ts
interface WorkFold {
  target: AxRef | null;
  agents: string[];
  actions: number;
  handoffs: number;
  openHandoff: boolean;
  returns: number;
  attention: number;
  waits: number;
  waitedMs: number | null;
  waitingSince: string | null;
  done: boolean;
  firstAt: string;
  lastAt: string;
}
```

### `WorkKind`

```ts
type WorkKind = (typeof WORK_KINDS)[number];
```