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.

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 shows how they fit together.

Exports

actorOf

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

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.

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.

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.

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.

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.

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.

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.

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.

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

type WorkKind = (typeof WORK_KINDS)[number];